TreeView control

A TreeView control is a hierarchical display of information. Each item in a TreeView control consists of text and pictures, which can be manipulated during program runtime.

Properties

TreeView property

Datatype

Description

Accelerator

Integer

Specifies the ASCII value of the accelerator key you want to use for the control.

AccessibleDescription

String

A description of the control and/or its purpose for use by accessibility tools such as readers for visually impaired users.

AccessibleName

String

A label that briefly describes the control, such as the text in a button or the name of a menu item.

AccessibleRole

AccessibleRole (enumerated)

Describes what kind of user interface element the control is.

BackColor

Long

Specifies the numeric value of the background color: -2 to 16,777,215. For more information about color, see the section called “RGB” in PowerScript Reference.

Border

Boolean

Specifies whether the control has a border. Values are:

TRUE -- Control has a border.

FALSE -- Control does not have a border.

BorderStyle

BorderStyle (enumerated)

Specifies the border style of the control. Values are:

StyleBox!

StyleLowered!

StyleRaised!

StyleShadowBox!

BringToTop

Boolean

Specifies whether PowerBuilder moves the control to the top of the front-to-back order. Values are:

TRUE -- Control is on top of other controls.

FALSE -- Control is not on top of other controls.

CheckBoxes

Boolean

Specifies whether the state images are replaced by check boxes. The check boxes are set to unchecked by default. The TreeView control processes mouse and keyboard input to toggle the checked state. Values are:

TRUE -- Check boxes are displayed.

FALSE -- Check boxes are not displayed.

The state of an item's check box can be determined by checking the state picture index for the item:

Unchecked = 1

Checked = 2

ClassDefinition

PowerObject

An object of type PowerObject containing information about the class definition of the object or control.

DeleteItems

Boolean

Specifies whether the user can delete a TreeView item from a TreeView control using the Delete key. Values are:

TRUE -- The user can delete items from the control.

FALSE -- The user cannot delete items from the control.

DisableDragDrop

Boolean

Disable Drag Drop determines whether events for dragging, such as BeginDrag, are triggered when the user clicks on an item and drags. Values are:

TRUE -- Drag events are not triggered.

FALSE -- Drag events are triggered.

DragAuto

Boolean

Specifies whether PowerBuilder puts the control automatically into Drag mode. Values are:

TRUE -- When the control is clicked, the control is automatically in Drag mode.

FALSE -- When the control is clicked, the control is not automatically in Drag mode. You have to manually put the control into Drag mode by using the Drag function.

In either case, DisableDragDrop must be set to false for dragging to occur.

DragIcon

String

Specifies the name of the stock icon or the file containing the icon you want to display when the user drags the control (the ICO file). The default icon is a box the size of the control.

When the user drags the control, the icon displays when the control is over an area in which the control can be dropped (a valid drop area). When the control is over an area that is not a valid drop area, the No-Drop icon displays.

EditLabels

Boolean

Specifies whether the user can edit the item labels in a control by clicking on a selected item. Values are:

TRUE -- The user can edit item labels.

FALSE -- The user cannot edit item labels.

Enabled

Boolean

Specifies whether the control is enabled (can be clicked). Values are:

TRUE -- Control can be clicked.

FALSE -- Control cannot be clicked.

FaceName

String

Specifies the name of the typeface in which the text of the control displays (for example, arial or courier).

FontCharSet

FontCharSet (enumerated)

Specifies the font character set used for the text in the control. The application must be running on an appropriate version of PowerBuilder under an operating system that supports the selected character set. For a complete list of possible values, see the list of properties for the FontCharSet variable on the Enumerated tab page of the Browser.

FontFamily

FontFamily (enumerated)

Specifies the font family (type style) used for the text in the control. Values are:

AnyFont!

Decorative!

Modern!

Roman!

Script!

Swiss!

FontPitch

FontPitch (enumerated)

Specifies the font pitch for the text in the control. Values are:

Default!

Fixed!

Variable!

FullRowSelect

Boolean

Specifies whether full row selection is enabled. Values are:

TRUE -- Clicking anywhere on a row causes the entire row to be selected, and selecting any item in the row causes the entire row to be highlighted.

FALSE -- Selecting one item in a row does not cause the entire row to be highlighted or selected.

This property cannot be used in conjunction with HasLines = TRUE.

HasButtons

Boolean

Specifies whether TreeView parent items have + and - buttons associated with them to indicate whether they are expanded (-) or collapsed (+). Values are:

TRUE -- Parent items have buttons.

FALSE -- Parent items do not have buttons.

If SingleExpand is set to true to specify that only one item can be expanded, more than one item can be expanded by clicking on the item buttons if HasButtons is also true.

HasLines

Boolean

Specifies whether TreeView items are connected by lines. Values are:

TRUE -- Items are connected by lines.

FALSE -- Items are not connected by lines.

Height

Integer

Specifies the height of the control, in PowerBuilder units.

HideSelection

Boolean

Specifies whether selected text stays selected (highlighted) even when the control does not have focus. Values are.

TRUE -- Text does not stay highlighted.

FALSE -- Text stays highlighted.

ImeMode

Integer

Specifies the input method editor mode. This property is relevant only to applications running on a Japanese version of PowerBuilder.

Indent

Integer

Specifies the size, in PowerBuilder units, that TreeView items are indented. Negative values are accepted but the items are outdented beyond the left edge of the control.

Room is always reserved for the regular picture, whether or not it is displayed. An indent of less than 90 has no effect for the standard picture width. Set PictureWidth to 0 to remove extra space.

Italic

Boolean

Specifies whether the text in the control is italic. Values are:

TRUE -- Text is italic.

FALSE -- Text is not italic.

LayoutRTL

Boolean

Specifies that the layout of the control should be a mirror image of the standard layout. Values are:

TRUE -- Elements in the control are right justified

FALSE -- Elements in the control are left justified (default).

LinesAtRoot

Boolean

Specifies whether PowerBuilder will connect TreeView root items with lines. Values are:

TRUE -- TreeView control connects root items with lines when HasLines is also true.

FALSE -- Control does not connect root items with lines.

PictureHeight

Integer

Specifies the size, in pixels, for the height of the TreeView item picture.

In a script, this value can be set only before a picture has been added to the picture index list.

If the picture height is 0, PowerBuilder uses the height of the first picture added to the picture index list.

PictureMaskColor

Long

Specifies the color to be transparent when used in a TreeView item picture. Used when the picture is added at initialization or with the function AddPicture, and can be changed between adds.

PictureName[ ]

String

Specifies the file path or URL address of the files containing the pictures added during initialization. The file extension BMP, ICO, GIF, JPG or JPEG is required.

Not updated after initialization.

PictureWidth

Integer

Specifies the size, in pixels, for the width of the TreeView item picture.

In a script, this value can be set only before a picture has been added to the picture index list.

If the picture width is 0, PowerBuilder uses the width of the first picture added to the picture index list.

Pointer

String

Specifies the name of the stock pointer or the file containing the pointer used for the control.

RightToLeft

Boolean

Specifies that characters should be displayed in right-to-left order. The application must be running on an operating system that supports right-to-left display. Values are:

TRUE -- Characters display in right-to-left order.

FALSE -- Characters display in left-to-right order (default).

SingleExpand

Boolean

Specifies whether only the selected TreeView item is allowed to be expanded. A single mouse click selects an item.

TRUE -- When an item is selected, it is automatically expanded and the previously selected item is automatically collapsed.

FALSE -- More than one item can be expanded at a time.

Note that if HasButtons = true, more than one item can be expanded at a time by clicking on the item buttons.

SortType

grSortType

Selects the sort method. Values are:

Ascending! -- Alphabetic by label.

Descending! -- Reverse-alphabetic by label.

UserDefinedSort! -- According to the script in the Sort event.

Unsorted! -- Not sorted.

When SortType specifies sorting, sorting happens automatically. For Unsorted!, you can call functions for alphabetic sorting.

StatePictureHeight

Integer

Specifies the size, in pixels, for the height of the state picture.

In a script, this value can be set only before a state picture has been added to the state picture list.

If the state picture height is 0, PowerBuilder uses the height of the first picture added to the state picture index list.

StatePictureMaskColor

Long

Specifies the color to be transparent when used in a state picture. Used when the picture is added at initialization or with the function AddStatePicture, and can be changed between adds.

StatePictureName[ ]

String

Specifies the file path or URL address of the picture used as the state picture. The state picture is displayed to the left of the regular picture. The item is shifted right to make room for it.

The picture can be an icon, cursor, or bitmap supplied by the user or a stock picture from the PowerBuilder library. Not updated after initialization.

StatePictureWidth

Integer

Specifies the size in pixels for the width of the state picture.

In a script, this value can be set only before a state picture has been added to the state picture list.

If the state picture width is 0, PowerBuilder uses the width of the first picture added to the state picture index list.

TabOrder

Integer

Specifies the tab value of the control within the window (0 means the user cannot tab to the control).

Tag

String

Specifies the tag value assigned to the control.

TextColor

Long

Specifies the numeric value of the color used for text: -2 to 16,777,215.

TextSize

Integer

Specifies the size of the text in the control, in points.

For backward compatibility, the size is stored as a negative number; for example, 10-point text size is stored as -10.

ToolTips

Boolean

Specifies whether an item's label should be displayed in a tooltip if the label is cut off by the right edge of the control. Values are:

TRUE -- Tooltips displaying the label text are displayed when the label is cut off on the right side. This is the default.

FALSE -- Tooltips are not displayed.

TrackSelect

Boolean

Specifies whether items appear in a different color when the mouse moves over them (hot tracking). Values are:

TRUE -- An item changes color when the mouse moves over it.

FALSE -- An item does not change color when the mouse moves over or pauses on it.

Underline

Boolean

Specifies whether the text in the control is underlined. Values are:

TRUE -- Text is underlined.

FALSE -- Text is not underlined.

Visible

Boolean

Specifies whether the control is visible. Values are:

TRUE -- Control is visible.

FALSE -- Control is not visible.

Weight

Integer

Specifies the stroke weight of the text in the control; for example, 400 for normal or 700 for bold.

Width

Integer

Specifies the width of the control, in PowerBuilder units.

X

Integer

Specifies the X position (the distance from the left edge of the window), in PowerBuilder units.

Y

Integer

Specifies the Y position (the distance from the top of the window), in PowerBuilder units.


Events

TreeView event

Occurs

BeginDrag

When the user begins a drag operation with the left mouse button. If the DragAuto property is set to true, the drag begins automatically. If the DragAuto property is set to false, the drag operation must be done programmatically.

BeginLabelEdit

When the user starts to edit a TreeView item label. Return 1 to prevent setting to the new text. Return 0 to accept the new text.

BeginRightDrag

When the user begins a drag operation with the right mouse button. If the DragAuto property is set to true, the drag begins automatically. If the DragAuto property is set to false, the drag operation must be done programmatically.

Clicked

When the control is clicked.

Constructor

When the object is created, immediately before the Open event occurs in the window.

DeleteItem

When a TreeView item is deleted.

Destructor

When the object is destroyed, immediately after the Close event occurs in the window.

DoubleClicked

When the control is double-clicked.

DragDrop

When a dragged control is dropped on the TreeView control.

DragEnter

When a dragged control enters the control, including entering the narrow border around the display area.

DragLeave

When a dragged control leaves the control, including leaving by crossing into the tab page display area.

DragWithin

When a dragged control is within the control, but not on a TreeView item.

EndLabelEdit

When the user finishes editing a TreeView item label. Return 1 to prevent setting to the new text. Return 0 to accept the new text.

GetFocus

Just before the control receives focus (before it is selected and becomes active).

Help

When the user presses the F1 key or drags the context help button (question mark) from the title bar to a menu item or control.

ItemCollapsed

When an item has collapsed.

ItemCollapsing

When an item is collapsing. Return 1 to prevent collapsing or 0 to allow it.

ItemExpanded

When an item has expanded.

ItemExpanding

When an item is expanding. Return 1 to prevent expansion or 0 to allow it.

If you want to populate the children each time an item expands, do it in the ItemExpanding event.

If no children are created during the ItemPopulate or Item Expanding events, the item does not expand.

ItemPopulate

When an item is expanding for the first time. Return 1 to prevent expansion or 0 to allow it.

If no children are created during the ItemPopulate or Item Expanding events, the item does not expand.

Key

When the user presses a key.

LoseFocus

When the control loses focus (becomes inactive).

Notify

When a TreeView control sends a wm_notify message to its parent.

Other

When a Windows message occurs that is not a PowerBuilder event.

RightClicked

When the control is right-clicked.

RightDoubleClicked

When the control is right double-clicked.

SelectionChanged

When the selection has changed.

SelectionChanging

When the selection is changing. Return 1 to prevent the selection from changing or 0 to allow it.

Sort

When sorting occurs and the SortType property is set to UserDefinedSort! The event occurs for each pair of items being sorted.


Functions

TreeView function

Datatype returned

Description

AddPicture

Integer

Adds an icon, cursor, or bitmap to the image list. Does not update PictureName.

AddStatePicture

Integer

Adds an icon, cursor, or bitmap to the state image list. Does not update StatePictureName.

ClassName

String

Returns the name of the control.

CollapseItem

Integer

Collapses the specified TreeView item.

DeleteItem

Integer

Deletes the specified TreeView item and all its children, if any.

DeletePicture

Integer

Deletes the specified icon, cursor, or bitmap from the image list.

DeletePictures

Integer

Deletes all icons, cursors, or bitmaps from the image list.

DeleteStatePicture

Integer

Deletes the specified icon, cursor, or bitmap from the state image list.

DeleteStatePictures

Integer

Deletes all icons, cursors, or bitmaps from the state image list.

Drag

Integer

Starts or ends the dragging of a TreeView item.

EditLabel

Integer

Starts the editing of a specific TreeView item label.

ExpandAll

Integer

Expands the children and subsequent levels for the specified TreeView item.

ExpandItem

Integer

Expands the specified TreeView item.

FindItem

Long

Returns the handle for the specified TreeView item.

GetContextService

Integer

Creates a reference to a context-specific instance of the specified service.

GetItem

Integer

Retrieves information for a specified item.

GetItemAtPointer

Integer

Gets the handle or the index of the item under the cursor.

GetParent

PowerObject

Returns a reference to the name of the parent object.

Hide

Integer

Hides the specified TreeView item.

InsertItem

Long

Inserts a specified item at a specified position and level in a TreeView control.

InsertItemFirst

Long

Inserts a specified item as the first item at a specified level.

InsertItemLast

Long

Inserts a specified item as the last item at a specified level.

InsertItemSort

Long

Inserts a specified item at a specified level in the correct alphabetic position, if possible.

Move

Integer

Moves a control or object to a specified location.

PointerX

Integer

Determines the distance from the left edge of an object to the pointer location.

PointerY

Integer

Determines the distance from the top edge of an object to the pointer location.

PostEvent

Boolean

Adds the event to the end of the event queue of an object.

Print

Integer

Includes an object or lines of text in a print job.

Resize

Integer

Resizes a control to the specified dimensions.

SelectItem

Integer

Highlights an item in the control, making it the current item.

SetDropHighlight

Integer

Designates the specified TreeView item as the target of a DragDrop operation.

SetFirstVisible

Integer

Sets the specified TreeView item as the first item visible in a TreeView control. If there are enough items to allow it, the specified item scrolls to the top of the control. If not, it is selected.

SetFocus

Integer

Sets the focus for a specified object or control.

SetItem

Integer

Sets the information for the specified TreeView item.

SetLevelPictures

Integer

Specifies a picture index for all TreeView items at a specific level in a TreeView control.

SetOverlayPicture

Integer

Maps a picture index to an overlay picture index. Only four overlay picture indexes are available.

SetPosition

Integer

Sets the position of the TreeView control in the front-to-back order within a window.

SetRedraw

Integer

Controls the automatic redraw of an object after its properties have changed.

Show

Integer

Makes an object or control visible, if it is hidden. If the object is already visible, Show brings it to the top.

Sort

Integer

Sorts the children of a specified TreeView item according to the method of the SortType property or alphabetically if SortType is Unsorted!.

SortAll

Integer

Sorts the children of an item and all subsequent levels according to the method of the SortType property or alphabetically if SortType is Unsorted!.

TriggerEvent

Integer

Triggers a specified event in the control and executes the script for the event.

TypeOf

Object

Returns the type of the control.