VisListView

Namespace: PPJ.Runtime.Vis

Assembly: PPJ.Runtime.Vis.50 (5.0.0.0)

Displays icons or detail rows with Visual Toolchest list-view operations and SAL messages.

C#

public class VisListView : ListView, ISalWindow

VB.NET

Public Class VisListView
    Inherits ListView
    Implements ISalWindow

Example:

using (var list = new PPJ.Runtime.Vis.VisListView())
{
    list.InsertItem(0, "First item", -1);
    list.ViewList();
}

Constructors

VisListView()

Initializes the control, its SAL integration, and default components.

Properties

NamedProperties

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

RightToLeftLayout

Boolean: Gets or sets mirrored layout for the list view. (Default: False)

Until explicitly assigned, the getter uses the containing form setting when a form exists.

Methods

AddImage(hpicLarge, hpicSmall)

Adds a pair of pictures to the large and small image lists.

Parameter	Type	Description
hpicLarge	SalNumber	A valid nonzero large-picture handle.
hpicSmall	SalNumber	A valid nonzero small-picture handle.

Returns: SalNumber. The new large-image index, or -1 if either picture is missing or null.

Creates default image lists if necessary. The paired lists are expected to use matching indices.

Arrange(code)

Sets the list-view icon alignment.

Parameter	Type	Description
code	SalNumber	A value corresponding to ListViewAlignment.

Returns: SalBoolean. True after assignment.

AssignColumns(saTitles, naAlignments, naWidths, nNumColumns)

Replaces all columns from parallel arrays.

Parameter	Type	Description
saTitles	SalArray<SalString>	Column titles beginning at index zero.
naAlignments	SalArray<SalNumber>	HorizontalAlignment numeric values beginning at index zero.
naWidths	SalArray<SalNumber>	Column widths in horizontal form units beginning at index zero.
nNumColumns	SalNumber	The number of entries to read from each array.

Returns: SalBoolean. True when all columns have been added.

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.

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.

DeleteAllItems()

Clears all items.

Returns: SalBoolean. Always true.

DeleteItem(nItem)

Removes an item at the specified index.

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

Returns: SalNumber. The remaining item count.

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.

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.

EnsureVisible(item, partialOK)

Scrolls the list view to display an existing item.

Parameter	Type	Description
item	SalNumber	The zero-based item index.
partialOK	SalBoolean	Reserved for compatibility; ignored.

Returns: SalBoolean. True if the item exists; 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.

FindItem(flags, itemText, itemStart)

Searches through the native list-view find-item message.

Parameter	Type	Description
flags	SalNumber	The LVFI search flags.
itemText	SalString	The text used when LVFI_String is set.
itemStart	SalNumber	The zero-based index after which searching starts; -1 starts at the first item.

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

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.

FromHandle(handle)

Resolves this control type from a native window handle.

Parameter	Type	Description
handle	SalWindowHandle	The native control handle.

Returns: VisListView. The associated VisListView, or null when no managed control owns the handle.

A handle belonging to another control type causes an InvalidCastException.

GetAllSelectedItems(naSelections)

Replaces an array with the indices of all selected items.

Parameter	Type	Description
naSelections	SalArray<SalNumber>	The output array; reset and made dynamic before filling from index zero.

Returns: SalNumber. The resulting array length.

GetBkColor()

Reads the list-view background color.

Returns: SalNumber. The Win32 color value.

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.

GetColumn(nColumn, sTitle, nAlignment, nWidth)

Reads a column's caption, alignment, and width.

Parameter	Type	Description
nColumn	SalNumber	The zero-based column index.
sTitle	SalString	Receives the caption.
nAlignment	SalNumber	Receives the HorizontalAlignment numeric value.
nWidth	SalNumber	Receives the width in horizontal form units.

Returns: SalBoolean. True for an existing column; otherwise false and the outputs are unchanged.

GetColumnAlignment(nColumn)

Reads a column's text alignment.

Parameter	Type	Description
nColumn	SalNumber	The zero-based column index.

Returns: SalNumber. The HorizontalAlignment numeric value, or zero if the column is absent.

GetColumnTitle(nColumn)

Reads a column's caption.

Parameter	Type	Description
nColumn	SalNumber	The zero-based column index.

Returns: SalString. The caption, or an empty string if the column is absent.

GetColumnWidth(nColumn)

Reads a column's width.

Parameter	Type	Description
nColumn	SalNumber	The zero-based column index.

Returns: SalNumber. The width in horizontal form units, or zero if the column is absent.

GetControlType()

Gets the SAL window type of this control.

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

GetCountPerPage()

Gets the number of items that fit in a page of the native list view.

Returns: SalNumber. The native LVM_GETCOUNTPERPAGE result.

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.

GetFocusItem()

Reads the item with keyboard focus.

Returns: SalNumber. Its index, or -1 if no item is focused.

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.

GetImageCount()

Counts images in the small-image list.

Returns: SalNumber. The count, or zero if no small-image list exists.

GetItem(nItem, nSubItem, sItemText, nItemValue, nImage)

Reads a caption and the main item's value and image index.

Parameter	Type	Description
nItem	SalNumber	The zero-based item index.
nSubItem	SalNumber	Zero or a negative value for the main item; a positive subitem index otherwise.
sItemText	SalString	Receives the caption.
nItemValue	SalNumber	Receives the main item's Int32 Tag or zero; subitems return zero.
nImage	SalNumber	Receives the main image index; subitems return zero.

Returns: SalBoolean. True for an existing item or subitem; otherwise false with outputs unchanged.

GetItemCount()

Counts the items in the collection.

Returns: SalNumber. The item count.

GetItemPosition(item, position)

Gets the top-left corner of an item bounding rectangle.

Parameter	Type	Description
item	SalNumber	The zero-based item index.
position	VisPoint	Receives the client-area position in pixels; must not be null.

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

GetItemRect(nItem, rcItem, nCode)

Gets an item bounding rectangle.

Parameter	Type	Description
nItem	SalNumber	The zero-based item index.
rcItem	VisRect	Receives the item bounds in client pixels; must not be null.
nCode	SalNumber	Reserved for compatibility; the full item bounds are always returned.

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

GetItemState(nItem, nMask)

Reads masked focus, selection, and state-image flags.

Parameter	Type	Description
nItem	SalNumber	The zero-based item index.
nMask	SalNumber	The LVIS_* bits to retain.

Returns: SalNumber. The masked state, or zero if the item is absent.

GetItemText(nItem, nSubItem)

Reads an item or subitem caption.

Parameter	Type	Description
nItem	SalNumber	The zero-based item index.
nSubItem	SalNumber	Zero or negative for the main item; positive for a subitem.

Returns: SalString. The caption, or an empty string if the item is absent.

GetItemValue(nItem)

Gets the integer value stored in an item tag.

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

Returns: SalNumber. The integer tag value, or zero when the item or tag is missing.

A non-integer tag causes an InvalidCastException.

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(nItem, nFlags)

Finds the next native list-view item matching the specified state and direction.

Parameter	Type	Description
nItem	SalNumber	The starting item index; -1 starts before the first item.
nFlags	SalNumber	The LVNI search flags.

Returns: SalNumber. The matching index, or -1 when no item matches.

GetOrigin(ptOrigin)

Gets the native list-view origin.

Parameter	Type	Description
ptOrigin	VisPoint	Receives the origin coordinates in pixels; must not be null.

Returns: SalBoolean. True when the native operation succeeds; otherwise, false.

The output is assigned even when the native operation fails.

GetParent()

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

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

GetProperty(name, value)

Reads a SAL named property into a supplied variable.

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

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

GetProperty(name)

Gets the value of a SAL named property.

Parameter	Type	Description
name	SalString	The property name.

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

GetSelectedCount()

Counts selected items.

Returns: SalNumber. The selected-item count.

GetSelectedItem()

Reads the first selected item.

Returns: SalNumber. Its zero-based index, or -1 if there is no selection.

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.

GetSortColumn()

Reads the configured sort column.

Returns: SalNumber. The zero-based column index.

GetSortOrder()

Reads the compatibility sort order.

Returns: SalNumber. LVSORT_Descending for descending order; otherwise LVSORT_Ascending, including when sorting is disabled.

GetStringWidth(sCompare)

Measures text with the native list-view font.

Parameter	Type	Description
sCompare	SalString	The text to measure.

Returns: SalNumber. The measured width converted to horizontal form units.

GetStyle()

Gets the native list-view window-style flags.

Returns: SalNumber. The GWL_STYLE value.

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.

GetTextBkColor()

Reads the list-view background color.

Returns: SalNumber. The Win32 color value.

GetTextColor()

Reads the list-view foreground color.

Returns: SalNumber. The Win32 color value.

GetTopIndex()

Gets the index of the top visible item where supported by the current view.

Returns: SalNumber. Zero in large-icon, small-icon, or tile view; otherwise, the top item index, or -1 when no top item exists.

GetViewRect(rcView)

Gets the rectangle enclosing the native list-view items.

Parameter	Type	Description
rcView	VisRect	Receives the rectangle in pixels; must not be null.

Returns: SalBoolean. True when the native operation succeeds; otherwise, false.

The output is assigned even when the native operation fails.

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.

HitTest(ptTest, flags)

Finds the native list-view item at a client-area point.

Parameter	Type	Description
ptTest	VisPoint	The client-area test point in pixels; must not be null.
flags	SalNumber	Receives the LVHT hit-test flags.

Returns: SalNumber. The item index, or -1 when no item is hit.

HitTest(x, y, flags)

Finds the native list-view item at a client-area point.

Parameter	Type	Description
x	SalNumber	The horizontal client coordinate in pixels.
y	SalNumber	The vertical client coordinate in pixels.
flags	SalNumber	Receives the LVHT hit-test flags.

Returns: SalNumber. The item index, or -1 when no item is hit.

InsertDetails(nItem, saText, nImage)

Inserts an item and its detail subitems.

Parameter	Type	Description
nItem	SalNumber	The requested index, clamped to the range from zero through the current item count.
saText	SalArray<SalString>	A zero-based text array; element zero is the item label and later elements are subitems.
nImage	SalNumber	The image-list index.

Returns: SalNumber. The inserted item index.

InsertDetailsPic(nItem, saText, hpicLarge, hpicSmall)

Inserts a row of item and subitem captions and a newly added image pair.

Parameter	Type	Description
nItem	SalNumber	Insertion index, clamped to zero through the current item count.
saText	SalArray<SalString>	Zero-based captions; element zero is the item caption and later elements are subitems.
hpicLarge	SalNumber	A valid large-picture handle.
hpicSmall	SalNumber	A valid small-picture handle.

Returns: SalNumber. The inserted index, or -1 if the picture pair cannot be added.

InsertDetailsValue(nItem, saText, nItemValue, nImage)

Inserts a row of item and subitem captions with an application value.

Parameter	Type	Description
nItem	SalNumber	Insertion index, clamped to zero through the current item count.
saText	SalArray<SalString>	Zero-based captions; element zero is the item caption and later elements are subitems.
nItemValue	SalNumber	The application value, converted to Int32 and stored in Tag.
nImage	SalNumber	The index in the image lists, or -1 for no picture.

Returns: SalNumber. The inserted index.

InsertDetailsValuePic(nItem, saText, nItemValue, hpicLarge, hpicSmall)

Inserts a row of item and subitem captions with an application value and a newly added image pair.

Parameter	Type	Description
nItem	SalNumber	Insertion index, clamped to zero through the current item count.
saText	SalArray<SalString>	Zero-based captions; element zero is the item caption and later elements are subitems.
nItemValue	SalNumber	The application value, converted to Int32 and stored in Tag.
hpicLarge	SalNumber	A valid large-picture handle.
hpicSmall	SalNumber	A valid small-picture handle.

Returns: SalNumber. The inserted index, or -1 if the picture pair cannot be added.

InsertItem(nItem, sText, nImage)

Inserts a list-view item.

Parameter	Type	Description
nItem	SalNumber	The requested index, clamped to the range from zero through the current item count.
sText	SalString	The item label.
nImage	SalNumber	The image-list index.

Returns: SalNumber. The inserted item index.

InsertItemPic(nItem, sText, hpicLarge, hpicSmall)

Inserts an item and a newly added image pair.

Parameter	Type	Description
nItem	SalNumber	Insertion index, clamped to zero through the current item count.
sText	SalString	The item caption.
hpicLarge	SalNumber	A valid large-picture handle.
hpicSmall	SalNumber	A valid small-picture handle.

Returns: SalNumber. The inserted index, or -1 if the picture pair cannot be added.

InsertItemValue(nItem, sText, nItemValue, nImage)

Inserts an item with an application value.

Parameter	Type	Description
nItem	SalNumber	Insertion index, clamped to zero through the current item count.
sText	SalString	The item caption.
nItemValue	SalNumber	The application value, converted to Int32 and stored in Tag.
nImage	SalNumber	The index in the image lists, or -1 for no picture.

Returns: SalNumber. The inserted index.

InsertItemValuePic(nItem, sText, nItemValue, hpicLarge, hpicSmall)

Inserts an item with an application value and a newly added image pair.

Parameter	Type	Description
nItem	SalNumber	Insertion index, clamped to zero through the current item count.
sText	SalString	The item caption.
nItemValue	SalNumber	The application value, converted to Int32 and stored in Tag.
hpicLarge	SalNumber	A valid large-picture handle.
hpicSmall	SalNumber	A valid small-picture handle.

Returns: SalNumber. The inserted index, or -1 if the picture pair cannot be added.

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.

IsVisible()

Determines whether this control is visible.

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

KillTimer(idEvent)

Stops the native window timer with the specified identifier.

Parameter	Type	Description
idEvent	SalNumber	The timer identifier to remove.

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

MoveWindow(xOffset, yOffset)

Moves this control by an offset expressed in form units.

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

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

OnColumnClick(e)

Toggles sort direction, selects the clicked sort column, sorts, and raises the base event.

Parameter	Type	Description
e	ColumnClickEventArgs	The clicked column index.

OnHandleCreated(e)

Creates default image lists before raising the base handle-created event.

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

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.

RemoveAllImages()

Clears both image lists, creating the lists if necessary.

Returns: SalBoolean. Always true.

RemoveImage(nIndex)

Removes an image at the same index in both image lists.

Parameter	Type	Description
nIndex	SalNumber	The zero-based image index.

Returns: SalBoolean. True if both removals succeed; false on ArgumentOutOfRangeException.

The large-image removal is not rolled back if the small-image removal fails.

ReplaceImage(nIndex, hpicLarge, hpicSmall)

Replaces corresponding entries in the large and small image lists.

Parameter	Type	Description
nIndex	SalNumber	The zero-based image index.
hpicLarge	SalNumber	The large picture handle.
hpicSmall	SalNumber	The small picture handle.

Returns: SalBoolean. True on success; false when neither picture resolves or an IndexOutOfRangeException occurs.

When only one picture resolves, its bitmap is used for both sizes.

Scroll(size)

Scrolls the native list view by the supplied displacement.

Parameter	Type	Description
size	VisSize	The horizontal and vertical displacement in pixels; must not be null.

Returns: SalBoolean. True when the native operation succeeds; otherwise, false.

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(nMsg, nMywParam, nMylParam)

Dispatches a SAL message to this control's children.

Parameter	Type	Description
nMsg	SalNumber	The SAL or application-defined message code.
nMywParam	SalNumber	The first message parameter.
nMylParam	SalNumber	The second message parameter.

Returns: SalBoolean. The result of child-message dispatch; false if the parent is unavailable or disposed.

SetBkColor(nNewColor)

Sets the list-view background color.

Parameter	Type	Description
nNewColor	SalNumber	The SAL color to apply.

Returns: SalBoolean. Always true.

SetColumn(nColumn, nMask, sTitle, nAlignment, nWidth)

Updates the column attributes selected by a mask.

Parameter	Type	Description
nColumn	SalNumber	The zero-based column index.
nMask	SalNumber	LVCF_Text, LVCF_Fmt, and LVCF_Width flags selecting the supplied values.
sTitle	SalString	The new caption.
nAlignment	SalNumber	The HorizontalAlignment numeric value.
nWidth	SalNumber	The new width in horizontal form units.

Returns: SalBoolean. True when the column exists; otherwise false.

SetColumnAlignment(nColumn, nAlignment)

Sets a column's text alignment.

Parameter	Type	Description
nColumn	SalNumber	The zero-based column index.
nAlignment	SalNumber	The HorizontalAlignment numeric value.

Returns: SalBoolean. True if the column exists and is updated; otherwise false.

SetColumnTitle(nColumn, sTitle)

Sets a column's caption.

Parameter	Type	Description
nColumn	SalNumber	The zero-based column index.
sTitle	SalString	The new caption.

Returns: SalBoolean. True if the column exists and is updated; otherwise false.

SetColumnWidth(nColumn, nWidth)

Sets a column's width.

Parameter	Type	Description
nColumn	SalNumber	The zero-based column index.
nWidth	SalNumber	The new width in horizontal form units.

Returns: SalBoolean. True if the column exists and is updated; otherwise false.

SetContextMenu(sMenuName, nFlags)

Creates and assigns a context menu for this control.

Parameter	Type	Description
sMenuName	SalString	The name used to resolve the menu type.
nFlags	SalNumber	Use Sys.CM_TableCell to target the associated table column; other values target the control.

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

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.

SetFocusItem(nItem)

Gives keyboard focus to an item.

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

Returns: SalBoolean. True if the item exists; otherwise false.

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.

SetItem(nItem, nSubItem, nMask, sItemText, nItemValue, nImage)

Updates selected item attributes.

Parameter	Type	Description
nItem	SalNumber	The zero-based item index.
nSubItem	SalNumber	Zero or negative for the main item; positive for a subitem.
nMask	SalNumber	LVIF_Text, LVIF_Image, and LVIF_Param flags selecting attributes to update.
sItemText	SalString	The new caption.
nItemValue	SalNumber	The new application value, converted to Int32.
nImage	SalNumber	The new image-list index.

Returns: SalBoolean. True if the item or subitem exists; otherwise false.

Subitems support only text changes.

SetItemPosition(item, ptPosition)

Sets an icon item position through the native list view.

Parameter	Type	Description
item	SalNumber	The zero-based item index.
ptPosition	VisPoint	The requested position in pixels; each coordinate is packed into a 16-bit word.

Returns: SalBoolean. True when the native operation succeeds; otherwise, false.

SetItemState(nItem, nNewState, nStateMask)

Updates item state while suppressing generated SAM_Click notifications.

Parameter	Type	Description
nItem	SalNumber	The zero-based item index.
nNewState	SalNumber	The new LVIS state bits.
nStateMask	SalNumber	The state bits to change.

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

Supports focus, selection, state image, cut, and drop-highlight state.

SetItemText(nItem, nSubItem, sItemText)

Changes an item or subitem caption.

Parameter	Type	Description
nItem	SalNumber	The zero-based item index.
nSubItem	SalNumber	Zero or negative for the main item; positive for a subitem.
sItemText	SalString	The new caption.

Returns: SalBoolean. True if the item or subitem exists; otherwise false.

SetItemValue(nItem, nItemValue)

Stores an application value in an item's Tag.

Parameter	Type	Description
nItem	SalNumber	The zero-based item index.
nItemValue	SalNumber	The value converted to Int32.

Returns: SalBoolean. True if the item exists; 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.

SetProperty(name, value, length)

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

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

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

SetSize(width, height)

Sets this control's dimensions in form units.

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

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

SetSortColumn(nColumn)

Selects the column for the next explicit sort.

Parameter	Type	Description
nColumn	SalNumber	The zero-based column index.

Returns: SalBoolean. Always true.

SetSortOrder(nOrder)

Selects the ordering for the next explicit sort.

Parameter	Type	Description
nOrder	SalNumber	LVSORT_Ascending or LVSORT_Descending; other values disable ordering.

Returns: SalBoolean. Always true.

SetStyle(nStyle, fOn)

Enables or clears list-view styles and updates corresponding managed properties.

Parameter	Type	Description
nStyle	SalNumber	The LVS style bits to change.
fOn	SalBoolean	True to set the bits; false to clear them.

Returns: SalNumber. The updated style value.

The return variable is modified during assignment, so the result is not the previous style.

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.

SetTextBkColor(nNewColor)

Sets the list-view background color.

Parameter	Type	Description
nNewColor	SalNumber	The SAL color to apply.

Returns: SalBoolean. Always true.

SetTextColor(nNewColor)

Sets the list-view foreground color.

Parameter	Type	Description
nNewColor	SalNumber	The SAL color to apply.

Returns: SalBoolean. Always true.

SetTimer(idEvent, elapseMilliSec)

Creates or updates a native window timer for this control.

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

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

SetWindowColor(colorIndex, color)

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

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

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

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

ShowWindow()

Shows this control or table column.

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

SortItems()

Sorts once with the configured item sorter, then removes the sorter.

Returns: SalBoolean. True.

Subsequent insertions are not automatically sorted.

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.

ViewDetails()

Switches the list view to details.

Returns: SalNumber. Always zero.

ViewLargeIcons()

Switches the list view to large icons.

Returns: SalNumber. Always zero.

ViewList()

Switches to list view.

Returns: SalNumber. Zero.

ViewSmallIcons()

Switches the list view to small icons.

Returns: SalNumber. Always zero.

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 list-view notifications and native messages through SAL while suppressing selection clicks during focus entry.

Parameter	Type	Description
m	Message	The native message and 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
ISalWindow