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;This member must be set to the SFTBOX_CONTROL structure size (sizeof(SFTBOX_CONTROL)) before calling GetControlInfo and SetControlInfo, otherwise the call fails.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
| iBorderStyle | Border |
|---|---|
| SFTBOX_BORDER_NONE | The combo box control has no border. |
| SFTBOX_BORDER_FLAT | The 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_CLIENT | The 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.
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.
| iMouseOverTransitionEffect | Transition effect |
|---|---|
| SFTBOX_TRANSITION_NONE | No transition effects are used. |
| SFTBOX_TRANSITION_THEMEDVISTAONLY_NOFOCUS | Transition 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_THEMEDVISTAONLY | Transition 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_NOFOCUS | Transition 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_ALWAYS | Transition 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.
An application-defined value. The combo box control stores this value, but does not use it. This value can be modified using SetControlInfo.
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.
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.
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.
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.
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.
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:
| errorValue | Invalid SFTBOX_CONTROL structure member |
|---|---|
| SFTBOX_ERR_iBorderStyle | iBorderStyle |
| SFTBOX_ERR_iMouseOverTransitionEffect | iMouseOverTransitionEffect |
| SFTBOX_ERR_nDarkMode | nDarkMode |
| SFTBOX_ERR_nHighContrastMode | nHighContrastMode |
| SFTBOX_ERR_imageScaling | imageScaling |
| SFTBOX_ERR_pixelScaling | pixelScaling |
Read/only. TRUE if the combo box control is currently rendered using dark mode, otherwise FALSE (see IsDarkModeActive). SetControlInfo ignores this member.
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