SalTreeControl

Namespace: PPJ.Runtime.Windows

Assembly: PPJ.Runtime.50 (5.0.0.0)

Presents a hierarchy of nodes with SAL window actions and tree-control operations.

C#

public class SalTreeControl : TreeView, ISalWindow, ISalControl

VB.NET

Public Class SalTreeControl
    Inherits TreeView
    Implements ISalWindow, ISalControl

Example:

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

Constructors

SalTreeControl()

Initializes a SAL tree with node label editing and node tooltips enabled.

Properties

Label

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

NamedProperties

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

ShowRoot

Boolean: Gets or sets whether a synthetic root bearing the control name contains the top-level items.

Changing the setting moves existing nodes into or out of the synthetic root.

Methods

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(type)

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

Parameter	Type	Description
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.

CollapseItem(hItem)

Requests collapse of a node.

Parameter	Type	Description
hItem	SalNumber	The item handle.

Returns: SalBoolean. True when the item resolves and collapse is requested; otherwise, false.

DeleteItem(hItem)

Removes a node and its subtree.

Parameter	Type	Description
hItem	SalNumber	The item handle.

Returns: SalBoolean. True when a resolved node is removed; otherwise, false.

DemoteItem(hItem)

Attempts to append a node to the parent collection of its previous sibling.

Parameter	Type	Description
hItem	SalNumber	The item handle.

Returns: SalBoolean. False when the node, previous sibling, or parent is absent; true if insertion completes.

This implementation does not make the node a child of its previous sibling and does not detach it before adding it.

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.

EditItem(hItem)

Requests label editing for a node.

Parameter	Type	Description
hItem	SalNumber	The item handle.

Returns: SalBoolean. True when the item resolves and editing is requested; false when unresolved.

The tree must permit label editing, and BeforeLabelEdit can cancel the request.

EnableItem(hItem, enable)

Represents unsupported per-item enabling and disabling.

Parameter	Type	Description
hItem	SalNumber	The item handle; not used.
enable	SalBoolean	The requested state; not used.

Returns: SalBoolean. No value is returned.

Throws:

• NotSupportedException Always thrown.

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.

ExpandItem(hItem)

Requests expansion of a node.

Parameter	Type	Description
hItem	SalNumber	The item handle.

Returns: SalBoolean. True when the item resolves and expansion is requested; 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.

FindItemByData(item, data)

Searches descendant SAL tree items depth-first for an associated numeric value.

Parameter	Type	Description
item	SalNumber	The parent handle, or zero for the logical root.
data	SalNumber	The value to match.

Returns: SalNumber. The first matching handle, or a null SAL number when no match is found.

Subtrees rooted at ordinary non-SAL TreeNode instances are not searched.

FindItemByTitle(hItem, title)

Searches descendants depth-first for an exact caption match.

Parameter	Type	Description
hItem	SalNumber	The parent handle, or zero for the logical root; the parent itself is not tested.
title	SalString	The case-sensitive caption to find.

Returns: SalNumber. The first matching handle, or a null SAL number when no match 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.

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.

GetFirstItem(hItem)

Gets the first immediate child of an item.

Parameter	Type	Description
hItem	SalNumber	The parent handle, or zero for the logical root.

Returns: SalNumber. The child handle, or zero when no child is available.

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.

GetItemCount(hItem)

Counts immediate children of an item.

Parameter	Type	Description
hItem	SalNumber	The parent handle, or zero for the logical root.

Returns: SalNumber. The child count, or zero for an unresolved item.

GetItemData(hItem)

Gets the numeric value associated with a SAL tree item.

Parameter	Type	Description
hItem	SalNumber	The item handle.

Returns: SalNumber. The item value, or a null SAL number when the item is unavailable or is not a SalTreeItem.

GetItemParent(hItem)

Gets the parent node handle.

Parameter	Type	Description
hItem	SalNumber	The item handle.

Returns: SalNumber. The parent handle, or zero for an unresolved or top-level node.

GetItemText(hItem)

Gets the caption of a node.

Parameter	Type	Description
hItem	SalNumber	The item handle.

Returns: SalString. The caption, or a null string for an unresolved item.

GetItemTooltip(hItem)

Gets the tooltip text of a node.

Parameter	Type	Description
hItem	SalNumber	The item handle.

Returns: SalString. The tooltip, or a null string for an unresolved item.

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.

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.

GetNextItem(hItem)

Gets the next sibling node handle.

Parameter	Type	Description
hItem	SalNumber	The current item handle.

Returns: SalNumber. The next sibling handle, or zero when unavailable.

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.

GetPrevItem(hItem)

Gets the previous sibling node handle.

Parameter	Type	Description
hItem	SalNumber	The current item handle.

Returns: SalNumber. The previous sibling handle, or zero when unavailable.

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.

GetSelectedItem()

Gets the selected node handle.

Returns: SalNumber. The native node handle, or zero when no node is selected.

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.

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.

InsertItem(hItem, index, title)

Inserts a dynamic SAL tree item into the requested parent collection.

Parameter	Type	Description
hItem	SalNumber	The parent handle; zero or an unresolved handle inserts into the physical top-level collection.
index	SalNumber	The insertion index, or -1 to append.
title	SalString	The node caption.

Returns: SalNumber. The inserted native node handle.

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.

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.

IsModified()

Reads this control's SAL modification flag.

Returns: SalBoolean. True if the control reports a modified value; 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.

ItemHasCheckBox(hItem)

Represents an unsupported per-item checkbox query; use ItemsHaveCheckBoxes instead.

Parameter	Type	Description
hItem	SalNumber	The item handle; not used.

Returns: SalBoolean. No value is returned.

Throws:

• NotSupportedException Always thrown.

ItemIsChecked(hItem)

Checks the node check state.

Parameter	Type	Description
hItem	SalNumber	The item handle.

Returns: SalBoolean. True when checked; false for an unchecked or unresolved node.

ItemIsExpanded(hItem)

Checks whether the node is expanded.

Parameter	Type	Description
hItem	SalNumber	The item handle.

Returns: SalBoolean. True when expanded; false for a collapsed or unresolved node.

ItemIsSelected(hItem)

Compares the resolved item with the selected node.

Parameter	Type	Description
hItem	SalNumber	The item handle.

Returns: SalBoolean. True when both references match, including when neither an item nor a selection resolves; otherwise, false.

ItemsHaveCheckBoxes()

Gets the tree-wide checkbox setting.

Returns: SalBoolean. True when node checkboxes are enabled; otherwise, false.

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.

MoveDownItem(hItem)

Moves a node one position later in its parent collection.

Parameter	Type	Description
hItem	SalNumber	The item handle.

Returns: SalBoolean. True after moving; false for an unresolved, top-level, or last sibling node.

MoveItem(hItem, parentItem, position)

Inserts an existing node into the requested parent collection.

Parameter	Type	Description
hItem	SalNumber	The node handle.
parentItem	SalNumber	The destination parent handle.
position	SalNumber	The destination child index.

Returns: SalBoolean. False when either node fails to resolve; true if insertion completes.

The implementation does not detach the node before insertion; native TreeNodeCollection restrictions apply.

MoveUpItem(hItem)

Moves a node one position earlier in its parent collection.

Parameter	Type	Description
hItem	SalNumber	The item handle.

Returns: SalBoolean. True after moving; false for an unresolved, top-level, or first sibling node.

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.

OnAfterCollapse(e)

Sends SAM_ItemCollapsed with the node handle before raising the base event.

Parameter	Type	Description
e	TreeViewEventArgs	The collapsed node and action.

OnAfterExpand(e)

Sends SAM_ItemExpanded with the node handle before raising the base event.

Parameter	Type	Description
e	TreeViewEventArgs	The expanded node and action.

OnAfterSelect(e)

Updates the modified flag from the selection action and sends SAM_ItemSelected after the base event.

Parameter	Type	Description
e	TreeViewEventArgs	The selected node and selection cause.

OnBeforeLabelEdit(e)

Cancels editing unless the node is an editable SalTreeItem, then raises the base event.

Parameter	Type	Description
e	NodeLabelEditEventArgs	The node and cancellation state.

OnDoubleClick(e)

Raises the base event and sends SAM_DoubleClick with client cursor coordinates.

Parameter	Type	Description
e	EventArgs	The event data.

OnNodeMouseClick(e)

Sends SAM_ItemClicked with the clicked node handle before raising the base event.

Parameter	Type	Description
e	TreeNodeMouseClickEventArgs	The clicked node and mouse information.

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.

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.

PromoteItem(hItem)

Attempts to append an existing node to its current parent collection.

Parameter	Type	Description
hItem	SalNumber	The item handle.

Returns: SalBoolean. False for an unresolved or parentless item; true if insertion completes.

This implementation does not move the node to its grandparent and does not detach it before adding it.

Reset(remove)

Clears all logical root children or removes only dynamic children at that level.

Parameter	Type	Description
remove	SalBoolean	True to clear all root children; false to remove immediate dynamic items and ordinary non-SAL nodes.

Returns: SalBoolean. Always true after removal.

The optional synthetic root is retained. Dynamic removal does not recurse into retained static items.

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.

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.

SetItemChecked(hItem, isChecked)

Assigns the node checked state.

Parameter	Type	Description
hItem	SalNumber	The item handle.
isChecked	SalBoolean	The desired checked state.

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

SetItemData(hItem, value)

Replaces the numeric value stored in a SAL tree item.

Parameter	Type	Description
hItem	SalNumber	The item handle.
value	SalNumber	The new value.

Returns: SalNumber. The previous value, or a null SAL value when the node is not a resolved SalTreeItem.

SetItemEditable(hItem, editable)

Sets whether label editing is allowed for a SAL tree item.

Parameter	Type	Description
hItem	SalNumber	The item handle.
editable	SalBoolean	The desired editing permission.

Returns: SalBoolean. True for a resolved SalTreeItem; otherwise, false.

SetItemFontEnh(hItem, fontEnh)

Creates a node font using the tree font family and size with the requested enhancements.

Parameter	Type	Description
hItem	SalNumber	The item handle.
fontEnh	SalNumber	The SAL font enhancement flags.

Returns: SalBoolean. True when the node resolves; otherwise, false.

SetItemImage(hItem, selected, imageFile)

Loads a node image from a file or removes the existing image-list entry.

Parameter	Type	Description
hItem	SalNumber	The item handle.
selected	SalBoolean	True to change the selected image; false for the normal image.
imageFile	SalString	The image file path, or an empty value to remove the image.

Returns: SalBoolean. False for an unresolved node or nonexistent nonempty file; true when the image operation completes.

SetItemImageFromBinary(hItem, selected, format, picture)

Decodes binary image data for a node or removes its image-list entry when decoding yields no image.

Parameter	Type	Description
hItem	SalNumber	The item handle.
selected	SalBoolean	True for the selected image; false for the normal image.
format	SalNumber	The Sys.PIC_Format* decoding format.
picture	SalBinary	The encoded picture bytes.

Returns: SalBoolean. True when the node resolves and the operation completes; otherwise, false.

Invalid image data can raise decoder exceptions.

SetItemImageFromResource(hItem, selected, resource)

Assigns a resource image to a node or removes the existing image-list entry when no image is supplied.

Parameter	Type	Description
hItem	SalNumber	The item handle.
selected	SalBoolean	True for the selected image; false for the normal image.
resource	SalResource	The image resource, or null to remove the image.

Returns: SalBoolean. True when the node resolves and the operation completes; otherwise, false.

SetItemText(hItem, text)

Assigns the node caption.

Parameter	Type	Description
hItem	SalNumber	The item handle.
text	SalString	The new caption.

Returns: SalBoolean. True when the node resolves; otherwise, false.

SetItemTextColor(hItem, color)

Assigns the node foreground color using a SAL color value.

Parameter	Type	Description
hItem	SalNumber	The item handle.
color	SalNumber	The SAL color to translate.

Returns: SalBoolean. True when the node resolves; otherwise, false.

SetItemTooltip(hItem, tooltip)

Assigns the node tooltip text.

Parameter	Type	Description
hItem	SalNumber	The item handle.
tooltip	SalString	The new tooltip text.

Returns: SalBoolean. True when the node resolves; otherwise, false.

SetLabelText(text)

Assigns the text of this control's associated label.

Parameter	Type	Description
text	SalString	The label text to display.

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

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.

SetSelectedItem(hItem)

Selects a resolved tree node.

Parameter	Type	Description
hItem	SalNumber	The item handle.

Returns: SalBoolean. True when the item resolves and selection is assigned; 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.

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.

ShowItemCheckBox(hItem, bShow)

Represents unsupported per-item checkbox visibility; use ShowItemsCheckBoxes instead.

Parameter	Type	Description
hItem	SalNumber	The item handle; not used.
bShow	SalBoolean	The requested visibility; not used.

Returns: SalBoolean. No value is returned.

Throws:

• NotSupportedException Always thrown.

ShowItemsCheckBoxes(show)

Sets checkbox visibility for the entire tree.

Parameter	Type	Description
show	SalBoolean	True to show node checkboxes; false to hide them.

Returns: SalBoolean. Always true after assignment.

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.

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)

Routes the native window message through the SAL window implementation.

Parameter	Type	Description
m	Message	The message to process, including its mutable 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.

WindowActions

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

Implements

Name	Description
ISalControl	Provides access to a SAL control's typed value, associated label, and modification state.
ISalWindow	Exposes SAL message dispatch and runtime metadata for child controls, forms, dialogs, and MDI windows.