Document revision date: 10 November 2000

Provides locale-sensitive Motif compound string version of Toolkit ASCII default values.

Format

XmString DXmGetLocaleString(context, string, word_type) I18nContext context; char *string; I18nWordType word_type;

Return Value

A pointer to the Motif compound string containing the value.

Arguments

context

Reserved for future use. (Null value passed.)

string

Null-terminated string specifying the ASCII string value whose locale-sensitive version is to be retrieved (for example, the string "OK").

word_type

Specifies the type (part of speech) of a word in the string, as indicated by one of the following values:

Value	Description
I18NADJECTIVE	The word is an adjective.
I18NADVERB	The word is an adverb.
I18NNOUN	The word is a noun.
I18NVERB	The word is a verb.

Description

The DXmGetLocaleString routine provides a locale-sensitive Motif compound string version of Toolkit ASCII default values, such as "OK" or "Cancel". You can specify the part of speech (adjective, adverb, verb, or noun) associated with each word in the string.

Enters the application into context-sensitive help mode and either calls a help callback (if one exists) or searches for one in the widget's parent.

Format

void DXmHelpOnContext (widget, confine) Widget widget; Boolean confine;

Arguments

widget

The identifier of the widget (widget ID) to pass to the XmTrackingLocate routine.

confine

A Boolean value passed to XmTrackingLocate. When True, confines the help cursor (?) to the widget specified in the widget argument.

Description

The DXmHelpOnContext routine enters context-sensitive help mode, changing the cursor to the help cursor (?) and then waiting for an MB1 click on a widget. If the selected widget has a help callback, that help callback is called; otherwise, the widget's parent is checked for a help callback.

Note that a Null callback structure pointer is passed to the help callback. Therefore, help callbacks in your application should test the value of this pointer before they attempt to use it.

For related information, refer to the description of the XmTrackingLocate routine in the OSF/Motif Programmer's Reference.

Closes all of the remaining topic and navigation windows in Bookreader. (Note that Bookreader and LinkWorks are not available on Windows NT systems.)

Format

void DXmHelpSystemClose(help_context, routine, tag) Opaque help_context; void ((*routine )()), Opaque tag );

Arguments

help_context

Used by the DECwindows Motif Help System to pass required LinkWorks and help information from one routine to another.

routine

Used for error processing. If an error occurs within the DECwindows Motif Help System and it cannot be processed by either LinkWorks or Bookreader, the DECwindows Motif Help System calls the error processing routine you have included in your application and passes in an integer, or status, to indicate the status of the error processing operation, as follows:

Value	Description
1	The DECwindows Motif Help System could not find the LinkWorks shareable image.
2	The DECwindows Motif Help System could not translate a specified value into a valid file specification.

Note the following:

• The status argument is a system-supplied argument that supplements the routine and tag arguments you have already specified in the application.
• If an error cannot be processed by either LinkWorks or Bookreader and you have not specified a supplementary error handling routine, your system will generate an access violation error message.

tag

The argument you supply for the previously described routine argument. Associating a tag with the routine enables you to more easily determine where errors occur.

Description

Within the DECwindows Motif Help System, the DXmHelpSystemClose routine closes all of the remaining topic and navigation windows in the Bookreader. You should call this routine when your application is closing all of its other windows.

See the DECwindows Motif Guide to Application Programming for a complete description of the DECwindows Motif Help System. See also the DXmHelpSystemDisplay and DXmHelpSystemOpen routines for related information.

Displays a topic or directory of the help file in Bookreader. (Note that Bookreader and LinkWorks are not available on Windows NT systems.)

Format

void DXmHelpSystemDisplay(help_context, help_file, keyword, name, routine, tag) Opaque help_context; char *help_file; char *keyword; char *name; void ((*routine )()), Opaque tag );

Arguments

help_context

Used by the DECwindows Motif Help System to pass required LinkWorks and help information from one routine to another.

help_file

Optional. The file name of the help file. If Null or "" is supplied, Bookreader will use the help file name passed in to the DXmHelpSystemOpen routine; otherwise a new file name can be passed.

keyword

One of two values: "topic" or "dir". Pointers to these strings can be passed instead.

name

The topic symbol from the help callback if "topic" is used for the keyword. If "dir" is used, then name refers to the name of the Bookreader directory that should be opened, such as "Contents" or "Index". Either specific strings or pointers to strings may be passed in.

routine

Used for error processing. If an error occurs within the DECwindows Motif Help System and it cannot be processed by either LinkWorks or Bookreader, the DECwindows Motif Help System calls the error processing routine you have included in your application and passes in an integer, or status, to indicate the status of the error processing operation, as follows:

Value	Description
1	The DECwindows Motif Help System could not find the LinkWorks shareable image.
2	The DECwindows Motif Help System could not translate a specified value into a valid file specification.

Note the following:

• The status argument is a system-supplied argument that supplements the routine and tag arguments you have already specified in the application.
• If an error cannot be processed by either LinkWorks or Bookreader and you have not specified a supplementary error handling routine, your system will generate an access violation error message.

tag

The argument you supply to the previously described routine argument. Associating a tag with the routine enables you to more easily determine where errors occur.

Description

The DXmHelpSystemDisplay routine (which you use instead of a call to the help widget) displays a topic or directory of the help file in Bookreader, using the DECwindows Motif Help System. This routine can also be used to display topics or directories of books other than the ones passed in to DXmHelpSystemOpen.

See the DECwindows Motif Guide to Application Programming for a complete description of the DECwindows Motif Help System. See also the DXmHelpSystemDisplay and DXmHelpSystemOpen routines for related information.

Completes initialization operations required by LinkWorks and prepares to display a topic from the specified help file name. (Note that Bookreader and LinkWorks is not available on Windows NT systems.)

Format

void DXmHelpSystemOpen(help_context, main_window, help_file, routine, tag) Opaque *help_context; Widget main_window; char *help_file; void ((*routine )()), Opaque tag);

Arguments

help_context

Used by the DECwindows Motif Help System to pass required LinkWorks and help information from one routine to another. Note that help_context must be defined globally; the DXmHelpSystemDisplay and DXmHelpSystemClose routines subsequently use the address initially set for this argument.

main_window

The identifier (ID) for the main window of the application.

help_file

The file name of the help file. The default specifications are as follows:

Default on	Default on	Description
OpenVMS Systems	UNIX Systems
SYS$HELP:	/usr/lib/X11/help	Directory location
.DECW$BOOK	.decw_book	File extension

You can also provide your own location or extension along with the help file name.

Note that help_file is required for this routine but is optional for DXmHelpSystemDisplay.

routine

Used for error processing. If an error occurs within the DECwindows Motif Help System and it cannot be processed by either LinkWorks or Bookreader, the DECwindows Motif Help System calls the error processing routine you have included in your application and passes in an integer, or status, to indicate the status of the error processing operation, as follows:

Value	Description
1	The DECwindows Motif Help System could not find the LinkWorks shareable image.
2	The DECwindows Motif Help System could not translate a specified value into a valid file specification.

Note the following:

• The status argument is a system-supplied argument that supplements the routine and tag arguments you have already specified in the application.
• If an error cannot be processed by either LinkWorks or Bookreader and you have not specified a supplementary error handling routine, your system will generate an access violation error message.

tag

The argument you supply to the previously described routine argument. Associating a tag with the routine enables you to more easily determine where errors occur.

Description

Within the DECwindows Motif Help System, the DXmHelpSystemOpen routine completes all of the initialization operations required by LinkWorks, such as creating a DECwindows user interface object and a surrogate object, and then prepares to display a topic from the help file name passed in. You should make the call to this routine just before the main loop of your application.

See the DECwindows Motif Guide to Application Programming for a complete description of the DECwindows Motif Help System. See also the DXmHelpSystemClose and DXmHelpSystemDisplay routines for related information.

Prepares an application to use MRM widget-fetching facilities for the Digital supplied (DXm) Motif widgets.

Format

void DXmInitialize()

Description

The DXmInitialize routine performs a function similar to the MrmInitialize function, but for the DXm widgets. Calling DXmInitialize is equivalent to calling MrmRegisterClass for each of the DXm widgets (DXmColorMix, DXmHelp, DXmPrint, DXmCSText, and DXmSVN).

Loads the font specified by the font name or generates a new font name.

Format

XFontStruct *DXmLoadQueryFont (d, fontname) Display *d; char *fontname;

Return Value

A pointer to the XFontStruct of the font (if a font is successfully loaded). If a font cannot be loaded, Null is returned.

Arguments

d

The pointer to the display on which the font will be loaded.

fontname

A pointer to the XLFD font name used to load a font.

Description

The DXmLoadQueryFont routine loads the font specified by the font name or, if the font fails to load, generates a new font name, and loads that font instead.

See the X Window System for information about how the X Window System defines valid font names. See also the DXmFindFontFallback routine.

Returns the number of children that belong to the widget.

Format

Cardinal DXmNumChildren(widget) Widget widget;

Return Value

The number of children (a positive integer).

Arguments

widget

The identifier (widget ID) of the widget.

Description

The DXmNumChildren routine returns a positive integer that represents the number of children that belong to the widget.

Defines additional print formats and lets you add new options to the print widget option menus.

Format

unsigned long int DXmPrintWgtAugmentList(pw,list,data) Widget pw; int list; XtPointer data;

Return Value

An integer that represents either the number of print formats known to the print widget or the identifier of a new option added to the print widget option menu, depending on the operation performed. A Null return indicates that the addition of a print format or option was unsuccessful.

Arguments

pw

The print widget.

list

The print formats or options, indicated by the following values:

Value	Description
DXmFILE_BURST_SHEET	Specifies the availability and frequency of printed File Burst Sheets
DXmFILE_END_SHEET	Specifies the availability and frequency of printed File End Sheets
DXmFILE_START_SHEET	Specifies the availability and frequency of printed File Start Sheets
DXmINPUT_TRAY	Specifies the input tray holding the sheet to be used for the print job
DXmMESSAGE_LOG	Specifies what is to be done with error messages generated during the print operation
DXmOUTPUT_TRAY	Specifies the output tray in which the sheet is to be placed
DXmPAGE_SIZE	Specifies the size of the print image
DXmPRINT_FORMAT	Specifies the print format
DXmSHEET_SIZE	Specifies the size of the sheet
DXmSIDES	Specifies how many sides of the sheet will be printed

data

One of the following data structures:

• DXmPrintFormatStruct, which has the following structure:

  typedef struct _DXmPrintFormatStruct { XmString ui_string; (1) XmString os_string; (2) XmString var_string; (3) } DXmPrintFormatStruct;

  1. The label displayed in the user interface
  2. Specifies a string that identifies the print format for the operating system
  3. The OpenVMS logical or UNIX or Windows NT environment variable that identifies the print format
• DXmPrintOptionMenuStruct, which has the following structure:

  typedef struct _DXmPrintOptionMenuStruct { XmString ui_string; (1) XmString os_string; (2) } DXmPrintOptionMenuStruct;

  1. The label displayed in the user interface
  2. Specifies a string that identifies the print option for the operating system

Description

The DXmPrintWgtAugmentList routine defines additional print formats and lets you add new options to the print widget option menus. Note that the return value (an integer) is not required when adding print formats. However, the Intrinsics routines XtGetValues and XtSetValues use that integer when subsequent calls are made on the option menus.

See the X Window System Toolkit manual for more information about the Intrinsic routines and the DECwindows Motif Guide to Application Programming for a complete description of the print widget.

See also the following routines for related information:

• DXmCreatePrintBox
• DXmCreatePrintDialog
• DXmPrintWgtPrintJob

Submits files to the print service.

Format

unsigned long int DXmPrintWgtPrintJob(print_widget, filenames, filename_count) Widget print_widget; XmStringTable filenames; int filename_count;

Return Value

An integer that indicates the success or failure of the print job, as follows:

Value	Description
0	Print job failed.
1	Print job was successful.

Arguments

print_widget

The identifier (widget ID) of the print widget.

filenames

The file names to be printed.

filename_count

An integer that represents the number of file names.

Description

The DXmPrintWgtPrintJob routine completes the submission of the identified files to the appropriate print service and returns the success of the print job to the application.

Opens new entries in the structure.

Format

void DXmSvnAddEntries(widget, after, count, level, tags, index) Widget widget; int after; int count; int level; int* tags[]; Boolean index;

Arguments

widget

The identifier (widget ID) of the SVN widget.

after

An integer that represents the entry number that the newly opened positions are inserted after. (If you want to add an entry before number 1, then set this argument to 0.)

count

An integer that represents the number of entries to add to the array.

level

An integer that represents the level number of the entries being added. A level number of 0 indicates top-level entries.

tags

A pointer to an array of longwords that contain the tag values for each entry being added. If the tag values are not being used, a Null pointer may be passed. This value can also be changed with either the DXmSvnSetEntry or DXmSvnSetEntryTag routine call.

index

A Boolean value that, when True, indicates that all of the entries being added should appear in the scroll index window when the user drags the slider. This value can be changed with either the DXmSvnSetEntry or DXmSvnSetEntryIndexWindow routine. Note that the index window is used only when the DXmNliveScrolling resource is set to False.

Description

The DXmSvnAddEntries routine enables an application to process the expansion of an entry. The value supplied for count determines how many entries the application should open. The actual text of the entry is not passed.

The first time an entry is displayed to the user, the SVN widget issues the DXmSvnNgetEntryCallback to obtain information about the entry. If the user never positions the window in an area where a particular entry is visible, the callback will never be made. Make this call in your application between calls to DXmSvnDisableDisplay and DXmSvnEnableDisplay.

	privacy and legal statement
5635PRO_011.HTML