Building a new window

This section describes how to build windows from scratch. You use this technique to create windows that are not based on existing windows.

Creating a new window

To create a new window

  1. Open the New dialog box.

  2. On the PB Object tab page, select Window.

  3. Click OK.

    The Window painter opens. The new window displays in the Window painter's Layout view and its default properties display in the Properties view.

Defining the window's properties

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:

  • Type

  • Basic appearance

  • Initial position on the screen

  • Icon when minimized

  • Pointer

About defining a window's style

When you define a window's style in the Window painter, you are actually assigning values to the properties for the window. You can programmatically change a window's style during execution by setting its properties in scripts. For a complete list of window properties, see the section called “Window control” in Objects and Controls.

To specify window properties

  1. Click the window's background to display the window's properties in the Properties view.

    Another way to display window properties

    You can also select the window name in the Control List view.

  2. Choose the tab appropriate to the property you want to specify:

    To specify the window's

    Choose this tab

    Name, type, state, color, and whether a menu is associated with it

    General

    Icon to represent the window when you minimize it

    General

    Transparency

    General

    Opening and closing animation styles

    General

    Position and size when it displays at runtime

    Other

    Default cursor whenever the mouse moves over the window

    Other

    Horizontal and vertical scroll bar placement

    Scroll

    Toolbar placement

    Toolbar


Using the General property page

Use the General property page to specify the following window information:

  • Window type

  • Title bar text

  • Menu name

  • Color

  • Transparency

  • Animation

Specifying the window's type

The first thing you should do is specify the type of window you are creating.

To specify the window's type

  1. In the Properties view for the window, select the General tab.

  2. Scroll down the property page and select the appropriate window type from the WindowType drop-down list.


    Depending on the type of window, PowerBuilder enables or disables certain check boxes that specify other properties of the window. For example, if you are creating a main window, the Title Bar check box is disabled. Main windows always have title bars, so you cannot clear the Title Bar check box.

Specifying other basic window properties

By selecting and clearing check boxes on the General property page, you can specify whether the window is resizable or minimizable, is enabled, has a border, and so on.

Note the following:

  • A main window must have a title bar

  • A child window cannot have a menu

  • A response window cannot have a menu, Minimize box, or Maximize box

Associating a menu with the window

Many of your windows will have a menu associated with them.

To associate a menu with the window

  1. Do one of the following:

    • Enter the name of the menu in the Menu Name text box on the General property page

    • Click the Browse button and select the menu from the Select Object dialog box, which displays a list of all menus available to the application

  2. Click the Preview button in the PainterBar to see the menu.

For information about preview, see Viewing your work.

Changing the menu

You can change a menu associated with a window during execution using the ChangeMenu function. For more information, see the section called “ChangeMenu” in PowerScript Reference.

Choosing a window color

You can change the background color of your window.

To specify the color of a window

  • Do one of the following:

    • Specify the color of the window from the BackColor drop-down list on the General property page

    • If the window is an MDI window, specify a color in the MDI Client Color drop-down list

Changing default window colors

For main, child, pop-up, and response windows, the default color is ButtonFace if you are defining a 3D window, and white if you are not. If you or the user specified different display colors in the Windows Control Panel, a 3D window will display in the color that is set for the window background.

You can change the default for windows that are not 3D in the Application painter Properties view. To do so, click the Additional Properties button on the General page and modify the Background color on the Text Font tab page. New windows that are not 3D will have the new color you specified.

For more about using colors in windows, including how to define your own custom colors, see Working with Controls.

Choosing the window icon

If the window can be minimized, you can specify an icon to represent the minimized window. If you do not choose an icon, PowerBuilder uses the application icon for the minimized window.

To choose the window icon

  1. Click the window's background so the Properties view displays window properties.

  2. Select the General tab.

  3. Choose the icon from the Icon drop-down list or use the Browse (...) button to select an icon (.ICO) file.

    The icon you chose displays in the Icon list.

Changing the icon at runtime

You can change the window icon at runtime by assigning in code the name of the icon file to the window's Icon property, window.Icon.

Specifying the window's transparency

You can specify a value between 1 and 100% for the Transparency property of a window. This property is useful if you want a non-modal dialog box to remain visible but become semi-transparent when it loses focus.

Opening and closing windows with an animated effect

You can use a special effect when a window opens or closes. Effects include fading in or out, opening from the center, and sliding or rolling from the top, bottom, left, or right. You specify animation effects with the OpenAnimation, CloseAnimation, and AnimationTime properties. Set the AnimationTime property to between 1 and 5000 milliseconds to specify how long the animation effect takes to complete.

For example, if your application displays a splash screen while the application's main window is initializing, you can set the splash screen's CloseAnimation property to have the window fade out rather than just disappearing when the application is initialized or after a timeout by setting the CloseAnimation property to FadeAnimation!.

Choosing the window size and position

To resize a window in the Layout view

  • Drag the edge of the window in the Window painter's Layout view.

    Resizing a window is easiest using the Layout view, but you can also change the window's width and height properties in the Properties view.

To specify a window's position and size

  1. Click the window's background so the Properties view displays window properties.

  2. Select the Other tab.

  3. Enter values for x and y locations in PowerBuilder units.

    About x and y values

    For main, pop-up, response, and MDI frame windows, x and y locations are relative to the upper-left corner of the screen. For child windows, x and y are relative to the parent.

  4. Enter values for width and height in PowerBuilder units.

    The size of the window changes in the Layout view.

  5. To see the position of the window, click the Preview button in the PainterBar (not the Preview button on the PowerBar).

  6. To return to PowerBuilder, close the window.

For information about preview, see Viewing your work.

About PowerBuilder units

All window measurements are in PowerBuilder units (PBUs). Using these units, you can build applications that look similar on different resolution screens. A PBU is defined in terms of logical inches. The size of a logical inch is defined by your operating system as a specific number of pixels. The number is dependent on the display device. Windows typically uses 96 pixels per logical inch for small fonts and 120 pixels per logical inch for large fonts.

Almost all sizes in the Window painter and in scripts are expressed as PowerBuilder units. The two exceptions are text size, which is expressed in points, and grid size in the Window and DataWindow painters, which is in pixels.

For more about PowerBuilder units, see the section called “PixelsToUnits” in PowerScript Reference and the section called “UnitsToPixels” in PowerScript Reference.

Choosing the window pointer

The default pointer used when the mouse is over a window is an arrow. You can change this default on the Other page in the properties view.

To choose the window pointer

  1. Click the window's background so the Properties view displays window properties.

  2. Select the Other tab.

  3. At the bottom of the property page, choose the pointer from the Pointer drop-down list or use the Browse (...) button to select a cursor (.CUR) file.

Specifying the pointer for a control

You can specify the pointer that displays when the mouse is over an individual control. Select the control to display the Properties view for the control, then specify the Pointer property on the Other page.

Specifying window scrolling

If your window is resizable, it is possible that not all the window's contents will be visible during execution. In such cases, you should make the window scrollable by providing vertical and horizontal scroll bars. You do this on the Scroll property page.

By default, PowerBuilder controls scrolling when scroll bars are present. You can control the amount of scrolling.

To specify window scrolling

  1. Click the window's background so the Properties view displays window properties.

  2. Select the Scroll tab.

  3. Indicate which scroll bars you want to display by selecting the HScrollBar and VScrollBar check boxes.

  4. Specify scrolling characteristics as follows:

    Option

    Meaning

    UnitsPerLine

    The number of PowerBuilder units to scroll up or down when the user clicks the up or down arrow in the vertical scroll bar. When the value is 0 (the default), it scrolls 1/100 the height of the window.

    UnitsPerColumn

    The number of PowerBuilder units to scroll right or left when the user clicks the right or left arrow in the horizontal scroll bar. When the value is 0 (the default), it scrolls 1/100 the width of the window.

    ColumnsPerPage

    The number of columns to scroll when the user clicks the horizontal scroll bar itself. When the value is 0 (the default), it scrolls 10 columns.

    LinesPerPage

    The number of lines to scroll when the user clicks the vertical scroll bar itself. When the value is 0 (the default), it scrolls 10 lines.


Specifying toolbar properties

You can specify whether or not you want to display a menu toolbar (if the menu you associate with your window assigns toolbar buttons to menu objects) in your window. If you choose to display the toolbar, you can specify the location for it.

To specify toolbar properties

  1. Click the window's background so the Properties view displays window properties.

  2. Select the Toolbar tab.

    To display the toolbar with your window, select the ToolbarVisible check box.

  3. Set the location of the toolbar by selecting an alignment option from the ToolbarAlignment drop-down list.

    If you choose Float as your toolbar alignment, you must set the following values:

    • X and Y coordinates for the toolbar

    • Width and Height for the toolbar

For more information about defining toolbars, see Working with Menus and Toolbars.

Adding controls

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.

Adding nonvisual objects

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.

Saving the window

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

To save a window

  1. Select File>Save from the menu bar.

    If you have previously saved the window, PowerBuilder saves the new version in the same library and returns you to the Window painter workspace.

    If you have not previously saved the window, PowerBuilder displays the Save Window dialog box.

  2. Name the window in the Windows text box (see below).

  3. Type comments in the Comments text box to describe the window.

    These comments display in the Select Window window and in the Library painter. It is a good idea to use comments so you and others can easily remember the purpose of the window later.

  4. Specify the library where you want to save the window.

  5. Click OK.

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.