HP OpenVMS Systems Documentation

DECwindows Extensions to Motif

Contents

Index

DXmGetLocaleString

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.

DXmHelpOnContext

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.

DXmHelpSystemClose

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.

DXmHelpSystemDisplay

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.

DXmHelpSystemOpen

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.

DXmInitialize

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

DXmLoadQueryFont

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.

DXmNumChildren

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.

DXmPrintWgtAugmentList

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;
The label displayed in the user interface
Specifies a string that identifies the print format for the operating system
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;
The label displayed in the user interface
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

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.

DXmSvnAddEntries

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.

Contents

Index