HP OpenVMS Systems Documentation

By default, users can edit the text contained in the CSText widget. However, you can disable text editing by setting the XmNeditable resource to FALSE. (This resource is TRUE by default.) To change this value after the widget has been created, use the XtSetValues intrinsic routine or the support routines.

Use the DXmCSTextSetEditable and DXmCSTextGetEditable support routines to set and read the XmNeditable resource.

8.2.1.4 Limiting the Length of the Text

You can specify the maximum amount of text that the user can enter in the CSText widget by using the XmNmaxLength resource. To assign a value to this resource at run time, use the XtSetValues intrinsic routine or the DXmCSTextSetMaxLength support routine. To read the value of this resource at run time, use the XtGetValues intrinsic routine or the DXmCSTextGetMaxLength support routine. Example 8-6 includes an example of setting the XmNmaxLength resource.

8.2.2 Customizing the Appearance of the CSText Widget

You can customize the following appearance and function aspects of the CSText widget:

• Size
• Margins
• Resizing behavior
• Scroll bar positioning
• Text cursor appearance
• Position of the insertion point
• Current writing direction
• Current editing direction

The sections that follow describe these resources.

8.2.2.1 Specifying Size

To specify the dimensions of the CSText widget, use the XmNcolumns and XmNrows resources. These resources specify the size of the widget in relation to the size of the characters they contain, which is determined by the fonts used to display the characters.

Use the XmNcolumns resource to specify the width of the CSText widget. (Each character width is referred to as a column.) With this attribute, you can specify the width by the number of characters that the widget can contain horizontally. The default is 20 characters.

Use the XmNrows resource to specify the height of the CSText widget. The height of each row is determined by the height of a character. The overall height dimension of the CSText widget is determined by the number of rows that you specify in the XmNrows resource. The default is 1.

The exact measurement in pixels of these two dimensions depends on the font being used. In the DECwindows Motif Toolkit, fonts are specified in font lists, in this case in the XmNfontList argument. The CSText widget, which can use as many fonts as are specified in the font list, uses the maximum dimensional values from all of the specified fonts as the unit of the XmNcolumns and XmNrows resources.

Although you can specify the size of the CSText widget in pixels by using the common widget resources XmNwidth and XmNheight, this method is not recommended. Fixing the size of the widget in this way creates a dependency on the font. The size you specify might work well with a particular font, but if the font size is increased, the text characters might no longer fit inside the widget.

8.2.2.2 Specifying Margins

You can specify the amount of space around the text entry area of the CSText widget by using the XmNmarginWidth and XmNmarginHeight resources.

Use the XmNmarginWidth resource to specify the amount of space between the border of the widget and the beginning of the array of characters. (The length of the text determines the amount of space between the end of the text and the border.) Specify this margin in pixels. The default value is 6.

Use the XmNmarginHeight resource to specify the amount of space between the top and bottom borders of the widget and the top and bottom edges of the text entry area. Specify this margin in pixels. The default value is 6.

8.2.2.3 Controlling Resizing Behavior

If the user enters more text than will fit in the widget, the CSText widget does not attempt to expand to fit the text. Using the resources of the CSText widget, you can control this behavior in the following ways:

• Setting the resize resources to TRUE
• Making the text wrap
• Using the DXmCreateScrolledCSText routine

You can turn on the automatic resizing behavior of the CSText widget by using the XmNresizeHeight, XmNresizeWidth, or XmNwordWrap resource. The default for these resources is FALSE.

To allow the CSText widget to increase its height, set the XmNresizeHeight resource to TRUE. The XmNresizeHeight resource is ignored if the XmNscrollVertical resource is TRUE.

To allow the CSText widget to increase its width, set the XmNresizeWidth resource to TRUE. Note that if XmNresizeWidth is TRUE, the CSText widget will grow to display all text even if you set XmNcolumns to 1. The XmNresizeWidth resource is ignored if XmNwordWrap is TRUE.

The XmNstringDirection resource determines in which direction the CSText widget expands. For example, if the writing direction is right-to-left, the widget attempts to expand to the left, keeping the rightmost column fixed in its place. The default is left-to-right.

You can specify that the widget wrap words to the next line that would otherwise extend beyond the edge of the line by setting the XmNwordWrap resource to TRUE. This resource is ignored if the XmNeditMode resource is set to XmSINGLE_LINE_EDIT.

8.2.2.4 Scroll Bar Positioning

Another way to control resizing is to create a scrolled CSText widget. To do this, your application calls the DXmCreateScrolledCSText routine and sets either the XmNscrollVertical or XmNscrollHorizontal resource. (These resources do not affect a non-scrolled CSText widget.) Example 8-2 demonstrates creating a scrolled CSText widget.

   .
   .
   .
    ac = 0;
    XtSetArg( arglist[ac], XmNfontList, font_list ); ac++;
    XtSetArg( arglist[ac], XmNx, 40);ac++;
    XtSetArg( arglist[ac], XmNy, 100);ac++;
    XtSetArg( arglist[ac], XmNrows, 2 ); ac++;
    XtSetArg( arglist[ac], XmNcolumns, 35 ); ac++;
    XtSetArg( arglist[ac], XmNmaxLength, 10 ); ac++;
    XtSetArg( arglist[ac], XmNactivateCallback, callback_arg);ac++;
    XtSetArg( arglist[ac], XmNscrollVertical, TRUE);ac++;

    text_w = DXmCreateScrolledCSText(text_shell, "textwidget", arglist, ac );

    XmFontListFree (font_list );

    XtManageChild(text_w);
   .
   .
   .
 }

If you include a vertical and a horizontal scroll bar in a CSText widget, the widget will not resize its height or width to fit additional text. The scroll bar enables the user to scroll through text that is not currently visible.

By default, the vertical scroll bar appears on the right side of the widget, but you can make the scroll bar appear on the left side of the widget by setting the XmNscrollLeftSide resource to TRUE. The default is FALSE.

By default, the horizontal scroll bar appears on the bottom side of the widget, but you can make the scroll bar appear on the top side of the widget by setting the XmNscrollTopSide resource to TRUE. The default is FALSE.

Your application can call the DXmCSTextHorizontalScroll and/or DXmCSTextVerticalScroll routines to scroll text horizontally by the specified number of pixels and/or vertically by the specified number of lines.

8.2.2.5 Controlling Text Cursor Appearance

When the CSText widget has input focus, its text cursor blinks. By assigning values to CSText widget resources, you can specify the following:

• How fast the text cursor blinks
• Whether the text cursor is visible

Use the XmNblinkRate resource to specify how fast the text cursor should blink. Specify this value in milliseconds. The default is 500 milliseconds.

Use the XmNcursorPositionVisible resource to determine whether the text cursor is visible in the widget. (The text cursor is visible when it is drawn in the foreground color.) Set this value to TRUE if you want the text cursor to be visible. The default is TRUE.

Note that the XmNcursorPositionVisible argument specifies only whether the text cursor should be drawn in the foreground color. If the text cursor is positioned in a portion of the text that is not currently visible in the CSText widget, the text cursor will not be visible. To ensure that the text cursor is always in the visible portion of the text widget, use the XmNautoShowCursorPosition resource (described in Section 8.2.2.6).

You can also specify whether the shape of the text cursor indicates the current editing direction. For information about this topic, see Section 8.2.2.7.

8.2.2.6 Positioning the Insertion Point

Use the XmNcursorPosition resource to position the text cursor within the text contents of the widget. Specify the position of the insertion point as an offset from the beginning of the compound string. Determine the offset by counting the number of characters in the string, including spaces and new lines. The first character in a string is numbered 0 (zero). Successive characters are numbered sequentially.

To specify that the insertion point should always be in the visible portion of a scrollable CSText widget, set the XmNautoShowCursorPosition to TRUE. (The default is TRUE.) This causes the widget to scroll as the position of the insertion point changes, keeping the insertion point in the visible portion of the text.

The DXmCSTextGetInsertionPosition routine returns the current position of the insertion cursor. The position is an offset determined by counting the characters, including spaces and new lines. The first character is numbered 0 (zero). Successive characters are numbered sequentially.

To insert text at the end of the current compound string, call the DXmCSTextGetLastPosition routine to return the position of the last character in the compound string. Then, call the DXmCSTextSetInsertionPosition routine to set the insertion cursor to this position.

8.2.2.7 Identifying the Current Writing and Editing Directions

You can identify the current writing and editing directions of the text contained in a CSText widget by reading the value of the DXmNtextPath and DXmNeditingPath resources.

The DXmNtextPath resource indicates the main writing direction of the text in the CSText widget. The default is left to right. The CSText widget sets the value of the DXmNtextPath resource to the writing direction specified in the compound string that it contains when it is created. If this compound string has multiple segments, the CSText widget uses the value of the first segment.

The DXmNeditingPath resource indicates the writing direction enabled for text entry and editing. For example, if the value of the DXmNeditingPath resource is left to right, the delete key deletes characters to the left of the insertion point. If the value is right to left, the delete key deletes the character to the right of the insertion point.

At widget creation time, the CSText widget sets the value of the DXmNeditingPath resource to be the same as the value of the DXmNtextPath resource. However, the value of the DXmNeditingPath resource changes whenever a user changes the editing direction. (Users of your application can switch between the left-to-right and right-to-left editing directions by pressing the toggle key [F17].)

The CSText widget can indicate the current editing direction by changing the shape of the cursor. To use this feature, set the DXmNbidirectionalCursor resource to TRUE. By default, the text cursor does not indicate editing direction.

8.2.3 Multiline Editing in a CSText Widget

Like the XmText widget, the CSText widget supports multiline editing. (See the OSF/Motif Programmer's Guide for a description of XmText multiline editing.)

Multiline editing is especially useful when using a scrolled CSText widget. Your application must set the XmNeditMode resource to XmMULTI_LINE_EDIT to enable multiline editing. Example 8-3 demonstrates how to create a CSText widget that implements multiline editing.

   .
   .
   .
    cstring = XmStringCreateLtoR("Line number 1\nLine number 2",
                                    XmSTRING_ISO8859_1);

    ac = 0;
    XtSetArg( arglist[ac], XmNfontList, font_list ); ac++;
    XtSetArg( arglist[ac], XmNx, 40);ac++;
    XtSetArg( arglist[ac], XmNy, 100);ac++;
    XtSetArg( arglist[ac], XmNrows, 2 ); ac++;
    XtSetArg( arglist[ac], XmNcolumns, 35 ); ac++;
    XtSetArg( arglist[ac], XmNactivateCallback, callback_arg);ac++;
    XtSetArg( arglist[ac], XmNscrollVertical, TRUE);ac++;
    XtSetArg( arglist[ac], XmNeditMode, XmMULTI_LINE_EDIT);ac++;
    XtSetArg( arglist[ac], XmNvalue, cstring);ac++;

    text_w = DXmCreateScrolledCSText(text_shell, "textwidget", arglist, ac );
    XmStringFree(cstring);

   .
   .
   .

This example creates a scrolled CSText widget with multiline editing capability. The XmNrows argument limits the CSText widget to two rows; the user can use the scroll bar to view additional rows.

The initial compound string is displayed on two lines; the XmStringCreateLtoR routine scans the text for newline characters. When one is found, the text up to that point (Line number 1) is put into a segment followed by a separator component. Each segment can be individually selected.

By default, users can edit the text contained in the CSText widget, insert additional text, add new lines (segments) by pressing the Return key, and so forth. However, you can disable text editing by setting the XmNeditable resource to FALSE. (This resource is TRUE by default.)

All applications running in the DECwindows or X Window System environment have access to a global selection facility. This facility allows users of applications to select portions of the display by moving the pointer cursor. Selected portions appear highlighted on the display.

The CSText widget supports the selection mechanism automatically. In addition, you can do the following:

• Select text in the CSText widget.
• Retrieve the selected text.
• Copy selected text to the clipboard.
• Cut selected text from the clipboard.
• Paste selected text from the clipboard into your application.
• Get position information about the selection.
• Determine if the CSText widget owns the primary selection.
• Cancel the current selection.

Use the DXmCSTextSetSelection support routine to select a portion of the text in a CSText widget. This routine takes the following arguments:

• The widget identifier of the CSText widget
• The position in the text where you want to start the selection
• The position in the text where you want to end the selection
• The time of the event that led to the call to the selection

Section 8.2.1.2 describes how to determine positions in a compound string.

You obtain the time stamp of the event that triggered the selection from the X Event data structure.

If the selected text contains the insertion point, the selected text is deleted when new text is entered by the user. You can specify that this selected text not be deleted by setting the XmNpendingDelete resource to FALSE. By default, this resource is set to TRUE.

8.2.4.2 Retrieving Selected Text

Use the DXmCSTextGetSelection to retrieve the selected text in a CSText widget. The selected text is returned as a compound string.

8.2.4.3 Copy Selected Text to the Clipboard

The DXmCSTextCopy routine copies the selected (highlighted) text to the clipboard.

8.2.4.4 Pasting Selected Text from the Clipboard

The DXmCSTextPaste routine pastes the data on the clipboard into the text at the current cursor position.

8.2.4.5 Deleting Selected Text from the Clipboard

The DXmCSTextCut routine deletes the selected (highlighted) text after copying it to the clipboard.

8.2.4.6 Getting Position Information About the Selection

Use the DXmCSTextGetSelectionInfo routine to return the left and right positions of the selected (highlighted) text. As for the insertion cursor routines, the positions in the text are offsets determined by counting the characters, including spaces and new lines. The first character is numbered 0 (zero). Successive characters are numbered sequentially.

DXmCSTextGetSelectionInfo returns FALSE if there is no currently selected text.

Use the DXmCSTextPosToXY routine to identify the x and y position of a specified character in the text. Use the DXmCSTextXYToPos routine to identify the position in the text of the character nearest to a specified x and y position.

8.2.4.7 Determining Primary Selection Ownership

Use the DXmCSTextHasSelection routine to determine if the CSText widget owns the primary selection. See the OSF/Motif Programmer's Guide for a description of the primary selection mechanism.

8.2.4.8 Canceling the Selection of Text

Use the DXmCSTextClearSelection support routine to cancel the selection of text in the compound string text widget. DXmCSTextClearSelection turns off the selected text highlighting.

8.2.5 Associating Callbacks with CSText Widgets

When the text contained in a CSText widget changes, the widget uses the callback mechanism to notify your application. The text in the widget can change as the result of a user interaction, such as entering new text or editing existing text. Your program can also cause a callback by changing the text in a CSText widget using the XtSetValues intrinsic routine or a support routine.

In addition, the CSText widget performs callbacks whenever it accepts or loses input focus. Users can enter text from the keyboard only when the CSText widget has input focus. The CSText widget gets input focus when the user clicks MB1 anywhere within its borders.

The CSText widget performs a callback if it cannot find in its font list the character set required to display a segment of text. In this callback, the CSText widget identifies the required character set for which there is no entry in the font list. The CSText widget searches its font list a second time for the character set when the callback routine returns.

If you update the CSText widget's font list in the callback routine, the widget will find the character set in its font list and be able to display the text tagged with this character set. If you do not associate a callback routine with this callback reason, the CSText widget does not perform the second search of the font list. The CSText widget uses the first font found in the font list.

For complete information about the data returned in the callbacks performed by the CSText widget, see DECwindows Extensions to Motif.

To associate a callback routine with a CSText widget, pass a callback routine list to one of the callback resources. Table 8-2 lists the callback resources and describes the conditions that trigger these callbacks.