Home Library Learn Downloads Support Community
Sign in | United States - English | |
0 out of 6 rated this helpful - Rate this topic

TBBUTTON structure

Applies to: desktop apps only

Contains information about a button in a toolbar.

Syntax

Copy 
typedef struct {
  int       iBitmap;
  int       idCommand;
  BYTE      fsState;
  BYTE      fsStyle;
#ifdef _WIN64
  BYTE      bReserved[6];
#else 
#if defined(_WIN32)
  BYTE      bReserved[2];
#endif 
#endif 
  DWORD_PTR dwData;
  INT_PTR   iString;
} TBBUTTON, *PTBBUTTON, *LPTBBUTTON;

Members

iBitmap

Type: int

Zero-based index of the button image. Set this member to I_IMAGECALLBACK, and the toolbar will send the TBN_GETDISPINFO notification code to retrieve the image index when it is needed.

Version 5.81. Set this member to I_IMAGENONE to indicate that the button does not have an image. The button layout will not include any space for a bitmap, only text.

If the button is a separator, that is, if fsStyle is set to BTNS_SEP, iBitmap determines the width of the separator, in pixels. For information on selecting button images from image lists, see TB_SETIMAGELIST message.

idCommand

Type: int

Command identifier associated with the button. This identifier is used in a WM_COMMAND message when the button is chosen.

fsState

Type: BYTE

Button state flags. This member can be a combination of the values listed in Toolbar Button States.

fsStyle

Type: BYTE

Button style. This member can be a combination of the button style values listed in Toolbar Control and Button Styles.

bReserved[6]

Type: BYTE

Reserved.

bReserved[2]

Type: BYTE

Reserved.

dwData

Type: DWORD_PTR

Application-defined value.

iString

Type: INT_PTR

Zero-based index of the button string, or a pointer to a string buffer that contains text for the button.

Remarks

The iString member can return either a string pointer or an index. You can use the IS_INTRESOURCE macro to determine which is returned.

Requirements

Minimum supported client

Windows 2000 Professional

Minimum supported server

Windows 2000 Server

Header
Commctrl.h

 

 

Send comments about this topic to Microsoft

Build date: 3/6/2012

Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ
iString may be neither pointer nor index
The Remarks section says
"The iString member can return either a string pointer or an index."
This is not true.

I receive a value of 0xFFFFFFFF.
This is neither an index nor a pointer.

So it is recommended to check for -1 and additionally use IsBadReadPtr() before accessing the string pointer.

Elmü

Elmü,

You may have noticed that iString is of the type INT_PTR, not the usual UINT_PTR (and there is a significant difference between the two, addressing-wise, obviously). So, instead of only allowing values larger or equal to zero, it allows the entire range of sub-zero addresses that fits within the confines of the size of a signed integer.

Now, my theory is that MSFT, in all their wisdom, needed a manner of returning an error in this particular field. Considering that iString can be an index, or more precise, a zero-based index, the usual zero returned for an error (at least, in the particular era this structure was added to the API) is not possible as it is possibly the index to a string. So, they took the easy/fast/cheap road and simply changed the UINT_PTR that was in their design documentation (I bet there is truth to that statement, seems so... MSFT, doesn't it?) to an INT_PTR, just to be able to return 0xFFFFFFFF otherwise known as -1.

In other words, the 0xFFFFFFFF you receive is the indicator that something went wrong, e.g., an error has occurred.

It would have been nice had this been mentioned in the above documentation though.

However, checking for just -1 is not enough, check for ANY value smaller than zero. At the same time, IsBadReadPtr() (the entire IsBad family in fact), is actively recommended by MSFT to be not used, I suggest people adhere to that one.

The general consensus is that the IsBad family of functions (IsBadReadPtr, IsBadWritePtr, and so forth) is broken and should
not be used to validate pointers.


See approx. 1/4th down http://msdn.microsoft.com/en-us/library/bb871031.aspx for more information on that one.


Regards,

PureCode

History
This structure incorporates alignment padding.
The definition for this structure within CommCtrl.h is as follows:

typedef struct _TBBUTTON {
    int iBitmap;
    int idCommand;
    BYTE fsState;
    BYTE fsStyle;
#ifdef _WIN64
    BYTE bReserved[6];          // padding for alignment
#elif defined(_WIN32)
    BYTE bReserved[2];          // padding for alignment
#endif
    DWORD_PTR dwData;
    INT_PTR iString;
} TBBUTTON, NEAR* PTBBUTTON, *LPTBBUTTON;

Note the 6-byte alignment padding for 64-bit and the 2-byte alignment padding for 32-bit.

The above documentation makes no mention of this padding. Since the padding influences the size of the structure, I believe it to be important that this should be mentioned in the documentation.
History