# SftPicture2 — API Reference

> Complete A-Z reference for SftPicture2. The guide and feature documentation is in https://softelvdm.com/Vault/Softelvdm.com/llms/SftPicture2.txt

Online documentation: https://softelvdm.com/Documentation/SftPicture2

## SFT_IMAGEOVL Constants

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_imageovl*

Style flag for the *style* field of the *ImageOvl* arm of the [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) *Picture* union. Used only when the picture *type* is [SFT_PICTURE_IMAGELISTOVL](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types).

```
#define SFT_IMAGEOVL_GHOSTED    1
```

|  |  |
| --- | --- |
| SFT_IMAGEOVL_GHOSTED (1) | Render the overlay image with a ghosted (semi-transparent) effect rather than a solid composite. Useful for "in-progress" or "pending" indicator overlays. |

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE | SFT_PICTURE_IMAGELISTOVL | [Sft_SetPictureImageList](https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpictureimagelist)

## SFT_NOCOLOR

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_nocolor*

Sentinel COLORREF value meaning "no color / use default". Used by [SFT_TEXT](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_text) (the *colorFg* field) and by the *frameColor* field of [SFT_PICTURE_COLOR_SAMPLE](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types) pictures.

```
#define SFT_NOCOLOR     ((COLORREF)(-1))
```

A COLORREF field set to SFT_NOCOLOR tells the rendering code to use a sensible default - either inherit from a per-state field on the host control structure (for SFT_TEXT.colorFg) or skip the operation entirely (for SFT_PICTURE_COLOR_SAMPLE.frameColor, where SFT_NOCOLOR means "no border").

Per-product control structures expose their own product-specific NOCOLOR aliases (e.g. SFTBUTTON_NOCOLOR, SFTTREE_NOCOLOR) that all expand to the same *(COLORREF)(-1)* value. SFT_NOCOLOR and the per-product aliases are interchangeable - the underlying value is identical.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) | SFT_TEXT

## SFT_ORIENTATION Constants

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_orientation*

Orientation values for the *orientation* field on [SFT_TEXT](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_text).

```
#define SFT_ORIENTATION_HORZ    0
#define SFT_ORIENTATION_VERT    1
```

|  |  |
| --- | --- |
| SFT_ORIENTATION_HORZ (0) | Render text left-to-right along a horizontal baseline. Default. |
| SFT_ORIENTATION_VERT (1) | Render text rotated 90 degrees so the baseline runs vertically. Useful for narrow side-aligned slots. |

The *orientation* field is read-only as far as the host control is concerned - the application sets it once when populating the SFT_TEXT and the control honors it on every paint.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_TEXT

## SFT_PICALIGN Constants

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picalign*

Alignment values for the *align* and *valign* fields on [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) and [SFT_TEXT](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_text). *align* controls horizontal placement, *valign* controls vertical placement.

```
/* Horizontal (align) */
#define SFT_PICALIGN_CENTER     0
#define SFT_PICALIGN_LEFT       1
#define SFT_PICALIGN_RIGHT      2
#define SFT_PICALIGN_FLUSH      3

/* Vertical (valign) */
#define SFT_PICALIGN_VCENTER    0
#define SFT_PICALIGN_TOP        1
#define SFT_PICALIGN_BOTTOM     2
```

### Horizontal alignment (*align*)

|  |  |
| --- | --- |
| SFT_PICALIGN_CENTER (0) | Center the picture / text horizontally within its slot. Default. |
| SFT_PICALIGN_LEFT (1) | Left-align. |
| SFT_PICALIGN_RIGHT (2) | Right-align. |
| SFT_PICALIGN_FLUSH (3) | Flush / justify (text only - meaningful on multi-line SFT_TEXT content). |

### Vertical alignment (*valign*)

|  |  |
| --- | --- |
| SFT_PICALIGN_VCENTER (0) | Center vertically within the slot. Default. |
| SFT_PICALIGN_TOP (1) | Align to the top of the slot. |
| SFT_PICALIGN_BOTTOM (2) | Align to the bottom of the slot. |

Note: *align* and *valign* use overlapping numeric values (CENTER = 0 in both axes, etc.). Always use the value-name appropriate to the axis - the **_VCENTER** / **_TOP** / **_BOTTOM** names for *valign* and the **_CENTER** / **_LEFT** / **_RIGHT** / **_FLUSH** names for *align* - to keep code readable.

For SFT_TEXT, the *align* and *valign* settings drive the corresponding *DT_LEFT* / *DT_CENTER* / *DT_RIGHT* / *DT_TOP* / *DT_VCENTER* / *DT_BOTTOM* bits during *DrawText* automatically; do not set those bits in *SFT_TEXT.flag*.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE | SFT_TEXT

## SFT_PICFLAG Constants

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picflag*

Bit flag for the *flag1* field on [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture). Application code should leave *flag1* at zero - the flag is reserved for the picture-management implementation inside Softel vdm controls.

```
#define SFT_PICFLAG_FREE        1
```

|  |  |
| --- | --- |
| SFT_PICFLAG_FREE (1) | Internal ownership marker. Set by certain product-internal code paths to indicate that the resource referenced by the union is owned by the control rather than the application. Application code never sets or clears this flag. |

[Sft_ClearPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_clearpicture) asserts that *flag1* does not have SFT_PICFLAG_FREE set when called - reaching that assertion through application code generally means the SFT_PICTURE was used in an unintended way.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE | Sft_ClearPicture

## SFT_PICTURE Structure

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture*

SFT_PICTURE describes a single image, glyph or picture-bearing slot used by every Softel vdm control. It is a **type-tagged union**: the *type* field selects which arm of the embedded *Picture* union is meaningful. The same structure can hold a bitmap, icon, image-list entry, OLE picture, GDI+ image, .NET image, color sample, dimension placeholder, AVI animation, or one of the built-in glyphs (check box, radio button, up/down, sort indicator).

C

```
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 / _16x16 / _32x32
        HBITMAP hBitmap;                                 // SFT_PICTURE_BITMAP
        struct tagSftPicImage {                          // {linksame "SFT_PICTURE_IMAGELIST" def_sft_picture_types}
            HIMAGELIST hImageList;
            short iImage;                                // normal image index
            short iImageDisabled;                        // disabled image index
        } Image;
        struct tagSftPicImageOvl {                       // {linksame "SFT_PICTURE_IMAGELISTOVL" def_sft_picture_types}
            HIMAGELIST hImageList;
            short iImage;
            short iImageOvl;                             // overlay image index
            short ovlStyle;                              // SFT_IMAGEOVL_GHOSTED
        } ImageOvl;
        struct tagSftPicClrSample {                      // {linksame "SFT_PICTURE_COLOR_SAMPLE" def_sft_picture_types}
            int csW, csH;                                // width, height
            COLORREF sampleColor;                        // fill color
            COLORREF frameColor;                         // border color, -1 for none
        } ColorSample;
        struct tagSftPicDimensions {                     // {linksame "SFT_PICTURE_SIZEONLY" def_sft_picture_types}
            int dimW, dimH;                              // width, height
        } Dimension;
        struct tagSftPicCheckBox {                       // {linksame "SFT_PICTURE_CB" def_sft_picture_types} / _CB3 / _RB / _UPDOWN / _UPDOWNSORT
            int cbW, cbH;                                // width, height
            int state:2;                                 // (-1), 0, 1
            int enabled:1;                               // 0, -1
        } CheckBox;
        struct tagSftGDIPlusImage {                      // {linksame "SFT_PICTURE_GDIPLUS" def_sft_picture_types}
            LPVOID lpImageObject;                        // Gdiplus::Image*
        } GDIPlusImage;
        struct tagSftNETImage {                          // {linksame "SFT_PICTURE_NET" def_sft_picture_types}
            IUnknown* pUnknown;                          // .NET System.Drawing.Image (IUnknown)
        } NETImage;
        IPictureDisp* IPicDisp;                          // SFT_PICTURE_IDISPATCH
        IPicture* IPic;                                  // SFT_PICTURE_IPICTURE
        HWND hwndAnim;                                   // SFT_PICTURE_AVI
    } Picture;

} SFT_PICTURE, FAR * LPSFT_PICTURE;

typedef const SFT_PICTURE FAR * LPCSFT_PICTURE;
```

### Header members

type

Type discriminator. Selects which member of the *Picture* union is meaningful. One of the [SFT_PICTURE_*](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types) constants, or 0 for an empty slot.

align

Horizontal alignment of the picture within its slot. One of [SFT_PICALIGN_CENTER](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picalign) (default), SFT_PICALIGN_LEFT, SFT_PICALIGN_RIGHT or SFT_PICALIGN_FLUSH.

valign

Vertical alignment of the picture within its slot. One of SFT_PICALIGN_VCENTER (default), SFT_PICALIGN_TOP or SFT_PICALIGN_BOTTOM.

flag1

Reserved for the picture-management implementation - see [SFT_PICFLAG_FREE](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picflag). Application code should leave this field at zero.

### Picture union members

hIcon

Icon handle. Valid when *type* is SFT_PICTURE_ICON, SFT_PICTURE_ICON_16x16 or SFT_PICTURE_ICON_32x32.

hBitmap

Bitmap handle. Valid when *type* is SFT_PICTURE_BITMAP. The top-left pixel is treated as the transparent color.

hImageList, iImage, iImageDisabled

Image list handle and entry indices. Valid when *type* is SFT_PICTURE_IMAGELIST. *iImage* is drawn in the enabled state; *iImageDisabled* is drawn in the disabled state (set to -1 to reuse *iImage* - the system applies a generic graying effect at draw time).

iImageOvl, style

Overlay image index and overlay style. Valid when *type* is SFT_PICTURE_IMAGELISTOVL (in addition to *hImageList* and *iImage* above). *style* accepts [SFT_IMAGEOVL_GHOSTED](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_imageovl).

w, h, sampleColor, frameColor

Color sample fields - width, height, fill color, border color. Valid when *type* is SFT_PICTURE_COLOR_SAMPLE. Set *frameColor* to -1 (or [SFT_NOCOLOR](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_nocolor)) to draw no border.

w, h

Layout-placeholder dimensions. Valid when *type* is SFT_PICTURE_SIZEONLY. The slot reserves space for a *w* by *h* rectangle but draws nothing.

w, h, state, enabled

Glyph fields - width, height, state, enabled flag. Valid when *type* is SFT_PICTURE_CB, SFT_PICTURE_CB3, SFT_PICTURE_RB, SFT_PICTURE_UPDOWN or SFT_PICTURE_UPDOWNSORT. *state* interpretation depends on the type (CB: 0/1; CB3 and RB: -1/0/1; UPDOWN: 0=down, 1=up; UPDOWNSORT: 0=descending, 1=ascending). *enabled* grays the glyph when zero (UPDOWNSORT ignores this field).

lpImageObject

Pointer to a *Gdiplus::Image* object. Valid when *type* is SFT_PICTURE_GDIPLUS. The application creates and owns the GDI+ Image; the SFT_PICTURE only stores the pointer.

pUnknown

Pointer to an IUnknown for a .NET image (typically obtained via *System.Drawing.Image.GetIUnknownForObject*). Valid when *type* is SFT_PICTURE_NET.

IPicDisp

*IPictureDisp* pointer. Valid when *type* is SFT_PICTURE_IDISPATCH. The application owns the picture object's reference count.

IPic

*IPicture* pointer. Valid when *type* is SFT_PICTURE_IPICTURE. The application owns the picture object's reference count.

hwndAnim

HWND of a Microsoft Animation control playing an AVI clip. Valid when *type* is SFT_PICTURE_AVI.

### Initialization and ownership

Allocate a SFT_PICTURE on the stack or as a struct field; initialize it with [Sft_InitPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_initpicture) (or *memset(0)*) before its first use; populate it with one of the [Sft_SetPicture*](https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpicturebitmap) setters; and reset it with [Sft_ClearPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_clearpicture) before deallocation or before assigning a different picture.

Resource ownership: the resources stored in a SFT_PICTURE - HBITMAP, HICON, HIMAGELIST, IPicture pointers, GDI+ Image objects, .NET IUnknown pointers, animation HWNDs - remain owned by the application. Sft_ClearPicture only zeroes the structure; it never destroys handles or releases COM references. Keep the resources alive for as long as the host control might use them (typically until the control is destroyed).

Per-product support: not every control supports every picture type. Each product's documentation lists the picture types it accepts.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE_* | SFT_PICALIGN_* | [SFT_TEXT](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_text) | Sft_InitPicture | Sft_SetPictureBitmap

## SFT_PICTURE Type Constants

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types*

Type discriminator values for the *type* field on [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture). The value selects which member of the *Picture* union is meaningful and is normally set automatically by one of the [Sft_SetPicture*](https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpicturebitmap) setter functions.

```
#define SFT_PICTURE_ICON            1       // Icon (any size)
#define SFT_PICTURE_IMAGELIST       2       // ImageList
#define SFT_PICTURE_IDISPATCH       3       // IDispatch - IPictureDisp
#define SFT_PICTURE_IPICTURE        4       // IPicture
#define SFT_PICTURE_IMAGELISTOVL    5       // ImageList with overlay index
#define SFT_PICTURE_BITMAP          10      // Bitmap with bg-color replacement (top-left corner)
#define SFT_PICTURE_BITMAP_BL       11      // Reserved (not yet supported)
#define SFT_PICTURE_BITMAP_NONE     12      // Reserved (not yet supported)
#define SFT_PICTURE_COLOR_SAMPLE    20      // Color sample (filled rectangle, optional border)
#define SFT_PICTURE_AVI             25      // Animation control (AVI clip)
#define SFT_PICTURE_SIZEONLY        26      // Layout placeholder (no rendering)
#define SFT_PICTURE_CB              27      // Two-state check box glyph
#define SFT_PICTURE_CB3             28      // Three-state check box glyph
#define SFT_PICTURE_RB              29      // Radio button glyph
#define SFT_PICTURE_UPDOWN          30      // Up / down arrow glyph
#define SFT_PICTURE_UPDOWNSORT      31      // Sort-direction indicator
#define SFT_PICTURE_ICON_32x32      SFT_PICTURE_ICON  // Discontinued alias
#define SFT_PICTURE_ICON_16x16      33      // Discontinued (16x16 icon)
#define SFT_PICTURE_GDIPLUS         50      // GDI+ image (PNG, TIFF, JPEG, GIF, EMF+)
#define SFT_PICTURE_NET             51      // .NET System.Drawing.Image
```

### Resource-bearing types

| Constant | Slot | Description |
| --- | --- | --- |
| SFT_PICTURE_BITMAP | *Picture.hBitmap* | A device-dependent bitmap. The top-left pixel is the transparent color. |
| SFT_PICTURE_ICON | *Picture.hIcon* | An icon of any size. |
| SFT_PICTURE_ICON_16x16 | *Picture.hIcon* | **Discontinued.** 16x16 icon. New code should use SFT_PICTURE_ICON. |
| SFT_PICTURE_ICON_32x32 | *Picture.hIcon* | **Discontinued.** 32x32 icon (alias for SFT_PICTURE_ICON, value 1). New code should use SFT_PICTURE_ICON. |
| SFT_PICTURE_IMAGELIST | *Picture.Image* | An entry in an image list. Holds the *HIMAGELIST* plus a normal and an optional disabled image index. |
| SFT_PICTURE_IMAGELISTOVL | *Picture.ImageOvl* | An image list entry combined with an overlay image index. Style accepts [SFT_IMAGEOVL_GHOSTED](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_imageovl). |
| SFT_PICTURE_IDISPATCH | *Picture.IPicDisp* | An OLE picture object accessed through the *IPictureDisp* interface. |
| SFT_PICTURE_IPICTURE | *Picture.IPic* | An OLE picture object accessed through the *IPicture* interface. |
| SFT_PICTURE_GDIPLUS | *Picture.GDIPlusImage.lpImageObject* | A GDI+ image (PNG, TIFF, JPEG, GIF, EMF+) - the application supplies a *Gdiplus::Image** pointer. |
| SFT_PICTURE_NET | *Picture.NETImage.pUnknown* | A .NET image - the application supplies an *IUnknown** obtained from the .NET wrapper for *System.Drawing.Image*. |
| SFT_PICTURE_AVI | *Picture.hwndAnim* | An AVI clip hosted in a Microsoft Animation control - the SFT_PICTURE stores the animation control's HWND. |

### Built-in glyphs and placeholders

| Constant | Slot | Description |
| --- | --- | --- |
| SFT_PICTURE_COLOR_SAMPLE | *Picture.ColorSample* | A solid color swatch with optional border. Width / height / sample color / frame color. |
| SFT_PICTURE_SIZEONLY | *Picture.Dimension* | A layout placeholder that reserves space but draws nothing. Useful when an image will be supplied later or when the slot must match a sibling control's size. |
| SFT_PICTURE_CB | *Picture.CheckBox* | A two-state check box glyph (state 0 / 1). |
| SFT_PICTURE_CB3 | *Picture.CheckBox* | A three-state check box glyph (state -1 = indeterminate, 0 = unchecked, 1 = checked). |
| SFT_PICTURE_RB | *Picture.CheckBox* | A radio button glyph. |
| SFT_PICTURE_UPDOWN | *Picture.CheckBox* | An up / down arrow glyph (state 0 = down, 1 = up). |
| SFT_PICTURE_UPDOWNSORT | *Picture.CheckBox* | A sort-direction indicator (state 0 = descending, 1 = ascending). The *enabled* field is ignored. |

### Reserved values

*SFT_PICTURE_BITMAP_BL* (11) and *SFT_PICTURE_BITMAP_NONE* (12) are declared but not yet supported by any product. Do not use them in new code; they are reserved for future bitmap-rendering modes.

### Per-product support

Not every product supports every type. Each product's documentation lists which types it accepts in its image / picture / glyph fields. Setting an unsupported type usually produces an empty visual but does not crash.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE

## SFT_TEXT Flags

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_text_flags*

Bit flags for the *flag2* field on [SFT_TEXT](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_text). Control the text-area background and outline used during hit-testing and selection rendering.

```
#define SFT_TEXT_CARET              0x01
#define SFT_TEXT_FULLHEIGHT         0x02
#define SFT_TEXT_INFLATEBACKGROUND  0x04
#define SFT_TEXT_OUTLINESELECTION   0x10
#define SFT_TEXT_PAINTOUTLINE       0x20
```

| Flag | Effect |
| --- | --- |
| SFT_TEXT_CARET (0x01) | Draw a caret-style outline around the text. |
| SFT_TEXT_FULLHEIGHT (0x02) | Use the full slot height (instead of the text height) for the background or selection outline. |
| SFT_TEXT_INFLATEBACKGROUND (0x04) | Inflate the text-only background rectangle by a small amount before painting. |
| SFT_TEXT_OUTLINESELECTION (0x10) | Use the selection outline rather than the background rectangle for hit-test space determination. |
| SFT_TEXT_PAINTOUTLINE (0x20) | Paint the selection outline rather than the background rectangle. |

Flags can be combined with bitwise OR. The flags interact only with the text-area background and outline; they do not affect the text content itself.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_TEXT

## SFT_TEXT Structure

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_text*

SFT_TEXT describes a text label - the string itself, its font, color, alignment, orientation, optional GDI+ rendering hints, and a bit field of selection-outline / background flags. The structure is embedded as a *Text* (or similarly named) field on per-product control structures wherever the control renders application-supplied text.

C

```
typedef struct tagSftText {
    BYTE     orientation;          // SFT_ORIENTATION_HORZ / _VERT
    BYTE     align;                // SFT_PICALIGN_CENTER / _LEFT / _RIGHT / _FLUSH
    BYTE     valign;               // SFT_PICALIGN_VCENTER / _TOP / _BOTTOM
    BYTE     res1;                 // reserved

    UINT     flag;                 // DT_* text drawing flags
    HFONT    hFont;                // font (NULL = HWND font from WM_SETFONT)
    COLORREF colorFg;              // text color (SFT_NOCOLOR = use control color)
    LPCTSTR  lpszText;             // null-terminated text
    HBRUSH   hbrBgText;            // optional text-only background brush
    UINT     flag2;                // SFT_TEXT_* flags

    BOOL     fWantGdiText;         // render text through GDI+ instead of GDI
    int      textRenderHint;       // GDI+ TextRenderingHint
    int      textAlpha;            // GDI+ text alpha
    int      textContrast;         // GDI+ contrast

} SFT_TEXT, FAR * LPSFT_TEXT;

typedef const SFT_TEXT FAR * LPCSFT_TEXT;
```

### Members

orientation

Text orientation. [SFT_ORIENTATION_HORZ](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_orientation) (default) renders left-to-right; SFT_ORIENTATION_VERT renders rotated 90 degrees so the baseline runs vertically.

align

Horizontal alignment of the text within the slot. [SFT_PICALIGN_CENTER](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picalign) (default), SFT_PICALIGN_LEFT, SFT_PICALIGN_RIGHT or SFT_PICALIGN_FLUSH (justify).

valign

Vertical alignment. SFT_PICALIGN_VCENTER (default), SFT_PICALIGN_TOP or SFT_PICALIGN_BOTTOM.

flag

DrawText / DrawTextEx flags applied during rendering. Common values are DT_SINGLELINE, DT_WORDBREAK, DT_END_ELLIPSIS, DT_NOPREFIX (suppress accelerator underline) and DT_HIDEPREFIX (hide unless Alt is held). The *align* and *valign* fields drive the corresponding DT_LEFT / DT_CENTER / DT_RIGHT / DT_TOP / DT_VCENTER / DT_BOTTOM bits automatically; do not set those bits in *flag*.

hFont

Font handle for this text. When NULL the control renders text in the font attached to the host's HWND (set with WM_SETFONT) - this is the conventional case in MFC and dialog-based applications. Setting an explicit font here overrides the HWND font for this slot only. The application owns *hFont* and must keep it alive while the control uses it.

colorFg

Text color. Set to [SFT_NOCOLOR](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_nocolor) (the default) to inherit the per-state color from the host control's own color fields. Any other value overrides the control's text color and is used in every state.

lpszText

Pointer to a null-terminated text string. Use a single ampersand (&) to mark an accelerator key (the next character is underlined; Alt+key activates the host control if it supports accelerators). Use two ampersands (&&) to render a literal ampersand. The pointer is read at draw time; the application keeps the string alive until the next API call replaces it.

hbrBgText

Optional background brush used to paint a rectangle behind the text only (the rest of the host's background uses its own color fields). Set to NULL when no text-only background is needed.

flag2

Bit field of [SFT_TEXT_*](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_text_flags) flags controlling the text-area background and outline used during hit-testing and selection rendering.

fWantGdiText

TRUE to render text through GDI+ instead of GDI. GDI+ produces sub-pixel-accurate antialiasing on rotated and scaled text; GDI is faster and matches the rest of the Windows UI. Default is FALSE (GDI).

textRenderHint

GDI+ text-rendering hint. Used only when *fWantGdiText* is TRUE. One of the *Gdiplus::TextRenderingHint* values - *TextRenderingHintAntiAlias*, *TextRenderingHintAntiAliasGridFit*, *TextRenderingHintClearTypeGridFit*, etc. 0 (*TextRenderingHintSystemDefault*) is a safe default.

textAlpha

GDI+ text alpha (0-255). Used only when *fWantGdiText* is TRUE. 255 is fully opaque (the default); lower values produce semi-transparent text useful for watermark and disabled-overlay styling.

textContrast

GDI+ gamma-correction contrast value (0-12). Used only when *fWantGdiText* is TRUE. The Gdiplus default is 4. Lower values lighten the rendered text against dark backgrounds; higher values darken it.

### Initialization and ownership

Allocate a SFT_TEXT on the stack or as a struct field; initialize it with [Sft_InitText](https://softelvdm.com/Documentation/SftPicture2/Topic/function_inittext) (or *memset(0)*) before its first use; populate *lpszText* (and optionally *hFont*, *colorFg*, *align*, *valign*); and pass the structure to the per-product API call that consumes it.

The application owns the string, font and brush handles referenced by SFT_TEXT. The control reads them at draw time and never frees them. Keep them valid for the lifetime of the host or until the next API call replaces them.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) | SFT_PICALIGN_* | SFT_ORIENTATION_* | SFT_NOCOLOR | SFT_TEXT_* | Sft_InitText

## Sft_ClearPicture

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/function_clearpicture*

Reset a [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) to the empty state. Asserts that the structure is not internally owned (does not have [SFT_PICFLAG_FREE](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picflag) set) and that the *type* value is one of the recognized [SFT_PICTURE_*](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types) constants.

C

```
void Sft_ClearPicture(LPSFT_PICTURE lpPicture);
```

### Parameters

lpPicture

Pointer to a SFT_PICTURE. Must not be NULL.

### Comments

Call before deallocating a SFT_PICTURE or before assigning a different picture into the same slot. The [Sft_SetPicture*](https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpicturebitmap) setters call Sft_ClearPicture internally, so direct calls are needed only when the application wants to leave the slot empty.

Resource ownership: Sft_ClearPicture only zeroes the structure - it never destroys handles or releases COM references stored in the *Picture* union. Resources stored in a SFT_PICTURE remain owned by the application; clear the structure first, then release the resource through the appropriate Win32 / COM call (*DeleteObject*, *DestroyIcon*, *IPicture::Release*, *delete (Gdiplus::Image*)*, etc.).

The internal assertion on *type* catches uninitialized SFT_PICTURE memory - if Sft_ClearPicture asserts, the structure was likely never zeroed (use [Sft_InitPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_initpicture) on freshly allocated SFT_PICTURE instances).

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE | Sft_InitPicture | [Sft_CopyPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_copypicture)

## Sft_CopyPicture

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/function_copypicture*

Copy one [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) into another. Handles and COM pointers are copied verbatim - the destination becomes a second reference to the same resources.

C

```
void Sft_CopyPicture(LPSFT_PICTURE lpPictureCopy, LPCSFT_PICTURE lpPictureOrig);
```

### Parameters

lpPictureCopy

Pointer to the destination SFT_PICTURE. Must not be NULL. Reset to empty by an internal [Sft_ClearPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_clearpicture) call before the copy.

lpPictureOrig

Pointer to the source SFT_PICTURE. Must not be NULL.

### Comments

Sft_CopyPicture is the right call when the application needs two SFT_PICTURE structures pointing at the same underlying picture - for example to hand a copy to a per-product API that captures the structure by value. The [SFT_PICFLAG_FREE](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picflag) bit is cleared on the destination so the copy is treated as application-owned regardless of the source's ownership flag.

Resource lifetime: after Sft_CopyPicture both structures reference the same handle / pointer. The application is still responsible for releasing the resource exactly once - whichever of the two structures outlives the resource must Sft_ClearPicture itself before the resource is destroyed.

The function asserts at runtime that the source's *type* is one of the recognized [SFT_PICTURE_*](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types) constants - useful for catching uninitialized memory.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE | [Sft_InitPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_initpicture) | Sft_ClearPicture

## Sft_SetPictureBitmap

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpicturebitmap*

*Also listed as: Sft_GetPictureBitmap, Sft_SetPictureBitmap*

Store an HBITMAP in a [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) as a [SFT_PICTURE_BITMAP](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types) slot, or read the HBITMAP back out.

C

```
void    Sft_SetPictureBitmap(LPSFT_PICTURE lpPicture, HBITMAP hBitmap);
HBITMAP Sft_GetPictureBitmap(LPCSFT_PICTURE lpPicture);
```

### Parameters

lpPicture

Pointer to a SFT_PICTURE. Must not be NULL on the setter; NULL is accepted on the getter and returns NULL.

hBitmap

Bitmap handle. NULL leaves the slot empty (the existing picture is cleared).

### Return Value (Sft_GetPictureBitmap)

The HBITMAP stored in the slot, or NULL if the slot is empty or holds a non-bitmap picture type.

### Comments

Sft_SetPictureBitmap calls [Sft_ClearPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_clearpicture) internally before assigning the new bitmap, so the previous picture's resources are released by the application separately if needed.

The top-left pixel of the bitmap is treated as the transparent color when the host control draws it.

Resource ownership: the application owns the HBITMAP and must keep it alive until either Sft_ClearPicture is called or the host control is destroyed. Use *DeleteObject* to release the bitmap when the application is done with it.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE | SFT_PICTURE_BITMAP | [Sft_IsPictureBitmap](https://softelvdm.com/Documentation/SftPicture2/Topic/function_ispictureby_type)

## Sft_GetPictureSize

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/function_getpicturesize*

Return the pixel width and height of a populated [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture). Handles every supported [SFT_PICTURE_*](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types) type and dispatches to the appropriate measurement (bitmap dimensions, icon dimensions, image-list cell size, GDI+ image size, COM picture HIMETRIC conversion, embedded width / height fields, etc.).

C

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

### Parameters

lpPicture

Pointer to a SFT_PICTURE. NULL is accepted and returns zero in both output parameters.

lpWidth

Pointer to an int that receives the picture width in pixels. May be NULL if the caller only needs the height.

lpHeight

Pointer to an int that receives the picture height in pixels. May be NULL if the caller only needs the width.

### Comments

Sft_GetPictureSize is the only function in *[SftPicture2.h](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main)* that is **not inline** - it is exported from the per-product DLL because the per-type measurement logic is large enough that inlining it across every translation unit would be wasteful.

For an empty slot (*type* = 0), the function returns 0 in both output parameters.

The returned dimensions are in physical pixels at the picture's native resolution. Per-product image / pixel scaling settings (where supported) are not applied here - they apply at draw time inside the host control.

See Also SftPicture2 | SFT_PICTURE

## Sft_InitPicture

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/function_initpicture*

Initialize a freshly allocated [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) so it represents an empty slot. Equivalent to *memset(0)*.

C

```
void Sft_InitPicture(LPSFT_PICTURE lpPicture);
```

### Parameters

lpPicture

Pointer to a SFT_PICTURE allocated by the application. Must not be NULL.

### Comments

Call once on each application-allocated SFT_PICTURE before its first use. SFT_PICTURE fields embedded in per-product control structures are initialized by the host control automatically and do not need a separate Sft_InitPicture call.

After Sft_InitPicture, the structure has *type* = 0 (empty slot), default alignment values, and zero in every union member. Pass it to one of the [Sft_SetPicture*](https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpicturebitmap) setters to populate it with a picture.

Sft_InitPicture does not check for or release any resources that may have been stored in the structure - if the structure may currently hold a picture, use [Sft_ClearPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_clearpicture) instead so the assertion in the FREE-flag check still fires.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE | Sft_ClearPicture | [Sft_InitText](https://softelvdm.com/Documentation/SftPicture2/Topic/function_inittext)

## Sft_InitText

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/function_inittext*

Initialize a freshly allocated [SFT_TEXT](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_text) so it represents an empty text label. Equivalent to *memset(0)*.

C

```
void Sft_InitText(LPSFT_TEXT lpText);
```

### Parameters

lpText

Pointer to a SFT_TEXT allocated by the application. Must not be NULL.

### Comments

Call once on each application-allocated SFT_TEXT before its first use. SFT_TEXT fields embedded in per-product control structures are initialized by the host control automatically and do not need a separate Sft_InitText call.

After Sft_InitText, the structure has zero in every field - which renders as no text, system font, default colors, GDI rendering. Populate *lpszText* (and optionally *hFont*, *colorFg*, *align*, *valign*) before passing the structure to a per-product API.

Sft_InitText does not release any resources stored in the structure - the application owns the string, font and brush handles and is responsible for releasing them when the SFT_TEXT (or the host control containing it) is no longer needed.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_TEXT | [Sft_InitPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_initpicture)

## Sft_IsPicture

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/function_ispicture*

Return TRUE if a [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) is non-empty (any picture type other than 0 has been assigned).

C

```
BOOL Sft_IsPicture(LPCSFT_PICTURE lpPicture);
```

### Parameters

lpPicture

Pointer to a SFT_PICTURE. NULL is accepted and returns FALSE.

### Return Value

TRUE if the slot is non-empty (the *type* field is non-zero), FALSE if the slot is empty or the pointer is NULL.

### Comments

Use Sft_IsPicture as a guard before calling code that requires a populated picture - for example, before reading any of the union members. For type-specific checks, use the [Sft_IsPicture* type-specific predicates](https://softelvdm.com/Documentation/SftPicture2/Topic/function_ispictureby_type).

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE | Sft_IsPicture* (type-specific)

## Sft_IsPicture* (type-specific)

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/function_ispictureby_type*

Type-specific predicates that return TRUE when a [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) holds a particular kind of picture. Use them to dispatch on picture type without switching on the *type* field directly.

C

```
BOOL Sft_IsPictureBitmap(LPCSFT_PICTURE lpPicture);
BOOL Sft_IsPictureIcon(LPCSFT_PICTURE lpPicture);
BOOL Sft_IsPictureIcon_32x32(LPCSFT_PICTURE lpPicture);
BOOL Sft_IsPictureIcon_16x16(LPCSFT_PICTURE lpPicture);
BOOL Sft_IsPictureImageList(LPCSFT_PICTURE lpPicture);
BOOL Sft_IsPictureImageListOvl(LPCSFT_PICTURE lpPicture);
BOOL Sft_IsPictureColorSample(LPCSFT_PICTURE lpPicture);
BOOL Sft_IsPictureIDispatch(LPCSFT_PICTURE lpPicture);
BOOL Sft_IsPictureIPicture(LPCSFT_PICTURE lpPicture);
BOOL Sft_IsPictureAnimate(LPCSFT_PICTURE lpPicture);
BOOL Sft_IsPictureDimension(LPCSFT_PICTURE lpPicture);
BOOL Sft_IsPictureCheckBox(LPCSFT_PICTURE lpPicture);
BOOL Sft_IsPictureCheckBox3(LPCSFT_PICTURE lpPicture);
BOOL Sft_IsPictureRadioButton(LPCSFT_PICTURE lpPicture);
BOOL Sft_IsPictureUpDown(LPCSFT_PICTURE lpPicture);
BOOL Sft_IsPictureUpDownSort(LPCSFT_PICTURE lpPicture);
BOOL Sft_IsPictureGDIPlusImage(LPCSFT_PICTURE lpPicture);
BOOL Sft_IsPictureNETImage(LPCSFT_PICTURE lpPicture);
```

### Parameters

lpPicture

Pointer to a SFT_PICTURE. NULL is accepted and returns FALSE for every predicate.

### Return Value

TRUE if the picture *type* matches the predicate, FALSE otherwise.

### Predicate / type mapping

| Predicate | Matches type |
| --- | --- |
| Sft_IsPictureBitmap | [SFT_PICTURE_BITMAP](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types), SFT_PICTURE_BITMAP_BL or SFT_PICTURE_BITMAP_NONE (any of the bitmap variants) |
| Sft_IsPictureIcon | SFT_PICTURE_ICON |
| Sft_IsPictureIcon_32x32 | SFT_PICTURE_ICON_32x32 (alias for SFT_PICTURE_ICON) |
| Sft_IsPictureIcon_16x16 | SFT_PICTURE_ICON_16x16 |
| Sft_IsPictureImageList | SFT_PICTURE_IMAGELIST |
| Sft_IsPictureImageListOvl | SFT_PICTURE_IMAGELISTOVL |
| Sft_IsPictureColorSample | SFT_PICTURE_COLOR_SAMPLE |
| Sft_IsPictureIDispatch | SFT_PICTURE_IDISPATCH |
| Sft_IsPictureIPicture | SFT_PICTURE_IPICTURE |
| Sft_IsPictureAnimate | SFT_PICTURE_AVI |
| Sft_IsPictureDimension | SFT_PICTURE_SIZEONLY |
| Sft_IsPictureCheckBox | SFT_PICTURE_CB |
| Sft_IsPictureCheckBox3 | SFT_PICTURE_CB3 |
| Sft_IsPictureRadioButton | SFT_PICTURE_RB |
| Sft_IsPictureUpDown | SFT_PICTURE_UPDOWN |
| Sft_IsPictureUpDownSort | SFT_PICTURE_UPDOWNSORT |
| Sft_IsPictureGDIPlusImage | SFT_PICTURE_GDIPLUS |
| Sft_IsPictureNETImage | SFT_PICTURE_NET |

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE | SFT_PICTURE_* | [Sft_IsPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_ispicture)

## Sft_SetPictureAnimate

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpictureanimate*

Store the HWND of a Microsoft Animation control playing an AVI clip in a [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) as a [SFT_PICTURE_AVI](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types) slot.

C

```
void Sft_SetPictureAnimate(LPSFT_PICTURE lpPicture, HWND hwndAnim);
```

### Parameters

lpPicture

Pointer to a SFT_PICTURE. Must not be NULL.

hwndAnim

HWND of a Microsoft Animation control (*ANIMATE_CLASS* from commctrl.h). NULL leaves the slot empty.

### Comments

Sft_SetPictureAnimate calls [Sft_ClearPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_clearpicture) internally before assigning the new animation HWND.

The animation control is created by the application using *Animate_Create* or by placing an Animate Control in a dialog template. The application loads the AVI clip (*Animate_Open*) and starts playback (*Animate_Play*); the host control simply paints the animation control inside the slot.

Per-product control fields (e.g. SFTBUTTON_CONTROL.fAVITransparent) often expose options that affect how the animation is composited - check the per-product help.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE | SFT_PICTURE_AVI | [Sft_IsPictureAnimate](https://softelvdm.com/Documentation/SftPicture2/Topic/function_ispictureby_type)

## Sft_SetPictureCheckBox

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpicturecheckbox*

*Also listed as: Sft_SetPictureCheckBox, Sft_SetPictureCheckBox3*

Store a check box glyph in a [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture). Two-state ([SFT_PICTURE_CB](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types)) and three-state (SFT_PICTURE_CB3) variants are provided.

C

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

### Parameters

lpPicture

Pointer to a SFT_PICTURE. Must not be NULL.

state

Glyph state.

|  |  |
| --- | --- |
| *Sft_SetPictureCheckBox* | 0 = unchecked, 1 = checked. |
| *Sft_SetPictureCheckBox3* | -1 = indeterminate, 0 = unchecked, 1 = checked. |

w, h

Width and height of the glyph in pixels. *h* must be greater than zero - calling with *h <= 0* clears the slot but does not assign a glyph.

fEnabled

TRUE for enabled appearance, FALSE for disabled (grayed) appearance.

### Comments

Both setters call [Sft_ClearPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_clearpicture) internally before assigning the new glyph. Internally each glyph is rendered through Windows themes when themes are active, falling back to the legacy GDI rendering when not.

Note: *Sft_SetPictureCheckBox* asserts that *state* is 0 or 1; *Sft_SetPictureCheckBox3* asserts that *state* is -1, 0 or 1. Out-of-range values trip the assertion in debug builds.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE | SFT_PICTURE_CB | [Sft_SetPictureRadioButton](https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpictureradiobutton) | [Sft_IsPictureCheckBox](https://softelvdm.com/Documentation/SftPicture2/Topic/function_ispictureby_type)

## Sft_SetPictureColorSample

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpicturecolorsample*

Store a solid color swatch with optional border in a [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) as a [SFT_PICTURE_COLOR_SAMPLE](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types) slot.

C

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

### Parameters

lpPicture

Pointer to a SFT_PICTURE. Must not be NULL.

w, h

Width and height of the color swatch in pixels. *h* must be greater than zero - calling with *h <= 0* clears the slot but does not assign a swatch.

sampleColor

The fill color of the swatch.

frameColor

Border color drawn around the swatch. Set to -1 (or [SFT_NOCOLOR](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_nocolor)) to draw no border.

### Comments

Sft_SetPictureColorSample calls [Sft_ClearPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_clearpicture) internally before assigning the new swatch.

Color samples are useful for color-picker controls, legend entries, and anywhere a small filled rectangle is more meaningful than a bitmap.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE | SFT_PICTURE_COLOR_SAMPLE | [Sft_IsPictureColorSample](https://softelvdm.com/Documentation/SftPicture2/Topic/function_ispictureby_type) | SFT_NOCOLOR

## Sft_SetPictureGDIPlusImage

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpicturegdiplusimage*

Store a *Gdiplus::Image** pointer in a [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) as a [SFT_PICTURE_GDIPLUS](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types) slot. GDI+ images cover PNG, TIFF, JPEG, GIF, EMF+ and any other format the Windows GDI+ runtime supports.

C

```
void Sft_SetPictureGDIPlusImage(LPSFT_PICTURE lpPicture, LPVOID lpImageObject);
```

### Parameters

lpPicture

Pointer to a SFT_PICTURE. Must not be NULL.

lpImageObject

A *Gdiplus::Image** pointer cast to *LPVOID*. NULL leaves the slot empty. The cast is required because the [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) header avoids a hard dependency on *gdiplus.h*.

### Comments

Sft_SetPictureGDIPlusImage calls [Sft_ClearPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_clearpicture) internally before assigning the new pointer.

Resource ownership: the application creates and owns the GDI+ Image object - typically through *new Gdiplus::Image(...)* or one of the per-product loader helpers (e.g. *SftButton_LoadGDIPlusImageFromFile*). Release the image with *delete* (or the matching loader-pair free) only after the host control no longer references it.

GDI+ must be initialized in the process before the image is created. The per-product loader helpers handle initialization automatically; applications that construct the *Gdiplus::Image* directly need to call *Gdiplus::GdiplusStartup* themselves.

See Also SftPicture2 | SFT_PICTURE | SFT_PICTURE_GDIPLUS | [Sft_IsPictureGDIPlusImage](https://softelvdm.com/Documentation/SftPicture2/Topic/function_ispictureby_type)

## Sft_SetPictureIcon

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpictureicon*

*Also listed as: Sft_SetPictureIcon, Sft_SetPictureIcon_16x16, Sft_SetPictureIcon_32x32*

Store an HICON in a [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) as one of the icon-bearing types ([SFT_PICTURE_ICON](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types), SFT_PICTURE_ICON_32x32 or SFT_PICTURE_ICON_16x16).

C

```
void Sft_SetPictureIcon(LPSFT_PICTURE lpPicture, HICON hIcon);
void Sft_SetPictureIcon_32x32(LPSFT_PICTURE lpPicture, HICON hIcon);
void Sft_SetPictureIcon_16x16(LPSFT_PICTURE lpPicture, HICON hIcon);
```

### Parameters

lpPicture

Pointer to a SFT_PICTURE. Must not be NULL.

hIcon

Icon handle. NULL leaves the slot empty (the existing picture is cleared).

### Comments

*Sft_SetPictureIcon* sets type SFT_PICTURE_ICON, which accepts an icon of any size. This is the recommended call for new code.

*Sft_SetPictureIcon_32x32* and *Sft_SetPictureIcon_16x16* are **discontinued** variants that set the SFT_PICTURE_ICON_32x32 (alias for SFT_PICTURE_ICON, value 1) and SFT_PICTURE_ICON_16x16 (value 33) types respectively. They exist for back-compatibility with applications written before SFT_PICTURE_ICON accepted any size. New code should use *Sft_SetPictureIcon* regardless of the icon's pixel dimensions.

Each setter calls [Sft_ClearPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_clearpicture) internally before assigning the new icon.

Resource ownership: the application owns the HICON and must keep it alive until the SFT_PICTURE is cleared or the host control is destroyed. Use *DestroyIcon* to release the icon when the application is done with it.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE | SFT_PICTURE_ICON | [Sft_IsPictureIcon](https://softelvdm.com/Documentation/SftPicture2/Topic/function_ispictureby_type)

## Sft_SetPictureIDispatch

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpictureidispatch*

Store an *IPictureDisp* pointer in a [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) as a [SFT_PICTURE_IDISPATCH](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types) slot. Used for OLE picture objects exposed through the IDispatch / IPictureDisp interface (the form returned by COM properties of type *OLE_PICTURE*).

C

```
void Sft_SetPictureIDispatch(LPSFT_PICTURE lpPicture, IPictureDisp* IPicDisp);
```

### Parameters

lpPicture

Pointer to a SFT_PICTURE. Must not be NULL.

IPicDisp

IPictureDisp pointer. NULL leaves the slot empty.

### Comments

Sft_SetPictureIDispatch calls [Sft_ClearPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_clearpicture) internally before assigning the new IPictureDisp pointer.

Reference counting: the SFT_PICTURE stores the raw pointer without calling *AddRef*. The application is responsible for ensuring the picture object outlives the SFT_PICTURE - typically by keeping its own reference and calling *Release* after the host control no longer needs the picture.

IPictureDisp wraps the same underlying picture types as [Sft_SetPictureIPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpictureipicture) (bitmaps, icons, metafiles); use whichever interface the picture-bearing COM source exposes.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE | SFT_PICTURE_IDISPATCH | Sft_SetPictureIPicture | [Sft_IsPictureIDispatch](https://softelvdm.com/Documentation/SftPicture2/Topic/function_ispictureby_type)

## Sft_SetPictureImageList

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpictureimagelist*

*Also listed as: Sft_SetPictureImageList, Sft_SetPictureImageListOvl*

Store an image-list reference in a [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) as a [SFT_PICTURE_IMAGELIST](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types) or SFT_PICTURE_IMAGELISTOVL (with overlay) slot.

C

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

void Sft_SetPictureImageListOvl(LPSFT_PICTURE lpPicture, HIMAGELIST hImageList,
                                short iImage, short iImageOverlay, short style);
```

### Parameters

lpPicture

Pointer to a SFT_PICTURE. Must not be NULL.

hImageList

Image list handle. NULL leaves the slot empty.

iImage

Index of the entry in *hImageList* drawn in the enabled state.

iImageDisabled

(*Sft_SetPictureImageList* only.) Index drawn in the disabled state. Set to -1 to reuse *iImage* - the system applies a generic graying effect at draw time.

iImageOverlay

(*Sft_SetPictureImageListOvl* only.) Index of the entry to draw as an overlay on top of *iImage*.

style

(*Sft_SetPictureImageListOvl* only.) Overlay style flags. Accepts [SFT_IMAGEOVL_GHOSTED](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_imageovl) for a semi-transparent overlay. Use 0 for a solid composite.

### Comments

Both setters call [Sft_ClearPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_clearpicture) internally before assigning the new image-list reference.

Resource ownership: the application owns the HIMAGELIST and must keep it alive until the SFT_PICTURE is cleared or the host control is destroyed. Image lists shared between multiple SFT_PICTURE instances must outlive the last consumer.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE | SFT_PICTURE_IMAGELIST | SFT_IMAGEOVL_GHOSTED | [Sft_IsPictureImageList](https://softelvdm.com/Documentation/SftPicture2/Topic/function_ispictureby_type)

## Sft_SetPictureIPicture

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpictureipicture*

Store an *IPicture* pointer in a [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) as a [SFT_PICTURE_IPICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types) slot. Used for OLE picture objects exposed through the IPicture interface (the form returned by *OleLoadPicture* / *OleCreatePictureIndirect*).

C

```
void Sft_SetPictureIPicture(LPSFT_PICTURE lpPicture, IPicture* IPic);
```

### Parameters

lpPicture

Pointer to a SFT_PICTURE. Must not be NULL.

IPic

IPicture pointer. NULL leaves the slot empty.

### Comments

Sft_SetPictureIPicture calls [Sft_ClearPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_clearpicture) internally before assigning the new IPicture pointer.

Reference counting: the SFT_PICTURE stores the raw pointer without calling *AddRef*. The application is responsible for ensuring the picture object outlives the SFT_PICTURE - typically by keeping its own reference and calling *Release* after the host control no longer needs the picture.

IPicture and [Sft_SetPictureIDispatch](https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpictureidispatch) (IPictureDisp) wrap the same underlying picture types (bitmaps, icons, metafiles); use whichever interface the picture-bearing COM source exposes.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE | SFT_PICTURE_IPICTURE | Sft_SetPictureIDispatch | [Sft_IsPictureIPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_ispictureby_type)

## Sft_SetPictureNETImage

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpicturenetimage*

Store an *IUnknown** pointer for a .NET image in a [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) as a [SFT_PICTURE_NET](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types) slot.

C

```
void Sft_SetPictureNETImage(LPSFT_PICTURE lpPicture, IUnknown* lpImageObject);
```

### Parameters

lpPicture

Pointer to a SFT_PICTURE. Must not be NULL.

lpImageObject

*IUnknown** for a .NET *System.Drawing.Image*, typically obtained from the .NET-side wrapper via *Marshal.GetIUnknownForObject* (or its product-specific equivalent). NULL leaves the slot empty.

### Comments

Sft_SetPictureNETImage calls [Sft_ClearPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_clearpicture) internally before assigning the new pointer.

Reference counting: the SFT_PICTURE stores the raw IUnknown pointer without calling *AddRef*. The .NET / managed code that supplied the IUnknown is responsible for ensuring the image outlives the SFT_PICTURE.

SFT_PICTURE_NET is intended for hosts that wrap a .NET interop layer around a Softel vdm DLL. The native side stores and renders the image; the .NET side manages the image's lifetime.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE | SFT_PICTURE_NET | [Sft_IsPictureNETImage](https://softelvdm.com/Documentation/SftPicture2/Topic/function_ispictureby_type)

## Sft_SetPictureRadioButton

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpictureradiobutton*

Store a radio button glyph in a [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) as a [SFT_PICTURE_RB](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types) slot.

C

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

### Parameters

lpPicture

Pointer to a SFT_PICTURE. Must not be NULL.

state

0 = cleared, 1 = selected. The implementation also stores the value verbatim, so -1 (indeterminate) is accepted but renders the same as cleared.

w, h

Width and height of the glyph in pixels. *h* must be greater than zero - calling with *h <= 0* clears the slot but does not assign a glyph.

fEnabled

TRUE for enabled appearance, FALSE for disabled (grayed) appearance.

### Comments

Sft_SetPictureRadioButton calls [Sft_ClearPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_clearpicture) internally before assigning the new glyph. The radio button is rendered through Windows themes when themes are active, falling back to the legacy GDI rendering when not.

The function asserts that *state* is 0 or 1 in debug builds.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE | SFT_PICTURE_RB | [Sft_SetPictureCheckBox](https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpicturecheckbox) | [Sft_IsPictureRadioButton](https://softelvdm.com/Documentation/SftPicture2/Topic/function_ispictureby_type)

## Sft_SetPictureSizeOnly

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpicturesizeonly*

Store a layout placeholder of fixed dimensions in a [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) as a [SFT_PICTURE_SIZEONLY](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types) slot. The slot reserves space but draws nothing.

C

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

### Parameters

lpPicture

Pointer to a SFT_PICTURE. Must not be NULL.

w, h

Width and height of the placeholder in pixels. *h* must be greater than zero - calling with *h <= 0* clears the slot but does not assign a placeholder.

### Comments

Sft_SetPictureSizeOnly calls [Sft_ClearPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_clearpicture) internally before assigning the new placeholder.

Useful when an image is going to be supplied later (e.g. loaded asynchronously) and the layout needs to reserve the space, or when the slot must match a sibling control's size for visual alignment.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE | SFT_PICTURE_SIZEONLY | [Sft_IsPictureDimension](https://softelvdm.com/Documentation/SftPicture2/Topic/function_ispictureby_type)

## Sft_SetPictureUpDown

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/function_setpictureupdown*

*Also listed as: Sft_SetPictureUpDown, Sft_SetPictureUpDownSort*

Store an up / down arrow glyph ([SFT_PICTURE_UPDOWN](https://softelvdm.com/Documentation/SftPicture2/Topic/def_sft_picture_types)) or a sort-direction indicator (SFT_PICTURE_UPDOWNSORT) in a [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture).

C

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

### Parameters

lpPicture

Pointer to a SFT_PICTURE. Must not be NULL.

fUp

TRUE for up arrow / ascending, FALSE for down arrow / descending.

w, h

Width and height of the glyph in pixels. *h* must be greater than zero - calling with *h <= 0* clears the slot but does not assign a glyph.

fEnabled

TRUE for enabled appearance, FALSE for disabled (grayed) appearance. *Sft_SetPictureUpDownSort* accepts the parameter for signature parity with the other glyph setters but ignores it visually - sort indicators do not have a disabled state.

### Comments

Both setters call [Sft_ClearPicture](https://softelvdm.com/Documentation/SftPicture2/Topic/function_clearpicture) internally before assigning the new glyph.

*Sft_SetPictureUpDown* produces a generic up / down arrow useful for spinner controls and similar adjustable values. *Sft_SetPictureUpDownSort* produces a sort-direction triangle (typically thicker / smaller) used in column headers to indicate the active sort column and direction.

See Also [SftPicture2](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main) | SFT_PICTURE | SFT_PICTURE_UPDOWN | SFT_PICTURE_UPDOWNSORT | [Sft_IsPictureUpDown](https://softelvdm.com/Documentation/SftPicture2/Topic/function_ispictureby_type)

## SFTPICTURE_VERSION

*Source: https://softelvdm.com/Documentation/SftPicture2/Topic/def_sftpicture_version*

Version constant identifying the major revision of *[SftPicture2.h](https://softelvdm.com/Documentation/SftPicture2/Topic/1_main)*.

```
#define SFTPICTURE_VERSION 2
```

SFTPICTURE_VERSION expands to **2** for the current header (the "2" in *SftPicture2.h* is the same number). Compile-time guards in product code that need to detect the header revision can use the symbol directly.

See Also SftPicture2