SftPicture2 Documentation

SFT_TEXT Structure

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 (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 (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 (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_* 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 (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 | SFT_PICTURE | SFT_PICALIGN_* | SFT_ORIENTATION_* | SFT_NOCOLOR | SFT_TEXT_* | Sft_InitText