Application Development

This chapter shows how to set up an interface that is suitable to a GUI platform or user environment. It also discusses strategies for writing applications for non-English-speaking users.

Two distributed files are especially important in designing the user interface:

• The message file contains messages that are seen by end users. It also defines default constants and formats—for example, text labels for message window push buttons, numeric/currency formats, date and time formats, and Panther error messages. You can also use the message file to customize screen editor features for specific languages and format conventions.

• The configuration map file lets you define system-independent aliases for colors, fonts, and line and box styles.

Both files exist independently of the application; this facilitates development and deployment in several ways:

• Definitions are in a single location, so they are easy to access and modify.

• You can edit the source and recompile it independently of the application executables.

• Different parts of an application can access the same definitions, which saves space and development time.

• You can deploy the same executable in different environments, where each distribution uses a different message and configuration map files that suits its own environment. For example, if you need to deploy an application in different countries, you can create separate message files, which translate message text, date/time formats, and numeric/currency formats to comply with local languages and customs. Similarly, an application that runs on Motif and Windows can use separate configuration files for each platform, which map GUI-specific font and color names to aliases.

Using Message Files

Messages are stored in a binary file that is referenced by the application variable SMMSGS, and are loaded into memory at startup. SMMSGS can be set in the environment or Windows initialization file, or in a setup file. The Panther configuration directory provides a file of message defaults in source (msgfile) and binary (msgfile.bin) formats. You can edit the message file source to suit the needs of a given application, then recompile it with the msg2bin utility.

Creating and Modifying Message Files

You can edit the source of the distributed message file; you can also supplement this file with message files that contain your own application messages. If you must change the Panther message file, first create a copy of the distributed message file and edit it instead of the original. By doing so, you avoid losing changes with new releases; you also have recourse to the original message file contents.

If you create custom application messages, maintain them in a separate file for these reasons:

• Custom messages are easier to maintain if they are kept in their own file.

• You avoid corrupting Panther messages.

• Custom message files are not overwritten by the new message file that is supplied with each new Panther release.

After you modify an ASCII message file, you must convert it to binary format with msg2bin. If the message file includes new entries, you must also create a C header file with msg2hdr.

• msg2bin converts ASCII message files to binary format for use by Panther. The output of msg2bin is a binary file; the utility uses message tags to distinguish between system and user messages. If you have multiple message files, you can compile them into a single binary file by running msg2bin with the -o option.

• msg2hdr converts the message source file to a C header file, which contains #define statements for each user message tag.

• msg2hdr can also define JPL global variables, which make the messages accessible in JPL.

How to Create or Add to a Message File

1. Create or access the ASCII message file using a text editor.
2. Edit existing entries or add new entries using the syntax described in the next section. For example:

   #user messages

   US_NOTAVAIL   = All copies of this movie are unavailable.

   US_ACTL       = Enter an actors last name.

   #administrator messages

   ADM_INVALIDRC = Invalid rating code.

3. Convert the ASCII file to binary format with the msg2bin utility.

   If you only edit the text of existing message tags, your work is done. If you add new entries to the message file, continue with step 4.

4. Define new message tags in a C header file. This makes the messages available to Panther functions such as sm_fquiet_err. Do this by running msg2hdr on the message source file. Messages are numbered sequentially from 0x0 to 0xF. For example:

   #define US_NOTAVAIL    0x0

   #define US_ACTL        0x1

   #define ADM_INVALIDRC  0x2

5. In order to access your messages in JPL, define your tags as global JPL variables in a C header file. Do this by running msg2hdr with the -j option on the message source file. For example:

   global US_NOTAVAIL (1)   0

   global US_ACTL (1)       1

   global ADM_INVALIDRC (1) 2

6. Relink the Panther executable so it includes the new header files (refer to page 42-2).

   Note: The message file only contains messages for end users; Panther developer messages are internally defined and cannot be modified.

Message file entries have the following format:

tag = msgString

tag

A string that can include letters, digits, and underscores; embedded blanks are invalid. An equal (=) sign must follow tag. Blanks before and after the equal sign are optional.

If you create your own messages, you can group them according to message tag prefixes. Messages with prefixes can be selectively loaded into memory with sm_msg_read. All system messages begin with a standard Panther prefix. These prefixes are reserved and can not be used for messages that you define:

SM	Messages and strings used by the Panther runtime library.
FM	Messages issued by the screen editor (prodev).
JM	Additional runtime messages used by Panther.
UT	Messages issued by some Panther utilities.
DM	Messages issued by database interactions.
TP	Messages issued by the middleware (JetNet and Oracle Tuxedo only).

msgString

If msgString defines a user message, it can contain any alphanumeric string on a single line; the string must contain at least one non-numeric character.

Note: The strings that define formats for date/time and numeric/currency have special syntax requirements.

Refer to page 45-12 for date/time syntax and page 45-19 for numeric/currency syntax.

Leading and trailing spaces are ignored. Enclose embedded and trailing spaces with quotation marks. Panther strips off the quotes when it displays the message.

For example, the distributed message file contains these entries:

SM_DAYA6       = Fri

SM_DAYA7       = Sat

SM_MOREDATA    = No more data.

SM_YES         = y

SM_NO          = n

SM_MONL1       = January

SM_MONL2       = February

SM_0DEF_DTIME  = %m/%d/%2y %h:%0M

SM_MB_HELPLABEL= &Help

SM_YN_ERR       = %MuPlease enter %Ky or %Kn into this field.

JM_HITACK      = %MdHit acknowledge key to continue

The following characters have special usage in message file entries:

Note: To use the backslash character in a message, enter two backslashes. msgString can also contain percent sequences that specify appearance, positioning, and acknowledgment information.

Refer to page 45-8 for information on these.

Missing Entries

If there is no tag for a message or msgString is missing from the message file and a call is made to display the message, Panther displays the message section and number from the #define statement. For example, if the entry for SM_HITANY is deleted from the Panther message file, and user input invokes this particular message, the status line displays <8-27>, which is the value for SM_HITANY from the include file smerror.h.

Message Classes

You can divide messages into message classes. You can define up to eight user classes, numbered 0 to 7. Each class can contain up to 65529 characters. Within each class, you can further differentiate messages through prefixes.

Use section classes and prefixes to divide messages into useful categories. A class of messages or messages of a given prefix can be individually loaded and unloaded from memory through sm_msg_read and sm_msg_del, respectively. Unclassified messages default to class 0.

Because unclassified messages cannot exceed 65529 characters, an application that requires many messages might require you to divide them into multiple classes.

Note: Panther reserves for its own use classes 8 through 15 and the prefixes described earlier (page 45-4).

Defining a Message Class

Each message class is defined by a message class entry with this format:

"XY" = digit

"XY"

A two-character code enclosed in quotation marks. Reserved prefixes (refer to page 45-4) cannot be used.

digit

A digit between 0 and 7, inclusive, that designates the class in library functions such as sm_msg_read.

All entries below a message class entry are part of the same message class. For example, the following message file excerpt defines two message classes with prefixes U0 and U1:

"U0"= 0 
U0_BADVAL    =  Bad value
U0_WRONGDATE =  Date must be with 30 days of current date
...

Given these entries, you can issue a command that reads all messages in class 0 that begin with the prefix U0:

sm_msg_read ("U0", 0, MSG_FILENAME|MSG_NOREPLACE, "umsg.bin")

This command reads all messages in class 0, irrespective of prefixes:

sm_msg_read ("", 1, MSG_FILENAME|MSG_NOREPLACE, "umsg.bin")

When the message file is compiled with msg2bin, tags are used to distinguish between system and user messages. User-defined messages are numbered consecutively, starting with the class number times 0x1000. Unclassified messages are numbered from zero. For example, the fourth message in user class four is numbered 0x4004. As a developer, you must remember to maintain the order of user messages and the assignment of their identifiers.

Setting Message Display and Behavior Options

Several percent escape options let you control message content and presentation. The character or characters that follow the percent sign are case-sensitive; type them exactly as shown. This prevents conflicts with percent escape options used by printf and the tokens used by date/time formats. Some percent escape options must appear at the beginning of the message; others are valid only for display in a window or on the status line.

Table 45-1 summarizes the available escape sequences, followed by detailed information about each option.

%A attr-value—Change display attributes

Valid only for status line messages, you can place %Aattr-value anywhere in the message text. It changes the display attributes of the text that follows it. attr-value is a four-digit hexadecimal value that represents one display attribute or the sum of two or more attributes.

If the string to get the attribute change starts with a hexadecimal digit (0...F), pad attr-value with leading zeros to four digits. Refer to Table 45-2 for valid attribute values.

Note: Monochrome terminals ignore color attributes. However, if you are developing for color terminals, include a color code with the %A. Otherwise, both the foreground and background colors default to black when the %A is not followed by a color code.

Table 45-2 lists the display attributes and their hexadecimal codes as defined in the include file smattrib.h.

Table 45-2 Display attributes and hexadecimal codes for status line messages

Foreground Attributes*		Background Attributes
Attribute Mnemonic	Hex Code	Attribute Mnemonic	Hex Code
REVERSE	0010	B_HILIGHT	8000
UNDERLN	0020
BLINK	0040
HILIGHT	0080
DIM	1000
Foreground Colors		Background Colors
BLACK (colors are additive)	0000	B_BLACK	0000
BLUE	0001	B_BLUE	0100
GREEN	0002	B_GREEN	0200
CYAN	0003	B_CYAN	0300
RED	0004	B_RED	0400
MAGENTA	0005	B_MAGENTA	0500
YELLOW	0006	B_YELLOW	0600
WHITE	0007	B_WHITE	0700
NORMAL_ATTR	0007	B_CONTAINER (inherit color from container)	4000
*Attributes are additive. One or more foreground attributes can be added to a background attribute, foreground color and background color.

For example, the following message appears in red characters on the default black background with Warning. in blinking characters.

SM_WARNBIG= %A44Warning.\
	%A0004Form is larger than screen size.

%B — Beep terminal

Place %B in a status line or message so that the terminal beeps via sm_bel when the message is displayed. This option must precede the message text.

%K—Display key label

Place %Klogical-key anywhere in the text of status line and error messages. Panther interprets logical-key as a mnemonic defined in smkeys.h. If the key translation file defines a key label for the logical key, the key label replaces the percent sequence in the message text. If there is no key label or no such logical key, %K is stripped off and logical-key remains in the message text.

Refer to page 6-2 in the Configuration Guide for more information about key translation files.

Figure 45-1 The key label is defined in the key translation file; the message file contains the message text. The result is displayed on the screen.

Note: If %K is used in a status line message, the user can push the corresponding logical key onto the input queue by mouse-clicking on the key label text.

%Md—Force user to acknowledge error message

Place %Md at the beginning of an error message so that the user is forced to press the predefined acknowledgment key ER_ACK_KEY to clear the message. If the user presses any other key, Panther displays an error message or beeps, depending on how application variable ER_SP_WIND is set. The keypress is not processed as data.

The %Md option corresponds to the default message behavior when application variable ER_KEYUSE is set to ER_NO_USE. If ER_KEYUSE is set to ER_USE—that is, your application default does not require use of the acknowledgement key—set %Md in a message in order to force the user to press the acknowledgment key to clear a message.

%M[time-out]—Display transient error message

Place %Mt at the beginning a transient status line message. Panther automatically dismisses the message after the specified timeout elapses and restores the previous status line display. Timeout specification is optional; the default timeout is one second. You can specify another timeout in units of 1/10 second with this syntax:

#(n)

where n is a numeric constant that specifies the timeout's length. If n is more than one digit, the value must be enclosed with parentheses. For example, this statement displays a message for 2 seconds:

msg emsg "%Mt(20)Changes have been saved to database."

The user can dismiss the message before the timeout by pressing any key or mouse clicking. Panther then processes the keyboard or mouse input. When the message is displayed in a window, users dismiss the message by choosing OK or by pressing the acknowledgement key; and Panther discards any keyboard input.

%Mu—Use any key to acknowledge error message

Valid only for error messages, you must place %Mu at the beginning of an error message. Panther forces message display to the status line and permits any keyboard or mouse input to serve as error acknowledgment. Panther then processes the keyboard or mouse input. In the following example, entering y or n acts as both message acknowledgment and data entry:

%MuPlease enter %Ky or %Kn into this field.

When the message is displayed in a window, users dismiss the message by choosing OK or pressing the acknowledgement key. Panther then discards any keyboard input.

%N—Insert line returns in message text

Insert one or more %N options in a message to force line returns in a windowed message. By default, message text wraps within the window.

%W—Display message in a window

Valid only for error messages, forces display in a window. Place %W at the beginning of the message.

The Panther message file includes entries that establish date and time formats and text. It also includes substitution variables that the screen editor displays as options for a date/time widget's Format Type property.

Modify date/time entries in the message file for these reasons:

• Translate the text (days of the week and names of months) to comply with local customs.

• Customize the formats (SM_ date/time entries) to comply with local customs or individual preferences.

• Customize the names of format mnemonics and format types for non-English developers or for individual preferences.

This section describes the tags and their default entries and how you can change the entries to meet the needs of both your development environment and your application.

Date/Time Defaults

When you choose Date/Time for the Data Formatting property of a widget, ten default choices for Format Type are available. The message file defines these format types: a name tag defines the name of a format type to appear on the Format Type option menu; and a corresponding format tag specifies the format associated with that name. For example FM_3MN_DEF_DT defines the name of the first format type as MON/DATE/YR4 HR:MIN2 and the corresponding format tag SM_3DEF_DTIME defines its format as %m/%d/%4y%h:%0M.

Table 45-3 lists the date/time name tags as delivered with Panther and their corresponding format type names, listed as they appear in the Properties window. The entries in Table 45-4 define the formats that correspond to the date/time tags and names in Table 45-3. (The tokens in the formats are defined in Table 45-5.)

Tags FM_5MN_DEF_DT through FM_9MN_DEF_DT are undefined in the provided message file; The Format Type property displays them as DEFAULT5 through DEFAULT9; they have the same format specification as FM_5MN_DEF_DT. The corresponding formats are defined in the message file, as shown in Table 45-4.

Date/Time Tokens

When specifying a format in the message file or as an argument to the library functions sm_sdtime or sm_udtime, you must use some combination of tokens—not those in the Properties window (MON or DEFAULT5). In this way, Panther does not need to parse the message file, and the library functions can be used without knowing the names of substitution variables defined in the message file. When Panther performs date calculations using a format, it replaces tokens with their appropriate values. All other characters in the format such as, commas, slashes, and colons are used literally. If you wish to refer to one of the default format types, there are format tokens ranging from %0f to %9f that correspond to each of the format tags (SM_ date/time entries).

The tokens are listed in Table 45-5. Most of these substitute a numeric value; message entries are indicated for those that substitute text. For example, %4y might substitute 1999, whereas %*m would, depending on the date, substitute one of the values defined by SM_MONL1 through SM_MONL12, perhaps July, perhaps Juillet.

Creating Date and Time Defaults

Ten date and time entries are available to define formats and the names that specify them. The tokens for SM_5DEF_DTIME through SM_9DEF_DTIME are defined to have the same format as SM_0DEF_DTIME. You can use these additional tags to create and name your own date/time formats.

How to Change or Create a Default Date/Time Format

1. Open the ASCII version of the message file with a text editor.
2. Change one of the SM_ date/time entries (SM_0DEF_DTIME through SM_9DEF_DTIME) to define the desired format.

   For example, the DEFAULT5 substitution variable has this initial format:

   SM_5DEF_DTIME =  %m/%d/%4y %h:%M0

   You can change this entry as follows:

   SM_5DEF_DTIME =  %d %*m %4y %h:%M0 %p

   Widgets that have their date Format Type property set to DEFAULT5 display dates in the format:

   30 November 2016 3:40 PM

3. Create the substitution variable with the corresponding FM_ tag:

   FM_5MN_DEF_DT = DATE and TIME

   DATE and TIME appears as an option for the Format Type property. 

   A widget whose Format Type is set to DATE and TIME displays dates in this format:

   30 November 2016 3:40 PM

4. Convert the ASCII message file to binary format with the msg2bin utility.

   Note: Tokens are provided (refer to Table 45-5) that correspond to each of the default formats so that these defaults can be used with the library functions sm_sdtime and sm_udtime.

To customize the date and time entries in the Panther message file for non-English applications, you can:

• Translate the text entries which name the days of the week and the months of the year. This text is assigned to the tags SM_DAYA1 ... SM_DAYA7 (abbreviated names of days), SM_DAYL1 ... SM_DAYL7 (full names of days), SM_MONA1 ... SM_MONA12 (abbreviated names of months), SM_MONL1 ... SM_MONL12 (full names of months).

• Change the formats associated with the SM_ date/time tags to comply with local customs.

By translating text and changing formats, widgets using the Format Type specification described in the example shown earlier on page 45-16, DEFAULT5 might appear as:

30 Novembre 2016  3:40 PM

To develop an application for French users, translate the text assigned to SM_DAYA1...SM_DAYA7, SM_DAYL1..SM_DAYL7, SM_MONA1...SM_MONA12, and SM_MONL1...SM_MONL12, like this:

SM_DAYA1  =  Dim
SM_DAYA2  =  Lun
SM_DAYA3  =  Mar
...

This method can be useful if you are distributing the same application to users who speak different languages. A user's SMMSGS variable in the local setup (smvars) file or system environment can specify the name of the appropriate message file and screen libraries. Date/time fields then display the date in a language and format familiar to the user, while all programming code remains independent of the user's language.

Translating Defaults for Developers

In addition to translating the text for days of the week and months of the year, and localizing formats, you can translate the names of substitution variables for non-English speaking developers, These entries are adjacent to each other in the Panther message file, beginning with FM_YR4 and ending with FM_9MN_DEF_DT.

For example, you might provide these entries for French-speaking developers:

FM_YR4  =  ANNÉE4

Given these changes, French-speaking developers using Panther can create date/time formats using substitution variables in their native language—MOIS2, ANNÉE4, and JOURA, while Spanish-speaking developers might use substitution variables like MES2, AÑO4, and DÍAA.

Literal Dates in Calculations

The Panther message file includes an entry to specify the format of literal dates used in @date calculations. The tag SM_CALC_DATE specifies the format. The default format is %m/%d/%4y (MON/DATE/YR4). For example, to count the number of days until the millennium, the library function sm_calc can be used with a literal date:

sm_calc (0,0,'days = @date(1/1/2000)- @date(today)');

When you choose Numeric for the Data Formatting (data_formatting) property of a widget, ten default choices for Format Type (numeric_type) are made available to you. The message file contains the definitions for these format types: A name tag defines the name of a format type to appear for the Format Type property in the Properties window, and a corresponding format tag specifies the format associated with that name. For example SM_0MN_CURR_DEF defines the name of the first format type as Local Currency and the corresponding format tag SM_0DEF_CURR defines its format as ".22,l$".

You can modify the message file to store ten different default numeric formats. Like the date/time message entries, one entry (SM_0DEF_CURR through SM_9DEF_CURR) defines the format, and a corresponding entry (SM_0MN_CURRDEF through SM_9MN_CURRDEF) specifies what the screen editor displays as options for a numeric widget's Format Type (numeric_type) property.

Numeric Format Syntax

Numeric formats are defined as r m x t p c c c c c:

To specify leading or trailing blanks in a format, enter blank spaces before or after the currency characters. The spaces become a part of the currency symbol.

For example, the format .22,l$ contains these specifications:

• period (decimal point) as the radix separator

• minimum of two decimal places

• maximum of two decimal places

• comma as the thousands separator

• the currency symbol precedes (to the left of) the number.

• the dollar sign ($) is the currency symbol

Formats in Provided Message File

Table 45-6 lists the numeric tags as delivered with Panther, their format type name, and the corresponding format tag and the default format. Description names are defined only for the first three format types. (Names for format types default to \Qdefault'). The last seven names and formats are for other types you can custom define. Therefore, the last seven format types are defined identically to SM1_DEF_CURR, which is set to two decimal places with a comma as the thousands separator.

SM_0MN_CURRDEF defines the name of the format type as Local Currency, and the corresponding format tag SM_0DEF_CURR defines its format as ".22,l$". A widget with this property specification would have data formatted, for example, as $5,100.75.

Creating a Default Numeric Format

A message file can specify ten numeric format entries. You can change any or all formats to suit your application's requirements. To create a numeric format:

• Edit the numeric format associated with a format tag.

• Define its corresponding numeric tag to equal the name of your newly created format variable.

How to Customize a Default Numeric Format

1. Open the ASCII version of the message file with a text editor.
2. Change one of the SM_ numeric entries (SM_0DEF_CURR through SM_9DEF_CURR) to define the desired format.

   To specify leading or trailing blanks in a format, enter blank spaces before or after the currency character. The spaces become a part of the currency symbol.

   For example, you can add a format for the French franc with this change:

   SM_9DEF_CURR = ',22.r F'

3. Add a descriptive definition in the corresponding SM_ numeric entry. For example:

   		SM_9MN_CURRDEF = Franc

   The Format Type property in the Properties window will display Franc as one of the values you can assign to a widget with numeric data.

4. Convert the ASCII message file to binary format with the msg2bin utility.

   Given the previous definition, the Format Type property in the Properties window displays Franc as one of the values you can assign to widgets with numeric data. Widgets thus formatted show currency data in the form:

   999.999,99 F.

In addition to modifying the numeric formats to comply with local customs, you can translate the names that appear on the numeric format type property menu for non-English speaking developers. The first three entries are adjacent to each other in the Panther message file, beginning with SM_0MN_CURRDEF and ending with SM_3MN_CURRDEF.. SM_4MN_CURRDEF through SM_9MN_CURRDEF are also available variables but not predefined in the message file.

For example, you might provide these entries for Spanish-speaking developers:

SM_0MN_CURRDEF = DINERO

Given these changes, Spanish-speaking developers see format type choices in their own language.

Decimal Symbols

Via the message file tag SM_DECIMAL you can define a default decimal symbol (or radix separator). When you define a widget to have or accept numeric data, you can also specify any decimal symbol (or radix separator). However, the SM_DECIMAL entry enforces a default symbol. If SM_DECIMAL is not specified in the message file, Panther tries to determine the appropriate symbol from the operating system.

Panther accommodates three types of decimal symbols. These decimals differ in scope and function.

system

The character that is used by the operating system when translating characters to internal values or vise versa—for example, in C functions atof and sprintf. The default is period.

Note: Setting the system decimal symbol incorrectly can cause unexpected results when Panther processes numeric values.

local

Defined by the message file entry for SM_DECIMAL, by default set to period. This setting overrides the system symbol within a Panther application. Set SM_DECIMAL according to local customs—for example, period in English-speaking countries; comma in Europe. If the system and local symbols are different, Panther translates appropriately when interacting with system routines.

widget

Set for a specific widget through its decimal_symbol property (refer to on page 10-20 in the Using the Editors). This symbol is used only for data entry validation and for displaying widget values. Use widget-level decimal symbols when you need to handle multiple decimal conventions within a single application.

The message file tags SM_MB_OKLABEL through SM_MB_HELPLABEL provide the text for message box push buttons.

Note: Microsoft Windows for other languages automatically translates standard push buttons to the appropriate language.

How to Change/Translate Push Button Labels

1. Access the ASCII version of the message file with a text editor.
2. Change the label text. Place an ampersand before the character to serve as the push button's key mnemonic.
3. Convert the ASCII message file to binary format with msg2bin.

For example, if you were converting your application to Spanish, you might include the following in your message file:

SM_MB_OKLABEL      =  &Ok
SM_MB_CANCELLABEL  =  &Cancelar
SM_MB_YESLABEL     =  &Si
SM_MB_NOLABEL      =  &No
SM_MB_RETRYLABEL   =  &Re-intentar
SM_MB_IGNORELABEL  =  &Ignorar
SM_MB_ABORTLABEL   =  A&bortar
SM_MB_HELPLABEL    =  &Ayuda

The values associated with the message tags SM_YES and SM_NO can be translated or standardized to meet your development or application's requirements. For example, you can translate the value for SM_YES to s (short for sí) for Spanish-speaking users.

Library functions such as sm_is_yes, and properties such as keystroke filter that use the SM_YES and SM_NO entries expect and return the appropriate character as defined in the message file. In the case of a Spanish-speaking user, entering s (for an affirmative response) is recognized, whereas y is ignored.

Using Alternate Message Files

The SMMSGS application variable specifies the binary file to read into memory at Panther's initialization. If you serve an international market, you can give users the option of selecting from alternate message files. At runtime the user can set the SMMSGS for the binary message file that is appropriate to his/her language.

Alternative files for an application (and for non-English versions of Panther) must be identical in terms of the number and sequencing of all messages (refer to page 45-4 for information about adding messages).

Configuration Map File

The configuration map file contains definitions for screens and widgets—colors, fonts, lines and box styles—that you can tailor to different platforms. The file is divided into several sections:

• [Colors] maps user-defined color names to system color names (page 45-26).

• [Schemes] maps color definitions to application components such as screens and widget types (page 45-30).

• [Lines] defines line and box styles (page 45-34).

• Several font sections that tell Panther which fonts and font sizes to display in the drop-down menus in the screen editor; they also define default fonts for display and report output, and map system-specific font names to Panther font aliases (page 45-36).

By defining these elements in GUI-specific files and using their names for screen and widget properties, you can create applications that are easy to port across different platforms. Instead of creating multiple instances of the same screens or reports that use GUI-specific font and color names, you can create multiple configuration map files—one for each platform on which your applications run. For example, you can create a color alias PanicButtonRed that resolves to different colors in different configuration maps.

Panther is installed with at least one configuration map file (*cmap) that suits your environment. You can edit these or create your own with an ASCII text editor, then run the utility cmap2bin to convert it to binary format.

During initialization, Panther looks for the application variable SMCOLMAP which can be defined in the environment or in an SMVARS file. This variable gives the full path name of the binary configuration map file.

Defining Colors

When you create a screen or widget, the screen editor seeks default color settings, or a scheme, for that object's type, foreground and background. The editor automatically sets the color property to Scheme and then resolves the scheme, looking first in the configuration map file. If the file provides no scheme for the object, the editor looks elsewhere for color defaults (refer to page 45-30).

Panther provides configuration map files with default schemes for screens and for each widget type. You can define your own color schemes that suit your environment, style preferences, or development and application requirements. Or you can rely on the local GUI to assign colors to your application objects.

You can set the Color Type property to one of these three settings:

• Scheme—The defaults defined in the [Schemes] section of the configuration map file, or if none, a set of default colors determined by settings defined either in the native GUI or in Panther.

• Basic—Panther's eight highlighted and eight unhighlighted colors, plus the Container option. (The Container option specifies that a widget within another object has the same background color as the container.)

• Extended colors—GUI-specific colors that are specified by a string and are resolved in the [Colors] section of the configuration map file, or directly by the GUI.

Defining Color Aliases

The [Colors] section defines GUI-independent color aliases that you can use in the Color Name property of screens and widgets. All color names, including Panther palette color names like hilight_red, must be added to the list of color aliases. Each entry appears on its own line in the following format: aliasColor = color

aliasColor

Any name you choose to identify a color.

color

One of the following:

• An RGB value in a platform-specific form:

  For Windows, use the form "red/green/blue" where red, green and blue are numbers between 0 and 255. For example:

  PanicButtonRed = "205/92/92"

  For Motif, use the form "#RedGreenBlue" where Red, Green, and Blue are hex numbers between 00 and ff. For example:

  PanicButtonRed = "#cd5c5c"

• A GUI specific name (in Motif only). For more information on Motif color names, refer to page 4-5.in the Configuration Guide. For example:

  PanicButtonRed = "Indian Red"

• Panther keywords in the form basicColor (attributes); where basicColor corresponds to one of Panther's 16 colors (or "container") and attributes is an optional display attribute (refer to Table 45-7). For example:

  NumberField = BLACK UNDERLN

  This style of definition can create a GUI-independent color alias. For example:

  SpringGreen=Green Hilight
SummerGreen=Green Dim

  If a widget had the Motif color SpringGreen specified and Panther could not find it, it would substitute the Panther color Green Hilight, which is always defined. A configuration map with similar aliases would allow a Motif-specific screen to appear similarly when running in Panther's character mode.

  Note: Under Windows, Panther screens and widgets that have highlighted background colors are different from those having unhighlighted background colors. Panther display attributes have no effect in Motif.

  Table 45-7 Panther color and attribute keywords

  Color	Color keyword	Attribute	Attribute keyword
  Black	BLACK	Reverse video	REVERSE
  Blue	BLUE	Underline	UNDERLN
  Green	GREEN	Blink	BLINK
  Cyan	CYAN	Highlight	HILIGHT
  Red	RED	Dim	DIM
  Magenta	MAGENTA
  Yellow	YELLOW
  White	WHITE
  Container	CONTAINER

The keyword CONTAINER specifies that a widget within another object has the same background color as the container. Therefore CONTAINER cannot be used to specify a foreground color. Also, because CONTAINER may contain attributes, you cannot specify any additional attributes with it.

Editor Colors

A number of predefined color aliases control the editor's appearance. All editor color aliases begin with se; entries use the same format as user-defined colors. For example, this entry in a Windows configuration map file sets the background color of the design screen:

seFormBg = "127/255/0"

Table 45-8 lists screen editor color aliases and the objects whose appearance they control:

Sample Colors Section

The following examples are from ASCII configuration map files; the aliases ensure that colors specified for one platform display correctly on others without editing Color Name properties of application components. Given the appropriate configuration map file, an application displays colors that are correct for its environment.

The [Colors] section in the Motif configuration map defines these color aliases:

Slate Gray   = "#708090"
Olive Drab   = "#6B8E23"
ButtonBlue   = "#0938EE"

For character mode, the [Colors] section redefines these aliases with Panther color names:

Slate Gray   = HILIGHT WHITE
Olive Drab   = GREEN
ButtonBlue   = BLUE

For a Windows configuration map, these aliases are redefined with RGB values:

Slate Gray   = "112/128/144"
Olive Drab   = "107/142/35"
ButtonBlue   = "09/38/240"

If you specify Slate Gray on the three platforms, the correct color is displayed. If you alias the Motif color to map to a Panther-specific color, you ensure that when your application runs in character-mode Panther, Slate Gray is displayed as the Panther color hilight white.

Defining Color Schemes

You can decide on a set of default colors for each newly created object in the screen editor. When the Color Type property is set to Scheme, Panther uses the configuration map file to resolve the object's foreground and background colors, according to its type.

The Schemes section of the configuration map file can include explicit settings or defer to the GUIs resource database or initialization file.

Default Schemes

If the configuration map file omits a [Schemes] section, Panther uses the following default schemes:

• Windows: Control Panel colors.

• Motif: the *fg and *bg settings in the resource database.

• Character-mode Panther: white foreground, black background.

Scheme Syntax

Each entry in the[Schemes] section appears on its own line in the following format:

object = color

object

Any widget type, including lines and boxes, screen, and borders, followed by either a foreground (FG) or background (BG) mnemonic; for example, ToggleButtonFG and ListBoxBG. Refer to Table 45-9 for a list of valid object specifications.

color

One of the following specifications:

• An RGB value in a platform-specific form:

  For Windows, use the form "red/green/blue" where red, green and blue are numbers between 0 and 255. For example:

  MultiTextFG = "0/0/255"

  For Motif, use the form "#RedGreenBlue" where Red, Green, and Blue are hex numbers between 00 and ff. For example:

  MultiTextFG = "#0000ff"

• Panther keywords in the form basic_color [attribute]; where basic_color corresponds to one of Panther's 16 colors (or "container") and attribute is an optional display attribute. (Refer to Table 45-7.) You may not use the container color for foreground color designations. For example:

  TEXTFG = BLACK UNDERLN

• A GUI independent color alias. For example, this entry sets LabelBg to Panther blue, an alias that must be defined in the [Colors] section:

  LabelBG=Panther blue

• Use the keyword GUI to indicate the native GUI resource database or initialization file. For example, the following indicates that the native GUI resolves the foreground color for toggle buttons:

  TogglebuttonFG=GUI

• Use the keyword GUI and the Motif or Windows screen element scheme value. (Do not use any additional attributes with a GUI keyword color designation.) For example, for Windows:

  PushButtonFG = GUI Buttonface

  For Motif:

  PushButtonBG = Prolifics*background

• GUI-specific colors. These exist only in Motif; their usage limits the scheme's color portability to other environments. For more information on Motif color names, refer to page 4-5 in the Configuration Guide.

  CheckBoxFg =tomato

  Table 45-9 Objects for setting schemes (keywords are case-insensitive).

  Object Specification	Descriptions
  BoxTopBg	Top border background of box widget.
  BoxTopFg	Top border foreground of box widget.
  CardBg	Tab card widget background (ignored in Windows).
  CardFg	Tab card widget foreground (ignored in Windows).
  CheckBoxBg	Check box background.
  CheckBoxFg	Check box foreground.
  ComboBoxBg	Combo box background.
  ComboBoxFg	Combo box foreground.
  DeckBg	Tab deck widget background (ignored in Windows).
  FormBg	Screen color scheme.
  FormBorderBg	Screen border background.
  FormBorderFg	Screen border foreground.
  GraphBg	Graph widget background.
  GraphFg	Graph widget foreground.
  GridBg	Grid widget background.
  GridFg	Grid widget foreground.
  LabelBg	Static label background.
  LabelFg	Static label foreground.
  LineBg	Line widget background.
  LineFg	Line widget foreground.
  ListBoxBg	List box background.
  ListBoxFg	List box foreground.
  MultiTextBg	Multitext background.
  MultiTextFg	Multitext foreground.
  OptionMenuBg	Option menu background.
  OptionMenuFg	Option menu foreground.
  OutputBg	Dynamic label background.
  OutputFg	Dynamic label foreground.
  PushButtonBg	Push button background.
  PushButtonFg	Push button foreground.
  RadioButtonBg	Radio button background.
  RadioButtonFg	Radio button foreground.
  ScaleBg	Scale widget background.
  ScaleFg	Scale widget foreground.
  TextBg	Single line text background.
  TextFg	Single line text foreground.
  ToggleButtonBg	Toggle button background.
  ToggleButtonFg	Toggle button foreground.

[Lines] section entries map character-mode styles for lines and boxes to GUI styles. Character-mode line and box styles are defined in the box and border entries of your terminal's video file.

Each entry appears on its own line in the following format:

styleName = styleContent

styleName

A predefined or new style name. Spaces are allowed and case is irrelevant.

styleContent

A predefined style name or another alias style name defined in this file. Spaces are allowed and case is irrelevant. Currently supported predefined style names include:

Dash	Dashdot	Dashdotdot	Default
Dot	Double Dash	Double	Etched In
Etched In Dash	Etched Out	Etched Out Dash	In
None	Out	Single
Style 0	Style 1	...	Style 9

You can use this section of the configuration map file to assign the styles 0 through 9 to GUI-specific line styles. For example, you might define the following entries for Motif:

[Lines]

These entries tell Panther for Motif that when to interpret style 0 as an alias for etched in, and style 1 as etched out.

Character Mode Styles

Styles 0 through style 9 are native to Panther 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 screen editor, that style is mapped to style 1 on non-character Panther applications. GUI-specific styles map to style 1 when running in character mode.

GUI Styles

The default line and box style for all GUI platforms is etched in. Table 45-10 shows which styles are supported by different platforms, and how Panther displays styles that are undefined or are not supported by the GUI. Supported styles are represented by asterisks (*). Because Windows supports the same styles for lines and boxes, the table does not differentiate between these two widgets; however, Motif supports a different set of styles for each widget type, so these are depicted separately.

Note: Under Windows, screens that have their 3D property set to No display Etched In and Etched Out as single lines.

To control mapping, assign the desired specification in the configuration map file.

Setting Display and Printing Fonts

Display font defaults and aliases are defined in a single section—[Windows Fonts] for Windows and [Display Fonts] for other platforms.

Font defaults and aliases for printed reports are defined in one of four sections: in the [Windows Fonts] font display section for output from Windows print drivers, a [Postscript Fonts] section for PostScript and PDF output, a [PDF Fonts] section for PDF output, and a [Text Fonts] section for ASCII output. For more information about how to use fonts in reports, refer to page 8-11 in Reports.

Entries in these sections let you:

• Specify the fonts and point sizes that appear on drop-down menus for the Font Name and Point Size properties.

• Specify the application's default font and point size.

Point Sizes

You can specify the point sizes that appear on the Point Size property's drop-down menu with an entry that has this format:

point_sizes = size[ size]...

For example:

point_sizes = 8 9 10 12 14 16 18 20 24 36 48 72

Note: Panther uses the point_sizes entry only for scalable fonts. For a non-scalable font, Panther gets its available sizes from the GUI and displays these on the drop-down menu.

Default Font

You can specify the application-wide font that Panther applies when you accept Default for a screen's Font Name property with an entry that has this format:

default_font = font-spec

font-spec is a font specification that is valid for this configuration map file's environment.

For applications running on Windows, specify the font name only. For example:

default_font = Arial

For Motif applications, specify fonts with the XLFD font naming convention; substitute the wildcard character * for all weight, slant, and size properties. For example:

default_font = -*-Helvetica-*

For the PDF driver, you must specify the name of the TrueType or Type 1 font file. The file name's extension will be used to determine the type of font. The extension must be .ttf for TrueType fonts and either .pfa or .pfb for Type 1 fonts. For Type1 fonts, there must also be the corresponding .afm file in the same directory. For example, in Windows,

default_font = c:\windows\Fonts\times.ttf

and in Linux or UNIX,

default_font = /usr/share/fonts/default/Type1/n021003l.pfb

Note: At runtime, Panther uses the default font for any font specification that it cannot resolve.

Default Font Size

The default_point_size entry specifies the application-wide font size that Panther applies when you accept Default for a screen's Font Size property. Use the format:

default_point_size = size

Panther font aliases are especially useful in an application's portability across platforms. Each platform has its own configuration map, and Panther font aliases map to local font specifications. Panther font aliases appear on the Font Name property's drop-down menu. In GUI environments, Panther resolves these with the names of fonts supplied by the GUI itself.

Each Panther font alias is defined with the following format:

aliasName [(fontQualifier...) ] = fontSpec 
          [[ (fontQualifier...) ] = fontSpec]...

You can specify different qualifiers for the same font alias on separate lines, and thereby map it to unique font specifications. For example, the following definition uses different qualifiers to map the Prolifics font Helvetica to two different fonts, depending on whether the Italic property is set:

Prolifics Helvetica (noitalic) = Arial
                    (italic)   = ArialItalic

If more than one entry matches a widget's properties, the first matching entry determines which font is displayed.

The following sections discuss each component of a font definition.

aliasName

The name that you choose to identify a font alias. Panther font aliases are defined in the configuration map file. They appear before the GUI-specific font specifiers in the Font Name property option menu.

fontQualifier

Optionally limits usage of aliasName to those objects that also use the specified qualifiers. You can AND together space-delimited font qualifiers from each of the following columns, in any order:

bold	italic	underline	pointSize[ pointSize ]...
nobold	noitalic	nounderline

For example, a Windows configuration map file might contain two definitions for the Helvetica font, the first qualified, the second unqualified:

Prolifics Helvetica (italic 12 14) = ArialItalic 
                                   = Arial

If a widget's Font Name property is set to Prolifics Helvetica, Panther uses Arial unless two other conditions are also true: the Italic property is set to Yes, and the Point Size property is set to either 12 or 14. In this case, Panther uses ArialItalic.

Point size qualifiers can limit the number of choices available in the Point Size property's option menu. For example, given the following Windows font definition, choosing Prolifics Times Roman as a widget's Font Name property limits the choices on the Point Size drop-down menu to Default, 8, and 10:

Prolifics Times Roman (8 10) = Times New Roman

Note: Point size qualifiers are used on the Point Size property's option menu only if they are valid for the selected font.

fontSpec

fontSpec maps the font name to a font supported by the GUI environment. For applications running on Windows, specify fonts with this syntax:

fontname[-point-size] [-bold] [-italic] [-underline]

For example:

Prolifics Helvetica    = Arial-14-bold 
Data Entry Text  = Arial

For Motif applications, specify fonts with the XLFD font naming convention:

-foundry-family-weight-slant-width-style-pixel size 
-point size-x resolution-y resolution-spacing
-average width-charset registry-charset encoding

You can substitute any component in an XLFD font name with the wildcard character *. For example:

Prolifics Courier          = -*-courier-*-r-* 
Prolifics Courier (italic) = -*-courier-*-o-*

If fontSpec omits values for point size, slant, or weight, Panther supplies these values from the corresponding property settings—Point Size, Italic, and Bold. For example, the following entries for the Prolifics Helvetica font—each in separate configuration map files for Windows and Motif—specify only the font's family name:

Prolifics Helvetica  = Arial 
Prolifics Helvetica = -*-helvetica-* 
Prolifics Helvetica = helvetica

Given these definitions, any widget using Prolifics Helvetica as its font can also have its Point Size, Bold, and Italic properties set; these properties are used to resolve the displayed font. So, if the widget's Bold and Italic properties are set to Yes, Panther resolves the Prolifics Helvetica to Arial-bold-italic on Windows and -*-helvetica-bold-i-* in Motif, and passes on these specifications to their respective GUIs.

Conversely, these definitions of a font named HelvBold sets its weight to bold:

HelvBold = Arial-bold

HelvBold = -*-helvetica-bold-*

The explicit weight specifications for HelvBold override the Bold properties for a widget that uses this font; the font is always displayed as bold.

For the PDF driver, you must specify the name of the TrueType or Type 1 font file. The file name's extension will be used to determine the type of font. The extension must be .ttf for TrueType fonts and either .pfa or .pfb fir Type 1 fonts. For Type1 fonts, there must also be the corresponding .afm file in the same directory. For example, in Windows,

Prolifics Courier = c:\windows\Fonts\cour.ttf

and in Linux or UNIX,

Prolifics Courier = /usr/share/fonts/default/Type1/n022003l.pfb

The following configuration map file defines colors, fonts, and line styles for Windows applications.

[Colors]

---

Translating Applications

Panther provides the following capabilities for modifying application for international usage:

• Panther uses 8-bit character data without appropriating a bit for internal use.

• The library functions sm_dblval and sm_dtofield, which read and write real values, respectively, use the C standard library functions atof and sprintf to interpret the system decimal symbol (radix character) correctly.

• The library function sm_is_yes uses the characters designated in the SM_YES and SM_NO entries in the Panther message file. Therefore, if you translate the message file, the screen use and display of those values are automatically internationalized. The function uses toupper to recognize upper-case variations.

You can also use the Panther message file to set date and time formats (page 45-17) and currency formats (page 45-19) to conform to local usage.

8-Bit Character Data

Panther supports 8-bit character data. Video files specific to the terminal can give special instructions, if necessary, on how to display international characters. This is needed if the terminal requires shifting to a different character set to display non-ASCII characters. Most terminals used in the international market do not need to shift character sets.

The video file can also be used to translate between two different standards for international characters. Thus, screens can be created with one standard and displayed using a different one.

The use of 8-bit characters for international symbols does not necessarily preclude use of graphics in character-mode applications. Unused entries in a character set, such as 0x01 through 0x1f or 0x80 through 0x9f, can be mapped to line graphics symbols.

Unless a widget has a keystroke filter, Panther ignores the characters that are entered into it from the keyboard. Internally, it only manipulates numbers. Cursor control keys such as arrows and TAB, and function keys are all assigned logical values that are outside the range 0x00 to 0xff, and thus cannot conflict with international characters.

Keyboards that support international character sets usually produce a single 8-bit byte (perhaps with the high bit set) for each character. However, some terminals generate a sequence to represent an international character. If so, you can use a text editor to map the byte sequences to a logical value, just as the video file is used to map the logical value to the sequence required by the display terminal.

For more information on how to display non-English characters or to receive them from the keyboard, refer to page B-1 in the Upgrade Guide.

Translating Screens in Application Programs

There are a number of approaches to translating your application screens. If your application requires translation for international distribution, consider the following questions:

• How many translations are needed?

• Do users need access to multiple languages at runtime? When they start the application only, or during a session?

• Is the application relatively complete and static, or are changes and enhancements still be made?

The answers to these questions determine which method to use. In any event you must provide the translator with the information that needs to be translated, and pictures of the screens to provide some context. In addition, screen size and spacing should be considered when translating screens to other languages.

There are essentially three different approaches you can take to provide an application to a multilingual audience. Each approach requires some up-front planning, and some development strategy. The localization process can be performed at:

• Distribution time

• Installation time

• Runtime, which can be either at startup or dynamically at the user's request.

There are probably several ways to approach the development of a product that needs to be translated and distributed in multiple languages. One of the most obvious methods is to simply translate application screens to each of the languages that you support.

Language-specific screens can be released in a variety of ways, regardless of when the localization process takes places. For example, you can create multiple libraries; each one contains a set of screens translated to a specific language. By setting the SMFLIBS application variable either at distribution, installation, or runtime, you or a user can access the desired language-specific library.

The following sections describe other methods to consider when you develop an application.

Distribution Translation

A distribution translation means that when the application leaves your facility, it is released with a specific set of screens. The end user receives exactly what you send.

Method One

Develop language-specific repositories. At distribution time, use the binherit utility to update the content of each screen by using the appropriate repository for the required language.

Method Two

At design time, define the initial text for all widgets as a variable or token, for example %Name%, %Address%, etc. When the screens are completed, use the f2asc utility to convert the binary screens to ASCII format. Provide your translator with the tokenized references. Then develop a translation script that will search the ASCII file and replace the token with the translated constant. The function of the translation utility would be to find and replace tokenized text, replacing %Name% with Name for English, or Nom for the French version.

Each ASCII translation can be easily maintained and updated as screens change.

After the ASCII translations are made, they can be converted back to screens in binary format with f2asc and distributed accordingly.

This method has these advantages and disadvantages:

Advantages	File naming conventions can be adhered to across all libraries.
	Screen dimensions and widgets can be easily adjusted and repositioned to accommodate languages and sentence structure that might require more space on a screen.
	Adding a new language only requires a new translation.
Drawbacks	Maintenance of many different languages can be time consuming.
	You must distribute more than one library to an end user who requires more than one language.
	Languages cannot be changed dynamically at runtime.

In an installation translation, the application is packaged with more than one language and the desired language is installed. You can provide an installation mechanism that lets the user set SMFLIBS to point to and open a library of language-specific screens.

This method has the advantage of letting users decide which language to install. On the other hand, it requires disk space to accommodate storage of multiple sets of screens; and languages cannot be changed dynamically at runtime.

Runtime Translation

In a runtime translation, users can dynamically change languages at runtime. Depending on their requirements, users might only need to select a preferred language at start up, or they might need to change languages during a session.

Method One

A start up method can be implemented in the same way described for an installation translation: you provide a mechanism that lets users choose which language to display. For example, a logon screen can provide radio buttons that correspond to each supported language, so users can choose the desired language. Their choice sets SMFLIBS to point to and open the appropriate library of screens.

This method has the advantage of allowing multilingual organization to run the application easily; users choose their preferred language without requiring reinstallation of the software.

This method has one possible drawback, that installation requires enough disk space to accommodate all translated screens.

Method Two

Design your screens to include all translations in one screen binary. You can do this by creating dynamic labels as scrolling arrays with only one onscreen occurrence, and then synchronizing all the label arrays on the screen, you can provide an occurrence for each language you support. The user, via a programmatic call, can scroll the array to the language of choice. For example, the third occurrence might be Italian, while the fourth occurrence is Japanese. So, if the user chooses Italian, via a screen entry function the third occurrence is displayed. If Japanese is specified, the labels can be programmatically scrolled to the fourth occurrence and so on.

This method has two advantages:

• All translations exist in one place with each screen binary.

• While working in the application, a user can choose which language to display.

  This method has one possible drawback, that some translations require more space than others; screens must be designed with these limitations in mind.