Window control

Windows are the main interface between the user and a PowerBuilder application. Windows can display information, request information from a user, and respond to the user's mouse or keyboard actions.

The definition of a window includes properties, events, and functions. The properties determine the style of the window -- how it looks. The events are actions in the window; when an event is triggered, the associated script is executed. The functions can trigger events in the window, manipulate or change the window, or provide information about the window.

Properties

Every window has a style that determines how it looks to the user. That style is governed by values assigned to the properties of the window.

Window property

Datatype

Description

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.

AnimationTime

Integer

Specifies how long an animation specified with the OpenAnimation or CloseAnimation property plays. Value is a positive integer in the range 1 to 5000 milliseconds. The default is 200 milliseconds.

BackColor

Long

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

Border

Boolean

Specifies whether the window has a border. Values are:

  • TRUE -- Has a border.

  • FALSE -- Does not have a border.

BringToTop

Boolean

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

  • TRUE -- Moves to the top.

  • FALSE -- Does not move to the top.

Center

Boolean

Causes the window to be centered when it is created or sized. Values are:

  • TRUE -- Window is centered.

  • FALSE -- Window is not centered.

ClassDefinition

PowerObject

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

ClientEdge

Boolean

Specifies whether the client area of the window appears sunken within the frame.

  • TRUE -- Client area appears sunken.

  • FALSE -- Client area does not appear sunken.

CloseAnimation

WindowAnimationStyle (enumerated)

Specifies an optional animation effect that displays when the window closes.

ColumnsPerPage

Integer

Specifies the number of columns on a 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 the number of PowerBuilder units to scroll the window horizontally when the user clicks in the scroll bar.

ContextHelp

Boolean

When WindowType = Response!, this property specifies whether the small question mark button appears in the title bar. The question mark button can fire the Help event on the control that is clicked next.

  • TRUE  -- Question mark button is displayed in title bar next to minimize button in Response windows.

  • FALSE -- Question mark button is not displayed.

Control[ ]

WindowObject

Contains the controls in the window. You should not change the contents of this array in a script.

ControlMenu

Boolean

Specifies whether the Control Menu box displays in the title bar. Values are:

  • TRUE -- Displays in title bar.

  • FALSE -- Does not display in title bar.

Enabled

Boolean

Specifies whether the window is enabled (can send and receive messages). Values are:

  • TRUE -- Can send/receive messages.

  • FALSE -- Cannot send/receive messages.

Height

Integer

Specifies the height of the window, in PowerBuilder units.

You cannot resize minimized or maximized windows at runtime.

HScrollBar

Boolean

Specifies whether a horizontal scroll bar displays in the window. Values are:

  • TRUE -- A scroll bar displays.

  • FALSE -- A scroll bar does not display.

Icon

String

Specifies a stock icon or an ICO file that displays when the window is minimized.

The default value is AppIcon!, which is the icon selected for the Application object. If no icon is selected for the Application object, the Windows logo is used.

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 the number of PowerBuilder units to scroll the window vertically when the user clicks in the scroll bar.

MaxBox

Boolean

Specifies whether a Maximize Box displays in the title bar. Values are:

  • TRUE -- Maximize Box displays.

  • FALSE -- Maximize Box does not display.

MenuID

Menu

Specifies the ID of a menu.

PowerBuilder uses MenuID internally. To change the menu for a window from a script, use the ChangeMenu function; to display a pop-up menu, use the PopMenu function. In both functions, enter the fully qualified name to identify the menu or Menu object.

MenuName

String

Specifies the name of a menu.

PowerBuilder uses MenuName internally. To change the menu for a window from a script, use the ChangeMenu function; to display a pop-up menu, use the PopMenu function. In both functions, enter the fully qualified name to identify the menu or Menu object.

MinBox

Boolean

Specifies whether a Minimize Box displays in the title bar. Values are:

  • TRUE -- Minimize Box displays.

  • FALSE -- Minimize Box does not display.

OpenAnimation

WindowAnimationStyle (enumerated)

Specifies an optional animation effect that displays when the window opens.

PaletteWindow

Boolean

When WindowType = Popup!, this property specifies that the window has an appearance appropriate for small palette windows that display over the application.

  • TRUE  -- Pop-up window displays as the topmost window with a smaller Close button in the title bar and no Minimize or Maximize buttons.

  • FALSE -- No change in appearance.

Pointer

String

Specifies the name of the file containing the pointer that is used for the window.

Resizable

Boolean

Specifies whether the window is resizable. Values are:

  • TRUE -- Window is resizable.

  • FALSE -- Window is not resizable.

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.

Tag

String

Specifies the tag value assigned to the window.

Tabs

Enumerated

Properties for the shapes of the tabs:

  • windowdocktabslanted!

  • windowdocktabrectangular!

  • windowdocktabsingleslanted!

Location of the close button on a tab, if any:

  • windowdocktabclosebuttonnone!

  • windowdocktabclosebuttononactive!

  • windowdocktabclosebuttonshared!

Colors of tabs:

  • gradients are available

  • default to theme colors is available

Icon and Scroll Button for tabbed windows or documents:

  • TabbedWindowTabIcon / TabbedDocumentTabIcon

  • TabbedWindowTabScroll / TabbedDocumentTabScroll

Tabbed Window and Document Title Bars

Enumerated

Colors of tabbed window and document title bars:

  • TabbedWindowActiveTabBackColor / TabbedDocumentActiveTabBackColor

  • TabbedWindowActiveTabGradientBackColor / TabbedDocumentActiveTabGradientBackColor

  • TabbedWindowActiveTabTextColor / TabbedDocumentActiveTabTextColor

  • TabbedWindowInActiveTabBackColor / TabbedDocumentInActiveTabBackColor

  • TabbedWindowInActiveTabGradientBackColor / TabbedDocumentInActiveTabGradientBackColor

  • TabbedWindowInActiveTabTextColor / TabbedDocumentInActiveTabTextColor

  • TabbedWindowMouseoverTabBackColor / TabbedDocumentMouseoverTabBackColor

  • TabbedWindowMouseoverTabGradientBackColor / TabbedDocumentMouseoverTabGradientBackColor

  • TabbedWindowMouseoverTabTextColor / TabbedDocumentMouseoverTabTextColor

  • TabbedWindowTabsAreaColor / TabbedDocumentTabsAreaColor

  • TabbedWindowTabsAreaGradientColor / TabbedDocumentTabsAreaGradientColor

  • TabbedWindowTabsAreaGradientVert / TabbedDocumentTabsAreaGradientVert

Title bar states:

  • TitleBarActiveColor / TitleBarInActiveColor

  • TitleBarActiveGradientColor / TitleBarInActiveGradientColor

  • TitleBarActiveGradientVert / TitleBarInActiveGradientVert

  • TitleBarActiveaTextColor / TitleBarInActiveTextColor

Title

String

Specifies the text of the window title.

TitleBar

Boolean

Specifies whether a title bar displays. Values are:

  • TRUE -- Title bar displays.

  • FALSE -- No title bar displays.

The user can move a window only if it has a title bar.

ToolbarAlignment

ToolbarAlignment (enumerated)

In an MDI frame window, specifies where the toolbar displays. Values are:

  • AlignAtBottom!

  • AlignAtLeft!

  • AlignAtRight!

  • AlignAtTop!

  • Floating!

ToolbarHeight

Integer

In an MDI frame window, specifies the height of the toolbar when it is a floating toolbar.

ToolbarVisible

Boolean

In an MDI frame window, specifies whether the toolbar displays. Values are:

  • TRUE -- Toolbar displays.

  • FALSE -- Toolbar does not display.

ToolbarWidth

Integer

In an MDI frame window, specifies the width of the toolbar when it is a floating toolbar.

ToolbarX

Integer

In an MDI frame window, specifies the X coordinate (distance from the left edge of the window, in PowerBuilder units) of the toolbar when it is a floating toolbar.

ToolbarY

Integer

In an MDI frame window, specifies the Y coordinate (distance from the top of the window, in PowerBuilder units) of the toolbar when it is a floating toolbar.

Transparency

Integer

Specifies the transparency of a window. Value is a percentage in the range 0 (opaque) to 100 (completely transparent).

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 window is visible. Values are:

  • TRUE -- Window is visible.

  • FALSE -- Window is not visible.

VScrollBar

Boolean

Specifies whether a vertical scroll bar displays. Values are:

  • TRUE -- Scroll bar displays.

  • FALSE -- Scroll bar does not display.

Width

Integer

Specifies the width of the window, in PowerBuilder units.

You cannot resize minimized or maximized windows at runtime.

WindowDockOptions

WindowDockOptions (enumerated)

WindowDockOptions are for child windows to specify how they can be opened:

  • WindowDockOptionAll!

  • WindowDockOptionTabbedDocumentOnly!

  • WindowDockOptionDockedOnly!

  • WindowDockOptionFloatOnly!

  • WindowDockOptionTabbedDocumentAndDockedOnly!

  • WindowDockOptionTabbedDocumentAndFloatOnly!

  • WindowDockOptionDockedAndFloatOnly!

WindowDockState

WindowDockState (enumerated)

Specifies the docking behaviors for the sheets that open in the MDI (multiple document interface) frame window. Values are:

  • WindowDockStateDocked!

  • WindowDockStateFloating!

  • WindowDockStateTabbedDocument!

  • WindowDockStateTabbedWindow!

WindowState

WindowState (enumerated)

Specifies the state in which you want to run a window. Values are:

  • Maximized!

  • Minimized!

  • Normal!

Do not change the WindowState property in the Open event of a window opened as a sheet.

WindowType

WindowType (enumerated)

Specifies the type of window. Values are:

  • Child!

  • Main!

  • MDI!

  • MDIHelp!

  • MDIDock!

  • MDIDockHelp!

  • Popup!

  • Response!

X

Integer

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

The values of the X coordinates in all windows except child windows are measured from the left side of the screen. In child windows, they are measured from the left side of the workspace of the parent window.

The workspace is the area between the sides of the window (not including the thickness of the frame, toolbar, or scroll bar, if any) and the top and bottom of the window (not including the thickness of the border or the title bar, menu bar, toolbar, or scroll bar, if any).

You cannot move a maximized window at runtime.

Y

Integer

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

The values of the Y coordinates in all windows except child windows are measured from the top of the screen. In child windows, they are measured from the top of the workspace of the parent window.

The workspace is the area between the sides of the window (not including the thickness of the frame, toolbar, or scroll bar, if any) and the top and bottom of the window (not including the thickness of the border or the title bar, menu bar, toolbar, or scroll bar, if any).

You cannot move a maximized window at runtime.


Events

Scripts for events in a window and the controls in the window determine how the window behaves. Scripts control the action that is initiated when an event occurs within the window.

Window event

Occurs

Activate

Just before the window becomes active. When an Activate event occurs, the first object in the tab order for the window gets focus. If there are no enabled objects in the window, the window gets focus.

Clicked

When the user clicks in an unoccupied area of the window (any area with no visible, enabled object).

Close

When the window is closed.

CloseQuery

When you remove a window from display (close it). When you close a window, PowerBuilder triggers the CloseQuery event and then inspects the value of Message.ReturnValue. If the Message.ReturnValue is 1, the window cannot be closed.

Closing any window causes PowerBuilder to close all child and pop-up windows that it opened, and closing an MDI Frame window causes PowerBuilder to close all sheet windows within it. Any window thus closed can set Message.ReturnValue to cancel the close operation.

Deactivate

When the window becomes inactive.

DoubleClicked

When the user double-clicks in an unoccupied area of the window (any area with no visible, enabled object).

DragDrop

When a dragged control is dropped on the window.

DragEnter

When a dragged control enters the window.

DragLeave

When a dragged control leaves the window.

DragWithin

When a dragged control is within the window.

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.

Hide

Just before the window is hidden.

HotLinkAlarm

After a Dynamic Data Exchange (DDE) server application has sent new (changed) data and the client DDE application has received it.

Key

When the user presses a key and the insertion point is not in a RichTextEdit or DataWindow edit control.

MouseDown

When the user presses the left mouse button in an unoccupied area of the window (any area with no visible, enabled object).

MouseMove

When the pointer is moved within the window.

MouseUp

When the user releases the left mouse button in an unoccupied area of the window (any area with no visible, enabled object).

Open

When a script executes the Open function for a window. The event occurs after the window has been opened but before it is displayed.

Other

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

RButtonDown

When the right mouse button is pressed in an unoccupied area of the window (any area with no visible, enabled object).

RemoteExec

When a DDE client application has sent a command.

RemoteHotLinkStart

When a DDE client application wants to start a hot link.

RemoteHotLinkStop

When a DDE client application wants to end a hot link.

RemoteRequest

When a DDE client application requests data.

RemoteSend

When a DDE client application has sent data.

Resize

When the user or a script opens or resizes a window.

Show

When a script executes the Show function for this window. The event occurs just before the window is displayed.

SystemKey

When the user presses Alt or Alt plus another key, except when the insertion point is in a DataWindow control or RichTextEdit control.

Timer

When a specified number of seconds elapses after the Timer function has been called.

ToolbarMoved

In an MDI frame window, when the user moves the FrameBar or SheetBar.


Functions

The following functions can trigger events in a window, manipulate or change a window, or provide information about a window.

PowerScript system functions

You can also use the PowerScript system functions in scripts for a window. For a list of the PowerScript system functions, see the Browser.

Opening and closing a window

Use the Open function to open a window and the Close function to close a window. Open and Close are system functions and are not listed here.

Window function

Datatype returned

Description

ArrangeSheets

Integer

Arranges the sheets or icons in the specified MDI frame window.

ChangeMenu

Integer

Changes the menu associated with a window.

ClassName

String

Returns the name assigned to the window.

CloseChannel

Integer

Closes a DDE channel.

CloseUserObject

Integer

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

CommitDocking

Integer

After all persisted sheets are opened, this function arranges them and makes them visible.

ExecRemote

Integer

Asks a DDE server application to execute the specified command.

GetActiveSheet

Window

Returns the currently active sheet in the specified MDI frame window.

GetCommandDDE

Integer

Obtains the command sent by the client application when your application is a DDE server.

GetCommandDDEOrigin

Integer

When called by the DDE server application, obtains the application name parameter used by the DDE client sending the command.

GetContextService

Integer

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

GetDataDDE

Integer

Obtains data sent from another DDE application and stores it in the specified string variable.

GetDataDDEOrigin

Integer

Determines the origin of data from a hot-linked DDE server application or a DDE client application and, if successful, stores the application's DDE identifiers in the specified strings.

GetFirstSheet

Window

Returns the top sheet in the MDI frame.

GetNextSheet

Window

Returns the sheet that is behind the specified sheet in the MDI frame.

GetParent

PowerObject

Returns a reference to the name of the parent object.

GetRemote

Integer

Asks a DDE server application to provide data and stores that data in the specified variable.

GetToolbar

Integer

Gets the values of the Visible, Alignment, and Title properties of the toolbar.

GetToolbarPos

Integer

Gets position information (coordinates) for a floating toolbar.

Hide

Integer

Makes the window invisible.

LoadDockingState

Integer

Loads two arrays of equal size: type names of persisted sheets and the corresponding IDs.

Move

Integer

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

The Move function does not move a maximized or minimized window.

OpenChannel

Long

Opens a channel to a DDE server application.

OpenSheet

Integer

Opens a sheet within an MDI (multiple document interface) frame window and creates a menu item for selecting the sheet on the specified menu.

OpenSheetAsDocument

Integer

Opens a sheet as a document within an MDI frame window for dockable windows.

OpenSheetDocked

Integer

Opens a sheet docked in a specified position within an MDI frame window for dockable windows.

OpenSheetFromDockingState

Integer

Opens one or more persisted sheets within an MDI frame window for dockable windows.

OpenSheetInTabGroup

Integer

Opens a sheet in a tab group within an MDI frame window for dockable windows.

OpenSheetWithParm

Integer

Opens a sheet within an MDI (multiple document interface) frame window and creates a menu item for selecting the sheet on the specified menu, as OpenSheet does and also stores a parameter in the system's Message object.

OpenSheetWithParmAsDocument

Integer

Opens a sheet as a document within an MDI frame window for dockable windows and stores a parameter in the system's Message object.

OpenSheetWithParmDocked

Integer

Opens a sheet docked in a specified position within an MDI frame window for dockable windows and stores a parameter in the system's Message object .

OpenSheetWithParmFromDockingState

Integer

Opens one or more persisted sheets within an MDI frame window for dockable windows and stores a parameter in the system's Message object.

OpenSheetWithParmInTabGroup

Integer

Opens a sheet in a tab group within an MDI frame window for dockable windows and stores a parameter in the system's Message object.

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.

ParentWindow

Window

Returns the parent window of the window.

PointerX

Integer

Returns the distance from the left edge of the screen to the pointer.

PointerY

Integer

Returns the distance from the top of the screen to the pointer.

PostEvent

Boolean

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

Print

Integer

Prints the window.

Resize

Integer

Changes the size of the window to the size specified in the width and height arguments.

The Resize function does not resize a minimized or maximized window.

RespondRemote

Integer

Sends a DDE message indicating whether the command or data received from a remote DDE application was acceptable.

SaveDockingState

Integer

Stores the MDI state in the registry.

SetDataDDE

Integer

Sends data to a DDE client application when PowerBuilder is acting as a DDE server.

SetFocus

Integer

Sets focus to the specified window.

SetMicroHelp

Integer

Sets the MicroHelp text in the specified MDI frame window.

SetPosition

Integer

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

SetRedraw

Integer

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

SetRemote

Integer

Asks a DDE server application to accept data and store it in the specified location.

SetSheetID

Integer

Sets the unique identifier for an open sheet.

SetToolbar

Integer

Sets the values of the Visible, Alignment, and Title properties of the toolbar.

SetToolbarPos

Integer

Sets the position of a fixed toolbar.

Show

Integer

Makes the window visible.

StartHotLink

Integer

Establishes a hot link with a DDE server application so that PowerBuilder is notified immediately of any changes in the specified data.

StartServerDDE

Integer

Establishes your application as a DDE server.

StopHotLink

Integer

Terminates a hot link with a DDE server application.

StopServerDDE

Integer

Causes your application to stop acting as a DDE server application.

TriggerEvent

Integer

Sends an event to a window control and executes the script associated with the event.

TypeOf

Object

Returns the type of the window.

WorkSpaceHeight

Integer

Returns the height of the workspace of the specified window.

The workspace is the area between the sides of the window (not including the thickness of the frame, toolbar, or scroll bar, if any) and the top and bottom of the window (not including the thickness of the border or the title bar, menu bar, toolbar, or scroll bar, if any).

WorkSpaceWidth

Integer

Returns the width of the workspace of the specified window.

WorkSpaceX

Integer

Returns the distance from the left edge of the screen to the left edge of the workspace of the specified window.

WorkSpaceY

Integer

Returns the distance from the top of the screen to the top of the workspace of the specified window.