SftButton/DLL 3.0 - Button Control

SFTBUTTON_CONTROL Structure

SFTBUTTON_CONTROL holds the complete state of a SftButton control - its colors, images, text, border, theme and behavior - in a single structure. Applications populate a SFTBUTTON_CONTROL and pass it to SetControlInfo to configure the button, and call GetControlInfo to retrieve the current state.

Recommended pattern: call GetControlInfo to fill a local SFTBUTTON_CONTROL with the current state, modify only the fields you care about, and call SetControlInfo to write the changes back. Constructing a SFTBUTTON_CONTROL from scratch with memset / zeroing is also valid - all default values are zero or SFTBUTTON_NOCOLOR.

C

typedef struct tagSftButtonControl {

    int cbSize;                          // sizeof(SFTBUTTON_CONTROL)

    /* outer background (drawn outside the button rectangle) */
    COLORREF colorBgOutside;

    /* main button colors */
    COLORREF colorBg;                    // background fill
    COLORREF colorBgPressed;             // background when pressed
    COLORREF colorFg;                    // text color
    COLORREF colorFgDownArrow;           // dropdown arrow color
    COLORREF colorFgPressed;             // text color when pressed
    COLORREF colorFgGrayed;              // text color when disabled
    COLORREF colorDarkEdge;              // 3D edge - dark
    COLORREF colorLightEdge;             // 3D edge - light
    COLORREF colorShadowEdge;            // 3D edge - shadow
    COLORREF colorWhiteEdge;             // 3D edge - white

    /* foreground images and text (drawn over the background) */
    SFT_PICTURE Picture1;
    SFT_PICTURE Picture2;
    SFT_TEXT    Text;

    /* behavior flags */
    BOOL fToggle;                        // act as a check box
    BOOL fDropDownToggle;                // dropdown arrow is a toggle
    BOOL fFollows;                       // dropdown press follows main press
    BOOL fDropDownFollows;               // main press follows dropdown press
    BOOL fPressed;                       // toggle state
    BOOL fDropDownPressed;               // dropdown toggle state

    BOOL fBorderAlways;                  // always draw the border
    int  nBorderStyle;                   // SFTBUTTON_BORDER_*

    BOOL fShowDropDown;                  // show a dropdown sidebar
    BOOL fDropDownDownClick;             // generate dropdown click on press
    BOOL fAllowFocus;                    // accept keyboard focus
    BOOL fDefault;                       // is the dialog default button
    BOOL fAVITransparent;                // AVI background is transparent

    int  nUseThemes;                     // SFTBUTTON_THEME_*
    BOOL fHideDefault;                   // hide the default-button outline

    long nCustomCode;                    // application-defined value
    long clickInterval;                  // auto-repeat interval (ms)

    /* gradient and per-state background colors */
    COLORREF colorBgStart, colorBgEnd;   // gradient endpoints
    COLORREF colorBgFocus, colorBgFocusStart, colorBgFocusEnd; // focus state
    COLORREF colorBgHover, colorBgHoverStart, colorBgHoverEnd; // hover state
    BOOL     fHideFocus;                 // suppress the focus rectangle
    int      nFillOrientation;           // SFT_ORIENTATION_HORZ / SFT_ORIENTATION_VERT
    int      nDropDownStyle;             // SFTBUTTON_DROPDOWNSTYLE_*

    HWND hwndNotifyWindow;               // alternate notification target
    int  hwndNotifyID;                   // alternate notification id

    int  iHoverStyle;                    // SFTBUTTON_HOVERSTYLE_*
    BOOL fNoBackground;                  // do not draw a background
    int  iClickStyle;                    // SFTBUTTON_CLICKSTYLE_*
    int  iAutoSize;                      // SFTBUTTON_AUTOSIZE_*
    int  iBounce;                        // SFTBUTTON_BOUNCE_*

    int  nDarkMode;                      // SFTBUTTON_DARKMODE_*
    int  nHighContrastMode;              // SFTBUTTON_HIGHCONTRAST_*

    int  imageScaling;                   // SFTBUTTON_IMAGESCALING_*
    int  pixelScaling;                   // SFTBUTTON_PIXELSCALING_*

    /* per-state foreground pictures (fall back to base when empty) */
    SFT_PICTURE Picture1Hover, Picture2Hover;
    SFT_PICTURE Picture1Pressed, Picture2Pressed;
    SFT_PICTURE Picture1Disabled, Picture2Disabled;

    /* per-state background pictures (fall back to PictureBG when empty) */
    SFT_PICTURE PictureBG;
    SFT_PICTURE PictureBGHover;
    SFT_PICTURE PictureBGPressed;
    SFT_PICTURE PictureBGDisabled;

    /* read-only - layout */
    RECT rectDropDown;                   // dropdown sidebar rectangle
    RECT rectButton;                     // main button rectangle

    /* read-only - last error from SetControlInfo */
    int errorValue;                      // SFTBUTTON_ERR_*

    /* read-only - resolved state */
    BOOL fDarkModeActive;                // dark mode is currently in effect
    BOOL fHighContrastActive;            // high contrast is currently in effect
    BOOL fHoverOn;                       // mouse is hovering over the control
    BOOL fHoverOnPic1;                   // hovering specifically over Picture1
    BOOL fHoverOnPic2;                   // hovering specifically over Picture2
    BOOL fHoverOnText;                   // hovering specifically over the text

} SFTBUTTON_CONTROL, * LPSFTBUTTON_CONTROL;

typedef const SFTBUTTON_CONTROL * LPCSFTBUTTON_CONTROL;

Identity

cbSize

Size of the structure in bytes. Set to sizeof(SFTBUTTON_CONTROL) before calling GetControlInfo or SetControlInfo. Used by the control to verify the caller's binary compatibility with the DLL build.

Colors

Color fields are COLORREF values. Any field can be set to SFTBUTTON_NOCOLOR to mean "use the system / theme / palette default" - the control then chooses an appropriate color for the current rendering mode (light, dark, or high-contrast).

colorBgOutside

Background color for the area surrounding the button rectangle (visible when the button is smaller than its window).

colorBg, colorBgStart, colorBgEnd

Background fill in the normal state. colorBg is the solid fill. colorBgStart / colorBgEnd, when both are valid colors, draw a gradient instead. nFillOrientation selects horizontal or vertical gradient direction.

colorBgFocus, colorBgFocusStart, colorBgFocusEnd

Background fill in the focus state (button has keyboard focus and is not pressed or hovered).

colorBgHover, colorBgHoverStart, colorBgHoverEnd

Background fill in the hover state.

colorBgPressed

Background fill when the button is pressed.

colorFg, colorFgPressed, colorFgGrayed, colorFgDownArrow

Text color (per state) and dropdown-arrow color.

colorDarkEdge, colorLightEdge, colorShadowEdge, colorWhiteEdge

Per-edge 3D border colors used when nBorderStyle is SFTBUTTON_BORDER_STANDARD.

Images

Twelve SFT_PICTURE fields cover two foreground image layers and a background image layer, each with four states (normal, hover, pressed, disabled). See Button Images for the picture model and the layer order.

Picture1, Picture1Hover, Picture1Pressed, Picture1Disabled

Foreground image layer 1, per state. If a per-state field is empty, the control falls back to Picture1.

Picture2, Picture2Hover, Picture2Pressed, Picture2Disabled

Foreground image layer 2, drawn on top of layer 1.

PictureBG, PictureBGHover, PictureBGPressed, PictureBGDisabled

Background pictures, drawn over the background fill, under the foreground image layers.

Text

Button text is held in a single SFT_TEXT field with its own color, font and alignment. See Text and Fonts.

Text

Text content, font and alignment. The text color comes from colorFg (or colorFgPressed / colorFgGrayed per state) - SFT_TEXT.colorFg is honored as an override.

Behavior flags

fToggle, fPressed

fToggle = TRUE makes the button a two-state check-box style button; the current state is held in fPressed. See Toggle (Check Box) Behavior.

fDropDownToggle, fDropDownPressed

Toggle behavior for the dropdown sidebar.

fFollows, fDropDownFollows

When TRUE, pressing the main button also visually presses the dropdown (or vice versa). See Dropdown Button.

fShowDropDown, nDropDownStyle, fDropDownDownClick

Dropdown sidebar visibility, style and click behavior. See SFTBUTTON_DROPDOWNSTYLE.

fAllowFocus, fHideFocus, fDefault, fHideDefault

Keyboard focus participation, focus rectangle visibility, dialog default-button status, and default-button outline visibility.

fAVITransparent

For SFT_PICTURE_AVI pictures: TRUE if the AVI's background should be made transparent.

fNoBackground

Disables background drawing entirely. Useful when the button is layered over an application-supplied background that should show through.

fBorderAlways, nBorderStyle

Border drawing. fBorderAlways forces the border to draw in every state (otherwise it appears only in pressed / hover / focus states). See SFTBUTTON_BORDER.

nUseThemes

Theme participation. See SFTBUTTON_THEME and Using Themes. Themes are automatically suppressed when dark mode or high contrast is active.

nDarkMode

Dark mode setting. See SFTBUTTON_DARKMODE and Dark Mode. SetDarkMode is the recommended way to change this field at runtime - it raises SFTBUTTONN_DARKMODE_CHANGED and re-renders the control.

nHighContrastMode

High contrast setting. See SFTBUTTON_HIGHCONTRAST and High Contrast. SetHighContrastMode is the recommended way to change this field at runtime.

imageScaling

Selects whether caller-supplied images (Picture1, Picture2 and per-state / background variants) are drawn at native pixel size (ASIS) or scaled by currentDPI / 96 (STRETCH, default). See SFTBUTTON_IMAGESCALING and Per-Monitor DPI and Scaling. SetImageScaling is the recommended way to change this field at runtime.

pixelScaling

Selects whether caller-supplied pixel dimensions on this structure are used verbatim (ASIS) or interpreted as 96-DPI reference values and scaled at render time (STRETCH, default). See SFTBUTTON_PIXELSCALING and Per-Monitor DPI and Scaling. SetPixelScaling is the recommended way to change this field at runtime.

iHoverStyle, iClickStyle, iAutoSize, iBounce

Hover detection style, click region behavior, auto-size anchoring, and press animation. See SFTBUTTON_HOVERSTYLE, SFTBUTTON_CLICKSTYLE, SFTBUTTON_AUTOSIZE, SFTBUTTON_BOUNCE.

nFillOrientation

Direction of the background gradient. SFT_ORIENTATION_HORZ (left to right) or SFT_ORIENTATION_VERT (top to bottom, default). See Colors and Gradients.

clickInterval

Auto-repeat interval in milliseconds for the press-and-hold action. Zero disables auto-repeat.

nCustomCode

Application-defined integer value. The control does not interpret this field; it is supplied for callers that need to attach an arbitrary tag to a button.

hwndNotifyWindow, hwndNotifyID

When hwndNotifyWindow is non-NULL, button notifications are sent to that window with control id hwndNotifyID instead of to the button's parent window. Useful for owner-draw frameworks that need to intercept notifications above the immediate parent.

Read-only fields

rectDropDown, rectButton

The dropdown sidebar and main-button rectangles in client coordinates. Refreshed on every layout pass.

errorValue

Set by SetControlInfo when an out-of-range field is supplied. See SFTBUTTON_ERR.

fDarkModeActive

TRUE when the button is currently rendering with the dark palette. The same value is returned by IsDarkModeActive.

fHighContrastActive

TRUE when the button is currently rendering with the system high-contrast palette. The same value is returned by IsHighContrastActive.

fHoverOn, fHoverOnPic1, fHoverOnPic2, fHoverOnText

Resolved hover state. fHoverOn is TRUE whenever the mouse is over the button; the fHoverOnPic1 / fHoverOnPic2 / fHoverOnText flags are TRUE only when the mouse is over the corresponding region (used with SFTBUTTON_HOVERSTYLE_EXACT).

Pointer typedefs

typedef SFTBUTTON_CONTROL       *LPSFTBUTTON_CONTROL;
typedef const SFTBUTTON_CONTROL *LPCSFTBUTTON_CONTROL;

LPSFTBUTTON_CONTROL is passed to GetControlInfo (the control writes its current state into the structure). LPCSFTBUTTON_CONTROL is passed to SetControlInfo (the control reads and copies values from the structure; it does not keep the pointer).

Examples

C

        SendMessage(hwndDlg, WM_SETICON, ICON_BIG, (LPARAM)LoadIcon(g_hInst, MAKEINTRESOURCE(IDI_ICON1)));
        SendMessage(hwndDlg, WM_SETICON, ICON_SMALL, (LPARAM)LoadIcon(g_hInst, MAKEINTRESOURCE(IDI_ICON1)));

        // Apply dark mode to dialog
        SftDarkMode_ApplyToDialog(hwndDlg);

        // Configure SftButton control 1
        {
            SFTBUTTON_CONTROL Ctl;
            Ctl.cbSize = sizeof(SFTBUTTON_CONTROL);
            SftButton_GetControlInfo(hwndButton1, &Ctl);
            Ctl.nDarkMode = SFTBUTTON_DARKMODE_AUTO;/* automatic dark mode support */
            SftButton_SetControlInfo(hwndButton1, &Ctl);
        }

        // Configure SftButton control 2

View Entire Sample Code

See Also GetControlInfo | SetControlInfo | SFTBUTTON_NOCOLOR | Dark Mode | High Contrast