HeaderPane
Main
Hide
Share Link
Print

ItemLabelPicture

Defines an item's label picture.

C

BOOL WINAPI SftBox_GetItemLabelPicture(HWND hwndCtl, LONG indexTC, LPSFT_PICTURE lpPicture);
BOOL WINAPI SftBox_SetItemLabelPicture(HWND hwndCtl, LONG indexTC, LPCSFT_PICTURE lpPicture);

C++

BOOL CSftBox::GetItemLabelPicture(LONG indexTC, LPSFT_PICTURE lpPicture) const;
BOOL CSftBox::SetItemLabelPicture(LONG indexTC, LPCSFT_PICTURE lpPicture);

Parameters

hwndCtl

The window handle of the combo box control.

indexTC

The zero-based index of the item for which the label picture is to be retrieved or set. Using SetItemLabelPicture, this parameter may be -1 to register the label picture size and make the label picture area visible.

lpPicture

A pointer to a SFT_PICTURE structure. GetItemLabelPicture returns the item's label picture in this structure. SetItemLabelPicture uses the picture described by this structure as the label picture for the specified item. If the SFT_PICTURE structure defines a bitmap handle, the top, left pixel of the bitmap must contain the image's background color. This color will be replaced by the actual window background color when the bitmap is displayed. If indexTC is -1, the picture is only used to determine the size of all label pictures. Using SetItemLabelPicture, this parameter may be NULL to remove an item's label picture or to stop displaying label pictures for all items (set indexTC to -1).

Returns

GetItemLabelPicture and SetItemLabelPicture return TRUE if the function was successful, otherwise FALSE is returned.

Comments

The GetItemLabelPicture and SetItemLabelPicture functions define an item's label picture.

GetItemLabelPicture and SetItemLabelPicture can be used to define a label picture using a bitmap, icon or ImageList image. GetItemLabel and SetItemLabel can be used to define a label picture using a bitmap handle only.

In a fixed height combo box, all label pictures used for all items must be the same size. New pictures can be registered at any time, but all label pictures in use must be replaced by pictures of the new size.

In a variable height combo box (see SFTBOXSTYLE_VARIABLE), label pictures can be of varying sizes. The largest picture size must be registered using SetItemLabelPicture.

If an item doesn't have a label picture, the space normally occupied by the label picture is left blank.

An item may have an associated label picture without the label picture area actually being visible. The label picture area doesn't become visible until the (largest) label picture size has been registered using SetItemLabelPicture by setting indexTC to -1. The registered label picture size applies to the dropdown portion and the static portion. GetShowLabels can be used to determine if the label picture area is visible.

The application retains ownership of any resources used to define the picture and cannot free these resources until the combo box control no longer uses these (usually until the combo box control is destroyed or the pictures are changed).

In a combo box using a virtual data source, SetItemLabelPicture can only be used to register the label picture size, otherwise an error is returned. The LabelPicture member of the SFTBOX_ITEM structure is used instead.

See Also C/C++ API | Categories | Notifications


Last Updated 11/21/2026 - (email)
© 2026 Softel vdm, Inc.