SalWindow

Namespace: PPJ.Runtime.Windows

Assembly: PPJ.Runtime.50 (5.0.0.0)

Adapts WinForms controls to SAL window messages, editing operations, layout, and compatibility services.

C#

public class SalWindow

VB.NET

Public Class SalWindow

Most static operations translate accessory or embedded controls to the corresponding SAL window. APIs that dispatch messages directly intentionally retain the original control routing.

Example:

void SetCaption(System.Windows.Forms.Control window)
{
    PPJ.Runtime.Windows.SalWindow.SetText(window, "Customer details");
    PPJ.Runtime.Windows.SalWindow.BringToTop(window);
}

Constructors

SalWindow(salWnd)

Creates a SAL implementation and action manager for a window.

Name	Type	Description
salWnd	ISalWindow	The SAL window to which this implementation belongs.

Properties

DesignMode

Boolean: Gets the SAL runtime design-mode state.

DisableMessages

Boolean: Gets or changes the current thread message-suppression nesting count.

Each true assignment increments the count; each false assignment decrements it without going below zero. Pair assignments in a try/finally block.

DragLocation

Point: Gets the saved drag-start location.

DragSource

Control: Gets the control currently providing the SAL drag operation.

DropDisabled

Boolean: Gets or sets whether the current drop is disabled.

DropLocation

Point: Gets the current pointer location within the drop target.

DropTarget

Control: Gets the current SAL drop target.

KeepMask

Boolean: Gets or sets whether reading masked edit text retains the mask.

MapEnterToTab

Boolean: Gets or sets whether SAL keyboard handling maps Enter to Tab.

NamedProperties

SalNamedProperties: Gets the named-property collection, creating an empty collection on first access.

ProfessionalColors

ProfessionalColorTable: Gets the shared professional color table for WinForms rendering.

The table is created on first access.

Methods

AddListItem(ctrl, text)

Adds a text item to a supported list control.

Parameter	Type	Description
ctrl	Control	The list or combo-box control to access.
text	String	The item text to add.

Returns: Int32. The resulting item index, or Sys.LB_Err for an unsupported or unavailable control.

AddMessageActions(handler)

Deprecated: Deprecated. Use AddWindowActions() Registers a delegate with this window's action manager.

Parameter	Type	Description
handler	Delegate	The action delegate to register.

This obsolete entry point is equivalent to AddWindowActions.

AddMessageActions(target)

Deprecated: Deprecated. Use AddWindowActions(). Adds another window's registered action handlers to this window.

Parameter	Type	Description
target	ISalWindow	The SAL window whose handlers are copied into this instance.

This obsolete entry point delegates to AddWindowActions.

AddWindowActions(handler)

Registers a delegate with this window's action manager.

Parameter	Type	Description
handler	Delegate	The action delegate to register.

AddWindowActions(target)

Adds another window's registered action handlers to this window.

Parameter	Type	Description
target	ISalWindow	The SAL window whose handlers are copied into this instance.

BringToTop(ctrl)

Brings a control forward or activates its top-level/MDI form.

Parameter	Type	Description
ctrl	Control	The control to translate.

Returns: Boolean. True when a control resolves; otherwise, false.

CanCopy()

Checks whether the focused control has content that can be copied.

Returns: Boolean. True when SAL finds selected text, selected table rows, or other copyable content; otherwise, false.

CanCut()

Checks whether the focused control has content that can be cut.

Returns: Boolean. True when the focused control passes SAL enabled, editability, and selection checks; otherwise, false.

CanPaste()

Checks whether SAL permits pasting into the focused control.

Returns: Boolean. The focused control's SAL paste-availability result.

CanUndo()

Reports SAL undo-command availability for the focused control.

Returns: Boolean. True when a focused control is available; otherwise, false.

This compatibility check does not inspect undo history or guarantee that Undo can perform an undo.

Center(ctrl)

Centers a control within its parent or a top-level form relative to its owner/screen.

Parameter	Type	Description
ctrl	Control	The control to center.

Returns: Boolean. True when a control resolves; otherwise, false.

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

Clear()

Dispatches the clear clipboard command to the focused control.

Returns: Boolean. The table or column command result, or true when ordinary control content is cleared; false if no target is available.

Clear(ctrl)

Clears text, checked state, or selection according to the control type.

Parameter	Type	Description
ctrl	Control	The control to clear.

Returns: Boolean. False for a null target or a form; otherwise, true.

Date pickers are first set to the current date. This operation clears selection, not the item collection, for list controls. Unsupported non-form controls can return true without a change.

ClearCursor(ctrl, type)

Restores the default cursor for a window or drag role.

Parameter	Type	Description
ctrl	Control	The non-null target control.
type	Int32	The cursor role to reset.

Returns: Boolean. The cursor-assignment result.

Uses IBeam for subclasses of TextBox and Default for other types, including TextBox itself.

ClearList(ctrl)

Removes all items from a supported list control.

Parameter	Type	Description
ctrl	Control	The list control to translate and clear.

Returns: Boolean. True for an ISalListControl, ListBox, or ComboBox; otherwise, false.

A plain ComboBox also has its text cleared.

Copy()

Copies the focused control's selected text or content to the clipboard.

Returns: Boolean. The table or column command result, or true after copying ordinary control content; false if no target is available.

CopyProfile(ctrl, profile)

Copies number and date/time format settings into a control's writable culture.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.
profile	Int32	The SAL profile or locale identifier supplying the format settings.

Returns: Boolean. False for an unavailable control or a SAL edit control with a missing/read-only culture; otherwise, true.

CopyString(text)

Places persistent Unicode text on the Windows clipboard.

Parameter	Type	Description
text	String	The text to copy.

Clipboard exceptions are logged and suppressed.

CreateFont(name, size, enhancement)

Creates a point-sized font from a family name and SAL enhancement flags.

Parameter	Type	Description
name	String	The font family name.
size	Single	The size in points; nonpositive values use 8 points.
enhancement	Int32	The combined bold, italic, underline, and strikeout FONT_Enh flags.

Returns: Font. The created font, or null when the name is null or empty.

CreateWindow(type, owner, args)

Creates and shows a modeless form of the specified type.

Parameter	Type	Description
type	Type	The form type to instantiate.
owner	Control	The owning control or form.
args	Object[]	Arguments used by the form creation path.

Returns: Control. The created form, or null if it was disposed during creation.

An ordinary form owned by an MDI container is assigned that MDI parent.

CreateWindow(typeName, parent, args)

Resolves a form type relative to the calling assembly, then creates and shows it.

Parameter	Type	Description
typeName	String	The application form type name.
parent	Control	The owning control or form.
args	Object[]	Arguments used by the form creation path.

Returns: Control. The created form, or null if it was disposed during creation.

CreateWindow(type, parent, left, top, width, height, flags, args)

Creates and shows a SAL form with optional embedding and initial visibility.

Parameter	Type	Description
type	Type	The form type to instantiate.
parent	Control	The parent for embedding or owner for normal display.
left	Single	The embedded-form left coordinate in form units.
top	Single	The embedded-form top coordinate in form units.
width	Single	The embedded-form width in form units.
height	Single	The embedded-form height in form units.
flags	Int32	CREATE_AsChild, CREATE_Hidden, and CREATE_Border flags.
args	Object[]	The form creation arguments.

Returns: Control. The new form, or null when a child has no parent or the form is destroyed during creation.

Embedding is supported for SalForm-derived types. The bounds and border option are used only on that path; other forms use their normal Show behavior.

CreateWindow(typeName, parent, left, top, width, height, flags)

Resolves and creates a SAL form with child-window, visibility, and border options.

Parameter	Type	Description
typeName	String	The form type name resolved relative to the calling assembly.
parent	Control	The parent or owner; required for child-form creation.
left	Single	The child form's horizontal position in form units.
top	Single	The child form's vertical position in form units.
width	Single	The child form's width in form units.
height	Single	The child form's height in form units.
flags	Int32	The combined CREATE_AsChild, CREATE_Hidden, and CREATE_Border options.

Returns: Control. The created form, or null when the underlying creation path does not retain a live form.

Cut()

Copies and clears content from the focused control.

Returns: Boolean. The table or column command result, or true after processing ordinary control content; false if no target is available.

Call CanCut when command availability must respect the control's editability.

DeleteListItem(ctrl, index)

Removes an item from a supported list control.

Parameter	Type	Description
ctrl	Control	The list or combo-box control to access.
index	Int32	The zero-based item index.

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

Destroy(ctrl)

Closes a form or disposes another control.

Parameter	Type	Description
ctrl	Control	The control to destroy.

Returns: Boolean. False for an unresolved target; otherwise, true.

SAL forms are marked closed once. If still being created, they receive a posted WM_CLOSE instead of an immediate Close call.

DisableWindow(ctrl)

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

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.

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

DisableWindowAndLabel(ctrl)

Disables input to the specified control and disables its associated label.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.

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

DragAcceptFiles(ctrl, accept)

Changes native file-drop acceptance for a control.

Parameter	Type	Description
ctrl	Control	The target control with an existing handle.
accept	Boolean	True to accept file drops; false to disable them.

Returns: Boolean. True when the request is applied; false when the target or handle is unavailable.

DragDropStart()

Starts SAL drag-and-drop at the current mouse position.

Returns: Boolean. False when no mouse button is pressed; true after the drag operation completes.

Uses an empty string as drag data.

DragDropStart(pt, data)

Starts SAL drag-and-drop with an explicit source position and payload.

Parameter	Type	Description
pt	Point	The drag-start point in source-client pixels.
data	Object	The drag payload; null becomes an empty string.

Returns: Boolean. False when no mouse button is pressed; otherwise, true after the operation completes.

Sends SAM_DragStart before entering the native drag loop and SAM_DragEnd during cleanup. DragDropStop during the start handler prevents entry into the loop.

DragDropStop()

Requests termination of SAL drag mode by clearing the current source.

Returns: Boolean. True when a source was active; otherwise, false.

EnableWindow(ctrl)

Enables a control or makes a table column editable.

Parameter	Type	Description
ctrl	Control	The control to enable.

Returns: Boolean. False for a null or disposed target; otherwise, true.

TextBoxBase controls also become writable. Native disabled styles and associated tab-stop changes are corrected when needed.

EnableWindowAndLabel(ctrl)

Enables input to the specified control and enables its associated label.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.

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

EndDialog(ctrl, value)

Closes a modal dialog with a return value.

Parameter	Type	Description
ctrl	Control	The modal form.
value	Int32	The SAL return value, or DialogResult value for a non-SAL form.

Returns: Boolean. True when closure is initiated; false for an unresolved/nonmodal target or a SAL dialog already marked closed.

A SAL dialog still being created is hidden and receives a posted WM_CLOSE.

FillDoubleGradient(g, start, middle, end, bounds, firstGradientSize, secondGradientSize, vertical)

Draws two edge gradients with a solid middle-color region between them.

Parameter	Type	Description
g	Graphics	The destination graphics surface.
start	Color	The color at the leading edge.
middle	Color	The center color.
end	Color	The color at the trailing edge.
bounds	Rectangle	The overall drawing rectangle.
firstGradientSize	Int32	The leading gradient length in graphics units.
secondGradientSize	Int32	The trailing gradient length in graphics units.
vertical	Boolean	True for vertical gradients; false for horizontal gradients.

The middle strip has a minimum thickness of one. Gradient lengths are used directly rather than clamped to the overall rectangle.

FillGradient(g, start, end, bounds, vertical)

Fills a rectangle with a linear color gradient.

Parameter	Type	Description
g	Graphics	The destination graphics surface.
start	Color	The starting color.
end	Color	The ending color.
bounds	Rectangle	The rectangle in graphics coordinates.
vertical	Boolean	True for a top-to-bottom gradient; false for left-to-right.

Nonpositive width or height produces no drawing.

FindChild(ctrl, name)

Recursively finds the first descendant matching a control name.

Parameter	Type	Description
ctrl	Control	The root control to translate.
name	String	The exact, case-sensitive Control.Name.

Returns: Control. The first matching descendant in control-collection order, or null.

FindChild(ctrl, type)

Recursively finds the first descendant matching a control type.

Parameter	Type	Description
ctrl	Control	The root control to translate.
type	Type	The type used with IsInstanceOfType.

Returns: Control. The first matching descendant in control-collection order, or null.

FindControl(ctrl, name, throwIfNotFound)

Gets a control-valued member by name.

Parameter	Type	Description
ctrl	Control	The control whose members are inspected.
name	String	The member name.
throwIfNotFound	Boolean	True to throw when the member does not exist.

Returns: Control. The member value as Control, or null when absent or not a control.

FindMember(ctrl, name, throwIfNotFound)

Resolves a named member on the translated control.

Parameter	Type	Description
ctrl	Control	The control to inspect.
name	String	The member name.
throwIfNotFound	Boolean	True to throw MissingMemberException when lookup fails; false to return null.

Returns: ReferenceInfo. A ReferenceInfo wrapper, or null when lookup fails and exceptions are disabled.

FireWindowActions(ctrl, msgCode, wParam, lParam)

Dispatches a message to the derived control SAL handlers.

Parameter	Type	Description
ctrl	Control	The target control.
msgCode	Int32	The message identifier.
wParam	SalNumber	The first message parameter.
lParam	SalNumber	The second message parameter.

Returns: WindowActionsEventArgs. The dispatch event data, or WindowActionsEventArgs.Empty when no SAL adapter exists.

Resolves derived instances but does not translate accessories, avoiding duplicate routing.

FireWindowActionsToChildren(ctrl, msg, wParam, lParam)

Dispatches a message directly to child SAL handlers.

Parameter	Type	Description
ctrl	Control	The parent control.
msg	Int32	The message identifier.
wParam	SalNumber	The first message parameter.
lParam	SalNumber	The second message parameter.

Returns: Boolean. False for a null/disposed parent; otherwise, true.

Traverses children in SAL order but does not descend into forms or user controls. Recipients require existing handles. MDI child forms receive native messages; WM_CLOSE and WM_DESTROY for ordinary descendants are delivered to handlers to avoid destroying controls.

FormUnitsToPixels(ctrl, units, vertical)

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

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.
units	Single	The length in form units.
vertical	Boolean	True for a vertical measurement; false for a horizontal measurement.

Returns: Int32. The converted pixel length.

FromHandle(handle, type)

Resolves a SAL window handle and casts the translated control through SAL inheritance rules.

Parameter	Type	Description
handle	SalWindowHandle	The window handle to resolve.
type	Type	The required application or framework type.

Returns: Object. The cast object, or null when the handle does not resolve to a control.

Throws:

• InvalidCastException The translated control cannot be cast to the requested type.

GetClassName(ctrl)

Gets the application class name used by SAL compatibility code.

Parameter	Type	Description
ctrl	Control	The control to inspect.

Returns: String. The application type name, an empty string for runtime-defined types, or null for a missing/native-control target.

Forms use their base type; nested table types are unwrapped through their base classes.

GetClientArea(ctrl)

Finds the client area accessory for a control.

Parameter	Type	Description
ctrl	Control	The control whose accessory is requested.

Returns: SalFormClientArea. The client area accessory, or null if none is found.

GetControlName(ctrl)

Gets the specified control's name.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.

Returns: String. The control name, or an empty string when the control cannot be resolved.

GetControlName(ctrl, sName)

Copies the specified control's name to the supplied variable.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.
sName	SalString	Receives the control name when the operation succeeds.

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

GetControlType(ctrl)

Gets the SAL window type of the specified control.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.

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

GetDataLength(ctrl)

Gets a SAL edit control's input-length limit.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.

Returns: Int32. The maximum length, with zero and 32767 reported as -1; zero when the control is not a SAL edit control.

GetDataType(ctrl)

Gets the SAL data type represented by the specified control.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.

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

GetDefaultButton(ctrl)

Gets a form's accept button.

Parameter	Type	Description
ctrl	Control	The form to inspect.

Returns: Control. The button as a control, or null when the target is not a form or has no compatible button.

GetFirstChild(parent, typeMask)

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

Parameter	Type	Description
parent	Control	The parent control.
typeMask	Int32	The TYPE_* mask; zero matches nothing.

Returns: Control. The first matching child or accessory, or null.

Uses MDI child order for MDI forms, column creation order for tables, and tab order within the client area for ordinary controls.

GetFocus()

Gets the focused native window translated to its SAL handle.

Returns: SalWindowHandle. The translated focus handle.

GetFont(ctrl, sName, nSize, nEnhancement)

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

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.
sName	SalString	Receives the font family name.
nSize	SalNumber	Receives the size in points.
nEnhancement	SalNumber	Receives the combined Sys.FONT_Enh* style flags.

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

GetFont(font, name, size, enhancement)

Reads a font's family, point size, and SAL style flags.

Parameter	Type	Description
font	Font	The font to inspect.
name	String	Receives the family name.
size	Single	Receives the point size.
enhancement	Int32	Receives the combined bold, italic, strikeout, and underline Sys.FONT_Enh* flags.

Returns: Boolean. False if the font is null; otherwise, true.

GetFontNames()

Enumerates the installed font-family names.

Returns: String[]. An array of font-family names in the installed-font collection order.

GetFormat(ctrl)

Gets the format picture of a SAL edit control.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.

Returns: String. The format picture, or null for a control without SAL editing support.

GetFormatCode(ctrl)

Gets the SAL format code represented by an edit control.

Parameter	Type	Description
ctrl	Control	The control to inspect.

Returns: Int32. The recognized format code, casing/password code, Picture for an unrecognized nonempty format, or Unformatted.

Lower/upper casing takes precedence over the password flag.

GetFormattedText(ctrl, format)

Converts an editable control's value to text, optionally using its SAL format.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.
format	Boolean	True to apply the SAL format for number and date values and mask handling for string values; false to use the value's ordinary string conversion.

Returns: String. The converted text, an empty string for a null value, or null for a noneditable target.

GetFormParameter(ctrl, paramType, value)

Gets a form parameter directly from a SalForm.

Parameter	Type	Description
ctrl	Control	The SalForm instance; this method does not translate the control.
paramType	SalNumber	The requested form parameter code.
value	SalNumber	Receives the form parameter; unchanged when ctrl is not SalForm.

Returns: SalBoolean. True for SalForm; otherwise, false.

GetHintText(ctrl)

Gets the watermark of a SAL data field, multiline field, or combo box.

Parameter	Type	Description
ctrl	Control	The control to inspect.

Returns: String. The watermark text, or null for an unsupported control.

GetInputMask(ctrl)

Gets the input mask of a SAL edit control.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.

Returns: String. The edit mask, or null for a control without SAL editing support.

GetLabel(ctrl)

Gets the label associated with a control.

Parameter	Type	Description
ctrl	Control	The control whose label is requested.

Returns: Control. The associated label, or null when no label can be resolved.

SAL forms use their label mapping; other forms use the runtime's label-discovery fallback.

GetLabelText(ctrl)

Gets the text of a control associated label.

Parameter	Type	Description
ctrl	Control	The control whose label is requested.

Returns: String. The label text, an empty string when no label exists, or null for an unresolved target.

GetLabelText(ctrl, maxLen)

Gets the specified control's associated label text.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.
maxLen	Int32	The maximum number of leading characters to return.

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

GetLabelText(ctrl, sText, maxLen)

Copies the associated label text to a supplied variable.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.
sText	SalString	Receives the label text when it can be read.
maxLen	Int32	The maximum number of leading characters to copy.

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

GetListItemsCount(ctrl)

Gets the number of items in a supported list control.

Parameter	Type	Description
ctrl	Control	The list or combo-box control to access.

Returns: Int32. The item count, or Sys.LB_Err for an unsupported or unavailable control.

GetListItemState(ctrl, index)

Tests an item's selection state.

Parameter	Type	Description
ctrl	Control	The list or combo-box control to access.
index	Int32	The zero-based item index.

Returns: Boolean. The SAL list's selection result, the list-box selection state, or whether a combo box's selected index equals the requested index; false for unsupported controls.

GetListItemText(ctrl, index)

Gets an item's string representation.

Parameter	Type	Description
ctrl	Control	The list or combo-box control to access.
index	Int32	The zero-based item index.

Returns: String. The converted item text, or null when the item or supported control is unavailable.

GetListItemText(ctrl, index, text)

Copies an item's string representation to a SAL string.

Parameter	Type	Description
ctrl	Control	The list or combo-box control to access.
index	Int32	The zero-based item index.
text	SalString	Receives the item text on success; otherwise remains unchanged.

Returns: Int32. The copied character count, or Sys.LB_Err when item text is unavailable.

GetListItemTextLength(ctrl, index)

Gets the character count of an item's string representation.

Parameter	Type	Description
ctrl	Control	The list or combo-box control to access.
index	Int32	The zero-based item index.

Returns: Int32. The character count, or Sys.LB_Err when item text is unavailable.

GetListSelectedFile(ctrl, fileName)

Decodes a selected entry created by file-list population.

Parameter	Type	Description
ctrl	Control	The SAL file-list control.
fileName	SalString	Receives the selected file name, directory with a trailing backslash, or drive designation. Remains unchanged when no selection is available.

Returns: Boolean. True for a directory or drive entry; false for a file entry or unavailable selection.

A false result can still return a valid file name.

GetListSelectedFile(ctrl)

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

Parameter	Type	Description
ctrl	Control	The SAL file-list control.

Returns: String. The file name, directory with trailing backslash, or drive designation; an empty string when no selection is available.

GetListSelectedIndex(ctrl)

Gets a supported list control's current selection index.

Parameter	Type	Description
ctrl	Control	The list or combo-box control to access.

Returns: Int32. The zero-based selection index, or Sys.LB_Err if the control is unavailable or unsupported. A supported control returns -1 when no item is selected.

GetListSelectedItems(ctrl, selectedArray)

Copies available selected item indices into a dynamic SAL array.

Parameter	Type	Description
ctrl	Control	The list or combo-box control to access.
selectedArray	SalArray<SalNumber>	The output array, made dynamic and reset before selected indices are copied.

Returns: Boolean. True when at least one index is copied; false if no selection collection is available or it is empty.

When no collection is available, the supplied array is left unchanged.

GetListSelectedItemsCount(ctrl)

Gets the number of selected items from a SAL multiple-selection list.

Parameter	Type	Description
ctrl	Control	The SAL list control whose selection is counted.

Returns: Int32. The selected count for multiple-selection mode, -1 for single-selection mode, or zero when selection is disabled or the target is unavailable.

Use a control implementing ISalListControl. The ordinary ListBox fallback dereferences the absent SAL interface and can throw.

GetLocation(ctrl)

Gets the current window position in SAL form units.

Parameter	Type	Description
ctrl	Control	The control to measure.

Returns: PointF. The position in form units, or PointF.Empty for an unresolved target.

Uses native window bounds when a handle exists so values are current during move/size notifications; otherwise uses managed bounds.

GetMdiClient(ctrl)

Finds the MDI client child of an MDI container form.

Parameter	Type	Description
ctrl	Control	The form to inspect.

Returns: MdiClient. The MdiClient child, or null when the control is not an MDI container form.

GetMessageName(msg)

Gets the runtime's symbolic name for a recognized WinSDK message.

Parameter	Type	Description
msg	Int32	The Windows message code.

Returns: String. The stored message name, or an empty string for an unrecognized code.

GetMousePositionFromLParam(lParam)

Unpacks signed mouse coordinates from a native message parameter.

Parameter	Type	Description
lParam	IntPtr	The packed low-word X and high-word Y coordinates.

Returns: Point. The point formed from the two signed 16-bit coordinates.

GetNextChild(ctrl, typeMask)

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

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.
typeMask	Int32	The SAL window types to include; zero matches no controls.

Returns: Control. The next matching control, or null if no control matches.

GetParent(ctrl)

Gets the SAL parent or owning form for a control.

Parameter	Type	Description
ctrl	Control	The control to inspect.

Returns: Control. The parent/owner according to SAL containment rules, or null when unavailable.

Embedded forms skip accessory containers. Table columns resolve to their table or form-table window. Ordinary child controls return the parent container form.

GetProfile(ctrl)

Maps a control's formatting culture to a SAL profile identifier.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.

Returns: Int32. The default or program profile, a recognized country profile, or the culture's locale identifier.

A writable culture is reported as Sys.FMT_Profile_Program.

GetProfileParameter(ctrl, paramCode, paramValue)

Reads a numeric parameter from the control's formatting culture.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.
paramCode	Int32	The supported Sys.FMT_Parm_* parameter code.
paramValue	SalNumber	Receives the parameter value when its code is recognized.

Returns: Boolean. True for a recognized parameter code; otherwise, false.

The current SAL culture is used when the control has no culture. Date type and leading-zero parameters include compatibility defaults.

GetProfileParameter(ctrl, paramCode, paramValue)

Reads a text parameter from the control's formatting culture.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.
paramCode	Int32	The supported Sys.FMT_Parm_* parameter code.
paramValue	SalString	Receives the parameter value when its code is recognized.

Returns: Boolean. True for a recognized parameter code; otherwise, false.

The current SAL culture is used when the control has no culture.

GetProperty(ctrl, name)

Gets the value of a SAL named property.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.
name	String	The property name.

Returns: String. The property value, or null if the property or SAL window is unavailable.

GetProperty(ctrl, name, sValue)

Reads a SAL named property into a supplied variable.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.
name	String	The property name.
sValue	SalString	Receives the value only when the property is found.

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

GetSalMessageName(msg)

Gets the symbolic name of a recognized SAL message.

Parameter	Type	Description
msg	Int32	The message identifier.

Returns: String. The SAM name, or the numeric identifier formatted as a string when not recognized.

GetScrollBarPosition(ctrl)

Gets the value of a scrollbar control.

Parameter	Type	Description
ctrl	Control	The scrollbar to inspect.

Returns: Int32. The scrollbar Value, or zero for an unsupported target.

GetScrollBarRange(ctrl, nMin, nMax, nLine, nPage)

Reads a scrollbar's range and increments.

Parameter	Type	Description
ctrl	Control	The scrollbar control.
nMin	SalNumber	Receives the minimum.
nMax	SalNumber	Receives the maximum, including SAL scrollbar adjustments.
nLine	SalNumber	Receives the small-change increment.
nPage	SalNumber	Receives the large-change increment.

Returns: Boolean. False for a null input; otherwise, true. A non-scrollbar target produces zero for all outputs.

GetSize(ctrl)

Gets the current window size in SAL form units.

Parameter	Type	Description
ctrl	Control	The control to measure.

Returns: SizeF. The size in form units, or SizeF.Empty for an unresolved target.

Uses native window bounds when a handle exists so values are current during move/size notifications; otherwise uses managed bounds.

GetSortedControls(parent)

Gets child controls in SAL traversal order.

Parameter	Type	Description
parent	Control	The non-null parent control.

Returns: Control[]. A tab-index-sorted child array; table windows use the table-specific column and child ordering.

GetState(ctrl)

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

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.

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

GetStatusBar(ctrl)

Finds the status bar accessory for a control.

Parameter	Type	Description
ctrl	Control	The control whose accessory is requested.

Returns: SalFormStatusBar. The status bar accessory, or null if none is found.

GetStatusBarText(ctrl)

Gets the text from the status bar associated with a control.

Parameter	Type	Description
ctrl	Control	The control whose status bar is searched.

Returns: String. The status-bar text, or an empty string if none is found.

GetSysColor(colorValue)

Resolves a SAL system-color identifier to its current Windows color.

Parameter	Type	Description
colorValue	Int32	The SAL system-color identifier.

Returns: Int32. The current color as a Win32 color value.

GetText(ctrl)

Gets a control's text using SAL mask handling.

Parameter	Type	Description
ctrl	Control	The control whose text is read.

Returns: String. The text returned by SAL mask processing, or null if the control cannot be resolved.

GetText(ctrl, text, maxLen)

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

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.
text	SalString	Receives the retrieved text.
maxLen	Int32	The maximum character count for ordinary text; ignored for a Sys.DT_LongString value.

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

GetText(ctrl, maxLen)

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

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.
maxLen	Int32	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(ctrl)

Gets a control's text with SAL input-mask processing removed.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.

Returns: SalString. The unmasked SAL string, or a SAL null string when retrieval fails.

GetToolBar(ctrl)

Finds the toolbar accessory for a control.

Parameter	Type	Description
ctrl	Control	The control whose accessory is requested.

Returns: SalFormToolBar. The toolbar accessory, or null if none is found.

GetWindowColor(ctrl, colorIndex)

Gets a supported control color by SAL color index.

Parameter	Type	Description
ctrl	Control	The control to inspect.
colorIndex	Int32	COLOR_IndexWindow, Cell, CellText, WindowText, or Transparent.

Returns: Int32. The Win32 color value, COLOR_None for transparent, or zero for an unresolved target.

Table-column window colors use system defaults; cell colors use column properties. Unsupported index/type combinations translate Color.Empty.

HasAccessories(ctrl)

Tests whether a form directly contains any SAL accessory controls.

Parameter	Type	Description
ctrl	Control	The form to inspect.

Returns: Boolean. True if a direct child implements the SAL accessory contract; false for other controls or forms without accessories.

HideWindow(ctrl)

Hides the specified control or table column.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.

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

HideWindowAndLabel(ctrl)

Hides the specified control and its associated label.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.

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

InsertListItem(ctrl, index, text)

Inserts a text item into a supported list control.

Parameter	Type	Description
ctrl	Control	The list or combo-box control to access.
index	Int32	The insertion position from zero through the item count, or -1 to append.
text	String	The item text to insert.

Returns: Int32. The insertion result from the list, or Sys.LB_Err for an invalid position or unsupported control.

Invalidate(ctrl)

Invalidates a control and its children for repainting.

Parameter	Type	Description
ctrl	Control	The control to invalidate.

Returns: Boolean. True when a control resolves; otherwise, false.

IsChecked(ctrl)

Reads the checked state of a check box or radio button.

Parameter	Type	Description
ctrl	Control	The target control.

Returns: Boolean. The checked state, or false for other control types.

IsDerivedFrom(ctrl, type)

Tests the specified control's runtime type against an application base type.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.
type	Type	The type to test, including the framework's emulated inheritance relationships.

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

IsEmpty(ctrl)

Tests whether an editable control has no unmasked text.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.

Returns: Boolean. True when the control is editable and its unmasked text is null or empty; otherwise, false.

IsEnabled(ctrl)

Tests whether a control is enabled.

Parameter	Type	Description
ctrl	Control	The control to inspect.

Returns: Boolean. The enabled state, or false for an unresolved control.

Uses COL_Editable for table columns, native window state when a handle exists, and the managed Enabled property otherwise.

IsKeyboardMessage(msg)

Tests whether a message falls in the WinSDK keyboard-message interval.

Parameter	Type	Description
msg	Int32	The message code.

Returns: Boolean. True from WM_KEYFIRST through WM_KEYLAST, inclusive; otherwise, false.

IsModified(ctrl)

Reads the specified control's SAL modification flag.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.

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

IsMouseMessage(msg)

Tests whether a message falls in the WinSDK mouse-message interval.

Parameter	Type	Description
msg	Int32	The message code.

Returns: Boolean. True from WM_MOUSEFIRST through WM_MOUSELAST, inclusive; otherwise, false.

IsSalMessage(msg)

Tests whether a message code appears in the runtime's recognized SAL-action set.

Parameter	Type	Description
msg	Int32	The message code to classify.

Returns: Boolean. True for an explicitly recognized SAL action; otherwise, false.

IsScrollBarVisible(control, bars)

Tests the native horizontal and vertical scrollbar style bits.

Parameter	Type	Description
control	Control	The non-null control to inspect.
bars	ScrollBars	The scrollbar condition to test; Both requires both flags and None requires neither.

Returns: Boolean. True when the condition matches; false when no handle exists or the value is unsupported.

IsValid(ctrl)

Validates the current value against a SAL edit control's data type.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.

Returns: Boolean. The control's data-type validation result, or false when the target lacks SAL editing support.

IsValidDateTime(ctrl)

Tests whether the control's masked text is a valid date/time for its format and culture.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.

Returns: Boolean. True if the editable control's text passes SAL date/time validation; otherwise, false.

IsValidDecimal(ctrl, precision, scale)

Tests masked control text against a decimal precision and scale.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.
precision	Int32	The allowed decimal precision.
scale	Int32	The allowed number of fractional digits.

Returns: Boolean. True when the editable text passes SAL decimal validation using the control's format and culture; otherwise, false.

IsValidEditMask(mask)

Checks the basic syntax of a SAL edit mask.

Parameter	Type	Description
mask	String	The mask to inspect.

Returns: Boolean. True for a nonempty mask containing a recognized mask character, with at most one asterisk placed at the end.

This is a basic structural check, not a full parsing or value-validation pass.

IsValidFormat(format, code)

Tests a numeric or date/time format by formatting and parsing a sample value.

Parameter	Type	Description
format	String	The format string to test.
code	Int32	Use Sys.FMT_Pic_Number or Sys.FMT_Pic_DateTime.

Returns: Boolean. True if the sample converts back to a non-null SAL value; false for unsupported codes or conversion exceptions.

IsValidInteger(ctrl)

Tests whether the control's masked text is a valid SAL integer.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.

Returns: Boolean. True if the editable text passes integer validation using the control's format; otherwise, false.

IsValidNumber(ctrl)

Tests whether the control's text without its mask is a valid SAL number.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.

Returns: Boolean. True if the editable text passes numeric validation using the control's format and culture; otherwise, false.

IsVisible(ctrl)

Tests whether a control is visible.

Parameter	Type	Description
ctrl	Control	The control to inspect.

Returns: Boolean. The visible state, or false for an unresolved control.

Uses COL_Visible for table columns, native window state when a handle exists, and the managed Visible property otherwise.

KillTimer(ctrl, id)

Removes a native window timer.

Parameter	Type	Description
ctrl	Control	The timer owner control.
id	Int32	The native timer identifier.

Returns: Boolean. The native KillTimer result, or false for an unresolved target.

ListGetMultiSelect(ctrl)

Gets the selected-index collection of a multiple-selection list.

Parameter	Type	Description
ctrl	Control	The control to inspect.

Returns: IList. The live selected-index collection, or null for an unsupported or single-selection control.

MDIArrangeIcons(ctrl)

Arranges minimized child icons in an MDI container.

Parameter	Type	Description
ctrl	Control	The MDI container form.

Returns: Boolean. True when arranged; false when the translated target is not an MDI container.

MDICascade(ctrl)

Cascades child windows in an MDI container.

Parameter	Type	Description
ctrl	Control	The MDI container form.

Returns: Boolean. True when arranged; false when the translated target is not an MDI container.

MDITile(ctrl, vertical)

Tiles child windows in an MDI container.

Parameter	Type	Description
ctrl	Control	The MDI container form.
vertical	Boolean	True for vertical tiling; false for horizontal tiling.

Returns: Boolean. True when arranged; false when the translated target is not an MDI container.

MessageBeep(alert)

Plays the Windows sound associated with an alert type.

Parameter	Type	Description
alert	Int32	The native MessageBeep alert value.

Returns: Boolean. The native success result.

MessageBox(owner, text, title, flags)

Displays a modal Windows message box and restores focus when appropriate.

Parameter	Type	Description
owner	Control	The owner control; its form is used, or the active form/MDI child when unavailable.
text	String	The message text.
title	String	The caption.
flags	Int32	The combined button, icon, default-button, and supported message-box option flags.

Returns: Int32. The selected DialogResult value.

Focus restoration is skipped while SAL validation is active.

ModalDialog(type, owner, args)

Creates and shows a SAL modal dialog.

Parameter	Type	Description
type	Type	The SAL dialog type; MDI and form-table-window subclasses are rejected.
owner	Control	The dialog owner.
args	Object[]	Arguments used by the dialog creation path.

Returns: Int32. The dialog's SAL return value.

ModalDialog(typeName, owner, args)

Resolves a dialog type relative to the calling assembly and shows it modally.

Parameter	Type	Description
typeName	String	The application dialog type name.
owner	Control	The dialog owner.
args	Object[]	Arguments used by the dialog creation path.

Returns: Int32. The dialog's SAL return value.

Move(ctrl, offset)

Moves a control relative to its current location using form-unit offsets.

Parameter	Type	Description
ctrl	Control	The control to move.
offset	PointF	The horizontal and vertical offsets in form units.

Returns: Boolean. True if the control was resolved and moved; otherwise, false.

Paste()

Pastes clipboard text into the focused control.

Returns: Boolean. The table or column command result, or true after assigning ordinary control text; false if no target is available.

Call CanPaste to check SAL command availability before invoking this operation.

PasteString(text)

Reads Unicode text from the Windows clipboard.

Parameter	Type	Description
text	String	Receives the clipboard text on success; unchanged on failure.

Returns: Boolean. True when Unicode string data is available; otherwise, false.

Clipboard exceptions are logged and suppressed.

PixelsToFormUnits(ctrl, pixels, vertical)

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

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.
pixels	Int32	The pixel length to convert.
vertical	Boolean	True for a vertical measurement; false for a horizontal measurement.

Returns: Single. The converted length in form units.

PopulateList(ctrl, hSql, sql)

Executes a query and replaces list items with tab-separated result rows.

Parameter	Type	Description
ctrl	Control	The supported SAL list, ListBox, or ComboBox.
hSql	SalSqlHandle	The SQL handle used to prepare, execute, and read the query.
sql	String	The SQL to prepare, or null/empty to execute the previously prepared statement.

Returns: Boolean. True when the list is populated; false for an unsupported control or a preparation/execution failure.

Computes tab stops from schema sizes or text lengths, applies SQL Autotrim to trailing spaces, and updates the horizontal extent for ListBox controls.

PopulateList(ctrl, hSql, sql, errorHandler)

Populates a list from a query under a temporary SQL-error handler.

Parameter	Type	Description
ctrl	Control	The target list control.
hSql	SalSqlHandle	The connected SQL handle used to execute and read the query.
sql	String	The statement to prepare, or an empty value to execute the handle's previously prepared statement.
errorHandler	WhenSqlErrorHandler	The SQL-error handler active during preparation, execution, and fetching.

Returns: Boolean. The result of the underlying list-population operation.

After successful preparation and execution, existing items are cleared. Each result row becomes one item with tab-separated field values. Trailing spaces are trimmed when the SQL handle enables autotrim.

PopulateListFiles(ctrl, ctrlPath, pathName, attributes)

Replaces a SAL list with file, directory, and drive entries.

Parameter	Type	Description
ctrl	Control	The ISalListControl to populate.
ctrlPath	Control	The control that receives the resolved directory path.
pathName	SalString	The directory or wildcard specification; receives the final file pattern on success.
attributes	Int32	The FA_* selection flags.

Returns: Boolean. True on success; false for an unsupported list or a caught I/O/access failure.

Clears the list before enumeration and may change the process current directory. Directories use bracketed names and drives use the form [-c-]. The implementation applies its legacy attribute filtering directly.

PostMessage(ctrl, msg, wParam, lParam)

Posts a native window message asynchronously.

Parameter	Type	Description
ctrl	Control	The target control.
msg	Int32	The message identifier.
wParam	IntPtr	The first native parameter.
lParam	IntPtr	The second native parameter.

Returns: Boolean. The native post result, or false for a null/disposed target.

PreviewForm(ctrl)

Displays a form through the runtime print-preview helper.

Parameter	Type	Description
ctrl	Control	The form to translate and preview.

PrintForm(ctrl)

Prints a form through the runtime form-printing helper.

Parameter	Type	Description
ctrl	Control	The form to translate and print.

ProcessWndProc(m)

Dispatches a native window message through SAL handling and the underlying control.

Parameter	Type	Description
m	Message	The native message; its result can be updated.

When disposed, suppressed, or in design mode, uses default processing except for non-client creation. State-changing native messages are processed before notification; most other messages are dispatched before default processing.

RemoveMessageActions(handler)

Deprecated: Deprecated. Use RemoveWindowActions() Removes a delegate from this window's action manager.

Parameter	Type	Description
handler	Delegate	The action delegate to remove.

This obsolete entry point is equivalent to RemoveWindowActions.

RemoveWindowActions(handler)

Removes a delegate from this window's action manager.

Parameter	Type	Description
handler	Delegate	The action delegate to remove.

Scale(size, oldScale, newScale)

Converts pixel dimensions between two form-unit scales.

Parameter	Type	Description
size	Size	The pixel size to scale.
oldScale	Size	The original horizontal and vertical scale.
newScale	Size	The target horizontal and vertical scale.

Returns: Size. The rescaled size; an empty input is unchanged.

Scale(point, oldScale, newScale)

Converts pixel coordinates between two form-unit scales.

Parameter	Type	Description
point	Point	The pixel point to scale.
oldScale	Size	The original horizontal and vertical scale.
newScale	Size	The target horizontal and vertical scale.

Returns: Point. The rescaled point; an empty input is unchanged.

SendMessage(ctrl, msg, wParam, lParam)

Sends a native window message synchronously.

Parameter	Type	Description
ctrl	Control	The target control.
msg	Int32	The message identifier.
wParam	SalNumber	The first message parameter.
lParam	SalNumber	The second message parameter.

Returns: SalNumber. The native message result, or zero for a null/disposed target.

SendMessageToChildren(ctrl, msg, wParam, lParam)

Sends a message to child windows.

Parameter	Type	Description
ctrl	Control	The parent control.
msg	Int32	The message identifier.
wParam	SalNumber	The first message parameter.
lParam	SalNumber	The second message parameter.

Returns: Boolean. False for a null/disposed parent; otherwise, true.

Traverses children in SAL order but does not descend into forms or user controls. Recipients require existing handles. MDI child forms receive native messages; WM_CLOSE and WM_DESTROY for ordinary descendants are delivered to handlers to avoid destroying controls.

SendSalMessage(ctrl, msgCode, wParam, lParam)

Deprecated: Deprecated. Use SalWindow.FireWindowActions(). Dispatches a message and wraps its result in the obsolete SalMessage type.

Parameter	Type	Description
ctrl	Control	The target control.
msgCode	Int32	The message identifier.
wParam	SalNumber	The first message parameter.
lParam	SalNumber	The second message parameter.

Returns: SalMessage. A SalMessage wrapping the dispatch result.

Use FireWindowActions for new code.

SendValidateMessage()

Sends SAM_Validate to the focused SAL object.

Returns: Int32. The validation result, or VALIDATE_Ok when the operation is already active.

A reentrancy guard prevents recursive validation from this entry point.

SetChecked(ctrl, value)

Sets the checked state of a checkbox or radio button.

Parameter	Type	Description
ctrl	Control	The control to update.
value	SalNumber	The SAL numeric value converted to a Boolean checked state.

Returns: Boolean. True for a supported control; otherwise, false.

SetContextMenu(ctrl, menuName, flags)

Creates and assigns a context menu for the specified control.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.
menuName	String	The name used to resolve the menu type.
flags	Int32	Use Sys.CM_TableCell to target the associated table column; other values target the control.

Returns: Boolean. True if the menu was created; false if the control or menu type is unavailable or menu creation fails.

SetContextMenu(ctrl, menuType, flags)

Creates and assigns a named context-menu type.

Parameter	Type	Description
ctrl	Control	The target control.
menuType	Type	The context-menu type to instantiate.
flags	Int32	CM_TableCell to assign the table cell context menu; other values assign the control menu.

Returns: Boolean. False when the control/type/menu cannot be resolved; otherwise, true.

A CM_TableCell request on a non-table still returns true. During SAM_ContextMenu processing, the created menu is shown immediately at the mouse position.

SetCursor(ctrl, cursor, type)

Assigns a window or SAL drag cursor while suppressing SAL messages.

Parameter	Type	Description
ctrl	Control	The target control.
cursor	Cursor	The cursor to assign.
type	Int32	CURSOR_Window, CURSOR_DragDrop, or CURSOR_DisableDrop.

Returns: Boolean. True on assignment; false for an invalid target/type or a drag cursor target without a SAL adapter.

SetCursor(ctrl, cursorId, type)

Resolves a standard cursor identifier or native handle and assigns it.

Parameter	Type	Description
ctrl	Control	The target control.
cursorId	Int32	A standard CURSOR_* identifier or native cursor handle.
type	Int32	The cursor role accepted by the Cursor overload.

Returns: Boolean. The cursor-assignment result, or false for null ctrl.

SetCursor(ctrl, fileName, type)

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

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.
fileName	String	The cursor file path.
type	Int32	The cursor role: Sys.CURSOR_Window, Sys.CURSOR_DragDrop, or Sys.CURSOR_DisableDrop.

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

Only the window role changes the displayed cursor. Drag/drop roles are accepted for SAL windows without changing a cursor.

SetCursor(ctrl, blob, type)

Creates and assigns a cursor from serialized cursor data.

Parameter	Type	Description
ctrl	Control	The target control.
blob	Byte[]	The cursor data bytes.
type	Int32	The cursor role accepted by the Cursor overload.

Returns: Boolean. True on assignment; false for null ctrl or a caught creation/assignment exception.

Exceptions are logged.

SetDataLength(ctrl, maxLength)

Sets a SAL edit control's maximum input length.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.
maxLength	Int32	The character limit; -1 is translated to the control's zero default-limit value.

Returns: Boolean. True if the control implements the SAL editing contract; otherwise, false.

SetDefaultButton(ctrl)

Assigns a button as its form accept button.

Parameter	Type	Description
ctrl	Control	A ButtonBase that implements IButtonControl and belongs to a form.

Returns: Boolean. True after assignment; false when the target is not ButtonBase or has no form.

If focus is currently on a Button, focus moves to the new default button. Other ButtonBase types that do not implement IButtonControl cause InvalidCastException.

SetFocus(ctrl)

Requests keyboard focus for an eligible control.

Parameter	Type	Description
ctrl	Control	The target control.

Returns: Control. The previously focused managed control, or null for a rejected target or an unmapped previous handle.

Rejects table columns, SalActiveX controls, hidden controls, and disabled controls. During validation, defers the focus change and returns the current focus control.

SetFont(ctrl, name, size, enhancement)

Creates and assigns a font to the specified control.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.
name	String	The font family name.
size	Int32	The font size in points.
enhancement	Int32	The combined Sys.FONT_Enh* style flags.

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

SetFormat(ctrl, format)

Assigns a format picture, translating encoded SAL numeric format characters when present.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.
format	String	The format picture, including an encoded SAL numeric picture if required.

Returns: Boolean. True if the control implements SAL editing; otherwise, false.

Encoded group, decimal, and currency markers are translated with invariant-culture symbols.

SetFormatCode(ctrl, format)

Applies a standard SAL format code or casing/password behavior.

Parameter	Type	Description
ctrl	Control	The target edit control.
format	Int32	The FMT_Format_* code.

Returns: Boolean. True when applied, or for Picture even without a change; false for an unsupported code/target.

Casing and password changes are supported by SalDataField and SalTableColumn.

SetFormattedText(ctrl, text, applyFormat)

Assigns text through a SAL edit control's value property.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.
text	String	The value text to assign.
applyFormat	Boolean	Retained for compatibility and ignored.

Returns: Boolean. True if the control implements SAL editing; otherwise, false.

SetHintText(ctrl, text)

Sets the watermark of a SAL data field, multiline field, or combo box.

Parameter	Type	Description
ctrl	Control	The target control.
text	String	The watermark text.

Returns: Boolean. True for a supported control; otherwise, false.

SetInputMask(ctrl, mask)

Assigns the edit mask of a SAL edit control.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.
mask	String	The mask to assign.

Returns: Boolean. True if the control implements SAL editing; otherwise, false.

SetLabel(ctrl, label)

Associates a label with a control hosted by a SAL form.

Parameter	Type	Description
ctrl	Control	The control to associate with the label.
label	Control	The label control to associate.

Does nothing when the control cannot be resolved or its form does not implement SAL form behavior.

SetLabelText(ctrl, text)

Assigns the text of the specified control's associated label.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.
text	String	The label text to display.

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

SetListRedraw(ctrl, redraw)

Changes native redraw for an existing ListControl handle.

Parameter	Type	Description
ctrl	Control	The control to translate.
redraw	Boolean	True to enable redraw and refresh; false to suppress redraw.

Returns: Boolean. False for a null translated control; otherwise, true, including when no ListControl handle exists.

SetListSelectedIndex(ctrl, index)

Sets the selection index using SAL single- or multiple-selection rules.

Parameter	Type	Description
ctrl	Control	The list or combo-box control to access.
index	Int32	The zero-based item index. In multiple-selection mode, -1 selects all items and another out-of-range index clears them. In single-selection mode, -1 clears selection.

Returns: Boolean. True after accepted multiple-selection operations; for single-selection controls, true only when an item is selected. Clearing a single selection returns false.

SetListSelectedItems(ctrl, index, select)

Changes selection in a multiple-selection list.

Parameter	Type	Description
ctrl	Control	The list control.
index	Int32	The item index; -1 selects or clears all items for a plain ListBox. ISalListControl implementations receive the value directly.
select	Boolean	True to select; false to clear selection.

Returns: Boolean. True when the supported operation completes; false for an unsupported/single-selection control or invalid plain-list index.

SetListSelectedText(ctrl, startIndex, text)

Selects an item matching text while suppressing SAL messages.

Parameter	Type	Description
ctrl	Control	The list control.
startIndex	Int32	The index after which to search; -1 starts at the beginning.
text	String	The search text; null or empty text is not searched.

Returns: Int32. The matching item index, or -1 when none is found.

Search wraps to the beginning. A failed search clears displayed content only when there is no valid existing selection.

SetListTabStops(ctrl, tabStops)

Assigns tab stops for list item text.

Parameter	Type	Description
ctrl	Control	The list control or table column.
tabStops	SalArray<SalNumber>	The tab-stop positions in SAL form units.

Returns: Boolean. True when assigned; false for an unsupported target or a rejected tab-stop request.

Table columns store the array on their combo-box configuration. Native list controls convert positions to dialog units.

SetLocation(ctrl, pos)

Moves a control to a position expressed in form units.

Parameter	Type	Description
ctrl	Control	The control to move.
pos	PointF	The horizontal and vertical position in SAL form units.

Returns: Boolean. True when a control resolves; otherwise, false.

SetModified(ctrl, modified)

Sets the specified control's SAL modification flag.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.
modified	Boolean	True to mark the value modified; false to clear the flag.

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

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

SetProfile(ctrl, profile)

Assigns a culture profile to a SAL edit control.

Parameter	Type	Description
ctrl	Control	The target control.
profile	Int32	The FMT_Profile_* identifier.

Returns: Boolean. False for an unresolved control; otherwise, true, including non-edit controls.

The program profile clones Sys.CultureInfo so the assigned culture is writable; other profiles use TranslateProfile.

SetProfileParameter(ctrl, paramCode, paramValue)

Changes a numeric parameter in a SAL edit control's writable formatting culture.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.
paramCode	Int32	The supported Sys.FMT_Parm_* parameter code.
paramValue	SalNumber	The new parameter value.

Returns: Boolean. True when the parameter code is accepted; false for an unsupported code, noneditable target, or missing/read-only culture.

The current value is reassigned after updating the culture. Date-type, leading-zero, and time-leading-zero settings are accepted without changing those settings.

SetProfileParameter(ctrl, paramCode, paramValue)

Changes a text parameter in a SAL edit control's writable formatting culture.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.
paramCode	Int32	The supported Sys.FMT_Parm_* parameter code.
paramValue	SalString	The new parameter value.

Returns: Boolean. True when the parameter code is accepted; false for an unsupported code, noneditable target, or missing/read-only culture.

The current value is reassigned after updating the culture.

SetProperty(ctrl, name, value)

Adds or replaces a named property on a SAL window.

Parameter	Type	Description
ctrl	Control	The control whose SAL named-property collection is updated.
name	String	The case-sensitive property name.
value	String	The value to store, including null.

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

SetScrollBarPosition(ctrl, pos)

Sets a scrollbar value, clamping it to the configured range.

Parameter	Type	Description
ctrl	Control	The scrollbar control.
pos	Int32	The requested value.

Returns: Boolean. True when assigned without clamping; false for an unsupported target or a value outside the range.

An out-of-range request still updates the scrollbar to the nearest endpoint.

SetScrollBarRange(ctrl, min, max, line, page)

Sets a scrollbar's range and increments.

Parameter	Type	Description
ctrl	Control	The scrollbar control.
min	Int32	The new minimum.
max	Int32	The new maximum, assigned through the SAL override when available.
line	Int32	The small-change increment.
page	Int32	The large-change increment.

Returns: Boolean. True if the translated target is a scrollbar; otherwise, false.

SetSize(ctrl, size)

Sets a control's dimensions using form units.

Parameter	Type	Description
ctrl	Control	The control to resize.
size	SizeF	The new width and height in form units.

Returns: Boolean. True if the control was resolved and resized; otherwise, false.

SetStatusBarText(ctrl, text)

Sets the text of an associated status bar when one exists.

Parameter	Type	Description
ctrl	Control	The control whose status bar is searched.
text	String	The new text.

Returns: Boolean. True, including when no status bar exists.

SetStatusBarText(menu, text)

Sets status text for the form that owns a menu.

Parameter	Type	Description
menu	Menu	The menu whose owner is resolved.
text	String	The new status text.

Returns: Boolean. False when no owner is found; otherwise, the control overload result.

SetText(ctrl, text)

Assigns the translated control Text property.

Parameter	Type	Description
ctrl	Control	The target control.
text	String	The new text; an empty string becomes null for ComboBox controls.

Returns: Boolean. True when a control resolves; otherwise, false.

SetTimer(ctrl, id, millisec)

Creates or resets a native window timer.

Parameter	Type	Description
ctrl	Control	The timer owner control.
id	Int32	The timer identifier.
millisec	Int32	The requested interval in milliseconds.

Returns: Boolean. True when the native SetTimer call returns a nonzero identifier; otherwise, false.

SetWindowColor(ctrl, colorIndex, nColor)

Sets a supported control color by SAL color index.

Parameter	Type	Description
ctrl	Control	The control to update.
colorIndex	Int32	The target COLOR_Index* value.
nColor	Int32	The SAL color value.

Returns: Boolean. False for an unresolved control or unknown index; otherwise, true.

A recognized index can return true without a change when the control type does not support that color role.

ShowStatusBar(ctrl, visible)

Changes the visibility of a form's status bar.

Parameter	Type	Description
ctrl	Control	The form that owns the accessory.
visible	Boolean	True to show the accessory; false to hide it.

Returns: Boolean. True if the translated target is a form with the requested accessory; otherwise, false.

ShowToolBar(ctrl, visible)

Changes the visibility of a form's toolbar.

Parameter	Type	Description
ctrl	Control	The form that owns the accessory.
visible	Boolean	True to show the accessory; false to hide it.

Returns: Boolean. True if the translated target is a form with the requested accessory; otherwise, false.

ShowWindow(ctrl)

Shows the specified control or table column.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.

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

ShowWindowAndLabel(ctrl)

Shows the specified control and its associated label.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.

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

TrackPopupMenu(ctrl, menuName, flags, pos)

Creates and displays a popup menu at a screen position.

Parameter	Type	Description
ctrl	Control	The owner control.
menuName	String	The name used to resolve the menu type.
flags	Int32	TPM_RightAlign and TPM_CursorX/TPM_CursorY flags; center/context-menu flags are not implemented.
pos	Point	The screen position in pixels; cursor flags replace the corresponding coordinate.

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

Restores the previous context menu, updates the control, and schedules disposal of the temporary menu afterward.

TrackPopupMenu(ctrl, menuType, flags, pos)

Creates and displays a popup menu at a screen position.

Parameter	Type	Description
ctrl	Control	The owner control.
menuType	Type	The menu type to instantiate.
flags	Int32	TPM_RightAlign and TPM_CursorX/TPM_CursorY flags; center/context-menu flags are not implemented.
pos	Point	The screen position in pixels; cursor flags replace the corresponding coordinate.

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

Restores the previous context menu, updates the control, and schedules disposal of the temporary menu afterward.

TranslateColor(color)

Converts a drawing color to a SAL color constant or Win32 color value.

Parameter	Type	Description
color	Color	The color to translate.

Returns: Int32. A matching SAL system/default/transparency constant when available; otherwise, the Win32 color value.

TranslateControl(ctrl)

Resolves the actual SAL control behind accessories, embedded tables, and second-base instances.

Parameter	Type	Description
ctrl	Control	The control to translate.

Returns: Control. The translated control, or null for null input.

TranslateProfile(profile)

Resolves a SAL formatting profile to a culture.

Parameter	Type	Description
profile	Int32	A SAL country/default profile constant or a locale identifier.

Returns: CultureInfo. The mapped cached culture, or the current SAL culture for the default profile.

TranslateSalColor(colorValue)

Converts a SAL color value into a drawing color.

Parameter	Type	Description
colorValue	Int32	A SAL color constant or Win32 color value.

Returns: Color. The translated Color; COLOR_None becomes Transparent and COLOR_Default becomes Empty.

Undo()

Dispatches the undo clipboard command to the focused table or column.

Returns: Boolean. The table or column command result; false for ordinary controls or an unavailable target.

Update(ctrl)

Requests an update of the specified control.

Parameter	Type	Description
ctrl	Control	The control on which to perform the SAL operation.

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

UpdateMainMenu(form)

Refreshes SAL items in a form's merged or regular main menu.

Parameter	Type	Description
form	Form	The form whose menu is refreshed.

Returns: Boolean. True if a menu is found; otherwise, false.

For an MDI container with an active child, the child's menu is used. Refresh occurs within a root SAL context.

Validate(ctrl, showErrorMessage)

Validates a SAL edit control and applies its format after successful validation.

Parameter	Type	Description
ctrl	Control	The control whose SAL editing behavior is accessed.
showErrorMessage	Boolean	True to display the SAL invalid-data message when validation fails.

Returns: Boolean. True after successful validation and formatting; otherwise, false.

WaitCursor(wait)

Sets the current pointer to the wait or default cursor.

Parameter	Type	Description
wait	Boolean	True for WaitCursor; false for Default.

Returns: Boolean. True.

WinHelp(ctrl, file, command, index, key)

Invokes the legacy Windows WinHelp API.

Parameter	Type	Description
ctrl	Control	The owner control.
file	String	The help file path.
command	Int32	The HELP_* command.
index	Int32	The numeric argument for HELP_Context or HELP_SetIndex.
key	String	The search key for HELP_Key.

Returns: Boolean. False for an empty file name; otherwise, the native WinHelp result.

Yield(ctrl)

Processes pending UI messages for a control.

Parameter	Type	Description
ctrl	Control	The control whose native message queue entry is requested.

With no valid handle, calls Application.DoEvents. Otherwise removes and dispatches at most one matching message, invoking Sal.Quit for WM_QUIT.