HeaderPane
Main
Hide
Share Link
Print

SFTBOX_CONTROL Structure

The SFTBOX_CONTROL structure is used with GetControlInfo and SetControlInfo to retrieve and set a combo box control's attributes.

typedef struct tagSftBoxControl {

    int cbSize;                             // structure size

    /* Modifiable fields */
    BOOL fDesign;                           // design time
    BOOL fAllowNextRollup;                  // if set to FALSE, the next rollup is suppressed (based on mouse click)
    BOOL fAutoDropOnFocus;                  // auto drop on focus
    BOOL fAutoDropOnInput;                  // auto drop on input in edit control
    BOOL fCursorSelect;                     // selection follows cursor (dropdown/dropdown list)
    BOOL fStaticAligned;                    // static portion aligned with same item in dropdown portion
    BOOL fSelectEnabledItemsOnly;           // only enabled items are selectable
    BOOL fHeaderColorsOverrideTheme;        // true if header colors override windows theme colors
    BOOL fGridHorizontalFull;               // full width horizontal lines (when grid lines enabled)

    int iBorderStyle;                       // border style
#define SFTBOX_BORDER_NONE       0
#define SFTBOX_BORDER_FLAT       1
#define SFTBOX_BORDER_CLIENT     2
    int iMouseOverTransitionEffect;         // expand/collapse button transition effect when the mouse enters/leaves the combo box control
#define SFTBOX_TRANSITION_NONE                     0
#define SFTBOX_TRANSITION_THEMEDVISTAONLY_NOFOCUS  1
#define SFTBOX_TRANSITION_THEMEDVISTAONLY          2
#define SFTBOX_TRANSITION_ALWAYS_NOFOCUS           3
#define SFTBOX_TRANSITION_ALWAYS                   4

    SFTBOX_DWORD_PTR controlData;           // application-defined value

    BOOL fAllowNextRolldown;                // if set to FALSE, the next rolldown is suppressed (based on mouse click)

    int nDarkMode;                          // dark mode setting (SFTBOX_DARKMODE_OFF/ON/AUTO)
#define SFTBOX_DARKMODE_OFF             0           /* Always light (default) */
#define SFTBOX_DARKMODE_ON              1           /* Always dark */
#define SFTBOX_DARKMODE_AUTO            2           /* Follow Windows setting */

    int nHighContrastMode;                  // high contrast setting (SFTBOX_HIGHCONTRAST_OFF/ON/AUTO)
#define SFTBOX_HIGHCONTRAST_OFF         0           /* Ignore Windows high contrast, render normally (default) */
#define SFTBOX_HIGHCONTRAST_ON          1           /* Always use the system colors */
#define SFTBOX_HIGHCONTRAST_AUTO        2           /* Follow Windows setting */

    int imageScaling;                       // image DPI scaling (SFTBOX_IMAGESCALING_ASIS/STRETCH)
#define SFTBOX_IMAGESCALING_ASIS        0           /* draw every image at native pixel size (default) */
#define SFTBOX_IMAGESCALING_STRETCH     1           /* scale every image by the monitor DPI / 96 */

    int pixelScaling;                       // pixel dimension DPI scaling (SFTBOX_PIXELSCALING_ASIS/STRETCH)
#define SFTBOX_PIXELSCALING_ASIS        0           /* pixel values used as set (default) */
#define SFTBOX_PIXELSCALING_STRETCH     1           /* pixel values scaled by the monitor DPI / 96 */

    /* read/only fields */

    int errorValue;                         // error value set by SetControlInfo
#define SFTBOX_ERR_iBorderStyle                100
#define SFTBOX_ERR_iMouseOverTransitionEffect  101
#define SFTBOX_ERR_nDarkMode                   102
#define SFTBOX_ERR_nHighContrastMode           103
#define SFTBOX_ERR_imageScaling                104
#define SFTBOX_ERR_pixelScaling                105

    BOOL fDarkModeActive;                   // resolved dark mode state (read-only)
    BOOL fHighContrastActive;               // resolved high contrast state (read-only)

} SFTBOX_CONTROL, * LPSFTBOX_CONTROL;

typedef const SFTBOX_CONTROL * LPCSFTBOX_CONTROL;

Members

cbSize

This member must be set to the SFTBOX_CONTROL structure size (sizeof(SFTBOX_CONTROL)) before calling GetControlInfo and SetControlInfo, otherwise the call fails.

fDesign

Reserved for design tools. When set to TRUE, the combo box control is rendered as it appears at design time. Applications should not modify this member.

fAllowNextRollup

Defines whether the mouse click that is currently being processed can close the dropdown portion. The combo box control sets this member to TRUE at the start of each mouse click in the static portion or the dropdown portion. Clicking an item in the dropdown portion normally closes the dropdown portion when the mouse button is released. Certain mouse clicks in the static portion (for example on the item picture or a cell) also close the dropdown portion if it is currently dropped down. An application can set fAllowNextRollup to FALSE using SetControlInfo while processing the mouse click notification (for example SFTBOXN_LBUTTONDOWN_TEXT), so the dropdown portion remains visible. The setting applies to the current mouse click only.

The combo box control automatically suppresses closing the dropdown portion for mouse clicks on tree lines, expand/collapse buttons, plus/minus pictures, column headers and the row/column header, when columns are resized or reordered, when a context menu is requested and, if fSelectEnabledItemsOnly is TRUE, for clicks on disabled items. The ShowDropDown function always closes the dropdown portion.

fAutoDropOnFocus

Defines whether the dropdown portion is automatically dropped down when the combo box control receives the input focus. Set to TRUE so the dropdown portion is shown as soon as the combo box control receives the input focus from another window, otherwise FALSE. The default is FALSE. This value can be modified using SetControlInfo.

fAutoDropOnInput

Defines whether the dropdown portion is automatically dropped down when the user types a character. Set to TRUE so the dropdown portion is shown as soon as a character is typed while the combo box control has the input focus, otherwise FALSE. The default is FALSE. This value can be modified using SetControlInfo.

fCursorSelect

Defines whether the selection follows the mouse cursor in the dropdown portion of a dropdown or dropdown list combo box. If TRUE, the item under the mouse cursor is selected as the mouse cursor moves over the dropdown portion. This selection is temporary until the user accepts it. If fSelectEnabledItemsOnly is TRUE, disabled items are not selected this way. If FALSE, moving the mouse cursor does not change the selection. A simple combo box ignores this setting. The default is TRUE. This value can be modified using SetControlInfo.

fStaticAligned

Defines how the selected item is shown in the static portion of a dropdown list combo box. If TRUE, the item is displayed in the static portion at the same level as in the dropdown portion, using the same indentation and tree lines (see SetTreeLineStyle). If FALSE, the item is displayed as a level 0 item, without tree lines. The default is TRUE. This value can be modified using SetControlInfo.

fSelectEnabledItemsOnly

Defines whether only enabled items (see SetItemStatus) can be selected by the end-user. Set to TRUE so only enabled items can be selected by the end-user, otherwise FALSE. If TRUE, clicking a disabled item in the dropdown portion does not close the dropdown portion, and the FindString and SelectString families of functions skip disabled items. The default is FALSE. This value can be modified using SetControlInfo.

An application can always select an item (see SetCurSel), regardless of the setting of fSelectEnabledItemsOnly. GetCurSel may therefore return a disabled item. The GetItemStatus function can be used to test whether an item is enabled.

fHeaderColorsOverrideTheme

Defines whether the row/column header colors override Windows themes. Set to TRUE to render the row/column header using the colors defined using SetCtlColors (SFTBOX_COLORS, colorRowColHdrBg, colorRowColHdrDarkEdge, colorRowColHdrLightEdge) instead of Windows themes, otherwise set to FALSE. If all of these colors are set to their default value (SFTBOX_NOCOLOR), Windows themes are used. The setting applies to the static portion and the dropdown portion. This value can be modified using SetControlInfo.

fGridHorizontalFull

Defines whether horizontal grid lines extend into the empty area next to the last column. An empty area is only available if the last column is not an open-ended column (see SetOpenEnded). Set to TRUE so grid lines extend into the empty area next to the last column, otherwise FALSE. The default is FALSE. This value can be modified using SetControlInfo.

iBorderStyle

Defines the border drawn around the combo box control. In a simple combo box, the border is drawn around the edit control portion and around the item list. One value of the following table can be assigned to the iBorderStyle member.

iBorderStyleBorder
SFTBOX_BORDER_NONEThe combo box control has no border.
SFTBOX_BORDER_FLATThe combo box control has a flat border. If Windows themes are used (see SetUseThemes), the border is drawn using the current Windows theme.
SFTBOX_BORDER_CLIENTThe combo box control has a sunken, three-dimensional border. If Windows themes are used (see SetUseThemes), the border is drawn using the current Windows theme.

The initial value is derived from the window styles used when the combo box control is created: SFTBOX_BORDER_CLIENT if the extended window style WS_EX_CLIENTEDGE is used, SFTBOX_BORDER_FLAT if the window style WS_BORDER is used (without WS_EX_CLIENTEDGE), otherwise SFTBOX_BORDER_NONE. This value can be modified using SetControlInfo, which updates the layout of the combo box control and redraws it.

iMouseOverTransitionEffect

Defines whether transition effects for expand/collapse buttons and tree lines are used when the mouse enters/leaves the combo box control. Expand/collapse buttons and tree lines must be suitably defined to be visible (using SetShowButtons, SetShowButton0 and SetTreeLineStyle), otherwise this setting has no effect. A gradual, visual transition is used to show/hide the expand/collapse buttons and tree lines. GDI+ support is required for transition effects.

One value of the following table can be assigned to the iMouseOverTransitionEffect member.

iMouseOverTransitionEffectTransition effect
SFTBOX_TRANSITION_NONENo transition effects are used.
SFTBOX_TRANSITION_THEMEDVISTAONLY_NOFOCUSTransition effects are used only when Windows themes are used. When the combo box control does not have the input focus and the mouse cursor enters the combo box control area, the expand/collapse buttons and tree lines become visible. When the mouse cursor leaves the combo box control area, they are hidden. This is the default.
SFTBOX_TRANSITION_THEMEDVISTAONLYTransition effects are used only when Windows themes are used. When the mouse cursor enters the combo box control area, the expand/collapse buttons and tree lines become visible. When the mouse cursor leaves the combo box control area, they are hidden.
SFTBOX_TRANSITION_ALWAYS_NOFOCUSTransition effects are used with or without Windows themes. When the combo box control does not have the input focus and the mouse cursor enters the combo box control area, the expand/collapse buttons and tree lines become visible. When the mouse cursor leaves the combo box control area, they are hidden.
SFTBOX_TRANSITION_ALWAYSTransition effects are used with or without Windows themes. When the mouse cursor enters the combo box control area, the expand/collapse buttons and tree lines become visible. When the mouse cursor leaves the combo box control area, they are hidden.

This value can be modified using SetControlInfo.

controlData

An application-defined value. The combo box control stores this value, but does not use it. This value can be modified using SetControlInfo.

fAllowNextRolldown

Defines whether the mouse click that is currently being processed can drop down the dropdown portion. The combo box control sets this member to TRUE when a mouse click in the static portion is reported. Certain mouse clicks in the static portion (for example on the item picture, the label or a cell) drop down the dropdown portion if it is not currently dropped down. An application can set fAllowNextRolldown to FALSE using SetControlInfo while processing the mouse click notification of the static portion, so the dropdown portion is not shown. The setting applies to the current mouse click only.

nDarkMode

The dark mode setting of the combo box control, one of the values SFTBOX_DARKMODE_OFF, SFTBOX_DARKMODE_ON or SFTBOX_DARKMODE_AUTO. Modifying this value using SetControlInfo has the same effect as calling SetDarkMode.

nHighContrastMode

The high contrast setting of the combo box control, one of the values SFTBOX_HIGHCONTRAST_OFF, SFTBOX_HIGHCONTRAST_ON or SFTBOX_HIGHCONTRAST_AUTO. While high contrast is active, colors set by the application are ignored and the system colors of the user's contrast theme are used. High contrast takes precedence over dark mode. Modifying this value using SetControlInfo has the same effect as calling SetHighContrastMode.

imageScaling

The image scaling setting, SFTBOX_IMAGESCALING_ASIS or SFTBOX_IMAGESCALING_STRETCH. Image scaling governs every image the combo box control draws (item, cell, label, header and dropdown button pictures, expand/collapse buttons and glyphs). Modifying this value using SetControlInfo has the same effect as calling SetImageScaling.

pixelScaling

The pixel scaling setting, SFTBOX_PIXELSCALING_ASIS or SFTBOX_PIXELSCALING_STRETCH. Pixel scaling governs pixel dimensions set by the application (column widths, indentation, row header width, horizontal extent, item height minimum/maximum, dropdown width and height in pixels). Modifying this value using SetControlInfo has the same effect as calling SetPixelScaling.

errorValue

Read/only. GetControlInfo sets this member to 0. If the SetControlInfo function fails because a structure member contains an invalid value, the errorValue member contains an error code, indicating which structure member has caused the failure:

errorValueInvalid SFTBOX_CONTROL structure member
SFTBOX_ERR_iBorderStyleiBorderStyle
SFTBOX_ERR_iMouseOverTransitionEffectiMouseOverTransitionEffect
SFTBOX_ERR_nDarkModenDarkMode
SFTBOX_ERR_nHighContrastModenHighContrastMode
SFTBOX_ERR_imageScalingimageScaling
SFTBOX_ERR_pixelScalingpixelScaling

fDarkModeActive

Read/only. TRUE if the combo box control is currently rendered using dark mode, otherwise FALSE (see IsDarkModeActive). SetControlInfo ignores this member.

fHighContrastActive

Read/only. TRUE if the combo box control is currently rendered using high contrast colors, otherwise FALSE (see IsHighContrastActive). SetControlInfo ignores this member. h1 Comments

The SFTBOX_CONTROL structure is used with GetControlInfo and SetControlInfo to retrieve and set combo box control attributes.

The structure contains additional reserved members, which are not shown above. To modify an attribute, an application retrieves the current settings using GetControlInfo, modifies the desired members and calls SetControlInfo. This ensures that all other members, including reserved members, contain valid values.

SFTBOX_CONTROL Ctl;
Ctl.cbSize = sizeof(SFTBOX_CONTROL);
if (SftBox_GetControlInfo(hwndCtl, &Ctl)) {
    Ctl.fAutoDropOnInput = TRUE;
    Ctl.fCursorSelect = FALSE;
    SftBox_SetControlInfo(hwndCtl, &Ctl);
}

Pointer typedefs: LPSFTBOX_CONTROL is a pointer to a SFTBOX_CONTROL structure, LPCSFTBOX_CONTROL is a pointer to a constant SFTBOX_CONTROL structure.

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


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