The SFT_PICTURE structure is used to describe a picture component (a bitmap, icon or ImageList image, GDI+ image, etc.).

typedef struct tagSftPicture {
    BYTE type;                          // see SFT_PICTURE_xxx
    BYTE align;                         // see SFT_PICALIGN_xxx
    BYTE valign;                        // see SFT_PICALIGN_xxx
    BYTE flag1;                         // see SFT_PICFLAG_xxx
    union tagSftPictureItem {
        HICON hIcon;                    // SFT_PICTURE_ICON, SFT_PICTURE_ICON_xxxx, icon
        HBITMAP hBitmap;                // SFT_PICTURE_BITMAPxxxx
        struct tagSftPicImage {         // SFT_PICTURE_IMAGELIST, imagelist
            HIMAGELIST hImageList;
            short iImage;               // normal image index
            short iImageDisabled;       // disabled image index
        } Image;
        struct tagSftPicClrSample {     // SFT_PICTURE_COLOR_xxxxx
            int w, h;                   // width, height
            COLORREF sampleColor;       // sample color
            COLORREF frameColor;        // frame color
        } ColorSample;
        struct tagSftPicDimensions {    // SFT_PICTURE_SIZEONLY
            int w, h;                   // width, height
        } Dimension;
        struct tagSftPicCheckBox {      // SFT_PICTURE_CB,SFT_PICTURE_CB3, ...
            int w, h;                   // width, height
            int state:2;                // (-1), 0, 1
            int enabled:1;              // 0, -1
        } CheckBox;
        struct tagSftGDIPlusImage {
            LPVOID lpImageObject;       // GDI+ Image object (Gdiplus::Image*)
        } GDIPlusImage;
        struct tagReserved {
            int res1, res2, res3, res4, res5, res6, res7, res8; // largest item
        } Unused;
#if !defined(_WIN32_WCE)
        IPictureDisp* IPicDisp;         // SFT_PICTURE_IDISPATCH
        IPicture* IPic;                 // SFT_PICTURE_IPICTURE
#endif
    } Picture;

} SFT_PICTURE, FAR * LPSFT_PICTURE;

typedef const SFT_PICTURE FAR * LPCSFT_PICTURE;

Members

type

Defines the type of the picture component.

0	Empty - no picture component has been defined.
SFT_PICTURE_BITMAP	Bitmap - The Picture union contains the bitmap handle in the hBitmap member.
SFT_PICTURE_CB	Check box - The Picture union describes the check box in the CheckBox structure.  The check box is rendered using the specified height and width (h, w), the check box state state and in enabled or disabled form (enabled).  If Windows themes are used, the check box is rendered using the current theme.
SFT_PICTURE_CB3	3-state check box - The Picture union describes the check box in the CheckBox structure.  The check box is rendered using the specified height and width (h, w), the check box state state and in enabled or disabled form (enabled).  If Windows themes are used, the check box is rendered using the current theme.
SFT_PICTURE_COLOR_SAMPLE	Color sample - The Picture union describes the picture in the ColorSample structure.  A color sample is a small rectangle used to show a color sampleColor.  The color sample can also be outlined using the color defined by frameColor.
SFT_PICTURE_GDIPLUS	GDI+ Image - The Picture union contains the Gdiplus::Image* pointer in the lpImageObject member. The image can be of any size or type supported by GDI+.  Windows Mobile Edition:  SFT_PICTURE_GDIPLUS is not supported.
SFT_PICTURE_ICON	Icon - The Picture union contains the icon handle in the hIcon member.  The icon can be of any size.  Windows Mobile Edition:  Defines a 32x32 pixel icon only.  Identical to SFT_PICTURE_ICON_32x32.
SFT_PICTURE_ICON_16x16	used with Windows Mobile Edition only:  Icon - The Picture union contains the icon handle in the hIcon member and defines a 16x16 pixel icon.
SFT_PICTURE_ICON_32x32	used with Windows Mobile Edition only:  Icon - The Picture union contains the icon handle in the hIcon member and defines a 32x32 pixel icon.
SFT_PICTURE_IDISPATCH	IDispatch - The Picture union contains the IDispatch pointer in the IPicDisp member. This describes an OLE Picture object, which is used to render the picture.  All picture types are supported, including bitmaps, icons, Windows metafiles.  Windows Mobile Edition:  SFT_PICTURE_IDISPATCH is not supported.
SFT_PICTURE_IMAGELIST	ImageList - The Picture union describes the ImageList picture in the Image structure.  The hImageList member contains the handle of an ImageList control.  iImage and iImageDisabled are index values for the image to display in enabled and disabled form.
SFT_PICTURE_IPICTURE	IPicture - The Picture union contains the IPicture pointer in the IPic member. This describes an OLE Picture object, which is used to render the picture. All picture types are supported, including bitmaps, icons, Windows metafiles.  Windows Mobile Edition:  SFT_PICTURE_IPICTURE is not supported.
SFT_PICTURE_RB	Radio button - The Picture union describes the radio button in the CheckBox structure.  The radio button is rendered using the specified height and width (h, w), the radio button state state and in enabled or disabled form (enabled).  If Windows themes are used, the radio button is rendered using the current theme.
SFT_PICTURE_SIZEONLY	Dimensions only - The Picture union describes the dimensions in the Dimension structure.  It contains the dimensions of the image only.  This results in a transparent image of the specified size.  This can be used to register the size of an image when an actual image is not required (e.g., when registering cell pictures using SetCellInfo with an index of -1).
SFT_PICTURE_UPDOWN	Up/down - The Picture union describes the up/down button in the CheckBox structure.  The up/down button is rendered using the specified height and width (h, w), the up/down button state state and in enabled or disabled form (enabled).  If Windows themes are used, the up/down button is rendered using the current theme.
SFT_PICTURE_UPDOWNSORT	Sorting direction - The Picture union describes the sort direction indicator in the CheckBox structure.  The sort direction indicator is rendered using the specified height and width (h, w), the sort direction indicator state state and in enabled or disabled form (enabled).  Visually, there is no difference between the enabled and disabled form.
additional values	Reserved for future use.

align

Reserved for future use. Must be initialized to 0.

valign

Reserved for future use. Must be initialized to 0.

flag1

Reserved for future use. Must be initialized to 0.

hIcon

An icon handle.  Valid if the picture component represents an icon (type == SFT_PICTURE_ICON, SFT_PICTURE_ICON_32x32 or SFT_PICTURE_ICON_16x16).

hBitmap

A bitmap handle.  Valid if the picture component represents a bitmap (type == SFT_PICTURE_BITMAP).

hImageList

An ImageList control handle.  Valid if the picture component represents an ImageList (type == SFT_PICTURE_IMAGELIST).  The iImage and iImageDisabled members must also be defined to describe a valid ImageList image.

iImage

The index of the image defined by the ImageList control hImageList.  This index is used to display the picture component if the item is enabled.  If disabled, the index defined by iImageDisabled is used instead.  Valid if the picture component represents an ImageList (type == SFT_PICTURE_IMAGELIST).

iImageDisabled

The index of the image defined by the ImageList control hImageList.  This index is used to display the picture component if the item is disabled.  If enabled or if the index value is -1, the index defined by iImage is used instead.  Valid if the picture component represents an ImageList (type == SFT_PICTURE_IMAGELIST).

w

The width of the image.  Valid if the picture component represents a color sample (type == SFT_PICTURE_COLOR_SAMPLE), a dimension only (type == SFT_PICTURE_SIZEONLY), a check box (type == SFT_PICTURE_CB), a 3-state check box (type == SFT_PICTURE_CB3), a radio button (type == SFT_PICTURE_RB), an up/down button (type == SFT_PICTURE_UPDOWN), or a sort direction indicator (type == SFT_PICTURE_UPDOWNSORT).

h

The height of the image.  Valid if the picture component represents a color sample (type == SFT_PICTURE_COLOR_SAMPLE), a dimension only (type == SFT_PICTURE_SIZEONLY), a check box (type == SFT_PICTURE_CB), a 3-state check box (type == SFT_PICTURE_CB3), a radio button (type == SFT_PICTURE_RB), an up/down button (type == SFT_PICTURE_UPDOWN), or a sort direction indicator (type == SFT_PICTURE_UPDOWNSORT).

sampleColor

The color of the color sample.  Valid if the picture component represents a color sample (type == SFT_PICTURE_COLOR_SAMPLE).  This color is used as fill color for the picture component of width w and height h.  The area may be framed using the defined frameColor.

frameColor

The color of the border around the color sample.  Valid if the picture component represents a color sample (type == SFT_PICTURE_COLOR_SAMPLE).  If this value is -1, no border is drawn around the color sample.

state

The state of the item represented by the image.  Valid if the picture component represents a check box (type == SFT_PICTURE_CB), a 3-state check box (type == SFT_PICTURE_CB3), a radio button (type == SFT_PICTURE_RB), an up/down button (type == SFT_PICTURE_UPDOWN), or a sort direction indicator (type == SFT_PICTURE_UPDOWNSORT).

Valid states are 0 (False) and 1 (True) for a check box (type == SFT_PICTURE_CB).

Valid states are -1 (Unknown), 0 (False) and 1 (True) for a 3-state check box (type == SFT_PICTURE_CB3).

Valid states are -1 (Unknown), 0 (False) and 1 (True) for a radio button (type == SFT_PICTURE_RB).

Valid states are 0 (Down) and 1 (Up) for an up/down button (type == SFT_PICTURE_UPDOWN).

Valid states are 0 (Descending) and 1 (Ascending) for a sort direction indicator (type == SFT_PICTURE_UPDOWNSORT).

enabled

Defines whether the item is rendered enabled or disabled.  Valid values are 0 (Disabled) and 1 (Enabled).  Valid if the picture component represents a check box (type == SFT_PICTURE_CB), a 3-state check box (type == SFT_PICTURE_CB3), a radio button (type == SFT_PICTURE_RB), an up/down button (type == SFT_PICTURE_UPDOWN), or a sort direction indicator (type == SFT_PICTURE_UPDOWNSORT).  This value has no visual effect if a sort direction indicator (type == SFT_PICTURE_UPDOWNSORT) is used.

lpImageObject

An Gdiplus::Image* pointer. Valid if the picture component represents an GDI+ image (type == SFT_PICTURE_GDIPLUS).  Describes a GDI+ image, which is used to render the picture.  Windows Mobile Edition:  lpImageObject and type == SFT_PICTURE_GDIPLUS are not supported. 

IPicDisp

An IDispatch pointer. Valid if the picture component represents an IDispatch pointer (type == SFT_PICTURE_IDISPATCH).  Describes an OLE Picture object, which is used to render the picture.  All picture types are supported, including bitmaps, icons, Windows metafiles.  Windows Mobile Edition:  IPicDisp and type == SFT_PICTURE_IDISPATCH are not supported. 

IPic

An IPicture pointer. Valid if the picture component represents an IPicture pointer (type == SFT_PICTURE_IPICTURE). Describes an OLE Picture object, which is used to render the picture. All picture types are supported, including bitmaps, icons, Windows metafiles.  Windows Mobile Edition:  IPic and type == SFT_PICTURE_IPICTURE are not supported.

Comments

The SFT_PICTURE structure is used to describe a picture component (a bitmap, icon or ImageList image, etc.).

The SFT_PICTURE structure can represent an icon, bitmap, ImageList, a color sample, a GDI+ image, an OLE Picture object, a check box, a radio button, an up/down button or a sort direction indicator. The SFT_PICTURE describes how the picture is rendered.

If an application allocates SFT_PICTURE structures, these must always be initialized using Sft_InitPicture.  Before they are deallocated, they must be cleared using Sft_ClearPicture.

Any resources that are stored in a SFT_PICTURE structure, such as a bitmap handle, icon handle, etc. remain owned by the application and must be deleted by the application.  The SFT_PICTURE structure and its supporting functions do not manage resources.

Any resources that are used by the control, such as a bitmap handle, icon handle, etc., must remain valid until the control no longer uses these resources, typically until the tree control is destroyed.

A number of functions are available to manipulate the contents of the SFT_PICTURE structure:

Sft_ClearPicture	Clears a SFT_PICTURE structure.
Sft_CopyPicture	Copies a SFT_PICTURE structure.
Sft_GetPictureSize	Returns the height and width of a picture component.
Sft_InitPicture	Initializes a SFT_PICTURE structure.
Sft_IsPicture	Returns TRUE if a SFT_PICTURE structure contains a picture component (i.e., it is not empty).
Sft_SetPictureBitmap	Assigns a bitmap to a SFT_PICTURE structure.
Sft_SetPictureCheckBox	Assigns an check box image to a SFT_PICTURE structure.
Sft_SetPictureCheckBox3	Assigns a 3-state check box image to a SFT_PICTURE structure.
Sft_SetPictureColorSample	Assigns a color sample to a SFT_PICTURE structure.
Sft_SetPictureGDIPlusImage	Assigns a Gdiplus::Image pointer to a SFT_PICTURE structure.
Sft_SetPictureIcon	Assigns an icon to a SFT_PICTURE structure.
Sft_SetPictureIcon_16x16	Assigns a 16x16 pixel icon to a SFT_PICTURE structure.
Sft_SetPictureIcon_32x32	Assigns a 32x32 pixel icon to a SFT_PICTURE structure.
Sft_SetPictureIDispatch	Assigns an OLE Picture object (IDispatch interface) to a SFT_PICTURE structure.
Sft_SetPictureImageList	Assigns an ImageList image to a SFT_PICTURE structure.
Sft_SetPictureIPicture	Assigns an OLE Picture object (IPicture interface) to a SFT_PICTURE structure.
Sft_SetPictureRadioButton	Assigns a radio button image to a SFT_PICTURE structure.
Sft_SetPictureSizeOnly	Assigns a dimension to a SFT_PICTURE structure.
Sft_SetPictureUpDown	Assigns an up/down image to a SFT_PICTURE structure.
Sft_SetPictureUpDownSort	Assigns a sort direction indicator image to a SFT_PICTURE structure.

Detail Information

void Sft_ClearPicture(LPSFT_PICTURE lpPicture);

Clears the SFT_PICTURE structure.  To initialize a newly allocated structure, use Sft_InitPicture instead.

void Sft_CopyPicture(LPSFT_PICTURE lpPictureCopy, LPCSFT_PICTURE lpPictureOrig);

Copies the SFT_PICTURE structure lpPictureOrig to the SFT_PICTURE structure lpPictureCopy.

void WINAPI Sft_GetPictureSize(LPSFT_PICTURE lpPicture,
        LPINT lpWidth,
        LPINT lpHeight);

Returns the height (lpHeight) and width (lpWidth) of the picture component described by lpPicture.  If it is empty, the width and height returned is 0.

void Sft_InitPicture(LPSFT_PICTURE lpPicture);

Initializes a SFT_PICTURE structure.

BOOL Sft_IsPicture(LPCSFT_PICTURE lpPicture);

Returns TRUE if the SFT_PICTURE structure contains a picture component (i.e., it is not empty).

void Sft_SetPictureBitmap(LPSFT_PICTURE lpPicture, HBITMAP hBitmap);

Assigns a bitmap handle hBitmap to the SFT_PICTURE structure.

void Sft_SetPictureCheckBox(LPSFT_PICTURE lpPicture,
        int state,
        int w,
        int h,
        BOOL fEnabled);

Assigns an check box image to the SFT_PICTURE structure.  Windows Mobile Edition:  The image size must be 16x16. If another size is selected using the w and h arguments, the image may not be visible.

void Sft_SetPictureCheckBox3(LPSFT_PICTURE lpPicture,
        int state,
        int w,
        int h,
        BOOL fEnabled);

Assigns a 3-state check box image to the SFT_PICTURE structure.  Windows Mobile Edition:  The image size must be 16x16. If another size is selected using the w and h arguments, the image may not be visible.

void Sft_SetPictureColorSample(LPSFT_PICTURE lpPicture,
        int w,
        int h,
        COLORREF sampleColor,
        COLORREF frameColor);

Assigns a color sample to the SFT_PICTURE structure.

void Sft_SetPictureGDIPlusImage(LPSFT_PICTURE lpPicture,
        LPVOID lpImageObject);

Assigns a Gdiplus::Image pointer to the SFT_PICTURE structure.  Windows Mobile Edition:  Sft_SetPictureGDIPlusImage is not supported.

void Sft_SetPictureIcon(LPSFT_PICTURE lpPicture, HICON hIcon);

Assigns an icon hIcon to the SFT_PICTURE structure.  The icon can be of any reasonable size.  Windows Mobile Edition:  Supports a 32x32 pixel icon only.

void Sft_SetPictureIcon_16x16(LPSFT_PICTURE lpPicture, HICON hIcon);

Windows Mobile Edition:  Assigns a 16x16 pixel icon hIcon to the SFT_PICTURE structure.

void Sft_SetPictureIcon_32x32(LPSFT_PICTURE lpPicture, HICON hIcon);

Windows Mobile Edition:  Assigns a 32x32 pixel icon hIcon to the SFT_PICTURE structure.

void Sft_SetPictureIDispatch(LPSFT_PICTURE lpPicture, IPictureDisp* IPicDisp);

Assigns an OLE Picture object (IDispatch interface) to the SFT_PICTURE structure.  Windows Mobile Edition:  Sft_SetPictureIDispatch is not supported.

void Sft_SetPictureImageList(LPSFT_PICTURE lpPicture,
        HIMAGELIST hImageList,
        short iImage,
        short iImageDisabled);

Assigns an ImageList image to the SFT_PICTURE structure.

void Sft_SetPictureIPicture(LPSFT_PICTURE lpPicture, IPicture* IPic);

Assigns an OLE Picture object (IPicture interface) to the SFT_PICTURE structure.  Windows Mobile Edition:  Sft_SetPictureIPicture is not supported.

void Sft_SetPictureRadioButton(LPSFT_PICTURE lpPicture,
        int state,
        int w,
        int h,
        BOOL fEnabled);

Assigns a radio button image to the SFT_PICTURE structure.  Windows Mobile Edition:  The image size must be 16x16. If another size is selected using the w and h arguments, the image may not be visible.

void Sft_SetPictureSizeOnly(LPSFT_PICTURE lpPicture,
        int w,
        int h);

Assigns a dimension to the SFT_PICTURE structure.

void Sft_SetPictureUpDown(LPSFT_PICTURE lpPicture,
        BOOL fUp,
        int w,
        int h,
        BOOL fEnabled);

Assigns an up/down image to the SFT_PICTURE structure.

void Sft_SetPictureUpDownSort(LPSFT_PICTURE lpPicture,
        BOOL fUp,
        int w,
        int h,
        BOOL fEnabled);

Assigns a sort direction indicator image to the SFT_PICTURE structure.

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