Document revision date: 10 November 2000

Controls whether the user can select a particular entry.

Format

void DXmSvnSetEntrySensitivity(widget, entry, sens) Widget widget; int entry; Boolean sens;

Arguments

widget

The identifier (widget ID) of the SVN widget.

entry

An integer that represents the number of the entry whose sensitivity will be set or changed.

sens

A Boolean value that, when True, means the entry is sensitive (the user can select it). If the value is False, the SVN widget will dim the display of the entry to indicate that the entry is not sensitive (the user cannot select it).

Description

The DXmSvnSetEntrySensitivity routine changes the sensitivity of an entry ("sensitivity" means whether the SVN widget will allow the user to select a particular entry). When using this routine, note the following:

• Make the call in your application between calls to DXmSvnDisableDisplay and DXmSvnEnableDisplay.
• If the newly specified sensitivity is the same as the current sensitivity, the call is ignored.
• If the newly specified sensitivity for the entry is different from the current sensitivity, that entry is redisplayed if necessary.
• If an entry is being changed to no longer be sensitive (the user cannot select the entry) and that entry is currently selected, the entry will be cleared (canceled) and then redisplayed.

Assigns an entry tag to a specified entry.

Format

void DXmSvnSetEntryTag(widget, entry, tag) Widget widget; int entry; unsigned int tag;

Arguments

widget

The identifier (widget ID) of the SVN widget.

entry

An integer that represents the number of the entry for which information will be set or changed.

tag

A value that the application will associate with this entry. This value is returned in all callbacks that set the entry_number field in the DXmSvnCallback structure.

Description

The DXmSvnSetEntryTag routine assigns an entry tag to a specified entry, enabling an application to respond to a DXmSvnNgetEntryCallback callback requesting information about that entry. The function of this routine is similar to the DXmSvnSetEntry routine but is more limited in scope, requiring only a subset of the information you would specify for the DXmSvnSetEntry routine.

See the DXmSvnSetEntry and DXmCreateSvn routines for related information.

Sets the position of the tree in tree display mode.

Format

void DXmSvnSetTreePosition(widget, x, y) Widget widget; int x; int y;

Arguments

widget

The identifier (widget ID) of the SVN widget.

x

An integer that represents the x position for the tree. This value is obtained by a previous call to the DXmSvnGetTreePosition routine.

y

An integer that represents the y position for tree. This value is obtained by a previous call to the DXmSvnGetTreePosition routine.

Description

The DXmSvnSetTreePosition routine enables applications to set the exact position of the display from previously stored coordinates. It is valid to call this routine only when the DXmSvnNdisplayMode resource is set to DXmSvnKdisplayTree. (The DXmSvnGetTreePosition routine retrieves the x- and y-coordinates from the SVN widget.)

Note that if the application does not currently have the exact same characteristics (for example, the same mode, fonts, or size and number of entries) as when the DXmSvnGetPosition routine was last called, calling the DXmSvnSetTreePosition routine may generate an incorrect display.

Make this call in your application between calls to DXmSvnDisableDisplay and DXmSvnEnableDisplay.

Specifies that the SVN widget use highlight graphics when showing highlighted entries.

Format

void DXmSvnShowHighlighting(widget) Widget widget;

Arguments

widget

The identifier (widget ID) of the SVN widget.

Description

The DXmSvnShowHighlighting routine shows all highlighting by displaying a box (drawn with dashes) around an entry. Make this call in your application between calls to DXmSvnDisableDisplay and DXmSvnEnableDisplay.

Specifies that the SVN widget use selection graphics when displaying selected entries.

Format

void DXmSvnShowSelections(widget) Widget widget;

Arguments

widget

The identifier (widget ID) of the SVN widget.

Description

The DXmSvnShowSelections routine allows the SVN widget to use reverse video selection graphics when displaying selected entries. Make this call in your application between calls to DXmSvnDisableDisplay and DXmSvnEnableDisplay.

Ensures that all entries are valid.

Format

void DXmSvnValidateAll(widget) Widget widget;

Arguments

widget

The identifier (widget ID) of the SVN widget.

Description

The DXmSvnValidateAll routine examines all entries to ensure that each is valid. If other entries are added while a particular entry is being validated, the routine validates those new entries as well. (The routine calls DXmSvnNgetEntryCallback to obtain entries from the application.) This routine will not complete its operation until all entries are valid. Make this call in your application between calls to DXmSvnDisableDisplay and DXmSvnEnableDisplay.

This chapter explains how to use the extensions that Digital has added to the Motif User Interface Language (UIL). Specifically, it explains how to use nested compound strings, the new command line qualifiers in the UIL compiler, and the Widget Meta Language (WML) binary databases.

In addition, Appendix A documents the UIL built-in tables (which include the additional routines provided by Digital) that you can use to check whether your UIL specification is consistent with the Motif Toolkit. This checking operation occurs during compilation.

3.1 Nested Compound Strings

A nested compound string allows you to nest a given compound string within another relative to the direction in which the string will be displayed. Use the NESTED_COMPOUND_STRING function when one compound string segment needs to be read right-to-left and another needs to be read left to right.

The result of the NESTED_COMPOUND_STRING function is a compound string containing a nested direction. The NESTED_COMPOUND_STRING has one of the following as its value:

• A concatenated nested_string_expression
• A directional string expression
• A string expression

The NESTED_COMPOUND_STRING function has the following syntax:

NESTED_COMPOUND_STRING(nested_string_expression ...)

Where:

nested_string_expression :== {nested_string_expression nested_string_expression ... (1) |RTOL (nested_string_expression) (2) |LTOR (nested_string_expression) (3) |string_expression [SEPARATE=Boolean_expression]}; (4)

1. The nested string expression is the concatenation of two or more nested_string_expressions into one nested_string_expression. Each nested_string_expression consists of one of the following:
   • A concatenated string expression
   • A directional string expression (either RTOL or LTOR)
   • A string expression
2. RTOL formats the nested string expression from right to left.
3. LTOR formats the nested string expression from left to right.
4. The string expression is any string allowed in the character set you have chosen. The string expression must be a null-terminated string. It can optionally contain the SEPARATE clause. The SEPARATE clause appends a separator to the end of the compound string if the Boolean expression is TRUE. If you omit the SEPARATE clause, the resulting string does not have a separator.

The compiler evaluates each string expression to see if it is one of the previously described four types, and then concatenates them all into one compound string with nested directional settings.

The following example shows UIL code for a nested compound string:

(RTOL ("Hello" LTOR ("123", separate=TRUE) "World" ))

This example compound string would be displayed as follows to the end user:

123 olleH dlroW

3.2 Command Qualifiers to the UIL Compiler

The UIL compiler uses the OSF/Motif Release 1.2 and DXm widgets by default. However, you may use other versions or other widgets by using different compiler command options. The following sections describe how to use the UIL compiler on OpenVMS, UNIX, and Windows NT operating systems.

3.2.1 UIL Compiler Command Qualifiers on OpenVMS Systems

Table 3-1 lists the qualifiers for the UIL compiler on OpenVMS systems.

Table 3-1 OpenVMS Compiler Command Qualifiers

Qualifier	Default	Description
/MOTIF	/MOTIF	Uses the OSF/Motif and Digital extended widget database.
/LOCALE	no value	Instructs the compiler to use the current locale when creating localized compound strings. (See the OSF/Motif Programmer's Guide for a description of the UIL -s flag.)
/WIDGET_META_DESCRIPTION=filespec		Selects the Widget Meta Description (WMD) file to be used when processing the UIL source. UIL comes with two WMD files: a standard OSF/Motif widget set, and a Digital extended widget set. To use the standard OSF/Motif widget set, supply the following file specification with this qualifier: DECW$SYSTEM_DEFAULTS: DECW$UIL_OSF_MOTIF_1_1.WMD
		If you want to use the Digital extended widget set, use this qualifier with the following file specification: DECW$SYSTEM_DEFAULTS: DECW$UIL_DXM_MOTIF.WMD (Ask your system manager if there are additional WMD files that you can use.)
/[NO]LIST	/NOLIST for interactive mode /LIST for batch mode	Directs the compiler to produce a listing file. The listing file goes in the current default directory and has the same name as the input file but with a .LIS file extension. If you include a file specification with the /LIST qualifier, the compiler uses that specification to name the listing file.
/[NO]MACHINE_CODE	/MACHINE_CODE	Functions like the /MACHINE_CODE (or equivalent) qualifier available for most high-level language compilers. If you specify both /LIS and /MACHINE_CODE on the UIL command line, the compiler places in the listing file a description of the records that it wrote to the UID file. This is analogous to a compiler placing the machine code it generates for a high-level language in the listing. The primary purpose of this listing is to isolate errors in the UIL compiler.
/[NO]OUTPUT	/OUTPUT	Directs the compiler to produce a User Interface Definition (UID) file. By default, /OUTPUT create a UID file in the current default directory with the same name as the input file, but with the UID extension. If you include a file specification with the /OUTPUT qualifier, the compiler uses that specification to name the UID file. The compiler does not produce a UID file when you use the /NOOUTPUT qualifier or when the compiler issues any diagnostics categorized as error or severe. You can use the /NOOUTPUT qualifier when you want to verify only that your UIL module is syntactically correct.
/[NO]WARNINGS	/WARNINGS	Directs the UIL compiler to suppress warning or informational messages or both.

3.2.2 UIL Compiler Command Flags on UNIX and Windows NT Systems

On UNIX and Windows NT operating systems, you use the following command format to invoke the OSF/Motif UIL compiler:

uil [-flags] filename

Table 3-2 lists the uil command flags.

Table 3-2 Motif UIL Compiler Command Flags on UNIX and Windows NT Systems

Flag	Default	Description
-s		Instructs the compiler to use the current locale when creating localized compound strings.
-wmd filename		Selects the Widget Meta Description (WMD) file to be used when processing the UIL source. UIL comes with two WMD files: a standard OSF/Motif widget set and a Digital extended widget set. If you want to use the standard OSF/Motif widget set, use the following file name with the -wmd flag. The location of this file varies. motif.wmd
		If you want to use the Digital extended widget set, you can use the following file with the -wmd flag. The location of this file varies. dxm-motif.wmd (Ask your system administrator if there are additional WMD files that you can use.)
-o filename	a.uid	Directs the compiler to produce a User Interface Definition (UID) file. By default, UIL creates a UID file with the name a.uid. No UID file is produced if the compiler issues any diagnostics categorized as error or severe.
-v filename	No listing is generated	Directs the compiler to produce a listing file. If the -v flag is not present, the compiler does not generate a listing.
-m	No machine code is listed	Directs the compiler to place in the listing file a description of the records that it added to the UID file. This feature helps you to isolate errors.
-w	Warning messages are generated	Directs the compiler to suppress all warning and informational messages. Only error messages and severe messages are generated.
-I[ pathname]	/usr/include	If you specify the -I flag followed by a full pathname, the compiler searches for include files whose names do not begin with a slash (/) in the following order: In the directory path of the main file In the directory specified by the -I flag In the standard directory (/usr/include) If you specify -I alone, the compiler searches only the directory in which the main file is located; it does not search for include files in the standard directory (/usr/include).

3.3 WML Binary Databases

The version of Motif supplied by Digital supports the Widget Meta Language (WML) in a binary form called Widget Meta Description (WMD). WML generates a WMD file describing widgets and other attributes for use with the UIL compiler. Digital has included two WML source files on each operating system. You can copy these files to your own subdirectory and modify them so that you can refer to your own widgets by name without making them user-defined.

The following sections describe WML support provided on OpenVMS, UNIX, and Windows NT operating systems. For additional information about the WML, see the OSF/Motif Programmer's Guide.

3.3.1 WML Files on OpenVMS Systems

Digital includes the following files to support WML databases on OpenVMS operating systems:

• DECW$UIL_OSF_MOTIF_1_1.WML specifies the Motif toolkit as shipped from OSF.
• DECW$UIL_DXM_MOTIF.WML describes the OSF/Motif toolkit with the Digital extensions to the toolkit.

When adding new widgets or changing widget characteristics, start with a copy of one of the two WML files. Use DECW$DXM_MOTIF.WML if you are using any Digital widgets. Use the OSF/Motif WML files if your application requires a strict OSF widget set.

Digital has also included the following two WMD files (which correspond to the two WML files):

• DECW$UIL_OSF_MOTIF_1_1.WMD specifies the Motif toolkit as shipped from OSF.
• DECW$UIL_DXM_MOTIF.WMD describes the OSF/Motif toolkit with the Digital extensions.

To allow you to add UIL support for additional widgets, Digital has provided you with the following files:

• Templates

  DECW$SYSTEM_DEFAULTS:DECW$UIL_OSF_MOTIF_1_1.WML
  DECW$SYSTEM_DEFAULTS:DECW$UIL_DXM_MOTIF.WML

  Use either of the previous files as a template for your own WML file.
• DECW$EXAMPLES:UILWMDCREATE.C
• DECW$EXAMPLES:UILWMDCREATE.COM

The procedure is as follows:

1. Extend the DECW$UIL_DXM_MOTIF.WML file to add support for your new widgets.
2. Copy DECW$EXAMPLES:UILWMDCREATE.C to your directory.
3. Add your widget's public include file to UILWMDCREATE.C. In the C file there is a comment section that indicates where in the file you add public include files.
4. Execute UILWMDCREATE.COM by entering a command in the following format:

   @DECW$EXAMPLES:UILWMDCREATE filename.WML

   
   This command procedure performs three major functions:

   1. Runs WML to create .h files.
   2. Compiles, links, and runs a modified UILWMDCREATE.C.
   3. Cleans up. (If the command procedure does not finish successfully, it will not clean up the extra files generated. Delete all the new files and subdirectories that the command procedure creates before trying to run the command procedure again.)
   
   After you execute this command procedure, you will have a WMD file that the UIL compiler will use instead of the internal database.
   Two other files, an MM and an SDML file, will be created; these are documentation files. The MM file is a troff MM macro format file; the SDML file is a VAX DOCUMENT file. You can use the MM file on a UNIX system, or the SDML file on an OpenVMS for VAX system to create a copy of the UIL built-in tables for your own widget set.
5. Invoke the UIL compiler by entering a command at the dollar sign ($) prompt, using the following format:

   UIL/MOTIF/WIDGET_META_LANGUAGE=filename.WMD filename.UIL

	privacy and legal statement
5635PRO_015.HTML