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.
Dockable windows are obsolete
Dockable windows become obsolete at the release of PowerBuilder 2019 R2. Obsolete features are no longer eligible for technical support and will no longer be enhanced. Customers who use dockable windows in their applications can choose to continue using the feature without support or migrate to normal floating windows.
Height of window title bar
The height of the window title bar is 100 pixels in PowerBuilder 2021 and earlier; while it is 140 pixels in PowerBuilder 2022 and later.
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 |
|---|---|---|
|
String |
A description of the control and/or its purpose for use by accessibility tools such as readers for visually impaired users. |
|
|
String |
A label that briefly describes the control, such as the text in a button or the name of a menu item. |
|
|
AccessibleRole (enumerated) |
Describes what kind of user interface element the control is. |
|
|
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. |
|
|
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. |
|
|
Boolean |
Specifies whether the window has a border. Values are:
|
|
|
Boolean |
Specifies whether PowerBuilder moves the window to the top of the front-to-back order. Values are:
|
|
|
Boolean |
Causes the window to be centered when it is created or sized. Values are:
|
|
|
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.
|
|
WindowAnimationStyle (enumerated) |
Specifies an optional animation effect that displays when the window closes. |
|
|
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.
|
|
Control[ ] |
WindowObject |
Contains the controls in the window. You should not change the contents of this array in a script. |
|
Boolean |
Specifies whether the Control Menu box displays in the title bar. Values are:
|
|
|
Boolean |
Specifies whether the window is enabled (can send and receive messages). Values are:
|
|
|
Integer |
Specifies the height of the window, in PowerBuilder units. You cannot resize minimized or maximized windows at runtime. |
|
|
Boolean |
Specifies whether a horizontal scroll bar displays in the window. Values are:
|
|
|
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. |
|
|
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. |
|
|
Boolean |
Specifies whether a Maximize Box displays in the title bar. Values are:
|
|
|
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. |
|
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. |
|
|
Boolean |
Specifies whether a Minimize Box displays in the title bar. Values are:
|
|
|
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.
|
|
String |
Specifies the name of the file containing the pointer that is used for the window. |
|
|
String |
Specifies the text to display as PowerTip when the user moves a cursor over the tab header of the sheet window. |
|
|
Boolean |
Specifies whether the window is resizable. Values are:
|
|
|
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:
|
|
|
String |
Specifies the tag value assigned to the window. |
|
|
Tabs |
Enumerated |
Properties for the shapes of the tabs:
Location of the close button on a tab, if any:
Colors of tabs:
Icon and Scroll Button for tabbed windows or documents:
|
|
Tabbed Window and Document Title Bars |
Enumerated |
Colors of tabbed window and document title bars:
Title bar states:
|
|
String |
Specifies the text of the window title. |
|
|
Boolean |
Specifies whether a title bar displays. Values are:
The user can move a window only if it has a title bar. |
|
|
ToolbarAlignment (enumerated) |
In an MDI frame window, specifies where the toolbar displays. Values are:
|
|
|
Integer |
In an MDI frame window, specifies the height of the toolbar when it is a floating toolbar. |
|
|
Boolean |
In an MDI frame window, specifies whether the toolbar displays. Values are:
|
|
|
Integer |
In an MDI frame window, specifies the width of the toolbar when it is a floating toolbar. |
|
|
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. |
|
|
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. |
|
|
Integer |
Specifies the transparency of a window. Value is a percentage in the range 0 (opaque) to 100 (completely transparent). |
|
|
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. |
|
|
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. |
|
|
Boolean |
Specifies whether the window is visible. Values are:
|
|
|
Boolean |
Specifies whether a vertical scroll bar displays. Values are:
|
|
|
Integer |
Specifies the width of the window, in PowerBuilder units. You cannot resize minimized or maximized windows at runtime. |
|
|
WindowDockOptions (enumerated) |
WindowDockOptions are for child windows to specify how they can be opened:
|
|
|
WindowDockState (enumerated) |
Specifies the docking behaviors for the sheets that open in the MDI (multiple document interface) frame window. Values are:
|
|
|
WindowState (enumerated) |
Specifies the state in which you want to run a window. Values are:
Do not change the WindowState property in the Open event of a window opened as a sheet. |
|
|
WindowType (enumerated) |
Specifies the type of window. Values are:
|
|
|
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. |
|
|
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. |
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 |
|---|---|
|
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. |
|
|
When the user clicks in an unoccupied area of the window (any area with no visible, enabled object). |
|
|
When the window is closed. |
|
|
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. |
|
|
When the window becomes inactive. |
|
|
When the user double-clicks in an unoccupied area of the window (any area with no visible, enabled object). |
|
|
When a dragged control is dropped on the window. |
|
|
When a dragged control enters the window. |
|
|
When a dragged control leaves the window. |
|
|
When a dragged control is within the window. |
|
|
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. |
|
|
Just before the window is hidden. |
|
|
After a Dynamic Data Exchange (DDE) server application has sent new (changed) data and the client DDE application has received it. |
|
|
When the user presses a key and the insertion point is not in a RichTextEdit or DataWindow edit control. |
|
|
When the user presses the left mouse button in an unoccupied area of the window (any area with no visible, enabled object). |
|
|
When the pointer is moved within the window. |
|
|
When the user releases the left mouse button in an unoccupied area of the window (any area with no visible, enabled object). |
|
|
When a script executes the Open function for a window. The event occurs after the window has been opened but before it is displayed. |
|
|
When a Windows message occurs that is not a PowerBuilder event. |
|
|
When the right mouse button is pressed in an unoccupied area of the window (any area with no visible, enabled object). |
|
|
When a DDE client application has sent a command. |
|
|
When a DDE client application wants to start a hot link. |
|
|
When a DDE client application wants to end a hot link. |
|
|
When a DDE client application requests data. |
|
|
When a DDE client application has sent data. |
|
|
When the user or a script opens or resizes a window. |
|
|
When a script executes the Show function for this window. The event occurs just before the window is displayed. |
|
|
When the user presses Alt or Alt plus another key, except when the insertion point is in a DataWindow control or RichTextEdit control. |
|
|
When a specified number of seconds elapses after the Timer function has been called. |
|
|
In an MDI frame window, when the user moves the FrameBar or SheetBar. |
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 |
|---|---|---|
|
Integer |
Arranges the sheets or icons in the specified MDI frame window. |
|
|
Integer |
Changes the menu associated with a window. |
|
|
String |
Returns the name assigned to the window. |
|
|
Integer |
Closes a DDE channel. |
|
|
Integer |
Removes the specified user object from view, closes it, and executes its Destructor event. |
|
|
Integer |
After all persisted sheets are opened, this function arranges them and makes them visible. |
|
|
Integer |
Asks a DDE server application to execute the specified command. |
|
|
Window |
Returns the currently active sheet in the specified MDI frame window. |
|
|
Integer |
Obtains the command sent by the client application when your application is a DDE server. |
|
|
Integer |
When called by the DDE server application, obtains the application name parameter used by the DDE client sending the command. |
|
|
Integer |
Creates a reference to a context-specific instance of the specified service. |
|
|
Integer |
Obtains data sent from another DDE application and stores it in the specified string variable. |
|
|
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. |
|
|
Window |
Returns the top sheet in the MDI frame. |
|
|
Window |
Returns the sheet that is behind the specified sheet in the MDI frame. |
|
|
PowerObject |
Returns a reference to the name of the parent object. |
|
|
Integer |
Asks a DDE server application to provide data and stores that data in the specified variable. |
|
|
Integer |
Gets the values of the Visible, Alignment, and Title properties of the toolbar. |
|
|
Integer |
Gets position information (coordinates) for a floating toolbar. |
|
|
Integer |
Makes the window invisible. |
|
|
Integer |
Loads two arrays of equal size: type names of persisted sheets and the corresponding IDs. |
|
|
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. |
|
|
Long |
Opens a channel to a DDE server application. |
|
|
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. |
|
|
Integer |
Opens a sheet as a document within an MDI frame window for dockable windows. |
|
|
Integer |
Opens a sheet docked in a specified position within an MDI frame window for dockable windows. |
|
|
Integer |
Opens one or more persisted sheets within an MDI frame window for dockable windows. |
|
|
Integer |
Opens a sheet in a tab group within an MDI frame window for dockable windows. |
|
|
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. |
|
|
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. |
|
|
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 . |
|
|
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. |
|
|
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. |
|
|
Integer |
Displays the specified user object, making its properties available to scripts. |
|
|
Integer |
Displays the specified user object, making its properties available to scripts, and stores a parameter in the system's Message object. |
|
|
Window |
Returns the parent window of the window. |
|
|
Integer |
Returns the distance from the left edge of the screen to the pointer. |
|
|
Integer |
Returns the distance from the top of the screen to the pointer. |
|
|
Boolean |
Adds an event to the end of the message queue for the window. |
|
|
Integer |
Prints the window. |
|
|
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. |
|
|
Integer |
Sends a DDE message indicating whether the command or data received from a remote DDE application was acceptable. |
|
|
Integer |
Stores the MDI state in the registry. |
|
|
Integer |
Sends data to a DDE client application when PowerBuilder is acting as a DDE server. |
|
|
Integer |
Sets focus to the specified window. |
|
|
Integer |
Sets the MicroHelp text in the specified MDI frame window. |
|
|
Integer |
Specifies the position of the window in the front-to-back order of the application. |
|
|
Integer |
Turns on or off automatic redrawing of the window after every change. |
|
|
Integer |
Asks a DDE server application to accept data and store it in the specified location. |
|
|
Integer |
Sets the unique identifier for an open sheet. |
|
|
Integer |
Sets the values of the Visible, Alignment, and Title properties of the toolbar. |
|
|
Integer |
Sets the position of a fixed toolbar. |
|
|
Integer |
Makes the window visible. |
|
|
Integer |
Establishes a hot link with a DDE server application so that PowerBuilder is notified immediately of any changes in the specified data. |
|
|
Integer |
Establishes your application as a DDE server. |
|
|
Integer |
Terminates a hot link with a DDE server application. |
|
|
Integer |
Causes your application to stop acting as a DDE server application. |
|
|
Integer |
Sends an event to a window control and executes the script associated with the event. |
|
|
Object |
Returns the type of the window. |
|
|
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). |
|
|
Integer |
Returns the width of the workspace of the specified window. |
|
|
Integer |
Returns the distance from the left edge of the screen to the left edge of the workspace of the specified window. |
|
|
Integer |
Returns the distance from the top of the screen to the top of the workspace of the specified window. |
