UserObject object

UserObjects are custom visual objects that you can build to supplement the standard PowerBuilder objects. UserObjects can display information, request information from a user, and respond to mouse or keyboard actions. You can also create a TabPage UserObject. Use the User Object painter to build UserObjects.

When you place a visible UserObject in a window, you are actually placing a UserObject control in the window. The control holds an instance of the UserObject you select for the window.

Properties

UserObject property

Datatype

Description

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 object has a border. Values are:

TRUE -- Object has a border.

FALSE -- Object does not have a border.

BorderStyle

BorderStyle (enumerated)

Specifies the style of the border of the object. Values are:

StyleBox!

StyleLowered!

StyleRaised!

StyleShadowBox!

BringToTop

Boolean

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

TRUE -- Object moved to top.

FALSE -- Object not moved to top.

ClassDefinition

PowerObject

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

ClassName

String

(External user objects only) Returns the name assigned to the object.

ColumnsPerPage

Integer

Specifies the number of columns on a scroll page. The default is 0 (10 columns per page). For information, see Scrolling in windows and user objects.

PowerBuilder multiplies UnitsPerColumn by ColumnsPerPage to determine how many PowerBuilder units to scroll the object horizontally when the user clicks in the scroll bar.

Control[ ]

WindowObject

Specifies the control's objects. You cannot change the contents of this array in a script.

DragAuto

Boolean

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

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

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

DragIcon

String

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

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

Enabled

Boolean

Specifies whether the object is enabled (can be selected). Values are:

TRUE -- Object can be selected.

FALSE -- Object cannot be selected.

Height

Integer

Specifies the height of the object, in PowerBuilder units.

HScrollBar

Boolean

Specifies whether a horizontal scroll bar displays. Values are:

TRUE -- Horizontal scroll bar displays.

FALSE -- Horizontal scroll bar does not display.

LibraryName

String

(External user objects only) The name of the dynamic-link library (DLL) that contains an external user object class.

LinesPerPage

Integer

Specifies the number of lines on a page. The default is 0 (10 lines per page). For information, see Scrolling in windows and user objects.

PowerBuilder multiplies UnitsPerLine by LinesPerPage to determine how many PowerBuilder units to scroll the object vertically when the user clicks in the scroll bar.

ObjectType

UserObjects (enumerated)

Specifies the type of user object. Valid values are:

CustomVisual!

ExternalVisual!

PictureMaskColor

Long

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

This property applies only when PictureName is a bitmap and only when the UserObject is a tab page.

PictureName

String

Specifies a value of the Pointer enumerated datatype or the filename of the bitmap, cursor, or icon or to be displayed on the tab.

This property applies only when the UserObject is a tab page.

Pointer

String

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

PowerTipText

String

Specifies text to be displayed as a PowerTip for the tab when the Tab control's PowerTips property is true. This property applies only when the UserObject is a tab page.

Style

Long

Specifies any additional style bits you want to use to control how the object displays (external user object only).

TabBackColor

Long

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

This property applies only when the UserObject is a tab page. It is not supported on Windows XP because the current XP theme controls the appearance of the tab.

TabTextColor

Long

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

This property applies only when the UserObject is a tab page.

TabOrder

Integer

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

Tag

String

Specifies the tag value assigned to the object.

Text

String

Specifies the text that displays in the object.

UnitsPerColumn

Integer

Specifies the number of PowerBuilder units to be scrolled right or left when a user clicks the left or right arrow in the horizontal scroll bar in a window or user object. The default is 0 (1/100 of the width of the window).

To make the end of the scroll bar match the content, UnitsPerLine must be set according to the content width. For information, see Scrolling in windows and user objects.

PowerBuilder multiplies UnitsPerColumn by ColumnsPerPage to determine the number of PowerBuilder units to scroll the window horizontally when the user clicks in the scroll bar.

UnitsPerLine

Integer

Specifies the number of PowerBuilder units to be scrolled up or down when a user clicks the up or down arrow in the vertical scroll bar in a window or user object. The default is 0 (1/100 of the window height).

To make the end of the scroll bar match the content, UnitsPerLine must be set according to the content length. For information, see Scrolling in windows and user objects.

PowerBuilder multiplies UnitsPerLine by LinesPerPage to determine the number of PowerBuilder units to scroll the window vertically when the user clicks in the scroll bar.

Visible

Boolean

Specifies whether the object is visible. Values are:

TRUE -- Object is visible.

FALSE -- Object is not visible.

VScrollBar

Boolean

Specifies whether a vertical scroll bar displays. Values are:

TRUE -- Vertical scroll bar displays.

FALSE -- Vertical scroll bar does not display.

Width

Integer

Specifies the width of the object, in PowerBuilder units.

X

Integer

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

Y

Integer

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


Events

UserObject event

Occurs

Constructor

Immediately before the Open event occurs in the window

Destructor

Immediately after the Close event occurs in the window

DragDrop

When a dragged control is dropped on the object

DragEnter

When a dragged control enters the object

DragLeave

When a dragged control leaves the object

DragWithin

When a dragged control is within the object

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

Other

When a Windows message occurs that is not a PowerBuilder event

RButtonDown

When the right mouse button is pressed on the object


Functions

UserObject function

Datatype returned

Description

AddItem

Integer

Adds item to list.

ClassName

String

Returns the name assigned to the object.

CloseUserObject

Integer

Removes the specified user object from view, closes it, and executes its Destructor event.

CreatePage

Integer

Creates a tab page if it has not already been created.

DeleteItem

Integer

Deletes item from list.

Drag

Integer

Starts or ends the dragging of the object.

GetContextService

Integer

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

GetParent

PowerObject

Returns a reference to the name of the parent object.

Hide

Integer

Makes the object invisible.

InsertItem

Integer

Inserts item in list.

Move

Integer

Places the object in a new location specified by the X and Y arguments.

OpenUserObject

Integer

Displays the specified user object, making its properties available to scripts.

OpenUserObjectWithParm

Integer

Displays the specified user object, making its properties available to scripts, and stores a parameter in the system's Message object.

PageCreated

Boolean

Reports whether a tab page has been created.

PointerX

Integer

Returns the distance from the left edge of the screen to the pointer, in PowerBuilder units.

PointerY

Integer

Returns the distance from the top of the screen to the pointer, in PowerBuilder units.

PostEvent

Boolean

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

Print

Integer

Prints the object.

Resize

Integer

Changes the size of the object based on the width and height.

SetFocus

Integer

Sets focus to the object.

SetPosition

Integer

Specifies the position of the object in the front-to-back order of the window.

SetRedraw

Integer

Turns on or off automatic redrawing of the object after every change.

Show

Integer

Makes the object visible.

TriggerEvent

Integer

Sends an event to the object and executes the script associated with the event.

TypeOf

Object

Returns the type of the object.