Text and TextField allow the user to cut, copy, and paste text by using the clipboard, primary transfer, or secondary transfer. The user can also drag and drop text within a widget, between widgets, or from a Label or List widget to a Text or TextField widget. In all cases, the user first selects text in some widget and then inserts the selected text into a Text or TextField widget.
This section explains how selection works in Text and TextField. Understanding selection requires understanding of several concepts: primary selection, secondary selection, clipboard selection, the destination widget, the insertion cursor, the selection anchor, and pending delete.
Selections are the primary means of exchanging data between X clients. A selection is a piece of data. Each display may have several kinds of selections, but only one selection of each kind can exist at any time on the display. A client owns each selection, and the selection is attached to a window. Clients can acquire or give up ownership of a selection and can request that the owner convert the selection into some data type and place the results on a property of a particular window. This mechanism makes it possible to select and then cut, copy, or paste data from one client to another. Selections are discussed in detail in the X Window System Inter-Client Communication Conventions Manual (ICCCM).
Text and TextField support transfers by using the three kinds of selection common to all X clients:
The primary selection is the principal selection on the display. Unless they are qualified, the terms selecting text and the selection refer to the primary selection.
The secondary selection is used to transfer data without disturbing the primary selection. Text and TextField use the secondary selection for quick transfer, in which the user selects and then moves or copies text by using a single series of mouse gestures.
The clipboard selection usually holds data cut or copied from one client and available to be pasted into another. Text and TextField provide actions for cutting and copying text to the clipboard and for pasting text from the clipboard.
The destination is the widget that, at any particular time, would receive the selection if the user were to invoke a move, copy, or paste operation. A Text or TextField widget must be both sensitive and editable to become the destination. When the XmNkeyboardFocusPolicy of the shell is XmEXPLICIT, an editable widget becomes the destination when it receives keyboard focus. When the XmNkeyboardFocusPolicy is XmPOINTER, an editable widget becomes the destination when it receives any mouse button or keyboard input. If the destination widget becomes insensitive or uneditable, there is no destination widget.
The insertion cursor is an I-beam cursor that shows where text, including a selection, would be inserted in a Text or TextField widget. The insertion cursor appears as a solid I-beam when the widget is in normal mode (explained below) and when it is either the widget with keyboard focus or the destination widget. Otherwise, the insertion cursor appears as a stippled I-beam.
The anchor is a position in the text of a widget that marks one boundary of a selection or a potential selection. For example, the user can select a range of text by pressing, dragging, and releasing Btn1. The anchor is set at the point of the button press, and the selection extends to the point of the button release. When the user takes an action to extend an existing selection, Motif first adjusts the anchor by using a balance-beam method: it moves the anchor to the end of the existing selection that is farthest from the point of the button or key press that initiates the extend action.
Text and TextField have an XmNpendingDelete resource. This resource controls whether or not text is deleted in certain situations. Consider the following conditions:
Given these conditions, an operation that inserts text (including a transfer of the secondary or clipboard selection) will delete the primary selection before inserting the text. Similarly, an operation that deletes text will delete the primary selection instead of the text that would otherwise be removed. When XmNpendingDelete is False, the insertion and deletion operations do not delete the selection.
Users typically use the mouse to make selections and to initiate and/or complete data transfers. (See the Motif User's Guide for complete details.) The XmDisplay resource XmNenableBtn1Transfer controls the purpose of Btn1 and Btn2 in a Text, TextField, Container, or List widget. For example, when XmNenableBtn1Transfer is set to XmOFF, users press Btn1 to select text and Btn2 to trigger certain kinds of data transfer. (See XmDisplay(3) in the Motif Programmer's Reference for details.)
Users can optionally use the keyboard instead of the mouse to perform selection and transfer operations. All operations available from the mouse, except secondary selection, are available from the keyboard. Text has two keyboard selection modes, Normal Mode and Add Mode.
In Normal Mode, if text is selected, a navigation operation deselects the selected text and moves the anchor to the current position of the insertion cursor before navigating. In Add Mode, navigation operations have no effect other than navigation.
In Normal mode, when the widget contains the primary selection and the insertion cursor is disjoint from it, any operation that inserts or pastes text into the widget (except a transfer of the primary selection from the same widget) first deselects the primary selection. In Add Mode, such an operation does not deselect the primary selection.
The user makes a primary selection with Btn1. Pressing Btn1 deselects any existing selection and moves the insertion cursor and the anchor to the position in the text where the button is pressed. Dragging Btn1 selects all text between the anchor and the pointer position, deselecting any text outside that range. Releasing Btn1 moves the insertion cursor to the position where the button is released. Clicking Btn1 deselects any existing selection and moves the insertion cursor and the anchor to the position where Btn1 is released.
ShiftBtn1 extends a selection using the balance-beam method. When the user presses ShiftBtn1, the selection becomes anchored at the edge of the selection farthest from the pointer position. When the user releases ShiftBtn1, the selection extends from the anchor to the position where ShiftBtn1 is released, and any text outside that range is deselected. The insertion cursor moves to the position where ShiftBtn1 is released.
Clicking CtrlBtn1 moves the insertion cursor to the position where CtrlBtn1 is released without affecting the selection.
Clicking Btn2 moves the insertion cursor to the position where Btn2 is released. Then, unless the insertion cursor is in the midst of the selection, it copies the primary selection to the insertion cursor and moves the insertion cursor to the end of the copied text. The original selection remains selected. Clicking ShiftBtn2 has the same effect except that it moves the primary selection to the insertion cursor, deleting the original selection if possible.
Dragging AltBtn2 outside of the primary selection starts a secondary selection consisting of all text between the position of the pointer and the position where AltBtn2 was pressed. Releasing AltBtn2 copies the secondary selection to the insertion cursor in the destination widget. Before copying the secondary selection, if the destination contains the primary selection and the insertion cursor is not disjoint from it, releasing AltBtn2 deletes the primary selection. Dragging AltShiftBtn2 also makes a secondary selection, and releasing AltShiftBtn2 moves the secondary selection to the destination widget.
Dragging Btn2 with the insertion cursor positioned within a primary selection initiates a drag operation. The user may press a modifier key to indicate whether the drag is a copy, move, or link operation. Releasing Btn2 either in the same Text widget or a different widget moves the insertion cursor to the position where Btn2 is released, drops the selected text at that point, and moves the insertion cursor to the end of the dropped text.
Pressing osfCancel during the operation aborts the operation and no data exchange occurs. If the user presses osfHelp over a drop site, the user has the option to continue or to cancel the drop operation in response to the help information that the application provides.
Selection operations available with the mouse, except secondary selection, are also available from the keyboard. Text has two keyboard selection modes, Normal Mode and Add Mode. In Normal Mode, if text is selected, a navigation operation deselects the selected text and moves the anchor to the current position of the insertion cursor before navigating. In Add Mode, navigation operations have no effect other than navigation. In both modes, pressing osfSelect has the same effect as pressing Btn1 at that position.
In Normal mode, when the widget contains the primary selection and the insertion cursor is disjoint from it, any operation that inserts or pastes text into the widget (except a transfer of the primary selection from the same widget) first deselects the primary selection. In Add Mode, such an operation does not deselect the primary selection.
Pressing osfExtend extends the current selection to the insertion cursor using the balance-beam method. The current selection becomes anchored at the edge of the selection farthest from the insertion cursor. The selection then extends from the anchor to the insertion cursor, and any text outside that range is deselected.
Shifted navigation operations also extend a selection. In Normal Mode, if no text is selected, a shifted navigation operation moves the anchor to the insertion cursor, navigates, selects the navigated text, and deselects any text outside that range. In the remaining cases--Normal Mode and Add Mode with any selection--a shifted navigation operation extends the selection using the balance-beam method. Before navigation, the current selection becomes anchored at the edge of the selection farthest from the insertion cursor. After navigation, the selection extends from the anchor to the insertion cursor, and any text outside that range is deselected.
osfPrimaryCopy copies the primary selection to the insertion cursor. osfPrimaryCut cuts the primary selection to the insertion cursor.
osfCopy copies the current selection in the Text widget to the clipboard; osfCut cuts the selection; and osfPaste inserts the contents of the clipboard at the insertion cursor.