Users Guide
Working with Windows

The Microsoft Windows operating environment has certain standards that graphical applications are expected to conform to. Windows, menus, and controls are supposed to look and behave in predictable ways from application to application.

This chapter describes some of the guidelines you should follow when designing windows and applications, but a full discussion is beyond the scope of this book. You should acquire a book that specifically addresses design guidelines for applications on the Windows platform and apply the rules when you use PowerBuilder to create your application.

When you build a window, you:

Two ways

There are two ways to build a window. You can:

For more information

For information on building windows from scratch, see Building a new window.

For information on using inheritance to build a window, see Using inheritance to build a window.

Main windows are standalone windows that are independent of all other windows. They can overlap other windows and can be overlapped by other windows.

You use a main window as the anchor for your application. The first window your application opens is a main window unless you are building a Multiple Document Interface (MDI) application, in which case the first window is an MDI frame.

For more on building MDI applications, see the section called “Building an MDI Application” in Application Techniques.

Using main windows

Define your independent windows as main windows. For example, assume that your application contains a calculator or scratch pad window that you want to have always available to the user. Make it a main window, which can be displayed at any time anywhere on the screen. As a main window, it can overlap other windows on the screen.

Pop-up windows are typically opened from another window, which in most cases becomes the pop-up window's parent.

A pop-up window can display outside its parent window. It cannot be overlaid by its parent. A pop-up window is hidden when its parent is minimized and when its parent is closed. When you minimize a pop-up window, the icon for the window displays at the bottom of the desktop.

Using pop-up windows

Pop-up windows are often used as supporting windows. For example, say you have a window containing master information, such as film listings. You can use a pop-up window to allow a user to see details of a particular entry.

Explicitly naming a parent

In most cases, the window that opens a pop-up window becomes that window's parent. For example, if a script in w_go has this statement, w_go is the parent of w_popup:

Open(w_popup)

You can also explicitly name a pop-up window's parent when you use Open in this way:

Open (popupwindow, parentwindow)

For example, the following statement opens w_popup and makes w_parent its parent:

Open(w_popup, w_parent)

However, there are also other considerations regarding which window becomes the parent of an opened window.

For more information, see the section called “Open” in PowerScript Reference.

Child windows are always opened from within a main or pop-up window, which becomes the child window's parent.

A child window exists only within its parent. You can move the child window within the parent window, but not outside the parent. When you move a portion of a child window beyond the parent, PowerBuilder clips the child so that only the portion within the parent window is visible. When you move the parent window, the child window moves with the parent and maintains the same position relative to the parent.

Child windows cannot have menus and are never considered the active window. They can have title bars and can be minimizable, maximizable, and resizable. When they are maximized, they fill the space of their parent; when they are minimized, their icon displays at the bottom of their parent.

The initial position of the child is relative to the parent and not to the entire screen. A child window closes when you close its parent.

You will probably not use child windows very often. Typically, if you want to display windows inside other windows, you will write MDI applications, where much of the window management happens automatically.

For more on building MDI applications, see the section called “Building an MDI Application” in Application Techniques.

Response windows request information from the user. They are always opened from within another window (its parent). Typically, a response window is opened after some event occurs in the parent window.

Response windows are application modal. That is, when a response window displays, it is the active window (it has focus) and no other window in the application is accessible until the user responds to the response window. The user can go to other applications, but when the user returns to the application, the response window is still active. Response windows act like modal pop-up windows.

Using response windows

For example, if you want to display a confirmation window when a user tries to close a window with unsaved changes, use a response window. The user is not allowed to proceed until the response window is closed.

Using message boxes

PowerBuilder also provides message boxes, which are predefined windows that act like response windows in that they are application modal. You open message boxes using the PowerScript MessageBox function.

For more information, see the section called “MessageBox” in PowerScript Reference.

An MDI window is a frame window in which you can open multiple document windows (sheets) and move among the sheets. There are two types of MDI frame windows: MDI frame and MDI frame with MicroHelp.

For more on building MDI applications, see the section called “Building an MDI Application” in Application Techniques.

Every window and control has a style that determines how it appears to the user. You define a window's style by choosing settings in the Window painter's Properties view. A window's style encompasses its:

When you build a window, you place controls, such as CheckBox, CommandButton, and MultiLineEdit controls, in the window to request and receive information from the user and to present information to the user.

After you place a control in the window, you can define its style, move and resize it, and write scripts to determine how the control responds to events.

For more information, see Working with Controls.

You can automatically create nonvisual objects in a window by inserting a nonvisual object in the window. You do this if you want the services of a nonvisual object available to your window. The nonvisual object you insert can be a custom class or standard class user object.

You insert a nonvisual object in a window in the same way you insert one in a user object. For more information, see Using class user objects.

You can save the window you are working on at any time.

Naming the window

The window name can be any valid PowerBuilder identifier of up to 40 characters. For information about PowerBuilder identifiers, see the section called “Identifier names” in PowerScript Reference.

A commonly used convention is to preface all window names with w_ and use a suffix that helps you identify the particular window. For example, you might name a window that displays employee data w_empdata.

As you develop a window, you can preview its appearance from the Window painter. By previewing the window, you get a good idea of how it will look during execution.

What you can do

While previewing the window, you can get a sense of its look and feel. You can:

What you cannot do

You cannot:

You can print a window's definition for documentation purposes.

Windows have several events including Open, which is triggered when the window is opened (before it is displayed), and Close, which is triggered when the window is closed. For example, you might connect to a database and initialize some values in the window's Open event, and disconnect from a database in the Close event.

Each type of control also has its own set of events. Buttons, for example, have Clicked events, which trigger when a user clicks the button. SingleLineEdits and MultiLineEdits have Modified events, which trigger when the contents of the edit control change.

Defining your own events

You can also define your own events, called user events, for a window or control, then use the EVENT keyword to trigger your user event.

For example, assume that you offer the user several ways to update the database from a window, such as clicking a button or selecting a menu item. In addition, when the user closes the window, you want to update the database after asking for confirmation. You want the same type of processing to happen after different system events.

You can define a user event for the window, write a script for that event, and then everywhere you want that event triggered, use the EVENT keyword.

To learn how to use user events, see Working with User Events.

PowerBuilder provides built-in functions that act on windows and on different types of controls. You can use these functions in scripts to manipulate your windows and controls. For example, to open a window, you can use the built-in window-level function Open, or you can pass parameters between windows by opening them with the function OpenWithParm and closing them with CloseWithReturn.

You can define your own window-level functions to make it easier to manipulate your windows. For more information, see Working with User-Defined Functions.

In scripts, you can assign values to the properties of objects and controls to change their appearance or behavior. You can also test the values of properties to obtain information about the object.

For example, you can change the text displayed in a StaticText control when the user clicks a CommandButton, or use data entered in a SingleLineEdit to determine what information is retrieved and displayed in a DataWindow control.

To refer to properties of an object or control, use dot notation to identify the object and the property:

object.property

control.property

Unless you identify the object or control when you refer to a property, PowerBuilder assumes you are referring to a property of the object or control the script is written for.

close(Parent)

All properties, events, and built-in functions for all PowerBuilder objects, including windows, and each type of control are described in Objects and Controls.

Often, data needs to be accessible in several scripts within a window. For example, assume a window displays information about one customer. You might want several CommandButtons to manipulate the data, and the script for each button needs to know the customer's ID. There are several ways to accomplish this:

When declaring variables, you need to consider what the scope of the variable is. If the variable is meaningful only within a window, declare it as a window-level variable, generally an instance variable. If the variable is meaningful throughout the entire application, make it a global variable.

For a complete description of the types of variables and how to declare them, see the section called “Declaring variables” in PowerScript Reference.

The following assignment statement in the script for the Clicked event for a CommandButton changes the text in the StaticText object st_greeting when the button is clicked:

st_greeting.Text = "Hello User"

The following statement tests the value entered in the SingleLineEdit sle_state and displays the window w_state1 if the text is "AL":

if sle_State.Text= "AL" then Open(w_state1)

Assume your application needs two windows with similar definitions. One window, w_employee, needs:

The window looks like this:

The only differences in the second window, w_customer, are that the title is Customer Data, the drop-down list displays customer files instead of employee files, and there is a Delete button so the user can delete files.

Your choices

To build these windows, you have three choices:

Using inheritance

Using inheritance has a number of advantages:

When you use inheritance to build an object, everything in the ancestor object is inherited in all its descendants. In the descendant, you can:

If you create a window by inheriting it from an existing window that has public or protected instance variables with simple datatypes, the instance variables display and can be modified in the descendant window's Properties view. You see them at the bottom of the General tab page. In this illustration, the last property is an inherited instance variable.

All public instance variables with simple datatypes such as integer, boolean, character, date, string, and so on display. Instance variables with the any or blob data type or instance variables that are objects or arrays do not display.

PowerBuilder uses this syntax to show names of inherited controls:

ancestorwindow::control

For example, if you select the Open button in w_customer, which is inherited from w_ancestor, its name displays on the General page in the properties view as w_ancestor::cb_open.

Names of controls must be unique in an inheritance hierarchy. For example, you cannot have a CommandButton named cb_close defined in an ancestor and a different CommandButton named cb_close defined in a child. You should develop a naming convention for controls in windows that you plan to use as ancestors.