SFTMASK_CONTROL Structure
SFTMASK_CONTROL holds the complete state of a SftMask control - its edit mask, behavior flags, caption, label, calendar, calculator, autocomplete settings and colors - in a single structure. Applications call GetControlInfo to retrieve the current state, modify the desired fields and pass the structure to SetControlInfo to configure the control.
Recommended pattern: call GetControlInfo to fill a local SFTMASK_CONTROL with the current state, modify only the fields you care about, and call SetControlInfo to write the changes back. Always set cbSize to sizeof(SFTMASK_CONTROL) first.
String pointers returned by GetControlInfo point to control-internal storage and must not be modified or freed. When calling SetControlInfo, all strings are copied by the control, so the application's buffers can be discarded after the call.
Reserved fields (fill*/res*) are omitted from the listing below; they must not be modified.
C
typedef struct tagSftMaskControl {
int cbSize; // sizeof(SFTMASK_CONTROL)
/* behavior flags */
BOOL fAllowEmpty; // empty is valid (with defined mask)
BOOL fAutoAdvance; // autoadvance if full/valid
BOOL fAutoSize; // autosize to contents
BOOL fAutoTab; // autotab if valid
BOOL fHideSelection; // hidden selection (w/o focus)
BOOL fHotTrack; // hover
BOOL fInsert; // insert mode
BOOL fLocked; // locked for input
BOOL fPadding; // padding date/time
BOOL fPromptUnderline;
BOOL fPromptUnderlineNoFocus;
BOOL fTabAdvance; // tab between fields
BOOL fTabAdvanceLast; // tab between fields at end of field
BOOL fEntrySelectMouse; // also honor entry selection when clicking
BOOL fDDButtonVScrollWidth; // dropdown has width of a vertical scrollbar
BOOL fLockedUpDown; // updown locked for input
BOOL fLockedDropDown; // dropdown locked for input
BOOL fAllowF4; // use F4 to open/close
BOOL fLockedEllipse; // ellipse locked
BOOL fDDButtonCalendar; // calendar drop down button
BOOL fIgnoreNumMinMax; // ignore numeric range during character input
BOOL fAllowEmptyWithoutMask; // empty is valid (without defined mask)
/* edit settings */
int iAlignment; // ES_LEFT/ES_CENTER/ES_RIGHT
int iBorderStyle; // SFTMASK_BORDER_*
int iClipMode; // SFTMASK_CLIP*
int iEditStyle; // SFTMASK_EDIT*
int iEntrySelect; // SFTMASK_ENTRY*
int iInputMode; // SFTMASK_INPUT*
int nMaxLength; // max length (no mask)
int iUseThemes; // SFTMASK_THEME_*
int iDragMode; // SFTMASK_DRAG_*
int selStart, selEnd; // start/end of selection
int iDefaultStyle; // SFTMASK_DEFAULT_*
int iLabelPosition; // SFTMASK_LABELPOSITION_*
int erroriPosition; // SFTMASK_ERRORPOSITION*
int erroriHandling; // SFTMASK_ERRORHANDLING*
/* strings */
LPTSTR lpszMask; // edit mask
LPTSTR lpszFormattedText; // formatted text (w/o focus)
LPTSTR lpszMsgErrorEmpty; // error message, empty control
LPTSTR lpszMsgErrorInvalid; // error message, invalid contents
LPTSTR lpszMsgTitle; // error message title
LPTSTR lpszDefaultText; // default text
LPTSTR lpszLabel; // label
LPTSTR lpszMsgErrorRequired; // warning message, data entry required
TCHAR chPromptChar; // prompt char
TCHAR chPswdChar; // password char
/* caption */
HFONT captionFont; // caption font
LPTSTR lpszCaption; // caption text
BOOL captionfTransparent; // caption transparency
int captioniPosition; // SFTMASK_POSITION*
int captioniAlignment; // ES_LEFT/ES_CENTER/ES_RIGHT
int captioniVerticalAlignment; // SFTMASK_VERTALIGN*
int captionnSizePercent; // height/width of caption in percent
int captionnWidth; // caption width (overrides captionnSizePercent)
/* calendar */
int caliFirstDay; // SFTMASK_FIRSTDAY*
long calCenturyBreak; // century break
DATE calFirstDate, calLastDate; // first and last valid date
BOOL calfShowToday; // calendar shows today's date
BOOL calfCircleToday; // calendar circles today's date
BOOL calfWeekNumbers; // show week numbers
BOOL calfDropOnFocus; // show calendar on input focus
BOOL calfSingleClickClose; // a single click closes the calendar
BOOL calAdjust4DigitYear; // adjust a 4 digit year (date mask)
/* calculator */
int nCalcLines; // # of lines in calculator
int nFracDigits; // # of fractional digits
int nViewCalcLines; // # of viewable lines in calculator
/* autocomplete */
BOOL auto_fEncrypt; // encrypt data
BOOL auto_fIgnoreCase; // ignore input case
short auto_nMaxEntries; // max saved entries
LPTSTR auto_lpszFile; // file name
int auto_iMode; // SFTMASK_AUTOCOMPLETE_*
BOOL auto_fOptimalHeight; // show optimal height autocomplete window
BOOL auto_fShowOne; // show even just one entry
int auto_maxShown; // maximum entries shown without scrollbar
LPTSTR auto_lpszDefaultDirectory; // default directory for filenames
int auto_iContents; // SFTMASK_AUTOCOMPLETECONTENTS_*
/* rendering modes */
int nDarkMode; // SFTMASK_DARKMODE_*
int nHighContrastMode; // SFTMASK_HIGHCONTRAST_*
int imageScaling; // SFTMASK_IMAGESCALING_*
int pixelScaling; // SFTMASK_PIXELSCALING_*
/* colors */
COLORREF colorBg, colorFg, colorSelectBg, colorSelectFg, colorFgGrayed, colorMaskFg, colorMaskFgGrayed;
COLORREF calcColorBg, calcColorFg, calcColorSelectBg, calcColorSelectFg, calcColorFrame, calcColorTotalBg, calcColorTotalFg;
COLORREF calendarColorBg, calendarColorMonthBg, calendarColorMonthFg, calendarColorOtherFg, calendarColorTitleBg, calendarColorTitleFg;
COLORREF captionColorBg, captionColorFg, captionColorFgGrayed;
COLORREF colorBgInvalid, colorFgInvalid;
COLORREF colorBgFocus, colorFgFocus, colorSelectBgFocus, colorSelectFgFocus;
long nCustomCode; // application-defined value
/* error images */
SFT_PICTURE ImageInvalid;
SFT_PICTURE ImageEmpty;
SFT_PICTURE ImageRequired;
/* read-only fields */
int errorValue; // SFTMASK_ERR_*
int errorPos; // position (if any)
BOOL fDarkModeActive; // resolved dark mode state
BOOL fHighContrastActive; // resolved high contrast state
} SFTMASK_CONTROL, * LPSFTMASK_CONTROL;
typedef const SFTMASK_CONTROL * LPCSFTMASK_CONTROL;Identity
cbSize
Size of the structure in bytes. Set to sizeof(SFTMASK_CONTROL) before calling GetControlInfo or SetControlInfo. Used by the control to verify the caller's binary compatibility with the DLL build.
Behavior Flags
fAllowEmpty, fAllowEmptyWithoutMask
Define whether an empty control is considered valid, with a defined mask (fAllowEmpty) or without a mask (fAllowEmptyWithoutMask). See Input Validation and Error Image.
fAutoAdvance
Automatically moves the caret location to the next input position once a numeric field has been completed. See Auto-Advance.
fAutoSize
Automatically adjusts the control's height so text is never clipped vertically, based on the fonts used. See Display Attributes.
fAutoTab
Automatically sets the input focus to the next control once valid input data has been entered and the entire contents are valid. See Auto-Tabbing.
fHideSelection
Hides the selection (highlighted text) while the control does not have the input focus.
fHotTrack
Enables hot-tracking (hover feedback) for the up-down, drop down and ellipse buttons.
fInsert
The current insert (TRUE) / overtype (FALSE) mode. See Insert/Overtype Mode and iInputMode.
fLocked
Locks the control for input (read-only). The user can still select and copy the contents.
fPadding
Adds extra spaces around locale date/time separators in date and time fields. See Edit Masks.
fPromptUnderline, fPromptUnderlineNoFocus
Underline input positions where data has not been entered, while the control has the input focus (fPromptUnderline) and while it does not (fPromptUnderlineNoFocus).
fTabAdvance, fTabAdvanceLast
Allow the Tab key to move between input fields within the control. fTabAdvanceLast controls whether the Tab key moves to the next control when the caret is at the end of the last input field. See Tabbing Within The Control.
fEntrySelectMouse
Also applies the entry selection behavior (iEntrySelect) when the control receives the input focus through a mouse click.
fDDButtonVScrollWidth
The drop down button uses the width of a vertical scrollbar.
fLockedUpDown, fLockedDropDown, fLockedEllipse
Disable the up-down buttons, the drop down button and the ellipse button, respectively.
fAllowF4
Allows the F4 key to open and close the popup calendar and autocomplete window.
fDDButtonCalendar
Displays a modern calendar drop down button instead of the standard combo box style arrow (used with SFTMASK_EDITCALENDARDROPDOWN).
fIgnoreNumMinMax
Ignores the numeric minimum/maximum range during character input. The range is still enforced during validation.
Edit Settings
iAlignment
The horizontal alignment of the contents: ES_LEFT, ES_CENTER or ES_RIGHT. Centered display is only possible while the control does not have the input focus.
iBorderStyle
The border style. See SFTMASK_BORDER Constants.
iClipMode
Defines whether literal characters are included in clipboard and text operations. See SFTMASK_CLIP Constants.
iEditStyle
Defines the additional buttons displayed (up-down, calendar drop down, ellipse). See SFTMASK_EDIT Constants.
iEntrySelect
Defines the selection behavior when the control receives the input focus. See SFTMASK_ENTRY Constants.
iInputMode
Defines the insert/overtype mode behavior. See SFTMASK_INPUT Constants.
nMaxLength
The maximum number of characters that can be entered when no mask is defined (Simple Edit Control). With a defined mask, the mask determines the input length.
iUseThemes
Defines whether Windows themes are used. See SFTMASK_THEME Constants.
iDragMode
Defines the drag & drop behavior. See SFTMASK_DRAG Constants.
selStart, selEnd
The start and end of the selection. selStart is the caret location. See Selection.
iDefaultStyle
Defines when the default text is applied. See SFTMASK_DEFAULT Constants and Default Text.
iLabelPosition
Defines the position of the label inside the edit area. See SFTMASK_LABELPOSITION Constants and Label.
erroriPosition, erroriHandling
Define the location of the error image and when it is updated. See SFTMASK_ERRORPOSITION Constants, SFTMASK_ERRORHANDLING Constants and Error Image.
Strings
lpszMask
The edit mask, composed of literal characters and input field tokens. See Edit Masks for the complete token reference. An empty string makes the control act as a Simple Edit Control. The mask can only be changed by itself - a SetControlInfo call that changes lpszMask must not change any other fields (see SFTMASK_ERR_MASKONLY).
lpszFormattedText
Optional text displayed while the control does not have the input focus, overriding the formatted contents. See Built-In Formatting.
lpszMsgErrorEmpty, lpszMsgErrorInvalid, lpszMsgErrorRequired, lpszMsgTitle
Error messages displayed by IsValidWithMsg and used as error image tooltips (lpszMsgTitle defines the message box title). See Input Validation and Error Image.
lpszDefaultText
Text automatically entered into an empty control, including special values such as =Today and =Now. See Default Text.
lpszLabel
A label displayed inside the edit area, at its left or right end. The special value "|" displays the locale currency symbol. See Label.
chPromptChar
The prompt character displayed at input positions where data has not yet been entered, while the control has the input focus. The default is a space character. Use fPromptUnderline instead of an underscore prompt character to mark input positions.
chPswdChar
The password character displayed instead of actual input data. Only takes effect if the <p mask subtoken is used or if no mask has been defined. See Edit Masks.
Caption
captionFont
The caption font. If NULL, the control's font is used.
lpszCaption
The caption text. An & character defines an accelerator key. See Built-In Caption.
captionfTransparent
Makes the caption background transparent, so the background of the enclosing dialog shows through.
captioniPosition, captioniAlignment, captioniVerticalAlignment
The caption position relative to the edit area (see SFTMASK_POSITION Constants), the horizontal text alignment (ES_LEFT/ES_CENTER/ES_RIGHT) and the vertical alignment (see SFTMASK_VERTALIGN Constants).
captionnSizePercent, captionnWidth
The caption size as a percentage of the overall control size, or as a fixed pixel width (captionnWidth overrides captionnSizePercent when nonzero). Setting both to 0 hides the caption. captionnWidth participates in pixel scaling (see Per-Monitor DPI and Scaling).
Calendar
caliFirstDay
The first day of the week shown by the popup calendar. See SFTMASK_FIRSTDAY Constants.
calCenturyBreak
The century break used to expand 2-digit years.
calFirstDate, calLastDate
The first and last valid date (DATE values). Dates outside this range are rejected during validation.
calfShowToday, calfCircleToday, calfWeekNumbers
Define whether the popup calendar shows today's date, circles today's date and shows week numbers.
calfDropOnFocus
Shows the popup calendar automatically every time the control receives the input focus.
calfSingleClickClose
A single click on a date closes the popup calendar and enters the date.
calAdjust4DigitYear
Adjusts a 4 digit year automatically when entering a date (date mask).
Calculator
nCalcLines, nViewCalcLines
The number of lines of intermediate results stored by the popup calculator, and the number of lines displayed. If more lines are stored than displayed, a vertical scrollbar is shown. See Popup Calculator.
nFracDigits
The number of fractional digits used by the popup calculator.
AutoComplete
auto_fEncrypt
Encrypts the autocomplete save file.
auto_fIgnoreCase
Matches saved entries ignoring case. Default TRUE.
auto_nMaxEntries
The maximum number of saved entries (1-1000). When the maximum is reached, the least recently saved or used entry is discarded.
auto_lpszFile
The autocomplete save file name. If the name starts with a "-" character, the remainder is appended to the user's application data folder. See AutoComplete.
auto_iMode
The autocomplete display method. See SFTMASK_AUTOCOMPLETE Constants.
auto_fOptimalHeight, auto_maxShown, auto_fShowOne
Control the autocomplete window size and display: optimal height sizing, the maximum entries shown without a scrollbar, and whether the window is shown for a single entry.
auto_lpszDefaultDirectory
The default directory used to complete relative input when displaying files or directories. See SFTMASK_AUTOCOMPLETECONTENTS Constants.
auto_iContents
Defines whether previously entered text or file/directory names are offered. See SFTMASK_AUTOCOMPLETECONTENTS Constants.
Rendering Modes
nDarkMode
The dark mode setting. See SFTMASK_DARKMODE Constants and Dark Mode.
nHighContrastMode
The high contrast setting. See SFTMASK_HIGHCONTRAST Constants and High Contrast.
imageScaling, pixelScaling
Per-monitor DPI scaling opt-ins for caller-supplied images and pixel dimensions. See SFTMASK_IMAGESCALING Constants, SFTMASK_PIXELSCALING Constants and Per-Monitor DPI and Scaling.
Colors
Color fields are COLORREF values. Any field can be set to SFTMASK_NOCOLOR to mean "use the applicable default" - the control then chooses an appropriate color for the current rendering mode (light, dark, or high contrast). System color values (COLOR_* | 0x80000000L) resolve to the current system colors.
colorBg, colorFg, colorSelectBg, colorSelectFg, colorFgGrayed, colorMaskFg, colorMaskFgGrayed
The edit area colors: background, foreground, selection colors, disabled foreground and the literal (mask) colors. See Display Attributes.
colorBgInvalid, colorFgInvalid
Colors used while the control's contents are invalid. See Input Validation.
colorBgFocus, colorFgFocus, colorSelectBgFocus, colorSelectFgFocus
Colors used while the control has the input focus.
calcColorBg, calcColorFg, calcColorSelectBg, calcColorSelectFg, calcColorFrame, calcColorTotalBg, calcColorTotalFg
The popup calculator colors. See Popup Calculator.
calendarColorBg, calendarColorMonthBg, calendarColorMonthFg, calendarColorOtherFg, calendarColorTitleBg, calendarColorTitleFg
The popup calendar colors. See Popup Calendar.
captionColorBg, captionColorFg, captionColorFgGrayed
The caption area colors. See Built-In Caption.
Miscellaneous
nCustomCode
An application-defined value stored with the control. Not interpreted by the control.
ImageInvalid, ImageEmpty, ImageRequired
The error images (SFT_PICTURE), shown when the contents are invalid, empty or required. See Error Image.
Read-Only Fields
errorValue, errorPos
The error resulting from the last SetControlInfo call and the offending position, if applicable. See SFTMASK_ERR Constants.
fDarkModeActive
The resolved dark mode state - TRUE while dark-palette rendering is in effect. See Dark Mode.
fHighContrastActive
The resolved high contrast state - TRUE while high contrast rendering is in effect. See High Contrast.
Examples
C
/**********************************************************************/
/* IP Address, Password, Phone Number, Path Autocomplete */
/**********************************************************************/
static void InitIPAddress(HWND hwndDlg)
{
HWND hwndEdit = GetDlgItem(hwndDlg, IDC_IPADDRESS);
SFTMASK_CONTROL Ctl;
Ctl.cbSize = sizeof(SFTMASK_CONTROL);
SftMask_GetControlInfo(hwndEdit, &Ctl);
Ctl.fAutoSize = TRUE;
Ctl.iAlignment = ES_LEFT;
Ctl.iBorderStyle = SFTMASK_BORDER_THIN;
Ctl.iEditStyle = SFTMASK_EDITUPDOWN;
Ctl.fAutoAdvance = TRUE; View Entire Sample Code
C++
{
CDialog::OnInitDialog();
SetIcon(m_hIcon, TRUE); // Set big icon
SetIcon(m_hIcon, FALSE); // Set small icon
// IP address with up-down buttons
{
SFTMASK_CONTROL Ctl;
Ctl.cbSize = sizeof(SFTMASK_CONTROL);
m_IPAddress.GetControlInfo(&Ctl);
Ctl.fAutoSize = TRUE;
Ctl.iAlignment = ES_LEFT;
Ctl.iBorderStyle = SFTMASK_BORDER_THIN;
Ctl.iEditStyle = SFTMASK_EDITUPDOWN;
Ctl.fAutoAdvance = TRUE; View Entire Sample Code
See Also GetControlInfo | SetControlInfo | Edit Masks | Display Attributes
On
Off