1. Create an instance of the print widget. By default, print two copies of the file or files and unmanage the print widget when the OK or Cancel push buttons are pressed.

Example 7-5 Creating the Print Widget Through UIL---C Support

. . . #include <DXm/DXmPrint.h> . . . /* Print Widget Creation */ static void create_print() { unsigned int ac; Arg arglist[10]; XtCallbackRec callback_arg[2]; start_watch(); (1)if (!print_widget) { if (MrmFetchWidget (s_MrmHierarchy, "main_print", toplevel_widget, &print_widget, &dummy_class) != MrmSUCCESS) s_error ("can't fetch print widget"); (2)callback_arg[0].callback = activate_print; callback_arg[0].closure = 0; callback_arg[1].callback = NULL; callback_arg[1].closure = NULL; ac = 0; (3)XtSetArg (arglist[ac], XmNokCallback, callback_arg);ac++; (4)XtSetArg (arglist[ac], DXmNsuppressOptionsMask, DXmSUPPRESS_DELETE_FILE | DXmSUPPRESS_OPERATOR_MESSAGE); ac++; (5)XtSetValues (print_widget, arglist, ac); } (6)XtManageChild(print_widget); stop_watch(); } . . .

1. If an instance of the print widget does not already exist, fetch one.
2. Assign values to elements of the callback routine list. Each callback routine data structure contains the address of a callback routine and a tag. In this case the callback routine is activate_print and there is no tag value. The null values signify the end of the callback routine list.
3. The XmNokCallback resource uses the null-terminated argument list to determine what routines to call when a user presses the OK push button.
4. Suppress the delete file and operator message resources.
5. Call XtSetValues to set the values for the print widget.
6. Manage the print widget.

Example 7-6 shows how the print widget for the OpenVMS DECburger example was created using the DXmCreatePrintDialog routine.

Example 7-6 Calling the DXmCreatePrintDialog Routine

. . . #include <DXm/DXmPrint.h> . . . (1)print_widget = (Widget)NULL; /* Print widget*/ . . . static void create_print() { unsigned int ac; Arg arglist[10]; (2)static int num_copies; XmString print_format; (3)XtCallbackRec callback_arg[2]; (4)if (!print_widget) { num_copies = 2; (5)callback_arg[0].callback = activate_print; callback_arg[0].closure = 0; callback_arg[1].callback = NULL; callback_arg[1].closure = NULL; ac = 0; (6)XtSetArg (arglist[ac], DXmNnumberCopies, num_copies); ac++; XtSetArg (arglist[ac], DXmNunmanageOnOk, TRUE); ac++; XtSetArg (arglist[ac], DXmNunmanageOnCancel, TRUE); ac++; XtSetArg (arglist[ac], XmNokCallback, callback_arg);ac++; (7)XtSetArg (arglist[ac], DXmNsuppressOptionsMask, DXmSUPPRESS_DELETE_FILE | DXmSUPPRESS_OPERATOR_MESSAGE); ac++; (8)print_widget = DXmCreatePrintDialog (toplevel_widget, "Print Widget", arglist, ac); (9)XtManageChild(print_widget); return; } (10)XtManageChild(print_widget); } . . .

1. The OpenVMS DECburger application defines the print widget in its global data section so that it can be referenced throughout the source file. DECburger explicitly initializes print_widget to null to make sure that it does not contain a garbage value. DECburger later tests print_widget to see if it exists, thereby preventing a garbage value from producing unexpected results.
2. The num_copies variable is used to set the DXmNnumberCopies resource. This example sets the number of copies to 2 by default.
3. DECburger declares the callback routine list as an array of callback routine data structures. Note that the array contains two elements. All callback routine lists must contain at least two elements because a callback routine list is a null-terminated list.
4. Test to see if the print widget already exists. If the print widget already exists, DECburger only needs to manage it.
5. Assign values to elements of the callback routine list. Each callback routine data structure contains the address of a callback routine and a tag. In this case, the callback routine is activate_print and there is no tag value. The null values signify the end of the callback routine list.
6. Call the XtSetArg intrinsics routine once for each resource you want to specify. DECburger sets the DXmNunmanageOnOk and DXmNunmanageOnCancel resources to unmanage the print widget when the OK or Cancel push button in the print widget main dialog box is pressed.
7. DECburger suppresses the Delete File and Operator Message options; the user cannot use the print widget to delete the file being printed, and operator messages are suppressed.
8. Call the DXmCreatePrintDialog routine to create the print widget. DXmCreatePrintDialog returns the widget ID of the print widget.
9. Manage the newly created print widget.
10. If the print widget already existed, DECburger only needs to manage the existing print widget.

After you have created an instance of the print widget through either UIL or the Toolkit routine, you must submit the print job to the printer queue. The DXmPrintWgtPrintJob routine is provided for this purpose. You pass the ID of the print widget, a list of the files to print, and the number of files to print to the DXmPrintWgtPrintJob routine.

Example 7-7 shows an example of calling the DXmPrintWgtPrintJob routine from the OpenVMS DECburger example program.

Example 7-7 Calling the DXmPrintWgtPrintJob Routine

. . . static void activate_print(w, tag, reason) Widget w; int *tag; XmAnyCallbackStruct *reason; { unsigned long int l_status; XmString file_pointer[1]; int l_num_names,l_i; char at_buffer[30]; FILE *fopen(), *fp; (1)if ((fp = fopen("order.txt", "w")) != NULL) { fprintf(fp, "Function Not Yet Implemented\n"); fclose(fp); (2)file_pointer[0] = XmStringCreateLtoR("order.txt", XmSTRING_DEFAULT_CHARSET); (3)l_status = DXmPrintWgtPrintJob(print_widget, file_pointer, 1); (4)printf("DXmPrintWgtPrintJob return status: %x\n",l_status); } } . . .

1. Open a file called order.txt for writing. If the open is successful, print the "Function Not Yet Implemented" message in the file and close it.
2. Create a compound string from the file name.
3. Call the DXmPrintWgtPrintJob routine, specifying the print widget ID, an XmString array containing the order.txt file, and the number of files to print (1).
4. Print the print-job status on the standard output.

This chapter provides the following:

• An overview of the compound string text widget in the DECwindows Motif Toolkit
• A description of the support routines used with the compound string text widget

A compound string is a string stored with character set and writing information. A compound string can consist of multiple segments, where each segment in the string can have a different character set and writing direction properties.

In a compound string, you specify not only the characters in the text string, but also the character set and writing direction you want for displaying the text string on a workstation screen. All DECwindows Motif Toolkit widgets that contain text labels use compound strings to represent these labels. By using the compound string text widget, you enable users of your application to enter and edit text in the same character set and writing direction used throughout the user interface for your application.

The DECwindows Motif Toolkit includes a compound string text widget, CSText, that you can use to give your application text editing capabilities. The CSText widget is available both with and without scroll bars:

• DXmCreateScrolledCSText
• DXmCreateCSText

Both versions of the CSText widget let users of your application enter text or edit existing text using the keyboard. The difference between the two widgets is that the DXmCreateScrolledCSText widget supports horizontal and vertical scroll bars, while DXmCreateCSText does not.

With the exception of the scroll bars, both versions of the CSText widget have the same visual appearance. The text entry area contains a text cursor that indicates where text will be inserted. When the widget has input focus, the text cursor blinks and is displayed at full brightness. When the widget does not have input focus, the text cursor appears dimmed and does not blink.

The text cursor in the CSText widget can also indicate the current editing direction. The editing direction is the direction in which characters can be inserted or deleted. If your application sets the DXmNbidirectionalCursor resource to true, users of your application can switch between the left-to-right and right-to-left editing directions by pressing the toggle key (F17). DXmNbidirectionalCursor is FALSE by default.

Whenever a user changes the editing direction in a CSText widget, the shape of the text cursor, called a bidirectional text cursor, can change to indicate the new editing direction. When the CSText widget does not have input focus, it contains a dimmed, standard text cursor. For information on how to create a CSText widget with a bidirectional text cursor, see Section 8.2.2.7.

The widget uses the callback mechanism to notify your application when the text it contains changes. Note, however, that the widget does not return the text in the callback. To retrieve the text, you must use the XtGetValues intrinsic routine or one of the support routines provided by the DECwindows Motif Toolkit for use with the CSText widget. (For more information about this topic, see Section 8.2.1.2.)

The DECwindows Motif Toolkit includes support routines for many commonly performed tasks, such as specifying the text contained in the CSText widget. The sections that follow describe how to use these support routines. Table 8-1 lists the support routines.

Table 8-1 CSText Widget Support Routines

Routine Name	Description
Manipulating the Text Content of the Widget
DXmCSTextCopy	Copies the currently selected (highlighted) text to the clipboard.
DXmCSTextCut	Deletes the currently selected (highlighted) text after copying it to the clipboard.
DXmCSTextGetString	Returns the compound string that is the current value of the CSText widget.
DXmCSTextInsert	Inserts the new compound string into the compound string at the specified position.
DXmCSTextNumLines	Returns the number of output lines in the compound string text widget.
DXmCSTextPaste	Pastes the data on the clipboard into the text at the current cursor position.
DXmCSTextRemove	Removes the currently selected (highlighted) text.
DXmCSTextReplace	Replaces the compound string characters between "from" and "to" with the given string; "from" and "to" are zero-based character offsets that include new lines.
DXmCSTextSetString	Replaces the text of the CSText widget with completely new text.
DXmCSTextHorizontalScroll	Scrolls text by the given number of pixels.
DXmCSTextGetEditable	Returns a Boolean value that indicates whether the user of the application can edit the current text contents of the widget. When this routine returns TRUE (1), the user can edit the text; when it returns FALSE (0), the user cannot edit the text.
DXmCSTextGetInsertionPosition	Returns the position (offset) of the insertion cursor.
DXmCSTextGetLastPosition	Returns the position (offset) corresponding to the last character in the string.
DXmCSTextGetMaxLength	Returns the maximum length of text that the widget will allow a user to enter.
DXmCSTextGetTopPosition	Returns the position (offset) of the top left (or top right) character in the displayed text.
DXmCSTextPosToXY	Identifies the x and y positions of a specified character in the text.
DXmCSTextXYToPos	Identifies the position in the text of the character nearest to a specified x and y position.
DXmCSTextHorizontalScroll	Scrolls text by the given number of pixels.
DXmCSTextSetAddMode	Controls whether the CSText widget is in Add Mode, which allows the user to move the insert cursor without affecting the primary selection.
DXmCSTextSetEditable	Sets the Boolean value that indicates whether the user can edit the current text contents of the CSText widget. To allow editing, set this value to TRUE.
DXmCSTextSetHighlight	Changes the highlighting mode of a compound string.
DXmCSTextSetInsertionPosition	Sets the insertion cursor to the given position (offset) in the source.
DXmCSTextSetMaxLength	Sets a size limit in characters, including newline characters, that the user can enter in the widget.
DXmCSTextSetTopPosition	Sets the position (offset), which will be at the top left (or top right) of the displayed text.
DXmCSTextShowPosition	Forces the given position to be displayed.
DXmCSTextVerticalScroll	Scrolls text by the specified number of lines.
DXmCSTextClearSelection	Cancels the selection of compound string text in the widget and turns off highlighting of the text.
DXmCSTextGetSelection	Gets the portion of the compound string text that has been selected using the selection mechanism. Selected text is highlighted on the display.
DXmCSTextGetSelectionInfo	Returns the left and right positions (offsets) corresponding to the currently selected (highlighted) text. Returns FALSE if there is no currently selected text.
DXmCSTextHasSelection	Returns TRUE if the compound string text widget currently owns the primary selection.
DXmCSTextSetSelection	Sets the portion of the compound string text specified by the start and end point positions as the selection, and highlights the text on the screen.

8.2 Modifying CSText Widget Resources

The following sections describe how to use the resources of the CSText widget and the CSText widget support routines.

8.2.1 Manipulating the Text Contents of the CSText Widget

The CSText widget provides text entry and text editing capabilities in a user interface. To manipulate the text contents of the CSText widget at run time (after the widget has been created), you can use either of the following two sets of routines:

• XtSetValues or XtGetValues intrinsic routines
• CSText widget support routines

The support routines offer several advantages over the XtSetValues or XtGetValues:

• The support routines use fewer system resources and, therefore, are more efficient.
• The support routines do not require that you create an argument list.

To place a compound string in a CSText widget after the widget has been created, you can use the XtSetValues intrinsic routine or a support routine.

To use the XtSetValues intrinsic routine, specify the address of the compound string as the value of the XmNvalue resource in an argument list. (The default is null.) Then pass this argument list to the XtSetValues intrinsic routine to assign the value to the widget resource.

You can use the CSText widget support routines to either modify the text the widget contains or replace the text entirely.

Use the DXmCSTextReplace support routine to modify the text currently in the CSText widget. This routine takes the following arguments:

• The identifier of the CSText widget
• The position in the text where the text to be replaced begins
• The position in the text after the text to be replaced ends
• The new text that you want to put in place of the existing text

Specify the position in the text as an offset from the beginning. Determine the offset by counting the characters, including spaces and new lines. The first character is numbered 0 (zero). Successive characters are numbered sequentially.

Use the DXmCSTextInsert routine to insert a new compound string into the compound string text source at the specified position. Specify the same position for both the start and the end points. If the start and end points are not specified as the same position, the text in the section defined by the start and end points is replaced by the new text.

Use the DXmCSTextPaste routine to insert the data on the clipboard into the text at the current cursor position.

Use the DXmCSTextSetString routine to replace all the text in a CSText widget. This routine places the address of the new text in the XmNvalue resource.

8.2.1.2 Retrieving Compound Strings from a CSText Widget

To retrieve the current value of a CSText widget, you can use the XtGetValues intrinsic routine or a support routine.

To use the XtGetValues intrinsic routine, create a variable to hold the address of the compound string and specify this variable as the value of the XmNvalue resource in an argument list. Then pass this argument list to the XtGetValues intrinsic routine. The XtGetValues intrinsic routine writes the address contained in the XmNvalue resource into the variable that you specified in the argument list. Do not free the returned pointer.

Use the DXmCSTextGetString support routine to retrieve the current contents of the CSText widget. This support routine returns the value of the XmNvalue resource. Free the returned pointer.

Example 8-1 shows how to use the DXmCSTextGetString routine.

Example 8-1 Using the DXmCSTextGetString Support Routine

. . . static void change_cs(w, tag, reason) Widget w; int *tag; XmNanyCallbackStruct *reason; { int ac = 0; Arg arglist[15]; XmString new_text; XtCallbackRec ok_arg[2]; new_text = DXmCSTextGetString(w); ac = 0; XtSetArg( arglist[ac], XmNdialogTitle, new_text);ac++; XtSetValues (text_shell, arglist, ac); . . . XtFree(new_text); . . . }