Using the Editors


Chapter 10 . Controlling the Way Things Look

To some degree, when you define the way things look, you also define the way those things act. This chapter describes how you control what the user sees, for example:


Giving Widgets Initial Data

You can specify that a widget has initial data or displays some initial text. This data is what displays when the screen first opens; it's what the user sees. Therefore, initial text can be, for example, instructions for the user, a default or suggested selection, or an identifier. The property to enter this information varies by widget type.

How to Define Initial Text or a Label for a Widget

  1. Select the widget.
  2. Depending on the widget type, you can define initial text by selecting the appropriate property:
  3. You can enter data in the dialog box by doing any of the following:
  4. Choose OK to close the dialog box and return to the Properties window.

Changing Widget Type

Through the editor you can change a widget from one type to another. For example, you can change a single line text widget into a list box, change a vertical scale to a horizontal scale, or a combo box into an option menu.

Note: Lines, boxes, graphs, grid widgets, and links cannot be changed to other widget types.

How to Change Widget Types

  1. Select the widget.
  2. Under Identity, in the Widget Type property, select the desired type from the Setting field option menu.

The original widget is replaced with a default widget of the specified type. Any properties that you defined for the original widget that are common to the new widget type are applied; however, properties which are not valid for the new widget are lost. Panther attempts to position the new widget in the same place as the original.

Initial text can be lost, particularly in cases where you change a multiarrayed widget, such as a list box, to a widget with a single onscreen element, like a single line text widget or option menu.


Formatting Text

Formatting text in a widget includes:

To Display or Not Display

Widgets designated as hidden are visible in Edit mode in screen editor, but are not visible in Test mode or at runtime.

How to Hide a Widget at Runtime

  1. Select the widget (except static labels).
  2. Under Identity, specify the visibility state in the Hidden property:

How to Hide the Contents of a Field

  1. Select the single line (including those within a grid widget) or multiline text widget.
  2. Under Format/Display, set the Password Field property to Yes. The Password Char subproperty is displayed.

    All initial text (as specified in the Initial Text property) is made invisible. At runtime, the field can be seen, however, characters typed or accepted into the field are not displayed. This property is useful for creating password fields.

  3. (Optional) In the Password Char subproperty, enter a single character that you want to display when the user types.

    For example, if you enter *, each character the user types in the field is represented by an asterisk. All initial text (as specified in the Initial Text property) is replaced with the specified password character.

Justification

In the English language, characters are usually entered from left to right; they are left-justified. By default, the characters in all widgets are left-justified, except for toggle buttons and push buttons, which have a centered label.

You can change the text justification on the following widget types: single line and multiline (without a word wrap specification) text widgets, dynamic labels, option menus, combo boxes, radio buttons, check boxes and list boxes.

How to Change Text Justification in a Widget

  1. Select the widget.
  2. Under Format/Display, specify the desired position in the Justification property:

How to Control the Text Justification on Box Widgets

  1. Select a box widget.
  2. Under Identity, enter a title for the box in the Label property. The Justification subproperty is displayed.
  3. Specify the desired position for the text: Left, Right, or Centered (default).

Aligning Button Labels in Motif

In Motif, you can change the default alignment of label text by making the appropriate entries in the resource file for your application. By default, all push button and toggle button labels are centered:

Prolifics*area*XmPushButton.alignment:						ALIGNMENT_CENTER
Prolifics*area*XmToggleButton.alignment: ALIGNMENT_CENTER

To left justify all push button and toggle button labels, set these resources to ALIGNMENT_BEGINNING:

Prolifics*area*XmPushButton.alignment:						ALIGNMENT_BEGINNING
Prolifics*area*XmToggleButton.alignment: ALIGNMENT_BEGINNING

To right justify all push button and toggle button labels, set the resource values to ALIGNMENT_END:

Prolifics*area*XmPushButton.alignment:						ALIGNMENT_END
Prolifics*area*XmToggleButton.alignment: ALIGNMENT_END

To left justify all push button labels on a specific screen, use the following resource specification in your resource file:

Prolifics*screen_name*area*XmPushButton.alignment: ALIGNMENT_BEGINNING
Prolifics*screen_name*area*XmToggleButton.alignment: ALIGNMENT_BEGINNING

For example, to left justify all push button labels on the screen named myscr, set the following resource:

Prolifics*myscr*area*XmPushButton.alignment: ALIGNMENT_BEGINNING

To align the label on an individual button on a screen, use the following resource specification in your resource file:

Prolifics*screen_name*area*button_name.alignment: alignment_specification

For example, to right justify the label on the widget mybutton1 only when it appears on the screen myscr, set the following resource:

Prolifics*myscr*area*mybutton1.alignment:						ALIGNMENT_END

To align the label on a button throughout your application, use the following resource specification in your resource file:

Prolifics*area*button_name.alignment:						alignment_specification

For example, the following resource specification will center the label on mybutton2 wherever it appears throughout the application.

Prolifics*area*mybutton2.alignment:						ALIGNMENT_CENTER

Specifying Fonts

You can use fonts in your application that are:

When you create a screen, a default font is applied, derived either from a Panther distributed configuration map (cmap) file or from your GUI platform. Under the Font heading in the Properties window, all font-specific properties are set to Default for the screen and for any widgets you add to the screen (except for those that have a font assignment of their own, because the widget is a copy or inherits its property values from a repository entry).

The Default setting means that at runtime Panther resolves which fonts to apply based on what is set at a higher level. Therefore, a widget's Default specification means it uses the screen font assignment. The screen's Default specification means it uses the application-wide specification.

You can define fonts at any of the following levels:

Assigning a Prolifics Font

Prolifics fonts include several standard font styles: Courier, Helvetica, Symbol, and Times Roman, etc. These are defined in your Panther configuration map file, and resolve appropriately to a GUI-specific font for your platform. Depending on the platform and the font selection, a point size and other display attributes are automatically assigned. (For details on editing the cmap file, refer to "Configuration Map File" in Application Development Guide.)

How to Assign a Font to a Screen or to One or More Widgets

  1. Select the screen or widget.
  2. Under Font, specify the desired typeface in the Font Name property by doing one of the following:
  3. Under Font, specify the desired size of the typeface in the Point Size property. The drop-down list of font sizes includes point sizes that are available for the specified font and are defined in your cmap file, plus Default.

    Under Windows, you can also enter a value if the font is scalable.

    Note: If you specified a font that includes default attributes, such as bold, italic, or underline, the following steps may have no effect on the way the font looks.

  4. Under Font, set the Bold property to one of the following:
  5. Under Font, set the Italic property to one of the following:
  6. Under Font, set the Underlined property (which has no effect under Motif) to one of the following:

Assigning a GUI Font Name

GUI-specific fonts are the least portable. Your specifications will reside with the screen and you should map them as needed in the configuration map file. Selecting a font in this way, as described here, allows you to choose attributes that may not be included in your cmap file and see a sample of how the selected font looks.

How to Assign a GUI-Specific Font

  1. Select the screen or widget.
  2. Under Font, select the Font Name property.
  3. Choose More. A GUI-specific font selection window opens.
  4. Select the desired font. The selection window shows a sample of how the font appears.
  5. Choose OK from the font selection window once you have made your selection. You resume in the Properties window.
  6. Choose OK on the Properties window to confirm your selection.

    Under Windows, Panther sets the point size and other style options to Yes in the corresponding properties—Bold, Italic, and Underlined. If the styles do not apply, the properties remain set to Default.

Displaying Null Values

To distinguish between when a field is null and when it has data that is not visible or available (for example, a field that is blank), you can specify that it should display a null indicator string when no data is present. A field is considered null if both of the following conditions are met:

When a field is null, the null indicator string is displayed in the field, and the field is, by default, selected on entry. The null indicator string is cleared when the user enters data.

The null indicator is defined as blank in the SM_NULLEDIT variable in your Panther message file. If you prefer a different default null indicator, you can change the value of SM_NULLEDIT. (For information on editing the message file, refer to "Creating and Modifying Message Files" in Application Development Guide.)

To distinguish a blank field from an empty (null) one, you can either:

How to Allow a Widget to Accept and Display a Null Value

  1. Select the widget.
  2. Under Format/Display, set the Null Field to Yes. Additional null-related subproperties are displayed.
  3. In the Null Text property, enter a character string (up to 256 characters long) that will be displayed at runtime when the field is empty or null.

    For example, enter an X, an * (asterisk), or null.

  4. (Optional) To fill the field with the specified indicator string, set the Repeating property to Yes.

    Whatever character or string you have entered in the Null Text property will fill the field to its maximum length. The Repeating property has no effect if you do not specify a Null Text property.

Widgets that have a Null Field setting are made null at runtime if any of the following occurs:

Use the library function sm_null to determine whether or not a field is null. The function sm_getfield returns the content of the field, which is the null text string (possibly replicated) if the field is, in fact, null.

Controlling Grid Formats

To control the appearance of data in grid widgets, you can set the following properties:


Creating Shifting/Scrolling Fields

A widget must occupy at least one position on the screen. However, a widget can be larger, in two dimensions, than its onscreen capacity; a field can shift and scroll. Shifting extends a field's widget beyond its onscreen width. Scrolling permits a field to hold more data items that will fit onscreen.

Creating an Array

Each widget is an array, although for the most part, an array of one occurrence. This is the base field. You increase the array to include additional occurrences by specifying that the widget has more than one element; the base field is the first element of the array.

How to Create an Array with More than One Occurrence

  1. Select the widget.
  2. Under Geometry, set the property appropriately for the widget type:
  3. (Optional) In the Spacing subproperty, enter the amount of space desired between each occurrence of the array. Refer to Table 9-1 for a list of valid units of measurement.
  4. (Optional) To create a horizontal array, set the Horizontal subproperty to Yes. If the current screen size cannot accommodate the horizontal array, it resizes at runtime to best accommodate all or as many elements of the array as can display (providing scroll bars to view offscreen widgets). For information on controlling a screen's viewport, refer to "Displaying Screens" in Application Development Guide.

Each element of an array is assigned a unique field number, but shares its properties with the base field. You assign a name to the array as a whole, and not for each element. The array slots are called occurrences. The elements of the array are the mechanism through which the array's occurrences are viewed. A scrolling array can have more occurrences than elements. A simple array has the same number of occurrences as elements.

Creating a Scrolling Array

Any widget that has either the Onscreen Rows property or Array Size property can be defined as a scrolling array. When you specify that a widget has a greater number of occurrences than can be displayed on the screen, the widget is referred to as a scrolling array.

For details on creating synchronized arrays, refer to "Synchronizing Scrolling Arrays."

How to Define Offscreen Occurrences for a Selected Widget

  1. Under Geometry, set the Scrolling property to Yes. Additional scrolling-related properties are displayed.
  2. Under Scrolling, in the Max Occurrences subproperty, enter the total number of occurrences. By default, Max Occurrences is set to be equal to the number of onscreen occurrences. Set the property to blank to allow for the maximum number of occurrences allowed for the operating system/database driver.

    The Max Occurrences value must be greater than or equal to the number specified in the Array Size property or Onscreen Rows property in order to scroll.

  3. (Optional) Under Scrolling, in the Scroll Increment property, specify the number of occurrences by which the array should scroll when the user presses Page Up or Page Down. The default is one less than the number of onscreen occurrences.
  4. (Optional for multiline text and list box widgets) Under Scrolling, the Vert. Scroll Bar property is, by default, set to Yes; set the property to No if you don't want vertical scroll bars.
  5. (Optional) Under Scrolling, set the Circular property appropriately:

Creating a Shifting Field

If the maximum length of a widget is greater than the display length, the widget is referred to as a shifting field. By default, single line and multiline text widgets are shifting fields.

How to Create a Shifting Field for a Selected Widget

  1. Under Geometry, set the Length property to the number of columns of data that the widget can display at a time.

    Note: This number does not necessarily define the number of characters that are displayed, especially if your screen or widget uses a proportionally spaced (varied-width) font.

  2. Under Geometry, in the Max Data Length property, enter a number greater than the Length property. This number defines the maximum number of columns that the widget can hold. Choose OK. Additional properties are displayed.
  3. (Optional) Under Max Data Length, in the Shift Increment subproperty, enter the number of characters by which the data should be shifted when the user moves the cursor beyond the onscreen length.
  4. (Optional for multiline text and list box widgets) Under Max Data Length, set the Hor. Scroll Bar property appropriately:

Creating a Date and Time Field

You can assign a date and/or time format to almost any widget type (except static labels and scales). You can enforce a format for user-entered dates or times, or specify the format in which the system date or time is displayed.

How to Set a Date/Time Format for a Selected Widget

  1. Under Format/Display, specify Date/Time in the Data Formatting property. Additional date/time-specific properties are displayed.

    Note: By default, the property is set to None. However, if the widget is derived from a database column and has as a date/time edit, Panther sets the Data Formatting property to Date/Time.

  2. In the Format Type subproperty (which for dates is date_format at runtime), select one of the following:
  3. In the System Update property, specify whether or not the date/time is updated by the system.
  4. In the Frequency subproperty, specify how often the system date/time is updated. Indicate time interval in seconds. The default is zero.

    If the interval is set to zero, the system date/time is updated only under the following conditions:

  5. In the Clock Type subproperty, specify a 12-hour or 24-hour clock.

    Note: If you specify a 12-hour clock, consider a custom format that includes an AM/PM indicator.

Defining a Custom Date/Time Format

In addition to the default settings that you can specify by name, you can format a date or time string to suit your needs by using combinations of literal strings and Panther-specific substitution variables (refer to Table 10-2).

A literal character forces entry of that particular character. A substitution variable forces entry of a string that matches the specified format. For example, if you enter a Custom Format setting of HR:MIN:SEC, a runtime entry of 09:19:21 is accepted.

To embed punctuation, such as spaces, slashes, or colons, enter literal characters as part of the Custom Format setting. Table 10-1 illustrates samples of date/time format strings and input that is considered valid.

Table 10-1 Examples of date/time format strings

Format String Acceptable Input

MON2/DATE2/YR2

03/03/89

DATE2/MON2/YR4

19/09/1956

DAYL MONL DATE, YR4

Saturday December 26, 1954

HR:MIN2AMPM

2:04PM

Table 10-2 lists the substitution variables you can use for customizing date/time formats.

Table 10-2 Substitution variables for customizing date/time format

Substitution Variable* Input

DATE

day of month

DAYA

abbreviated day name

DAYL

long day name

WEEKDAY

numeric day of the week

MON

month number

MON2

month number, zero filled

MONA

abbreviated month name

MONL

long month name

YR4

4 digit year

YR2

2 digit year

YDAY

day of year

HR

hour

HR2

hour, zero filled

MIN

minute

MIN2

minute, zero filled

SEC

second

SEC2

second, zero filled

AMPM

am or pm

*Substitution variables must be entered in upper case.


Defining a Numeric Format

You can display data as a string of numbers with the appropriate punctuation, like a comma and decimal point, or assign the appropriate currency characters to display monetary data. The format you define is applied to the data during field validation, and non-numeric data is discarded.

How to Set a Numeric Format for a Selected Widget

  1. Under Format/Display, in the Data Formatting property, specify Numeric. Additional number-specific subproperties are displayed.
  2. In the Format Type subproperty (which for Numeric is numeric_type at runtime), select either of the following settings:
  3. (Optional) If you specify Custom in the Format Type property, set the Min Decimals and Max Decimals subproperties to a value (both default to 2) between 0 and 9, inclusive.

    If Min Decimals is greater than the Max Decimals specification, numbers entered in the fields are rounded to the nearest whole number, and the number of decimal places specified is padded out with zeroes. For example, if Max Decimals is 0 and Min Decimals is 2, entering the number 22.546 displays as 23.00.

  4. Define numeric and/or currency punctuation to be used in your custom format of the data.
  5. (Optional) To display the data as monetary output, specify the desired currency format.
  6. In the Rounding property (a subproperty of a Numeric setting in the Data Formatting property), specify Round Up, Round Down, or Round Adjust (default is to round up above 5).

    Refer to Table 10-4 for examples of how rounding options work.

    Table 10-4 Examples of rounding options

    Number Entered Round Up Round Down Round Adjust

    2.056

    2.06

    2.05

    2.06

    -2.056

    -2.05

    -2.06

    -2.06

    2.055

    2.06

    2.05

    2.06

  7. Define what should occur if the numeric data is blank or equal to zero.

Giving Screens a 3D Appearance

Panther allows you to provide a three-dimensional appearance to your screens and the widgets on those screens when you are running Panther or a Panther application under Windows.

Note: If you are running Panther under Motif, which provides native support for three-dimensional widgets, use the settings in your Motif environment to enable or disable the 3D feature.

How to Implement the 3D Feature for a Screen

Select the screen. Under Identity, set the 3D property to one of the following:

If the 3D option is enabled in the .ini file for your application, message boxes and Windows common dialog boxes also take on a three-dimensional appearance. If this initialization option is not set, only those application screens that have the 3D screen property set to Yes appear in 3D.

The 3D screen property setting is ignored when Panther is running on a platform other than Windows. Thus, if your application will run on multiple platforms, Windows among them, set the 3D property to the value that will give the desired appearance under Windows; when the application runs on any other platform, screen appearance is unaffected.

Three-Dimensional Screen and Widget Appearance

This section describes how screens, and the widgets on those screens, appear when the 3D feature is enabled under Windows.

Screens

The background color of 3D screens and dialog boxes is determined by the Button Face color setting on the Windows control panel, and overrides the background color specified in the Properties window for the screen.

Dialog box title bars appear indented; title bars on non-dialog screens do not have a 3D appearance.

Screen size might increase slightly if additional space is needed to accommodate the 3D effects imposed on the screen's widgets.

Widgets

The following widgets do not change appearance when 3D is enabled:

All other visible widget types change in appearance, as described below. Unless otherwise noted, all widgets affected by the 3D setting take on the same back ground color as the screen on which they appear (that is, the Button Face color setting on the Windows control panel).

The amount of screen real estate needed by 3D widgets might increase slightly because of the border used to create the three-dimensional effect.

Text and multiline text widgets appear indented into the screen, with a 3D border around the entire widget.

List boxes appear indented into the screen, with a 3D border around the entire widget. Scroll bars are the screen background color if active; if inactive, they are the Window Background color, as set on the Windows control panel.

Option menus appear indented into the screen, with a 3D border surrounding both the text and the drop-down area.

The text area of the combo box appears indented into the screen. A 3D border surrounds the text area only and not the drop-down button.

The selection area on check boxes (square) and radio buttons (circle) appears indented into the screen; its color is the Window Background color, as set on the Windows control panel. The selection indicator (X or dot) is black. The label text does not appear 3-dimensional.

If the Line/Box Style property is set to Default, the line or box appears in the Etched In style. If it is set to any other style, the line or box is unaffected by the screen's 3D setting.

Boxes with a Line/Box Style property set to Default or Etched In take on the background color of the screen; if the Line/Box Style is set to any other value, the background color setting in the Properties window remains in effect.