Application Development

# Chapter 45. Customizing the User Interface

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:

## 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

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

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.

#### 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 Entry Syntax

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:

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.

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

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

#### Reserved Characters

Refer to page 45-8 for information on these.

### Message Classes

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.

#### Defining a Message Class

"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.
"U0"= 0 U0_BADVAL    =  Bad valueU0_WRONGDATE =  Date must be with 30 days of current date...
"U1" = 1WRONGRATE =  This is not the applicable rate....
sm_msg_read ("U0", 0, MSG_FILENAME|MSG_NOREPLACE, "umsg.bin")
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

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.

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

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.

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.

%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)
msg emsg "%Mt(20)Changes have been saved to database."

%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.

%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.

### Customizing Date and Time Formats

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

#### Date/Time Defaults

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.)

#### 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

##### 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.
SM_5DEF_DTIME =  %m/%d/%4y %h:%M0
You can change this entry as follows:
SM_5DEF_DTIME =  %d %*m %4y %h:%M0 %p
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.
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.

##### Defaults for Non-English Applications

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

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
SM_DAYA1  =  DimSM_DAYA2  =  LunSM_DAYA3  =  Mar...
SM_DAYL3  =  MardiSM_DAYL4  =  MercrediSM_DAYL5  =  JeudiSM_DAYL6  =  VendrediSM_DAYL7  =  Samedi...
...
SM_MONA1  =  JanSM_MONA2  =  FévSM_MONA3  =  Mar... SM_MONL7  =  JuilletSM_MONL8  =  AoûtSM_MONL9  =  SeptembreSM_MONL10 =  OctobreSM_MONL11 =  NovembreSM_MONL12 =  Décembre

#### Translating Defaults for Developers

FM_YR4  =  ANNÉE4
FM_YR2  =  ANNÉE2
FM_MON  =  MOIS
FM_MON2 =  MOIS2
FM_DATE =  JOUR
...

#### Literal Dates in Calculations

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

### Numeric Formats

#### Numeric Format Syntax

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

#### 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.

#### 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:

##### 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.
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.
999.999,99 F.

#### Translating Defaults for Developers

SM_0MN_CURRDEF = DINERO
SM_1MN_CURRDEF = NUMERO

### Decimal Symbols

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.

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.

### Customizing Push Button Labels for Message Boxes

#### 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.
SM_MB_OKLABEL      =  &OkSM_MB_CANCELLABEL  =  &CancelarSM_MB_YESLABEL     =  &SiSM_MB_NOLABEL      =  &NoSM_MB_RETRYLABEL   =  &Re-intentarSM_MB_IGNORELABEL  =  &IgnorarSM_MB_ABORTLABEL   =  A&bortarSM_MB_HELPLABEL    =  &Ayuda

### Setting Yes/No Values

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.

## 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:

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

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

### 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:

#### Editor Colors

seFormBg = "127/255/0"

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

#### Sample Colors Section

Slate Gray   = "#708090"Olive Drab   = "#6B8E23"ButtonBlue   = "#0938EE"
Slate Gray   = HILIGHT WHITEOlive Drab   = GREENButtonBlue   = BLUE
Slate Gray   = "112/128/144"Olive Drab   = "107/142/35"ButtonBlue   = "09/38/240"

### Defining Color Schemes

#### Default Schemes

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

#### Scheme Syntax

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:

### Defining Line and Box Styles

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

[Lines]
style 0 = etched in
style 1 = etched out

#### 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.

Table 45-10 Mapping of Panther line and box styles on GUI platforms

Line styles Windows Motif line Motif box

Default

etched in

etched in

etched in

Style 0

single

no line

etched in

None

single

no line

etched in

Styles 1-9

single

etched in

etched in

Etched In

*

*

*

Etched In Dash

dash

*

etched in

Etched Out

*

*

*

Etched Out Dash

dash

*

etched in

Single

*

*

etched in

Dash

*

*

etched in

Dot

*

dash

etched in

Dashdot

*

dash

etched in

Dashdotdot

*

dash

etched in

In

single

etched in

*

Out

single

etched out

*

Double

single

*

etched in

Double Dash

single

*

etched in

* Style is supported by the GUI platform.

### Setting Display and Printing Fonts

Entries in these sections let you:

#### Point Sizes

point_sizes = size[ size]...
point_sizes = 8 9 10 12 14 16 18 20 24 36 48 72

#### Default Font

default_font = font-spec
default_font = Arial
default_font = -*-Helvetica-*

#### Default Font Size

default_point_size = size

#### Panther Font Aliases

aliasName [(fontQualifier...) ] = fontSpec           [[ (fontQualifier...) ] = fontSpec]...
Prolifics Helvetica (noitalic) = Arial                    (italic)   = ArialItalic

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:

Prolifics Helvetica (italic 12 14) = ArialItalic                                    = Arial
Prolifics Times Roman (8 10) = Times New Roman

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]
Prolifics Helvetica    = Arial-14-bold Data Entry Text  = Arial
-foundry-family-weight-slant-width-style-pixel size -point size-x resolution-y resolution-spacing-average width-charset registry-charset encoding
Prolifics Courier          = -*-courier-*-r-* Prolifics Courier (italic) = -*-courier-*-o-*
Prolifics Helvetica  = Arial Prolifics Helvetica = -*-helvetica-* Prolifics Helvetica = helvetica
HelvBold = Arial-bold
HelvBold = -*-helvetica-bold-*

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

### Sample Configuration Map File

[Colors]
grape           = MAGENTA       # Prolifics colorAquatic Blue    = "64/32/200"   # Windows-style RGB value
# The following entries in the color map are for use in the# screen editor. If you remove them entirely, then SCHEME# colors are used, which may be desirable in Windows.
#seFormBG       = GUI WindowBackground#seBorderFG     = Unused by Pi for Windows#seLabelFG      = GUI WindowText#sePushFG       = GUI ButtonText#sePushBG       = GUI ButtonFace#seEntryFG      = GUI WindowText#seMultiFG      = GUI WindowText#seMultiBG      = GUI WindowBackground#sePwListFG     = GUI WindowText#sePwListBG     = GUI WindowBackground#seListFG       = GUI WindowText#seListBG       = GUI WindowBackground#seCheckFG      = GUI WindowText#seOptionmenuBG = GUI WindowBackground#seComboboxBG   = GUI WindowBackground#seTextBG       = GUI WindowBackground
# The following definitions are for the tool box
seTbFormBG      = BLACK#seTbBorderFG   = Unused by Pi for Windows#seTbTogFG      = Unused by Pi for Windows
[Schemes]
#OUTPUTFG       = GUI WindowText#TEXTFG         = GUI WindowText#MULTITEXTFG    = GUI WindowText#PUSHBUTTONFG   = GUI ButtonText#TOGGLEBUTTONFG = GUI ButtonText#RADIOBUTTONFG  = GUI WindowText#OPTIONMENUFG   = GUI WindowText#COMBOBOXFG     = GUI WindowText#LISTBOXFG      = GUI WindowText#SCALEFG        = GUI WindowText#LABELFG        = GUI WindowText#BOXTOPFG       = GUI WindowText#LINEFG         = GUI WindowFrame#CHECKBOXFG     = GUI WindowText #FORMBORDERFG   = Unused by Pi for WindowsGRAPHFG         = BLACK#GRIDFG         = GUI WindowText#FORMBG         = GUI WindowBackgroundOUTPUTBG        = CONTAINER#TEXTBG         = GUI WindowBackground#MULTITEXTBG    = GUI WindowBackground#PUSHBUTTONBG   = GUI ButtonFace#TOGGLEBUTTONBG = GUI ButtonFaceRADIOBUTTONBG   = CONTAINER#OPTIONMENUBG   = GUI WindowBackground#COMBOBOXBG     = GUI WindowBackground#LISTBOXBG      = GUI WindowBackgroundSCALEBG         = CONTAINERLABELBG         = CONTAINER#BOXTOPBG       = CONTAINER#LINEBG         = Unused by Pi for WindowsCHECKBOXBG      = CONTAINER#FORMBORDERBG   = Unused by Pi for Windows#GRAPHBG        = CONTAINER#GRIDBG         = CONTAINERACTIVEXBG       = CONTAINER#CARDBG         = Unused by Pi for Windows#DECKBG         = Unused by Pi for Windows
[Lines]
Style 1 = SingleMyFavoriteStyle = Double
[Windows Fonts]
# Point Size property drop-down
point_sizes = 8 9 10 12 13 14 16 18 20 22 24 26 28 36 48 72
# Application defaults for Font Name and Point Size# properties
default_font       (print)   = Times New Romandefault_point_size (print)   = 10
# Font Name             Qualifiers   Windows font# -------------------   ----------   ------------Prolifics Courier                  = Courier NewProlifics Times Roman              = Times New RomanProlifics Helvetica                = ArialProlifics Symbol                   = Symbol
[PostScript Fonts]
# Rules in this section apply only to ReportWriter's editor and# printed output.
# Point Size property drop-down
point_sizes = 8 9 10 11 12 13 14 16 18 20 22 24 26 28 36 48 72
# Application defaults for Font Name and Point Size properties
default_font                    = Times-Romandefault_point_size              = 10

# Font Name           Qualifiers      PostScript font# ---------           ----------      ---------------Prolifics Courier     (italic bold) = Courier-BoldOblique                      (italic)      = Courier-Oblique                      (bold)        = Courier-Bold                                    = Courier
Prolifics Times Roman (italic bold) = Times-BoldItalic                      (italic)      = Times-Italic                      (bold)        = Times-Bold                                    = Times-Roman
Prolifics Helvetica   (italic bold) = Helvetica-BoldOblique                      (italic)      = Helvetica-Oblique                      (bold)        = Helvetica-Bold                                    = Helvetica
Prolifics Symbol                    = Symbol
[Text Fonts]
# Rules in this section apply only to ReportWriter's editor and# printed output.

# Point Size property drop-down
point_sizes = 8 10 12 16 24 36

# Application defaults for Font Name and Point Size properties
default_font                 = Timesdefault_point_size           = 10

# Font Name           Qualifiers       Text Font# ---------           ----------       ---------Prolifics Courier     (10 italic)      = Courier_i_10Prolifics Courier     (10 bold)        = Courier_b_10Prolifics Courier     (10)             = Courier_10Prolifics Courier     (italic)         = Courier_iProlifics Courier     (bold)           = Courier_bProlifics Courier                      = Courier
Prolifics Times Roman (24 italic bold) = Times_i_b_24Prolifics Times Roman (24 italic)      = Times_i_24Prolifics Times Roman (24 bold)        = Times_b_24Prolifics Times Roman (24)             = Times_24Prolifics Times Roman (18 italic bold) = Times_i_b_18Prolifics Times Roman (18 italic)      = Times_i_18Prolifics Times Roman (18 bold)        = Times_b_18Prolifics Times Roman (18)             = Times_18Prolifics Times Roman (10 italic bold) = Times_i_b_10Prolifics Times Roman (10 italic)      = Times_i_10Prolifics Times Roman (10 bold)        = Times_b_10Prolifics Times Roman (10)             = Times_10Prolifics Times Roman (italic bold)    = Times_i_bProlifics Times Roman (italic)         = Times_iProlifics Times Roman (bold)           = Times_bProlifics Times Roman                  = Times
Prolifics Helvetica                    = Helvetica
Prolifics Symbol                       = Symbol

## Translating Applications

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

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.

### 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:

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:

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.

#### 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.

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

#### Installation Translation

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.

#### 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.

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.