Using the Editors

The role of the screen is determined, in part, by where it is stored. You can create a screen and store it:

• In a library where you and other developers can conveniently store many screens and access them at runtime.

• In a repository where it can function as a template or as a source of inheritance for objects used throughout your application.

This chapter describes:

• The different means provided to create a screen, ensuring that it is stored in the appropriate place on your system.

• General design considerations when creating and editing a screen with the screen editor.

• How you can document the contents of a screen.

When you design the interface to your application, there are at least two considerations to keep in mind:

• Portability from character-mode Panther to a GUI environment and vice versa, from a GUI environment to a web environment, and from one GUI environment to another. This can affect size, colors, and GUI-specific controls as well as other issues.

• Maintainability.

Creating, Opening, and Saving Screens

Your Panther screens are created in the editor and then stored in a library or a repository. An screen can be:

• A client screen—Defines the user interface.

• A repository entry—Allows for an inheritance link when you use the repository screen and its objects to create your application screens.

You can create a screen by:

• Opening a new, untitled screen in the workspace.

• Opening an existing screen in a library and saving it with a new name.

• Opening an existing screen in a library as a template.

You can populate a screen with widgets by:

• Using the screen wizard.

• Creating new widgets.

• Copying widgets from one screen to another.

• Copying widgets from a repository.

Creating a New Screen

A new, untitled screen is open by default when you start up the editor. This screen can be a client screen or a screen in a repository depending on where you choose to store it. Now you can begin populating the screen with widgets, or defining the screen's properties.

Note: As of Panther 4.5, a special type of screen, a frameset, can contain multiple screens. For more information, refer to Chapter 17, "Framesets and Splitters."

How to Create a New Screen

1. Choose FileNewScreen (or the New Screen button on the toolbar). The New Screen Tool dialog box appears and prompts:
   

2. Choose how you want the screen to be created:

   • Yes—Panther guides you through the creation of a screen using imported database tables in a repository (a repository must be open). Refer to Chapter 4, "Screen Wizard," for details on using the screen wizard.

   • No—An empty, untitled screen opens in the screen editor workspace.

   • Cancel—The new screen operation is cancelled.

Since you can have different types of application components open in the editor at the same time, you can identify screens in the following ways:

• The Screen Type property. Under Identity, the Screen Type property is set to Screen.

• The Type field in the Properties window. If a screen has focus (by clicking on a blank area of the screen), the Type field displays Screen.

• The screen's Title bar.

  • For newly created screens, the title bar displays Untitled#.

  • For screens stored in libraries, the title bar displays screenName@libraryName.

  • For screens stored in repositories, the title bar displays screenName@[Repository].

Creating a Screen from a Repository

You can create screens that are derived from your database by following the procedure for importing database tables to a repository (refer to "Populating a Repository with Database Objects"). Once you import the database tables, you can use the resulting repository entries to create your application screens.

How to Add Objects to Your Screen from a Repository

1. Choose FileOpenRepository if the repository is not open.
2. To open a repository entry, do either of the following:

   • Choose ViewRepository TOC. Select the desired repository entry from the Repository (TOC) and choose Open.

   • Choose FileOpenRepository Entry. Select the desired repository screen from the Open Repository Entry dialog box. Choose OK.

3. Select the desired widget or widgets on the repository screen and drag them to your application screen.

The copied (child) object in your application screen has property settings that match its parent in the repository. Inherited property values are indicated in reverse video in the Properties window. The position (Start Row, Start Column, End Row, and End Column properties) are not inherited; and although the initial value for the Name and Inherit From properties are derived from the parent object, there is no inheritance relationship for these property settings.

The Inherit From property for the child widget indicates the source of inheritance—the name defined for the parent object and its repository entry in the format repository_entry!widget_name. Refer to "Controlling Inheritance" for ways of controlling inheritance.

Creating a Dialog Box

A screen that has the Dialog property set:

• Cannot be resized, maximized, or minimized—At runtime, these options are not available on the screen's system menu, and the border (specifically in GUIs) has no maximize/minimize buttons. However, it can be moved.

• Is modal—At runtime, the user is forced to enter data, respond to, or acknowledge the dialog box before proceeding with the application. The menu bar and controls strings outside of the dialog box cannot be accessed while the modal dialog box is active.

  Note: Dialog screens are not available in web applications.

For additional information about window styles in Windows applications, refer to "Specifying Styles under Windows."

How to Define a Screen as a Dialog Box

1. Select the screen.
2. Under Identity, set the Dialog property to Yes.

The screen, in application/test mode, is now an application modal window. Consider providing some mechanism, like an OK button, to allow the user to continue or exit the screen.

For instructions on creating a tab dialog in Windows applications, refer to "Creating a Tab Dialog Screen."

Opening and Saving Screens

For information about opening screens, refer to "Opening Application Components."

For information about saving screens to a library, refer to "Saving an Application Component."

For information about saving screens to a repository, refer to "Saving Application Components to a Repository."

Resizing a Screen

By default, new screens have a predefined Height and Width property setting—18 (grid rows) by 48 (grid columns). These properties define the initial dimension of a screen.

Defining the Screen Size

Since Panther screens are virtual screens, you can create screens as large as 254 lines by 254 columns. When a virtual screen is larger than the physical display can accommodate, then the screen is viewed through a mechanism called a viewport.

How to Change the Size of the Current Screen

Do either of the following:

• Drag the screen edge or corner to the desired dimension.

• Set explicit dimensions in the Geometry properties, Height and Width.

The grid size and the size of the font can have an effect on screen size as well.

Conventions for Controlling Screen Size at Runtime

You can control the initial size of the screen as well as define what users can do to resize the screen.

Changing the Viewport

1. Select the screen.
2. Under Geometry, set the Resizeable property:

   • Yes—(default) The user can change the size of the screen by dragging on its corner or edge. Vertical and horizontal scroll bars are automatically displayed if the viewport is not large enough to display the screen's entire contents.

     In addition, when a user changes the size of a screen, you can control how widgets will grow or shrink to take advantage of the screen's new size. The screen editor Properties window is a good example of how widgets can resize and move depending on the window's size. Refer to "Controlling a Widget's Size at Runtime" for details on controlling widget size.

   • No—The initialize size of the screen is maintained. At runtime, the user cannot resize the screen, and the screen's system menu Size option (if applicable to the platform) is not available.

Panther provides a mechanism for resizing widgets based on the size of the screen, but you can also write a function that Panther calls when the viewport size is changed. The function can control how widgets, under a GUI platform, are resized and rearranged when the user changes the viewport size.

How to Attach a Custom Resize Function

1. Select the screen that requires the function.
2. Under Geometry, specify the function name in the Resize Function property.

In a GUI environment, you can control whether the standard maximize and minimize buttons are available to the user. In addition, you can define whether a screen starts off in a maximized or minimized (iconified) state. By default, when a screen is invoked, it starts up in the size you specify at design time.

At runtime, a user restores a window to its original size by:

• Double-clicking on the minimized icon to reopen the window.

• Choosing the Restore button in the upper-right corner of the screen, or choosing Restore from the screen's system menu to restore a maximized window to its previous size.

How to Define a Screen's Startup State

1. Select the screen.
2. Under Geometry, set the Startup property to the desired setting:

   • Maximized—Invokes the screen to occupy the entire display (entire MDI frame in Windows) when the screen is first displayed.

     Note: The Maximized value has no effect under Motif.

   • Iconified—Invokes the screen in a minimized, iconified state. A default operating system icon (an empty blank square box in Windows) is used if you have not set the Icon property (under Display) or if the specified pixmap in the Icon property cannot be found.

   • Normal—Invokes the screen in the application's current state of maximization.

1. Select the screen.
2. Under Geometry, set the Max/Min property under Geometry to one of the following settings:

   Note: While in Edit mode in the screen editor, all screens have a minimize button only, regardless of the property setting. This allows you to iconify screens while you are designing. In Test mode, screens reflect the actual property specifications.

   • Maximizeable—Provides a maximize button on the screen's title bar, and the Maximize option on the screen's system menu. This setting prevents the user from minimizing or iconifying the screen at runtime; there is no minimize button, and the Minimize option on the system menu is unavailable.

   • Minimizeable—Provides a minimize button on the screen's title bar, and the Minimize option on the screen's system menu. This setting prevents the user from maximizing the screen at runtime; there is no maximize button and the Maximize option on the system menu is unavailable.

   • Both (default)—Provides both maximize and minimize buttons, and both options are available on the screen's system menu. Only the minimize button appears while you are in Edit mode.

   • Neither—Prevents the screen from being maximized or minimized by removing the maximize and minimize buttons; both options are unavailable on the screen's system menu. The minimize button remains on the screen while you are in Edit mode.

     Note: If the Title Bar property is set to No, maximize and minimize buttons are not available nor is the system menu.

On a GUI platform, when a screen is minimized at runtime, a default operating system icon is provided by Motif, and Windows uses an empty square. You can provide your own icon that is displayed when the screen is minimized.

You can browse libraries with the Open button. Windows only supports *.ico formats for icon usage. Motif will display BMP (.bmp), GIF (.gif), JPEG (.jpg), XPM (.xpm, .xpm1, .xpm3) and XBM (.xbm) style files.

Note: Motif does not scale images, so if they are too large for the icon space, the icon image may appear truncated.

How to Assign an Icon To Display on a Minimized Screen

1. Select the screen.
2. Under Display in the Icon property, enter the filename or choose More to select the file from the Select Library Member dialog box. Choose OK.

   In addition, the Select Library Member dialog box provides the capability to browse libraries with the Open button, and to add icon image files to a library with the Add button. If you choose the Add button, the Select File dialog box opens and you can select the icon file that you want to include in a library.

3. To see how it looks, choose FileTest Mode (or the Test Mode button on the toolbar).
4. Choose the Minimize button on the upper right corner of the screen's title bar.

   The icon displays if the file is in one of your open libraries.

   To facilitate portability and provide maximum flexibility, omit the filename extension when you specify an icon file. At runtime, Panther searches for files in all open libraries using all possible image extensions supported on the local platform.

   If you have icon images of the same name but of different types (for example, logo.ico is the Windows icon format, while logo.jpg is a photograph), include the extension to ensure that the correct image is displayed at runtime.

   Note: Under Windows, if you compile the icon into your resource-definition file, the resource id must match the Icon property setting exactly.

---

Using the Screen Grid

Panther uses a grid to determine widget location. The height and width of the entire screen is measured in grid units, expressed in grid rows and grid columns, respectively.

Notes: The horizontal grid marks indicate different units of measurement: in character mode, the space between each grid mark represents two grid units; in GUI modes, it represents one unit.

In character-mode Panther, the grid is fixed; each character occupies one grid cell.

If you explicitly set the Grid Height and Grid Width properties, under a GUI platform, Panther uses these; otherwise, it uses the screen's font size to determine the grid size (refer to "Specifying Fonts" for more information on setting font preferences).

To toggle the display of the grid, choose OptionsGrid (or the Grid button on the toolbar).

How to Control the Size of the Positioning Grid

Select the screen. Under Geometry in the Grid Height and/or Grid Width properties, enter the desired measurement (default is grid units). (Refer to Table 9-1 for a list of valid units of measurement.)

This setting overrides the screen's font size as a determining factor for sizing the positioning grid.

Controlling Screen Location

When invoking a screen, you can specify parameters that control the screen's location and size. If you omit these parameters, Panther uses its own defaults. By default, Panther displays the screen in its entirety. When you invoke a screen:

• As a form, Panther displays it at the physical display's upper-left corner; this excludes the menu bar, which remains visible.

• As a window, Panther tries to leave the calling screen's last cursor position visible.

• If the screen size exceeds the actual display area, Panther creates a viewport. By default, the viewport's upper left corner (1,1) initially displays the screen's upper-left contents, unless this prevents display of the cursor. Panther ensures that the cursor's initial position in a viewport—usually the first field—is visible. If necessary, it adjusts the screen offset within the viewport accordingly.

Refer to "Displaying Screens" in Application Development Guide for detailed instructions on specifying screen position in control strings or runtime library functions.

Controlling Geometry Changes Across Platforms

Panther recalculates a screen's size and the positions of its widgets when you open a screen in an environment that is different from the one in which it was created—for example, a screen created in character mode that is opened in Motif. When this happens, Panther uses a positioning algorithm that makes several assumptions about screen size and the correct placement of widgets. By default, these assumptions include maximizing the use of whitespace while maintaining the relative positions of widgets to each other.

The screen's Positioning properties let you:

• Control spacing between widgets.

• Set a minimum margin within the screen's border.

• Control adjustments in screen size and widget positions.

  Note: Positioning properties are recognized only in GUI environments.

Spacing Widgets for Portability

1. Select the screen.
2. Under Geometry, in the Positioning subheading, set either or both of the following properties to the desired unit (default is grid units) of measurement required between widgets on the screen. (Refer to Table 9-1 for a list of valid units of measurement.)

   • Min Horiz Space—Determines the minimum amount of space maintained between widgets that are horizontally contiguous. If you place widgets closer than the distance specified by this property, Panther does not try to increase the space between them. When no value (default) is specified, widgets are allowed to touch.

   • Min Vert Space—Determines the minimum amount of space maintained between widgets that are vertically contiguous. If you place widgets closer than the distance specified by this property, Panther does not try to increase the space between them. When no value (default) is specified, widgets are allowed to touch.

     If all available whitespace is used up between widgets, Panther moves them or adjusts the screen size in order to maintain the minimum spacing required.

1. Select the screen.
2. Under Geometry, in the Positioning subheading, set the Region Margin property to the amount of space (grid unit is the default) desired between the border and the widgets on the screen. (Refer to Table 9-1 for possible units of measurement.)

   Note: The default 0 allows widgets to touch the screen border. If you place widgets within the margin, Panther does not try to increase the space between them and the screen's border.

When you open a screen in an environment different from the one in which it was created, Panther attempts to minimize differences between the presentation of the same screen on different platforms. Panther typically adjusts the widget's start positions and the screen's dimensions by shrinking or expanding the grid.

How to Control How Widgets Move and the Screen Resizes

1. Select the screen.
2. Under Geometry, in the Positioning subheading, set the Horizontal and/or Vertical Shrinking properties to one of the following:

   • Decrease region size—Adjusts widget positions and screen size according to changes in the font and point size. This is the default setting.

   • Keep region size—Keeps the screen size unchanged. Panther adjusts widget start positions to simulate their original proximity; when moving from character to GUI modes, this is likely to leave extra whitespace at the screen's borders.

   • Prevent grid shrinking—Keeps the screen size and widget start positions unchanged. When moving from character mode to GUI modes, the whitespace between widgets is liable to increase.

To illustrate how these settings work, three versions of the following screen were created in character mode. Each has different vertical and horizontal shrinking properties settings. In character mode, all versions appear to be identical (Figure 6-1).

Figure 6-1 Screen created in character mode.

When you port these screens to Windows, however, the differences become evident.

• Screen with Horizontal and Vertical Shrinking properties set to Decrease region size—Because the default screen font is proportional in Windows, the widgets require fewer columns and rows. Panther adjusts the widgets' start positions accordingly and shrinks the screen size to remove the extra whitespace that would otherwise be left over (Figure 6-2).
  

  Figure 6-2 Vertical and Horizontal shrinking properties were set to Decrease region size for this screen ported to Windows.

• Screen with Horizontal and Vertical Shrinking properties set to Keep region size—Panther repositions the widgets in order to maintain their relative proximity. However, the screen size remains unchanged, so extra whitespace is left in the screen's bottom and right margins (Figure 6-3).
  

  Figure 6-3 Vertical and Horizontal Shrinking properties were set to Keep region size for this screen ported to Windows.

• Screen with Vertical and Horizontal Shrinking properties set to Prevent grid shrinking—The screen size and widget positions remain the same. Because widgets occupy less space, the space between them is greater. Notice in Figure 6-4 that Panther repositions the widgets within the Search For box. Grid shrinking can occur within a box independently of the screen because a box is an autonomous positioning region with its own vertical and horizontal property settings—in this case, set to Decrease region size. For more information about using boxes as positioning regions, refer to "Using Boxes as Positioning Regions."
  

  Figure 6-4 Vertical and Horizontal Shrinking properties were set to Prevent grid shrinking for this screen ported to Windows.

Refer to "Controlling a Widget's Position at Runtime" for information on controlling widget position when a screen resizes.

Including Screen Wallpaper

Instead of displaying a screen background color, you can display a picture, drawing, or photograph as the screen background. This is referred to as wallpaper.

Panther supports BMP (.bmp), GIF (.gif), and JPEG (.jpg) files under Windows and Motif as well as XPM (.xpm, .xpm1, .xpm3) and XBM (.xbm) files under Motif. Images appear in the size in which they were created.

How to Assign a Wallpaper as a Screen Background

1. Select the screen.
2. Choose OptionsGrid or toggle the Grid button on the toolbar to turn the grid off.

   Note: The wallpaper does not display in Edit mode when the grid is on.

3. Under Display in the Wallpaper Pixmap property, enter the filename or choose More to select a file in a specific library from the Select Library Member dialog box. Choose OK.

   The image displays immediately if the file is in one of your open libraries.

   In addition, the Select Library Member dialog box provides the capability to browse libraries with the Open button, and to add image files on the system to a library with the Add button. If you choose the Add button, the Select File dialog box appears and allows you to select the files that you want to include in a library.

   To facilitate portability and provide maximum flexibility, omit the filename extension when you specify an image file. At runtime, Panther searches for files in all open libraries using all possible image extensions supported on the local platform.

   If you have images of the same name but of different types (for example, dog.xpm might be a bitmapped image while dog.jgp is a photograph), include the extension to ensure that the correct image is displayed at runtime.

   Note: Under Windows, if you compile the image into your resource-definition file, the resource id must match the Wallpaper Pixmap property setting exactly.

4. Under the Wallpaper Pixmap property, set the Style subproperty to the desired position of the wallpaper image on the screen:

   • Center—Positions the image on the center of the selected screen. If the image is smaller than the screen dimensions, whitespace appears around the picture. If the image is larger than the screen dimensions allow, the image is cropped equally on all borders.

   • Tile—(default) The image appears in the upper left corner of the selected screen. If the image size is smaller than the screen dimensions, the picture is repeated as many times as necessary to fill the window. If the image size is larger than the screen dimensions, the right and bottom borders of the picture are cropped.

To specify a wallpaper for Panther's MDI parent window in Windows applications, set the appropriate variables in your Panther initialization (*.ini) file. For details on settings in the initialization file, refer to MDIWallpaperPixmap in Configuration Guide.

Specifying a Mouse Pointer

In general, the mouse is the primary method for navigating in GUI applications. For the most part, the native window manager handles the way your mouse pointer looks and behaves. In Motif, the default pointer shape is an arrow, but can be specified in the pointerShape resource; in Windows, the default cursor is also an arrow. These are considered application-wide pointers. However, you can also specify a mouse pointer shape for a screen that is different from the default.

In addition, you can use the library function sm_delay_cursor to change mouse pointer shapes at runtime.

How to Define a Unique Cursor Shape for a Screen

1. Select the screen.
2. Under Display, enter the name of the GUI-specific cursor shape in the Pointer property. Refer to Table 6-1 for Motif specifications and to Table 6-2 for Windows specifications.

   Note: Motif and Windows each have pointer shape specifications that are unique to their environments. Therefore, they are not portable across platforms.

   Table 6-1 Pointer shape specifications for Motif*

   arrow	icon
   based_arrow_down	left_ptr
   boat	leftbutton
   center_ptr	question_arrow
   clock	sb_up_arrow
   coffee_mug	spider
   cross	spraycan
   dot	target
   double_arrow	top_left_corner
   fleur	umbrella
   hand1	watch
   *The entire list can be found in the file /usr/include/X11/cursorfont.h (the XC_ prefix is not required in the Pointer property setting).

   Table 6-2 Pointer shape specifications for Windows

   IDC_APPSTARTING	IDC_SIZE
   IDC_ARROW	IDC_SIZEALL
   IDC_CROSS	IDC_SIZENESW
   IDC_HAND	IDC_SIZENS
   IDC_HELP	IDC_SIZENWSE
   IDC_IBEAM	IDC_SIZEWE
   IDC_ICON	IDC_UPARROW
   IDC_NO	IDC_WAIT

In Windows, you can create your own cursor shapes and designate your custom cursor in the Pointer property for the screen.

How to Create and Specify a Custom Pointer Shape

1. Create the cursor shape using any image/bitmap editor.
2. Define the image in your resource-definition file (.rc file) using the following format:

   pointer CURSOR image_file

   where pointer is a name you devise to identify the image; image_file is the bitmap filename of the image you created.

3. Recompile to include the new definition.
4. In the screen editor, open and select the desired screen.
5. Under Display, specify your pointer in the Pointer property.

---

Including Borders and Decorations

By default, a screen has a border and is fully decorated with an area for the screen title (title bar), minimize and maximize buttons (in GUIs only), and a system menu. Scroll bars appear in the border only if they are necessary, that is, if the screen is larger than can be displayed in the physical monitor or you choose to display the screen as a viewport.

In addition to designing screens with and without borders, you can control what appears on a border and control the title bar components. For example:

• Display the screen's title in the title bar.

• Suppress the display of the title bar all together.

• Display the system menu and specify its content.

Designing the Screen Borders

Borders are included, by default, on all newly created screens. Borders can add visual interest and help distinguish the edges of a screen when it is opened on top of another screen of the same color. This is particularly useful in character mode applications. Borderless screens, on the other hand, have no title bar, system menu, or minimize and maximize buttons.

How to Define a Screen's Border Display

1. Select the screen.
2. Under Display, set the Border property.

   • Yes—(default). All newly created screens have a border.

   • No—At runtime, the screen is borderless and has no resize handles. The screen's title bar does not display, nor does the system menu, minimize and maximize buttons. The screen cannot be moved, resized, minimized, or maximized with a mouse; however, shortcut keys can still perform these actions.

     Note: The Border property and its subproperties are ignored on Windows applications.

1. Select the screen.
2. Under Display, set the Border property to Yes. Additional border properties are displayed.
3. Set the Border Style property to the desired style; styles are numbered 0 through 9 (style 1 is the default). The designated style will surround the screen.

   Note: The numeric styles correspond to characters and are defined in your video file. You can modify them in the video file to control the actual character set associated with a particular border style. (For more information, refer to "Borders and Line Drawing" in Configuration Guide.)

4. Set the FG (foreground) and/or BG Color Type properties for the Border. In addition, you can assign other display attributes to the screen border—such as intensity, reverse video, and blinking. (Refer to "Setting Display Attributes" for detailed information on setting screen border colors and attributes.)

While you are working in the editor, the title bar for your application screen displays the filename and library you specified when you saved the screen, or, when unsaved, it is Untitled followed by a number. However, to provide a title for your screen in application mode or test mode, you need to set the Title property.

How to Display a Title in the Screen's Border/Title Bar

1. Select the screen.
2. Under Identity, enter the screen title in the Title property.

   In application/test mode, the title is displayed in the screen's border or title bar.

3. To suppress the display of a title in the title bar, leave the Title property value blank.

   Note: The Title property has no effect in character mode if the Border property is set to No. In the GUIs, there is no effect if the Title Bar property is set to No.

Identifying a mnemonic for screens running in character mode provides users with an alternative way, and GUI-like means, of bringing focus to a screen. At runtime, the user can bring focus to a screen by choosing the Windows menu bar option, and then selecting the desired screen from the drop-down menu by typing the mnemonic that is highlighted. The mnemonic is designated as one of the characters in the screen's title.

How to Identify the Keyboard Mnemonic for the Screen

1. Select the screen.
2. Under Identity, enter a screen title in the Title property.
3. Under Identity, in the Mnemonic Position property, enter a letter or a number corresponding to the letter's position in the screen's title.

   For example, if the screen's title is Customer Information, you can specify any of its letters as the mnemonic. Enter an upper case C (or 1), or lower case u (or 2). Uppercase C or the number 1 defines the first letter in the string to be the mnemonic, while lowercase u or the number 2 defines the second letter in title to be the mnemonic.

   The property setting displays the position of the character followed by the character. For example, if you enter the mnemonic C for the Customer Information screen, the Mnemonic Position property displays 1 \QC'—the first character in the title.

All newly created screens have a title bar. The title bar includes the screen's title, the system menu in the upper left corner, and minimize and maximize buttons in the upper right corner.

Note: The Title Bar property has no effect in character mode if the Border property is set to No.

How to Define the Display of the Screen's Title Bar

1. Select the screen.
2. Under Display, set the Title Bar property.

   • Yes—(default) All features and decorations as well as the screen's title are displayed on the screen's title bar, unless other title bar-related properties have been turned off.

   • No—The screen's title bar and, therefore, its title are not displayed. In addition, the following title bar features are also suppressed:

     • Minimize and maximize buttons (on GUIs).

     • System menu.

     • At runtime, the screen cannot be moved, minimized, maximized, or closed. Consider providing alternative user options, such as a Cancel button, OK button, or some other mechanism for allowing the user to continue.

A screen's system (or control) menu is displayed in the upper left corner of the screen border (displays as [=] in character mode). By default, all newly created screens have a system menu. In general, the system menu includes the following options: Restore, Move, Size, Minimize, Maximize, and Close.

Note: In Motif, you can define the contents of your system menu in the .mwmrc file.

Most options on the system menu have other means of access, such as resize handles, and maximize and minimize buttons.

Note: The System Menu property has no effect if Border is set to No in character mode or Title Bar is set to No

How to Prevent Users from Closing a Screen from the System Menu

1. Select the screen.
2. Under Display, set the Close Item property to No.

   Note: This property setting is particularly useful on dialog boxes where user input may be required before proceeding.

1. Select the screen.
2. Under Display, set the System Menu property to No.

---

Specifying Styles under Windows

As of Panther 4.5, there are new options for opening windows under the Windows operating system. Previously windows could either be opened as MDI windows, or as dialogs. An MDI window cannot be moved outside the MDI frame. A dialog can be moved outside the MDI frame, but blocks access to the MDI frame – when a dialog is opened, focus cannot be given to any MDI windows, nor can the MDI menu be accessed until the dialog is closed.

The new options are implemented by the properties Keep in Frame and Topmost. These are screen-level properties and are found under the Identity section in the Properties window.

The Keep In Frame Property

The Keep in Frame property is a subproperty of the Dialog property. If a window is specified as a dialog, the new option doesn't apply.

The default value for Keep in Frame is Yes. A non-dialog window with Keep In Frame set to Yes will behave exactly like the MDI windows Panther has always supported. Setting Keep In Frame to No will make the screen open as a non-MDI window, that is not a modal dialog. Such a screen can be moved outside the MDI frame, but does not block access to the MDI windows nor to the MDIs menu bar.

When Keep in Frame is set to No, two further properties appear in the Properties window. These are Keep On Top and Parent Window. The Parent Window property is relevant only to windows that have Keep in Frame set to No, and Keep On Top also set to No. The Parent Window property will not appear in the Properties window if the Keep On Top property is set to Yes.

Unlike dialogs, screens that have Keep in Frame set to No can be minimized or maximized. The behavior when they are minimized is determined by the Parent Window property.

Windows outside the MDI frame do not appear in the Windows menu list in the standard MDI application menu. And they cannot be accessed by function keys like Ctrl+F6. They can, however be accessed by Windows shortcuts such as Alt+F6.

The Parent Window Property

Windows that have the Keep in Frame property set to No and are not designated as Topmost windows can either have no parent or they can be parented by the MDI frame. If the parent is designated as None then the screen can be hidden by the MDI frame when the latter is given focus. If the screen is designated as parented by the MDI frame, then the screen will always appear on top of the MDI frame. In this case, even if focus is given to the MDI frame, or one of the windows inside the MDI frame, the non-Keep in Frame window will always be displayed, and will not be obscured behind the MDI frame. Note that a non-Keep in Frame window whose parent is the MDI frame can still be hidden behind other windows that are not part of the Panther application. To designate that a window should never be obscured behind another window, whether that other window be part of the Panther application or not, use the Keep on Top property.

When a non-Keep In Frame window is minimized, the location of the icon representing it depends on the window's parent. A non-Keep In Frame window with no parent will be represented by an item on task bar. A non-Keep in frame window whose parent is the MDI frame will be represented by an icon in the desktop's lower left, just above the taskbar.

The Keep On Top Property

A non-Keep in Frame window can be designated as a Topmost window by setting the Keep On Top property to Yes. A Topmost window will generally be rendered on top of any other window on the desktop, no matter which application is active. The only windows that can be placed on top of a Topmost window are other Topmost windows.

Runtime Access to the Window Options Properties

At runtime the properties PR_KEEP_IN_FRAME, PR_KEEP_ON_TOP, and PR_WINDOW_PARENT are read only. Once a window has been opened, its status with regard to these settings cannot be changed.

Attaching a Menu Bar

Menu bars provide users with a convenient method for accessing a variety of commands and functions.

• In character mode, the menu bar is displayed at the top of the physical screen.

• Under Motif, the menu bar/toolbar is displayed at the top of the base window.

• Under Windows, the menu bar/toolbar is displayed at the top of the MDI frame.

When you click on a menu option, a submenu drops down. Drop-down menus display items that can either invoke dialog boxes or carry out commands.

How to Attach a Menu to a Screen

It is assumed that you have already created the menu and/or toolbar and that it resides in a menu script. For details on creating menu bars, refer to Chapter 25, "Menu Bar Editor." For information on loading menu script files, refer to Chapter 15, "Including Menus and Toolbars," in Application Development Guide.

1. Select the screen.
2. Under Focus, enter the name of the menu in the Menu Name property.

   At runtime, Panther checks the screen-level location to see if the named menu is in the installed menu script, and then checks application-level. If the named menu is not in an installed menu script, proceed to step 3.

3. Under Focus, in the Menu Script File property, enter the filename or choose More to select the file (*.mnu) from the Select Library Member dialog box.

   This specification loads the named script into this screen's memory. All other menus defined in this script are available for display with this screen.

   If you do not supply a menu name in the Menu Name property, Panther displays the first menu in the specified script.

You can also load menu scripts and install menus by calling sm_mnscript_load and sm_menu_install, respectively. Refer to the Programming Guide for a description of these functions.

Assigning a PopUp Menu

A popup menu can be opened when the user presses the right mouse button. By default, the screen's menu bar is displayed as the popup.

How to Display a Popup Menu that is Different from the Screen's Menu Bar

1. Select the screen.
2. Under Help, enter the name of the menu in the Popup Menu property.

The menu must be in a script that is already loaded in memory. Panther checks the screen-level location first, and then application-level for the named menu. For details on creating menu bars, refer to Chapter 25, "Menu Bar Editor." For information on loading menu script files, refer to Chapter 15, "Including Menus and Toolbars," in Application Development Guide.

At runtime, the user sees the specified popup menu when the right mouse button is pressed anywhere in the screen area. However, if the mouse is over a field that has its own popup menu designation, the field's popup menu is displayed instead. For information on attaching a popup menu to a widget, refer to "Invoking a Popup Menu."

Testing Menus

Once you attach the menu, you can test it with the screen.

1. Bring focus to the screen.
2. Choose FileTest Mode or choose the Test button on the toolbar.

   The screen is displayed in Test mode with its menu bar.

---

Documenting Screens

Two properties under Identity in the Properties window help you document the contents of your screens:

• Comments property—Provide a brief description of the screen.

• Memo Text property—Attach up to nine lines of text for additional comments or for programmatic use.

Adding Comments

By including a brief description of your screen, you can provide information to other developers about the screen, its content, and its purpose. This description is displayed when you view the Repository TOC and scroll through each of the repository entries.

How to Add or Edit Comments on Your Screen

1. Select the screen.
2. Under Identity, select the Comments property. The Comments dialog box opens.
3. Do one of the following to enter or edit text:

   • Type the text directly in the text area.

   • Choose Editor to access your local editor (as defined in the SMEDITOR variable).

   • Choose Read File to read in an external file located on your system.

   • Choose Save File to save the comments to an external file.

4. Choose OK to save the comments and return to the Properties window.

1. Select the screen.
2. Under Identity, expand the Memo Text subheading. Nine memo lines are displayed.
3. Type additional information, comments, and specifications that you can't indicate or specify as a screen property.

   At runtime, you can access the screen's Memo Text property to determine what action to take depending on the property's content. For information on accessing screen properties, refer to "Properties" on page 19-40 in Application Development Guide.

---

Defining XML Tags for Screens

As of Panther 5, you can import and export XML data from a Panther screen. To use this feature, you must:

• Define properties for the screens and the widgets to be included in the XML data

• Call the appropriate functions to write data to the buffer or file holding the XML data

This section describes the property specifications for screens. For information on widget properties, refer to "Defining XML Tags for Widgets." For details on using the XML interface, refer to Chapter 22, "Using XML Data," in the Application Development Guide.

How to Set XML Properties for Screens

1. Select the screen.
2. Under XML, enter a value in the XML Tag property.

• or

  Under XML, enter a value in both the XML Prefix and XML Postfix properities.

  Note: If the XML Prefix property is empty, the generated XML begins with the following line:

  <?xml version="1.0"?>

3. (Optional) If you entered an XML tag for the screen, you can enter additional attributes in the XML Attributes property.

---

Testing Screens

For information on testing screens, refer to Chapter 38, "Testing Application Components," in Application Development Guide.