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 RGB function in the 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.
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	Toolbar Alignment (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.
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! 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.
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.
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.
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.
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.
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.