Using the Editors


Chapter 22 . Graphics Widgets

Adding graphical elements to your screens can enhance the look and, in addition, can serve to illustrate, organize, and group information—thus achieving an attractive presentation as well as a functional one.

This chapter describes how to:


Using Boxes and Lines

Drawing a line or box on your screen is as simple as dragging the mouse.

How to Create a Line or Box

  1. Choose CreateLine or Box, or select the icon on the Create toolbar.
  2. Drag the mouse horizontally, vertically, and, in the case of a box, diagonally to the desired length or size.

    The widget acquires a native line style (Default). You can change the style, as well as assign foreground colors and background colors.

How to Control the Line or Box Placement

To control where the line or box starts and/or ends on the screen:

  1. Select the line or box widget.
  2. Under Geometry, define the start and end positions in the following properties.

    Use grid positions if portability is an issue, or use fractional specifications if desired. (Refer to Table 10-1 for a list of valid units of measurement.)

Specifying Styles for Boxes and Lines

When you draw a line or box on your screen, a default style is assigned which is appropriate to the native environment. However, you can choose other styles as well as assign a style that can, ultimately, make your specification portable to other platforms.

How to Define a Line Style for a Box or Line Widget

You can specify a line name alias by choosing Other in the Line/Box Style. The Other Style subproperty is displayed. Enter the name as defined in the configuration map file for your application.

To control line/box style mapping and alias names, you can assign the desired specification in the configuration map file. Refer to "Defining Line and Box Styles" in Application Development Guide for more information on assigning and mapping line/box styles.

Character Mode Lines and Boxes

Styles 0 through 9 are native to Prolifics running in character mode. Style 1 is defined as the default line style. When you assign a character-specific style as the Style property value for a line or box style in the editor, that style is mapped to style 1 on non-character mode Prolifics applications. GUI-specific styles map to style 1 when running in character mode.

GUI Lines and Boxes

Motif's native line styles are: single, double, dash, double dash, etched in, etched in dash, etched out, etched out dash, and none. The Default setting maps to a single line style. Motif's box styles are: etched in, etched out, in, and out; the Default setting maps to Etched In.

Native styles for lines and boxes in Windows are: single, dash, dot, dashdot, and dashdotdot. The Default setting maps to a single line style for both graphical elements.

If the 3D feature is enabled, the etched in style is also available under Windows. Refer to "Giving Screens a 3D Appearance" for an explanation of how line and box appearance is affected on 3D screens on these platforms.

Creating Frames

Frames can help you design attractive, logically structured, and easy-to-use screens. You create a frame by using the box widget. The box can be titled or untitled. Use frames around widgets on your screen to:

How to Include a Title on a Box

When you use a box to enclose, for example, related widgets, you can also provide a title on the box that identifies the fields as a group.

Notes: The Label property is not supported for boxes in Prolifics reports.

  1. Select a box widget.
  2. Under Identity, enter the text in the Label and choose OK. The Justification subproperty is displayed.

    By default, the label text is centered on the top border of the box.

  3. To change the text alignment, under Identity, set the Justification subproperty:

If you want to control how widgets resize and shift if you port your screens, you can use the screen's positioning properties, or you can identify the box widget as a positioning region in and of itself.

  1. (Optional) Under Geometry, set the Position Region property appropriately.

Adding Lines

Add lines to your screen to create physical definition and provide organization to the content of the screen. Like the box widget, you can choose the style of line.


Using Boxes as Positioning Regions

Prolifics uses a positioning algorithm to recalculate screen size and widget positions (refer to "Controlling Widget Positions and Screen Size" for more information) when you open a screen in an environment that is different from the one in which it was created. This algorithm uses the settings of the screen's Positioning properties (subproperties under Geometry).

Similarly, each box has its own set of Positioning properties, available when the Position Region property is set to Yes, that can be set independently of the screen. When you open a screen in a new environment, Prolifics recognizes each box as an autonomous positioning region and recalculates its size and the positions of widgets within it.

When a box widget's Position Region property is set to Yes, its Positioning properties let you:

Spacing Widgets within a Box

Two properties, Minimum Horizontal Space and Minimum Vertical Space, let you specify the minimum amount of space between widgets in any direction. You can set the amount of space in any unit of measurement (refer to Table 10-1). If all available whitespace is used up between widgets, Prolifics moves them or adjusts the box size in order to maintain the minimum spacing required.

Minimum Horizontal Space

Determines the minimum amount of space maintained between widgets that are horizontally contiguous. The default 0 allows widgets to touch. If you place widgets closer than the distance specified by this property,

Prolifics does not try to increase the space between them.

Minimum Vertical Space

Determines the minimum amount of space maintained between widgets that are vertically contiguous. The default value is 1 grid unit. If you place widgets closer than the distance specified by this property,

Prolifics does not try to increase the space between them.

How to Define a Margin Within the Box Frame

The Region Margin property creates a buffer of white space between the box's inner border and its contents.

  1. Select a box widget.
  2. Under Geometry, ensure that the Position Region property is set to Yes. The Positioning properties are then available.
  3. Under Geometry, expand the Positioning heading and set the Region Margin property to the desired amount of space.

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

    You can set the amount of space in any unit of measurement (refer to Table 10-1). For example, enter 4 to indicate four pixels or 3g to indicate three grid units.

How to Control the Box Dimensions and Widget Start Positions

When you open a screen in an environment different from the one in which it was created, Prolifics attempts to minimize differences between the presentation of the same screen on different platforms. In so doing, it typically adjusts a box widget's dimensions and the start positions of other widgets within it.

  1. Select a box widget.
  2. Under Geometry, ensure that the Position Region property is set to Yes. The Positioning properties are then available.
  3. Under Geometry, expand the Positioning heading and set the Horizontal Shrinking and/or Vertical Shrinking subproperties accordingly:

Prolifics adjusts widget start positions in order to simulate their original proximity; when moving from character mode to GUI modes, this is likely to leave extra white space at the box's borders.


Adding Borders to Widgets

How to Define a Widget Border and Style

The list box and multiline text widgets both have properties that allow you to specify a border style as well as a title. These properties have no effect on the GUI platforms; however, you can achieve the same look in the GUI environments by using a box widget around the widget.

  1. Select a list box or multiline text widget.
  2. Under Format/Display, set the Border property.
  3. Under Border, specify the desired line style (0 through 9) in the Style property (default is 1 which maps to a single line style).

    The numeric style specifications are defined in your video file (refer to "Borders and Line Drawing" in Configuration Guide for information on border styles).

How to Include a Title on a List Box or Multiline Text Widget

  1. Select a list box or multiline text widget.
  2. Under Format/Display, set the Border property to Yes. The additional border properties are displayed.
  3. Under Border, enter a title or any descriptive information in the Title subproperty. The text is aligned to the left corner of the border.

Displaying a Picture on Widgets

In general, a textual label is displayed on push buttons, toggle buttons, radio buttons, check boxes, static and dynamic labels.

Prolifics provides properties for you to specify the name of a pixmapped or bitmapped image that will display instead of the text on these particular widgets. These property settings have no effect in character mode.

To create a bitmap, use the image editor or paintbrush utility on Windows. On Motif, use the bitmap utility provided with X, or create a pixmap file in the standard pixmap format, either as a text file or via a utility provided with your GUI. Most GUI platforms also provide sample image files that you can use.

Prolifics supports BMP (.bmp), GIF (.gif), and JPEG (.jpg) files under Windows and Motif, XPM (.xpm, .xpm1, .xpm3) and XBM (.xbm) files on Motif.

Specifying the Image

Under the Format/Display heading in the Properties window, there are three image-related properties. Via these properties, you can assign one (static labels take only one) or more images (dynamic labels have only two of these properties) to a widget with each picture depicting a different state: active, armed, or inactive.

Note: Specify a textual label in the widget's Label property as well. If the Active Pixmap file is not found at runtime or is not supported by the local GUI, or if you run your application in character mode, the widget's label is displayed instead.

How to Display a Picture on a Widget

  1. Select the widget (push button, radio button, check box, toggle button, static label, or dynamic label).
  2. Under Format/Display in the Active Pixmap property, enter the name of the image file or choose More to select the file from the Select Library Member dialog box. Choose OK. Depending on the widget type, additional pixmap properties are displayed.

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

    At runtime, the specified image is displayed on the widget whenever the widget appears and as long as the widget is active (that is, it can get focus). If the widget is made inactive at runtime, you can specify another image to indicate the widget's state.

  3. Under the Active Pixmap property in the Armed Pixmap subproperty, enter the name of the image file or choose More to select it from the Select Library Member dialog box.

    The specified image is displayed on the widget when the widget is activated (or armed), that is, when it is pushed, selected, or checked. This property is not available for static or dynamic label widgets because they cannot get focus.

  4. Under the Active Pixmap property in the Inactive Pixmap subproperty, enter the name of the image file or choose More to select it from the Select Library Member dialog box.

    The specified image is displayed on the widget when the widget is set to be inactive (via the Active property under Identity) or is made inactive at runtime.

    Note: Via the Select Library Member dialog box, you can add image files on the system to an open library by choosing the Add button.

Portability of Images Files

To facilitate portability and provide maximum flexibility, omit the filename extension when you specify an image file. At runtime,

Prolifics searches for files in all open libraries using all possible image extensions supported on the local platform.

On the other hand, if you have multiple images of the same name but of different type (for example, dog.bmp 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.

Storing the Image Files

Under Motif, if the file is not found in an open library, then the path indicated in the resource file is used to search for X bitmap files (for the XmGetPixmap resource). Refer to the OSF/Motif Programmer's Reference.

Under Windows, Prolifics searches for bitmaps in these locations, in the order given:

  1. The application's resource file.
  2. Any DLLs loaded into memory by sm_slib_load.
  3. Open libraries.

Sizing the Image

Bitmapped and pixmapped images display by default at the size they were created. Default-sized widgets (those having no Height or Width property settings) will resize to accommodate the image. Once you attach the image, resize the widget to the desired size by either dragging the widget or by setting its Height and Width properties to accommodate the image.

Under Windows, bitmapped images automatically scale to fit within the specified geometry of the widget. Under Motif, the pixmapped image is truncated if it cannot fit within the specified dimensions of the widget.

To ensure that the widget size remains fixed and is unaffected by changes to the pixmap image, set explicit values in the widget's Height and Width properties.


Using Customer Drawn Widgets

You can use Prolifics's push buttons, toggle buttons, and dynamic label widgets to display dynamically drawn content by your application, instead of a label or a static pixmap. To let Prolifics know that you have installed a drawing function, set the Customer Drawn property under Format/Display to Yes. Use the library function sm_attach_drawing_func to attach the drawing function. This property setting only has an effect in GUIs. When running your application in character mode, the default Prolifics widgets display.

The widgets behave as they are defined through their properties. In other words, the push button and toggle button are pushed to activate, and dynamic labels are protected from getting focus at runtime. Prolifics handles all processing for these widgets as it normally would, except for drawing them. However, the shading, where applicable, is still handled by Prolifics.