SalComboBox

Namespace: PPJ.Runtime.Windows

Assembly: PPJ.Runtime.50 (5.0.0.0)

Combines an editable value and selectable list with SAL validation, formatting, and window actions.

C#

public class SalComboBox : ComboBox, ISalWindow, ISalEditControl, ISalControl, ISalListControl, IConvertible

VB.NET

Public Class SalComboBox
    Inherits ComboBox
    Implements ISalWindow, ISalEditControl, ISalControl, ISalListControl, IConvertible

Example:

void AddControl(System.Windows.Forms.Control parent)
{
    var control = new PPJ.Runtime.Windows.SalComboBox();
    control.Name = "SalComboBox";
    parent.Controls.Add(control);
}

Constructors

SalComboBox()

Initializes an unmodified, unvalidated combo box with a maximum text length of 100 and 16 visible drop-down items.

Properties

CultureInfo

CultureInfo: Gets or sets the culture used to parse and format values and configure spell checking.

At run time, an unset culture falls back to the containing SAL form and then Sys.CultureInfo. Throws:

• ArgumentException The assigned culture is neutral.

EditMask

String: Gets or sets the input mask, updating the length limit and editable text while preserving an existing modified state. (Default: "")

Removing the mask restores a maximum length of 32767.

EnableSpellChecker

Boolean: Gets or sets whether the field participates in the configured spell checker. (Default: False)

Label

Control: Gets or sets the label associated with this control through the SAL window implementation.

Modified

Boolean: Gets or sets the SAL modification flag for the combo box.

NamedProperties

SalNamedProperties: Gets the SAL named-property collection associated with this control.

ReadOnly

Boolean: Gets or sets whether user edits and selection keystrokes are suppressed. (Default: False)

Updates the native edit window and switches between standard editable and read-only background colors when those defaults are in use.

SelectedIndex

Int32: Gets or sets the selected item index while preserving the modified flag.

Invalid indices are ignored. Reassigning the current index refreshes editable text from the item; -1 clears selection.

Text

String: Gets the text according to input-mask rules or assigns text and clears the modified flag.

Editable text is limited by MaxLength. In DropDownList mode, assignment selects an item by prefix; an empty value clears selection.

Watermark

String: Gets or sets the native cue text displayed in an empty field. (Default: "")

A null value clears the watermark.

Methods

AddListItem(name)

Adds a text item, respecting the list sorting setting.

Parameter	Type	Description
name	SalString	The item text.

Returns: SalNumber. The added item index, or Sys.LB_Err for an unsupported target.

BringWindowToTop()

Brings this control to the front, or activates it when it is a top-level or MDI form.

Returns: SalBoolean. True if the translated control exists; otherwise, false.

CenterWindow()

Centers this window within its parent or, for a top-level form, its owner or screen working area.

Returns: SalBoolean. True when the translated control exists; otherwise, false.

A top-level form is constrained to the selected screen working area. A control without a parent is unchanged unless it is a top-level form.

Clear()

Clears the value or selection appropriate to this control type.

Returns: SalBoolean. False for an unavailable control or a form; otherwise, true.

Editable controls and labels have their text cleared; check boxes are unchecked; list selections are cleared. A date/time picker is set to the current date and time. Unrecognized control types are unchanged.

ClearCursor(nType)

Restores the default cursor for a role, using the I-beam for TextBox subclasses.

Parameter	Type	Description
nType	SalNumber	The cursor role: Sys.CURSOR_Window, Sys.CURSOR_DragDrop, or Sys.CURSOR_DisableDrop.

Returns: SalBoolean. True if the cursor is assigned to a supported role; otherwise, false.

ClearList()

Removes all items from the list.

Returns: SalBoolean. True when the target supports lists; otherwise, false.

DeleteListItem(index)

Removes the item at a zero-based index.

Parameter	Type	Description
index	SalNumber	The item to remove.

Returns: SalNumber. The remaining item count, or Sys.LB_Err for an invalid index or unsupported target.

DestroyWindow()

Closes this window when it is a form, or disposes the control.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

A true result reports that the close or disposal request was made; a form can apply its own closing behavior.

DisableWindow()

Disables input to this control, or clears editability for a table column.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

DisableWindowAndLabel()

Disables input to this control and disables its associated label.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

EnableWindow()

Enables input to this control, or enables editing for a table column.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

For text-box controls, this operation also clears the read-only setting.

Native disabled styles are also cleared. When needed, tab navigation is restored except for unchecked radio buttons.

EnableWindowAndLabel()

Enables input to this control and enables its associated label.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

FindChild(windowName)

Searches this window for a child control by name.

Parameter	Type	Description
windowName	SalString	The child control name to locate.

Returns: SalWindowHandle. The matching child handle, or a null SAL handle if no child is found.

FireWindowActions(msg, mywParam, mylParam)

Invokes this control's SAL action handlers directly and returns their result.

Parameter	Type	Description
msg	SalNumber	The action message code.
mywParam	SalNumber	The first action parameter.
mylParam	SalNumber	The second action parameter.

Returns: SalNumber. The result stored in the dispatched action arguments.

FormUnitsToPixels(formUnits, vertical)

Converts a length in form units to pixels using this control's form metrics.

Parameter	Type	Description
formUnits	SalNumber	The length in form units.
vertical	SalBoolean	True for a vertical measurement; false for a horizontal measurement.

Returns: SalNumber. The converted pixel length.

GetClassName()

Gets the translated application class name associated with this control.

Returns: SalString. The class name, an empty string for a runtime-defined class, or a null SAL string for an unresolved or native control.

Forms use their base type; nested table-window types are walked upward to a non-nested type.

GetControlType()

Gets the SAL window type of this control.

Returns: SalNumber. The SAL Sys.TYPE_* code for the translated control.

GetDataLength()

Gets the configured maximum input length.

Returns: SalNumber. The character limit, -1 for native default or unlimited limits, or zero for an unsupported target.

GetDataType()

Gets the SAL data type represented by this control.

Returns: SalNumber. The SAL data-type code, or zero if the translated control does not implement the SAL value contract.

GetFirstChild(typeMask)

Finds the first child matching a SAL window-type mask.

Parameter	Type	Description
typeMask	SalNumber	The SAL window types to include; zero matches no controls.

Returns: SalWindowHandle. The first matching child handle, or a null SAL handle when none matches.

Ordinary controls use tab order; table columns use their creation order, and MDI forms use their child-form collection.

GetFont(name, size, enhancement)

Reads the control font's family, point size, and style flags.

Parameter	Type	Description
name	SalString	Receives the font family name.
size	SalNumber	Receives the size in points.
enhancement	SalNumber	Receives the combined Sys.FONT_Enh* style flags.

Returns: SalBoolean. True if a font was available; otherwise, false.

GetFormat(picture)

Copies the current display picture.

Parameter	Type	Description
picture	SalString	Receives the picture, including an empty picture; remains unchanged for an unsupported target.

Returns: SalBoolean. True when the picture is available; otherwise, false.

GetFormat()

Gets the current display picture.

Returns: SalString. The picture, or a null string for an unsupported target.

GetFormatCode()

Gets the SAL format constant for the current picture, character casing, or password display.

Returns: SalNumber. A Sys.FMT_Format_* value; custom pictures return FMT_Format_Picture.

GetFormattedText(text, format)

Copies the field value as formatted or unformatted text.

Parameter	Type	Description
text	SalString	Receives the text when the target supports editing.
format	SalBoolean	True to apply the picture or retain a string input mask; false to use the value text.

Returns: SalBoolean. True when text is available; otherwise, false, leaving text unchanged.

GetFormattedText(format)

Gets the field value as formatted or unformatted text.

Parameter	Type	Description
format	SalBoolean	True to apply the picture or retain a string input mask; false to use the value text.

Returns: SalString. The value text, an empty string for an empty value, or a null string for an unsupported target.

GetInputMask(mask)

Copies the input mask when a nonempty mask is configured.

Parameter	Type	Description
mask	SalString	Receives the mask on success; remains unchanged otherwise.

Returns: SalBoolean. True for a nonempty mask; otherwise, false.

GetInputMask()

Gets the input mask used by the field.

Returns: SalString. The configured mask, or a null string for an unsupported target.

GetLabel()

Gets the label associated with this control.

Returns: SalWindowHandle. The associated label handle, or a null SAL handle if no label can be found.

GetLabelText(text, maxLength)

Copies the associated label text to a supplied variable.

Parameter	Type	Description
text	SalString	Receives the label text when it can be read.
maxLength	SalNumber	The maximum number of leading characters to copy.

Returns: SalNumber. The number of characters copied, or zero if no label text is available.

GetLabelText(maxLength)

Gets this control's associated label text.

Parameter	Type	Description
maxLength	SalNumber	The maximum number of leading characters to return.

Returns: SalString. The label text limited to the requested length, or an empty string if no label exists.

GetListItemsCount()

Counts the entries in the list.

Returns: SalNumber. The item count, or Sys.LB_Err for an unsupported target.

GetListItemState(index)

Checks whether a list item is selected.

Parameter	Type	Description
index	SalNumber	The zero-based item index.

Returns: SalBoolean. True when the item is selected; otherwise, false.

GetListItemText(index, text)

Copies the text of an indexed list item.

Parameter	Type	Description
index	SalNumber	The zero-based item index.
text	SalString	Receives the text on success; remains unchanged when the item is unavailable.

Returns: SalNumber. The text length, or Sys.LB_Err when the item is unavailable.

GetListItemText(index)

Gets the text of an indexed list item.

Parameter	Type	Description
index	SalNumber	The zero-based item index.

Returns: SalString. The item text, or a null string when the item is unavailable.

GetListItemTextLength(index)

Gets the number of characters in a list item.

Parameter	Type	Description
index	SalNumber	The zero-based item index.

Returns: SalNumber. The text length, or Sys.LB_Err when the item is unavailable.

GetListSelectedFile(fileName)

Decodes the selected file-list entry into a file, directory, or drive name.

Parameter	Type	Description
fileName	SalString	Receives the decoded name; remains unchanged when no item is selected.

Returns: SalBoolean. True for a directory or drive; false for an ordinary file or no selection.

GetListSelectedFile()

Gets the decoded name of the selected file-list entry.

Returns: SalString. The file name, a directory with a trailing separator, a drive ending in a colon, or an empty string when nothing is selected.

GetListSelectedIndex()

Gets the first selected item index.

Returns: SalNumber. The zero-based index, or Sys.LB_Err when no item is selected or the target is unsupported.

GetListSelectedItems(selectedArray)

Replaces an array with the selected indices of a multi-selection list.

Parameter	Type	Description
selectedArray	SalArray<SalNumber>	The destination, made dynamic and reset before indices are copied.

Returns: SalBoolean. True when at least one index is copied; false for an empty selection or a list without multi-selection.

GetListSelectedItemsCount()

Counts selected entries in a multi-selection list.

Returns: SalNumber. The selected count, zero when selection is disabled, or -1 for single-selection mode.

GetLocation(x, y)

Reads this control's location in form units.

Parameter	Type	Description
x	SalNumber	Receives the horizontal location.
y	SalNumber	Receives the vertical location.

Returns: SalBoolean. Always true; an unresolved control produces zero coordinates.

GetName(text)

Copies this control's name to the supplied variable.

Parameter	Type	Description
text	SalString	Receives the control name when the operation succeeds.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

GetName()

Gets this control's name.

Returns: SalString. The control name, or an empty string if the control cannot be resolved.

GetNextChild(typeMask)

Finds the next sibling matching a SAL window-type mask.

Parameter	Type	Description
typeMask	SalNumber	The SAL window types to include; zero matches no controls.

Returns: SalWindowHandle. The next matching control handle, or a null SAL handle when none matches.

GetParent()

Gets the SAL parent form, owner, or table container for this control.

Returns: SalWindowHandle. The parent window handle, or a null SAL handle if no parent can be resolved.

GetProperty(name, value)

Reads a SAL named property into a supplied variable.

Parameter	Type	Description
name	SalString	The property name.
value	SalString	Receives the value only when the property is found.

Returns: SalBoolean. True if a non-null property value was found; otherwise, false.

GetProperty(name)

Gets the value of a SAL named property.

Parameter	Type	Description
name	SalString	The property name.

Returns: SalString. The property value, or a SAL null string if the value is unavailable.

GetSize(width, height)

Reads this control's size in form units.

Parameter	Type	Description
width	SalNumber	Receives the width.
height	SalNumber	Receives the height.

Returns: SalBoolean. Always true; an unresolved control produces a zero size.

GetText(text, maxLen)

Copies this control's displayed text or long-string value to a SAL string.

Parameter	Type	Description
text	SalString	Receives the retrieved text.
maxLen	SalNumber	The maximum character count for ordinary text; ignored for a Sys.DT_LongString value.

Returns: SalNumber. The number of characters copied, or zero when no text is available.

GetText(maxLen)

Gets this control's displayed text or long-string value.

Parameter	Type	Description
maxLen	SalNumber	The maximum character count for ordinary text; ignored for a Sys.DT_LongString value.

Returns: SalString. The retrieved text, or an empty string if the control cannot be resolved.

GetTextUnmasked(text)

Copies text with removable input-mask characters stripped.

Parameter	Type	Description
text	SalString	Receives the unmasked text.

Returns: SalBoolean. True when the translated target exists; otherwise, false.

GetTextUnmasked()

Gets text with removable input-mask characters stripped.

Returns: SalString. The unmasked text, or a null string when the translated target does not exist.

GetWindowColor(colorIndex)

Reads a window or cell color as a Win32 color value.

Parameter	Type	Description
colorIndex	SalNumber	The Sys.COLOR_Index* color component to read.

Returns: SalNumber. The color encoded as a Win32 color value, or zero if the control is unavailable.

Transparent colors are reported as Sys.COLOR_None. Table-column window colors use the system window colors; cell colors use the column settings.

GetWindowState()

Gets the visibility and form-state classification of this window.

Returns: SalNumber. A Sys.Window_* state code; visible non-form controls report Sys.Window_Normal.

HideWindow()

Hides this control or table column.

Returns: SalBoolean. The visibility state before the operation, or false if the control cannot be resolved.

HideWindowAndLabel()

Hides this control and its associated label.

Returns: SalBoolean. The control's visibility before the operation, or false if it cannot be resolved.

InsertListItem(index, add)

Inserts text into the list at a requested position.

Parameter	Type	Description
index	SalNumber	The zero-based insertion index, or -1 to append using normal sorting behavior.
add	SalString	The item text.

Returns: SalNumber. The resulting index, or Sys.LB_Err for an invalid index or unsupported target.

InvalidateWindow()

Invalidates this control and its child controls for repainting.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

IsDerivedFromClass(typeClass)

Tests this control's runtime type against an application base type.

Parameter	Type	Description
typeClass	Type	The type to test, including the framework's emulated inheritance relationships.

Returns: SalBoolean. True if the runtime type derives from the requested type; otherwise, false.

IsEmpty()

Checks whether the unmasked text is null or empty.

Returns: SalBoolean. True for empty edit text; otherwise, false.

IsEnabled()

Determines whether this control accepts input.

Returns: SalBoolean. The enabled state, or the editable flag for a table column; false if the control cannot be resolved.

IsInputKey(keyData)

Allows Enter to be handled as a dialog key in simple combo boxes.

Parameter	Type	Description
keyData	Keys	The key and modifier flags.

Returns: Boolean. False for Enter in simple mode; otherwise, the base classification.

IsModified()

Reads this control's SAL modification flag.

Returns: SalBoolean. True if the control reports a modified value; otherwise, false.

IsValid()

Validates the value against the configured data type without applying display formatting.

Returns: SalBoolean. True when the value passes data-type validation; otherwise, false.

IsValidDateTime()

Checks the displayed text as a date and time using the current picture and culture.

Returns: SalBoolean. True when the value is valid; otherwise, false.

IsValidDecimal(precision, scale)

Checks the displayed text as a decimal with the specified digit limits, picture, and culture.

Parameter	Type	Description
precision	SalNumber	The maximum total number of digits.
scale	SalNumber	The maximum number of fractional digits.

Returns: SalBoolean. True when the value meets the decimal constraints; otherwise, false.

IsValidInteger()

Checks the displayed text as an integer using the current picture.

Returns: SalBoolean. True when the value is a valid integer; otherwise, false.

IsValidNumber()

Checks the unmasked text as a number using the current picture and culture.

Returns: SalBoolean. True when the value is a valid number; otherwise, false.

IsVisible()

Determines whether this control is visible.

Returns: SalBoolean. The visible state, or the visibility flag for a table column; false if the control cannot be resolved.

KillTimer(idEvent)

Stops the native window timer with the specified identifier.

Parameter	Type	Description
idEvent	SalNumber	The timer identifier to remove.

Returns: SalBoolean. The native timer-removal result, or false if the control cannot be resolved.

MoveWindow(xOffset, yOffset)

Moves this control by an offset expressed in form units.

Parameter	Type	Description
xOffset	SalNumber	The horizontal offset to add to the current position.
yOffset	SalNumber	The vertical offset to add to the current position.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

OnDoubleClick(e)

Raises the base double-click event and sends SAM_DoubleClick.

Parameter	Type	Description
e	EventArgs	The event data.

OnDropDown(e)

Raises the base drop-down event and sends SAM_DropDown.

Parameter	Type	Description
e	EventArgs	The event data.

OnDropDownClosed(e)

Restores any selection saved by incremental searching before raising the base close event.

Parameter	Type	Description
e	EventArgs	The event data.

OnHandleCreated(e)

Installs native list and edit subclasses, restores read-only state, and applies the watermark.

Parameter	Type	Description
e	EventArgs	The handle-creation event data.

OnKeyDown(e)

Suppresses editing and selection control keys while read-only before raising the base key event.

Parameter	Type	Description
e	KeyEventArgs	The key, modifier flags, and handled state.

OnKeyPress(e)

Enforces read-only and mask rules and performs incremental selection for sorted, noneditable lists.

Parameter	Type	Description
e	KeyPressEventArgs	The typed character and handled state.

OnReadOnlyChanged(args)

Raises the ReadOnlyChanged event.

Parameter	Type	Description
args	EventArgs	The event data.

OnTextChanged(e)

Reapplies an editable combo box input mask before raising the base event.

Parameter	Type	Description
e	EventArgs	The text-change event data.

Recursive notifications while the mask updates are ignored.

PixelsToFormUnits(numPixels, vertical)

Converts a pixel length to form units using this control's form metrics.

Parameter	Type	Description
numPixels	SalNumber	The pixel length to convert.
vertical	SalBoolean	True for a vertical measurement; false for a horizontal measurement.

Returns: SalNumber. The converted length in form units.

PopulateList(sql, select)

Replaces list items with tab-separated rows from a SQL result and calculates column tab stops.

Parameter	Type	Description
sql	SalSqlHandle	The connected SQL handle used to execute and fetch results.
select	SalString	The statement to prepare, or an empty value to execute the existing prepared statement.

Returns: SalBoolean. True after loading the result; false for an unsupported target or failed preparation or execution.

PopulateList(sql, select, errorHandler)

Loads SQL result rows into the list within a temporary SQL error-handler context.

Parameter	Type	Description
sql	SalSqlHandle	The SQL handle used to execute and fetch results.
select	SalString	The statement to prepare, or an empty value to reuse the prepared statement.
errorHandler	WhenSqlErrorHandler	The SQL error callback active during population.

Returns: SalBoolean. True after loading the result; false for an unsupported target or failed preparation or execution.

PopulateListFiles(ctrlPath, pathName, attributes)

Replaces list items with matching files, directories, and drives.

Parameter	Type	Description
ctrlPath	Control	The control that receives the resolved directory path.
pathName	SalString	The directory and wildcard specification; receives the resulting file pattern.
attributes	SalNumber	Sys.FA_* flags controlling which entries are included.

Returns: SalBoolean. True after population; false when the target is unsupported or changing directory fails.

This operation can change the process current directory.

PostMessage(msg, mywParam, mylParam)

Posts a native Windows message to this control for asynchronous processing.

Parameter	Type	Description
msg	SalNumber	The Windows or SAL message code.
mywParam	SalNumber	The first message parameter.
mylParam	SalNumber	The second message parameter.

Returns: SalBoolean. True if the native message was posted; false for an unavailable or disposed control, or if posting fails.

ProcessDialogKey(keyData)

Closes the list before processing Tab or Shift+Tab navigation.

Parameter	Type	Description
keyData	Keys	The key and modifier flags.

Returns: Boolean. The result of base dialog-key processing.

SendMessage(msg, mywParam, mylParam)

Sends a native Windows message to this control synchronously.

Parameter	Type	Description
msg	SalNumber	The Windows or SAL message code.
mywParam	SalNumber	The first message parameter.
mylParam	SalNumber	The second message parameter.

Returns: SalNumber. The native message result, or zero when the control is unavailable or disposed.

SendMessageToChildren(msg, mywParam, mylParam)

Sends a message to this control's child windows and eligible descendants.

Parameter	Type	Description
msg	SalNumber	The Windows or SAL message code.
mywParam	SalNumber	The first message parameter.
mylParam	SalNumber	The second message parameter.

Returns: SalBoolean. True after dispatching; false when the parent is unavailable or disposed.

Traversal does not descend into embedded forms or user controls. Close and destroy messages for ordinary child controls are routed to their action handlers instead of their native window procedures.

SetContextMenu(menuName, flags)

Creates and assigns a context menu for this control.

Parameter	Type	Description
menuName	SalString	The menu type name to resolve.
flags	SalNumber	Use Sys.CM_TableCell to assign the table's cell-editor menu; otherwise, assign the control's context menu.

Returns: SalBoolean. True if a control and menu type resolve and the menu is created; otherwise, false.

When called during a SAL context-menu action, the created menu is also shown at the current mouse position.

SetContextMenu(menuType, flags)

Creates and assigns a context menu for this control.

Parameter	Type	Description
menuType	Type	The menu type to instantiate.
flags	SalNumber	Use Sys.CM_TableCell to assign the table's cell-editor menu; otherwise, assign the control's context menu.

Returns: SalBoolean. True if a control and menu type resolve and the menu is created; otherwise, false.

When called during a SAL context-menu action, the created menu is also shown at the current mouse position.

SetCursor(resource, type)

Loads a cursor resource and assigns it to the requested role.

Parameter	Type	Description
resource	SalResourceCursor	The cursor resource to load.
type	SalNumber	The cursor role: Sys.CURSOR_Window, Sys.CURSOR_DragDrop, or Sys.CURSOR_DisableDrop.

Returns: SalBoolean. True if the cursor is assigned to a supported role; otherwise, false.

SetCursor(resourceId, type)

Assigns a system cursor or a cursor identified by its native handle to the requested role.

Parameter	Type	Description
resourceId	Int32	A Sys.CURSOR_* identifier, or a native cursor handle represented as an integer.
type	SalNumber	The cursor role: Sys.CURSOR_Window, Sys.CURSOR_DragDrop, or Sys.CURSOR_DisableDrop.

Returns: SalBoolean. True if the cursor is assigned to a supported role; otherwise, false.

SetCursor(blob, type)

Loads a cursor from binary data and assigns it to the requested role.

Parameter	Type	Description
blob	SalString	The cursor file data stored in a SAL binary string.
type	SalNumber	The cursor role: Sys.CURSOR_Window, Sys.CURSOR_DragDrop, or Sys.CURSOR_DisableDrop.

Returns: SalBoolean. True if loading and assignment succeed; otherwise, false.

SetCursorFile(file, type)

Loads a cursor file and assigns it to the requested role.

Parameter	Type	Description
file	SalString	The cursor file path.
type	SalNumber	The cursor role: Sys.CURSOR_Window, Sys.CURSOR_DragDrop, or Sys.CURSOR_DisableDrop.

Returns: SalBoolean. True if loading and assignment succeed; otherwise, false.

SetDataLength(length)

Sets the maximum input length.

Parameter	Type	Description
length	SalNumber	The character limit, or -1 to select the native unlimited setting.

Returns: SalBoolean. True when the target supports editing; otherwise, false.

SetFocus()

Moves keyboard focus to this control, deferring the change when SAL validation is in progress.

Returns: SalWindowHandle. The previously focused managed control as a SAL handle, or a null handle if the target is unavailable, a table column, an ActiveX host, disabled, or hidden.

SetFont(name, size, enhancement)

Creates and assigns a font to this control.

Parameter	Type	Description
name	SalString	The font family name.
size	SalNumber	The font size in points.
enhancement	SalNumber	The combined Sys.FONT_Enh* style flags.

Returns: SalBoolean. True if the font was created and assigned; otherwise, false.

SetFormat(picture)

Assigns a display picture, translating encoded SAL numeric pictures when present.

Parameter	Type	Description
picture	SalString	The display picture to assign.

Returns: SalBoolean. True when the target supports formatting; this does not indicate whether its Format setter accepted the picture.

SetFormatCode(format)

Applies a standard SAL picture, character casing, or password display setting.

Parameter	Type	Description
format	SalNumber	The Sys.FMT_Format_* setting. FMT_Format_Picture leaves the existing picture unchanged.

Returns: SalBoolean. True when the setting is supported; otherwise, false.

SetInputMask(mask)

Assigns the field input mask.

Parameter	Type	Description
mask	SalString	The mask to apply.

Returns: SalBoolean. True when the target supports edit masks; otherwise, false.

SetLabelText(sText)

Assigns the text of this control's associated label.

Parameter	Type	Description
sText	SalString	The label text to display.

Returns: SalBoolean. True if an associated label was found and updated; otherwise, false.

SetListRedraw(redraw)

Enables or disables native list repainting.

Parameter	Type	Description
redraw	SalNumber	The desired redraw state converted to a Boolean.

Returns: SalBoolean. True for an available target, including one without a native handle; otherwise, false.

Enabling redraw refreshes an existing list handle.

SetListSelectedIndex(index)

Replaces the current selection or applies a multi-selection sentinel.

Parameter	Type	Description
index	SalNumber	The item index. In multi-selection mode, -1 selects all and other invalid indices clear all. In single-selection mode, -1 clears selection.

Returns: SalBoolean. True for a processed multi-selection request or a successfully selected single item; false when clearing single selection or when the request is unsupported.

SetListSelectedItems(index, select)

Changes selected states in a multi-selection list.

Parameter	Type	Description
index	SalNumber	The item index, or -1 for all items.
select	SalBoolean	True to select; false to clear selection.

Returns: SalBoolean. True when the target supports multi-selection; otherwise, false. Invalid individual indices are ignored by SAL list controls.

SetListSelectedText(indexStart, text)

Finds and selects an item by its text prefix while suppressing SAL selection messages.

Parameter	Type	Description
indexStart	SalNumber	The index after which to begin searching, or -1 to search from the first item. The search can wrap.
text	SalString	The nonempty text prefix to find.

Returns: SalNumber. The matched index, or -1 when no match is found.

SetListTabStops(tabStops)

Sets the tab positions used to align tab-separated list text.

Parameter	Type	Description
tabStops	SalArray<SalNumber>	Tab positions expressed in horizontal form units.

Returns: SalBoolean. True when tab stops are assigned; false for an unsupported target or null array.

SetLocation(x, y)

Sets this control's location in form units.

Parameter	Type	Description
x	SalNumber	The new horizontal coordinate.
y	SalNumber	The new vertical coordinate.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

For forms, this also selects manual startup positioning.

SetModified(set)

Sets this control's SAL modification flag.

Parameter	Type	Description
set	SalBoolean	True to mark the value modified; false to clear the flag.

Returns: SalBoolean. True if the translated control supports SAL values; otherwise, false.

For editable SAL controls, this also clears the validation flag.

SetProperty(name, value, length)

Assigns a SAL named property after limiting the value's length.

Parameter	Type	Description
name	SalString	The property name.
value	SalString	The value to assign.
length	SalNumber	The number of leading characters to retain.

Returns: SalBoolean. True if the translated control implements the SAL window contract; otherwise, false.

SetSize(width, height)

Sets this control's dimensions in form units.

Parameter	Type	Description
width	SalNumber	The new width.
height	SalNumber	The new height.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

SetText(text)

Assigns the control's displayed text.

Parameter	Type	Description
text	SalString	The text to assign.

Returns: SalBoolean. True if the translated control exists and assignment completes; otherwise, false.

An empty string is passed as null when assigning combo-box text.

SetText(value, format)

Assigns the field value through its typed value conversion.

Parameter	Type	Description
value	SalString	The text to assign.
format	SalBoolean	Retained for compatibility; this argument is ignored.

Returns: SalBoolean. True when the target supports editing; otherwise, false.

SetTimer(idEvent, elapseMilliSec)

Creates or updates a native window timer for this control.

Parameter	Type	Description
idEvent	SalNumber	The timer identifier.
elapseMilliSec	SalNumber	The requested interval in milliseconds.

Returns: SalBoolean. True if the native timer was created; otherwise, false.

SetWindowColor(colorIndex, color)

Assigns a SAL window, table-cell, text, or transparent-image color.

Parameter	Type	Description
colorIndex	SalNumber	The Sys.COLOR_Index* component to update.
color	SalNumber	The SAL color value.

Returns: SalBoolean. True for a recognized color index and resolved control, even when the component does not apply to that control; otherwise, false.

Cell colors apply to table columns; window colors apply to other controls. Transparent colors require the SAL picture-control contract.

ShowWindow()

Shows this control or table column.

Returns: SalBoolean. The visibility state before the operation, or false if the control cannot be resolved.

ShowWindowAndLabel()

Shows this control and its associated label.

Returns: SalBoolean. The control's visibility before the operation, or false if it cannot be resolved.

TrackPopupMenu(menuName, flags, x, y)

Creates and displays a temporary popup menu at screen coordinates.

Parameter	Type	Description
menuName	SalString	The menu type name to resolve.
flags	SalNumber	SAL TPM_* alignment and cursor-position flags; center alignment and TPM_ContextMenu are unsupported.
x	SalNumber	The screen X coordinate, unless TPM_CursorX selects the cursor position.
y	SalNumber	The screen Y coordinate, unless TPM_CursorY selects the cursor position.

Returns: SalBoolean. True after the popup is shown; false when the target or menu cannot be resolved.

The previous context menu is restored after display and the temporary menu is queued for disposal.

TrackPopupMenu(menuType, flags, x, y)

Creates and displays a temporary popup menu at screen coordinates.

Parameter	Type	Description
menuType	Type	The menu type to instantiate.
flags	SalNumber	SAL TPM_* alignment and cursor-position flags; center alignment and TPM_ContextMenu are unsupported.
x	SalNumber	The screen X coordinate, unless TPM_CursorX selects the cursor position.
y	SalNumber	The screen Y coordinate, unless TPM_CursorY selects the cursor position.

Returns: SalBoolean. True after the popup is shown; false when the target or menu cannot be resolved.

The previous context menu is restored after display and the temporary menu is queued for disposal.

UpdateWindow()

Requests an update of this control.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

Validate()

Validates the data type and applies the display format, showing an error dialog if validation fails.

Returns: SalBoolean. True when validation succeeds; otherwise, false.

Validate(validate)

Validates the data type and applies the display format on success.

Parameter	Type	Description
validate	SalNumber	Use Sys.FMT_Validate_Dialog to display a validation error dialog; other values suppress it.

Returns: SalBoolean. True when validation succeeds; otherwise, false.

WinHelp(file, command, numData, strData)

Invokes the legacy Windows Help API for this control.

Parameter	Type	Description
file	SalString	The help file path.
command	SalNumber	The Sys.HELP_* command.
numData	SalNumber	The numeric topic or index for HELP_Context and HELP_SetIndex.
strData	SalString	The lookup text for HELP_Key.

Returns: SalBoolean. The native help result, or false for an empty file name.

WndProc(m)

Handles combo notifications, focus, resizing, and text limits and releases native subclasses on destruction.

Parameter	Type	Description
m	Message	The native message and its result.

Yield()

Dispatches one pending message for this window, or processes application messages when no window handle exists.

Message dispatch can reenter application code.

Events

MessageActions

SalMessageHandler Provides the legacy SAL message-handler event.

Use WindowActions for new handlers.

ReadOnlyChanged

EventHandler Occurs when ReadOnly changes.

WindowActions

WindowActionsEventHandler Occurs when this control dispatches a SAL or custom window action.

Inherited By

Name	Description
SalQuickToolTipComboBox	Provides a SAL combo box with Quick Objects tooltip and status-text compatibility methods.
VisColorComboBox
VisColorPaletteDropDown
VisComboBoxBase
VisDropDownBase
VisFontComboBox
VisFontNameComboBox
VisListViewDropDown
VisOutlineComboBox
VisPictureComboBox

Implements

Name	Description
ISalControl	Provides access to a SAL control's typed value, associated label, and modification state.
ISalEditControl	Extends the SAL control contract with validation, display formatting, edit masks, and culture settings.
ISalListControl	Provides SAL list operations over list-box and combo-box items and selections.
ISalWindow	Exposes SAL message dispatch and runtime metadata for child controls, forms, dialogs, and MDI windows.