1 <sect2 id="Text_Widget_Actions">
2 <title>Text Widget Actions</title>
5 <!-- .IN "Text widget" "actions" -->
7 <!-- Actions Supported by all Text Widgets -->
9 <!-- .IN "Text widget" "actions" "@DEF@" -->
11 All editing functions are performed by translation manager actions that may
12 be specified through the <function>translations</function> resource in the Text widget.
17 <literallayout class="monospaced">
18 <!-- .TA .5i 2.5i 3i -->
19 <!-- .ta .5i 2.5i 3i -->
20 Insert Point Movement Delete
21 forward-character delete-next-character
22 backward-character delete-previous-character
23 forward-word delete-next-word
24 backward-word delete-previous-word
25 forward-paragraph delete-selection
30 previous-line select-all
31 next-page select-start
32 previous-page select-adjust
33 beginning-of-file select-end
34 end-of-file extend-start
35 scroll-one-line-up extend-adjust
36 scroll-one-line-down extend-end
40 Miscellaneous New Line
41 redraw-display newline-and-indent
42 insert-file newline-and-backup
48 search backward-kill-word
49 multiply kill-selection
50 form-paragraph kill-to-end-of-line
51 transpose-characters kill-paragraph
52 no-op kill-to-end-of-paragraph
60 Most of the actions take no arguments, and unless otherwise noted you
61 may assume this to be the case.
66 <sect3 id='Cursor_Movement_Actions'>
67 <title>Cursor Movement Actions\fP</title>
89 These actions move the insert point forward or backward one character in
90 the buffer. If the insert point is at the end or beginning of a line
91 this action will move the insert point to the next (or previous) line.
112 These actions move the insert point to the next or previous word boundary.
113 A word boundary is defined as a Space, Tab or Carriage Return.
134 These actions move the insert point to the next or previous paragraph boundary.
135 A paragraph boundary is defined as two Carriage Returns in a row with only
136 Spaces or Tabs between them.
157 These actions move to the beginning or end of the current line. If the
158 insert point is already at the end or beginning of the line then no action is taken.
179 These actions move the insert point up or down one line. If the insert
180 point is currently N characters from the beginning of the line then it
181 will be N characters from the beginning of the next or previous line.
182 If N is past the end of the line, the insert point is placed at the end
204 These actions move the insert point up or down one page in the file.
205 One page is defined as the current height of the text widget. The
206 insert point is always placed at the first character of the top line by
228 These actions place the insert point at the beginning or end of the
229 current text buffer. The text widget is then scrolled the minimum
230 amount necessary to make the new insert point location visible.
247 scroll-one-line-down()
251 These actions scroll the current text field up or down by one line.
252 They do not move the insert point. Other than the scrollbars this is
253 the only way that the insert point may be moved off of the visible text
254 area. The widget will be scrolled so that the insert point is back on
255 the screen as soon as some other action is executed.
262 <sect3 id="Delete_Actions">
263 <title>Delete Actions</title>
270 delete-next-character()
281 delete-previous-character()
285 These actions remove the character immediately before or after the
286 insert point. If a Carriage Return is removed then the next line is
287 appended to the end of the current line.
304 delete-previous-word()
308 These actions remove all characters between the insert point location and
309 the next word boundary. A word boundary is defined as a Space, Tab or
320 This action removes all characters in the current selection.
321 The selection can be set with the selection actions.
328 <sect3 id="Selection_Actions">
329 <title>Selection Actions</title>
340 This action selects the word in which the insert point is currently located.
341 If the insert point is between words then it will select the previous word.
351 This action selects the entire text buffer.
361 This action sets the insert point to the current pointer location (if
362 triggered by a button event) or text cursor location (if triggered by
364 will then begin a selection at this location. If many of these
365 selection actions occur quickly in succession then the selection count
366 mechanism will be invoked (see the section titled \fBText Selections for
367 Application Programmers\fP for details). <!-- xref -->
377 This action allows a selection started with the <emphasis remap='I'>select-start</emphasis>
378 action to be modified, as described above.
384 select-end(<emphasis remap='I'>name</emphasis>[,<emphasis remap='I'>name</emphasis>,...])
388 This action ends a text selection that began with the <emphasis remap='I'>select-start</emphasis>
389 action, and asserts ownership of the selection or selections specified.
390 A <emphasis remap='I'>name</emphasis> can be a selection (e.g., <function>PRIMARY</function>) or a cut buffer
391 (e.g., <function>CUT_BUFFER0</function>). Note that case is important. If no
392 <emphasis remap='I'>names</emphasis> are specified, <function>PRIMARY</function> is asserted.
402 This action finds the nearest end of the current selection, and moves it
403 to the current pointer location (if triggered by a button event) or text
404 cursor location (if triggered by a key event).
414 This action allows a selection started with an <emphasis remap='I'>extend-start</emphasis> action
421 extend-end(<emphasis remap='I'>name</emphasis>[,<emphasis remap='I'>name</emphasis>,...])
425 This action ends a text selection that began with the <emphasis remap='I'>extend-start</emphasis>
426 action, and asserts ownership of the selection or selections specified.
427 A <emphasis remap='I'>name</emphasis> can be a selection (e.g. <function>PRIMARY</function>) or a cut buffer
428 (e.g <function>CUT_BUFFER0</function>). Note that case is important. If no names are
429 given, <function>PRIMARY</function> is asserted.
435 insert-selection(<emphasis remap='I'>name</emphasis>[,<emphasis remap='I'>name</emphasis>,...])
439 This action retrieves the value of the first (left-most) named selection
440 that exists or the cut buffer that is not empty and inserts it into the
441 Text widget at the current insert point location. A <emphasis remap='I'>name</emphasis> can be a
442 selection (e.g. <function>PRIMARY</function>) or a cut buffer (e.g <function>CUT_BUFFER0</function>).
443 Note that case is important.
450 <sect3 id="The_New_Line_Actions">
451 <title>The New Line Actions</title>
462 This action inserts a newline into the text and adds spaces to
463 that line to indent it to match the previous line.
473 This action inserts a newline into the text <emphasis remap='I'>after</emphasis> the insert point.
483 This action inserts a newline into the text <emphasis remap='I'>before</emphasis> the insert point.
490 <sect3 id="Kill_and_Actions">
491 <title>Kill and Actions</title>
513 These actions act exactly like the <emphasis remap='I'>delete-next-word</emphasis> and
514 <emphasis remap='I'>delete-previous-word</emphasis> actions, but they stuff the word that was
515 killed into the kill buffer (<function>CUT_BUFFER_1</function>).
525 This action deletes the current selection and stuffs the deleted text into
526 the kill buffer (<function>CUT_BUFFER_1</function>).
532 kill-to-end-of-line()
536 This action deletes the entire line to the right of the insert point position,
537 and stuffs the deleted text into the kill buffer (<function>CUT_BUFFER_1</function>).
547 This action deletes the current paragraph, if between paragraphs it deletes
548 the paragraph above the insert point, and stuffs the deleted text into
549 the kill buffer (<function>CUT_BUFFER_1</function>).
555 kill-to-end-of-paragraph()
559 This action deletes everything between the current insert point location and
560 the next paragraph boundary, and stuffs the deleted text into the kill
561 buffer (<function>CUT_BUFFER_1</function>).
568 <sect3 id="Miscellaneous_Actions">
569 <title>Miscellaneous Actions</title>
580 This action recomputes the location of all the text lines on the
581 display, scrolls the text to vertically center the line containing the insert point
582 on the screen, clears the entire screen, and redisplays it.
588 insert-file([<emphasis remap='I'>filename</emphasis>])
592 This action activates the insert file popup. The <emphasis remap='I'>filename</emphasis>
593 option specifies the default filename to put in the filename buffer of
594 the popup. If no <emphasis remap='I'>filename</emphasis> is specified the buffer is empty
605 This action may only be attached to a key event. When the
606 <function>international</function> resource is <function>false</function>, this action
607 calls XLookupString to translate the event into a (rebindable) Latin-1
608 character (sequence) and inserts it into the text at the
609 insert point. When the <function>international</function> resource is <function>true</function>,
610 characters are passed to the input method via XwcLookupString, and any
611 committed string returned is inserted into the text at the insert point.
617 insert-string(<emphasis remap='I'>string</emphasis>[,<emphasis remap='I'>string</emphasis>,...])
621 This action inserts each <emphasis remap='I'>string</emphasis> into the text
622 at the insert point location. Any <emphasis remap='I'>string</emphasis>
623 beginning with the characters "0x" followed by an even
624 number of hexadecimal digits is
625 interpreted as a hexadecimal constant and the
626 corresponding string is inserted instead. This
627 hexadecimal string may represent up to 50 8-bit characters.
628 When the<function>international</function> resource is
629 <function>true</function>, a hexadecimal string is intrepeted as
630 being in a multi-byte encoding, and a hexadecimal
631 or regular string will result in an error message
632 if it is not legal in the current locale.
638 display-caret(<emphasis remap='I'>state</emphasis>,<emphasis remap='I'>when</emphasis>)
642 This action allows the insert point to be turned on and off.
643 The <emphasis remap='I'>state</emphasis> argument specifies the desired state of the insert point.
644 This value may be any of the string
645 values accepted for Boolean resources (e.g. <function>on</function>, <function>True</function>,
646 <function>off</function>, <function>False</function>, etc.). If no arguments are specified, the
647 default value is <function>True</function>.
648 The <emphasis remap='I'>when</emphasis> argument specifies, for <function>EnterNotify</function> or <function>LeaveNotify</function>
649 events whether or not the focus field in the event is to be examined.
650 If the second argument is not specified, or specified as something other
651 than <function>always</function> then if the action is bound to an <function>EnterNotify</function>
652 or <function>LeaveNotify</function> event, the action will be taken only if the focus
653 field is <function>True</function>. An augmented binding that might be useful is:
661 <literallayout class="monospaced">
662 <!-- .TA 2.0i 2.5i 4.0i -->
663 <!-- .ta 2.0i 2.5i 4.0i -->
664 *Text.Translations: #override \\
665 <FocusIn>: display-caret(on) \\n\\
666 <FocusOut>: display-caret(off)
686 These actions do not currently do anything.
692 search(<emphasis remap='I'>direction</emphasis>,[<emphasis remap='I'>string</emphasis>])
696 This action activates the search popup. The <emphasis remap='I'>direction</emphasis> must be
697 specified as either <function>forward</function> or <function>backward</function>. The string is
698 optional and is used as an initial value for the <emphasis remap='I'>Search for</emphasis>: string.
699 For further explanation of the search widget see the section on
700 <function>Text Searches</function>.
706 multiply(<emphasis remap='I'>value</emphasis>)
710 The multiply action allows the user to multiply the effects of many of
711 the text actions. Thus the following action sequence
712 <emphasis remap='I'>multiply(10) delete-next-word()</emphasis> will delete 10 words. It does not
713 matter whether these actions take place in one event or many events.
714 Using the default translations the key sequence \fIControl-u,
715 Control-d\fP will delete 4 characters.
716 Multiply actions can be chained, thus \fImultiply(5)
717 multiply(5)\fP is the same as <emphasis remap='I'>multiply(25)</emphasis>. If the string
718 <function>reset</function> is passed to the multiply action the effects of all previous
719 multiplies are removed and a beep is sent to the display.
729 This action removes all the Carriage Returns from the current
730 paragraph and reinserts them so that each line is as long as possible, while
731 still fitting on the current screen. Lines are broken at word boundaries if
732 at all possible. This action currently works only on Text widgets
739 transpose-characters()
743 This action will swap the position of the character to the left of the
744 insert point with the character to the right of the insert point. The insert point will then
745 be advanced one character.
751 no-op([<emphasis remap='I'>action</emphasis>])
755 The no-op action makes no change to the text widget, and is mainly used
756 to override translations. This action takes one optional argument. If
757 this argument is <emphasis remap='I'>RingBell</emphasis> then a beep is sent to the display.
763 XawWMProtocols([<emphasis remap='I'>wm_protocol_name</emphasis>])
767 <!-- .IN "XawWMProtocols" -->
769 This action is written specifically for the file insertion and the search
771 dialog boxes. This action is attached to those shells by the Text widget,
772 in order to handle ClientMessage events with the WM_PROTOCOLS atom in the
773 detail field. This action supports WM_DELETE_WINDOW on the Text widget
774 popups, and may support other window manager protocols if necessary in
775 the future. The popup will be dismissed if the window manager sends
776 a WM_DELETE_WINDOW request and there are no parameters in the action
777 call, which is the default. The popup will also be dismissed if the
778 parameters include the string ``wm_delete_window,'' and the event is a
779 ClientMessage event requesting dismissal or is not a ClientMessage event.
780 This action is not sensitive to the case of the strings passed as parameters.
790 <!-- .IN "Input Method" -->
791 When the <function>international</function> resource is <function>true</function>,
792 input is usually passed to an input method, a separate
793 process, for composing. Sometimes the connection to
794 this process gets severed; this action will attempt to
795 reconnect it. Causes for severage include network
796 trouble, and the user explicitly killing one input
797 method and starting a new one. This action may also
798 establish first connection when the application is
799 started before the input method.
806 <sect3 id="Text_Selections_for_Application_Programmers">
807 <title>Text Selections for Application Programmers</title>
808 <!-- .IN "Text widget" "Text Selections for Application Programmers" -->
811 The default behavior of the text selection array is described in the
812 section called <function>Text Selections for Users</function>. To modify the selections
813 a programmer must construct a <function>XawTextSelectType</function> array (called the
814 selection array), containing the selections desired, and pass this as
815 the new value for the <function>selectionTypes</function> resource. The selection
816 array may also be modified using the <xref linkend='XawTextSetSelectionArray' xrefstyle='select: title'/>
817 <!-- .IN "XawTextSetSelectionArray" "" -->
818 function. All selection arrays must end with the value
819 <function>XawselectNull</function>. The <function>selectionTypes</function> resource has no converter
820 registered and cannot be modified through the resource manager.
824 The array contains a list of entries that will be called when the user
825 attempts to select text in rapid succession with the <emphasis remap='I'>select-start</emphasis>
826 action (usually by clicking a pointer button). The first entry in the
827 selection array will be used when the <emphasis remap='I'>select-start</emphasis> action is
828 initially called. The next entry will be used when <emphasis remap='I'>select-start</emphasis>
829 is called again, and so on. If a timeout value (1/10 of a second) is
830 exceeded, the the next <emphasis remap='I'>select-start</emphasis> action will begin at the top
831 of the selection array. When <function>XawselectNull</function> is reached the array
832 is recycled beginning with the first element.
835 <tgroup cols='2' align='center'>
836 <colspec colname='c1'/>
837 <colspec colname='c2'/>
840 <entry><function>XawselectAll</function></entry>
841 <entry>Selects the contents of the entire buffer.</entry>
844 <entry><function>XawselectChar</function></entry>
845 <entry>Selects text characters as the pointer moves over them.</entry>
848 <entry><function>XawselectLine</function></entry>
849 <entry>Selects the entire line.</entry>
852 <entry><function>XawselectNull</function></entry>
853 <entry>Indicates the end of the selection array.</entry>
856 <entry><function>XawselectParagraph</function></entry>
857 <entry>Selects the entire paragraph.</entry>
860 <entry><function>XawselectPosition</function></entry>
861 <entry>Selects the current pointer position.</entry>
864 <entry><function>XawselectWord</function></entry>
865 <entry>Selects whole words as the pointer moves onto them.</entry>
873 The default selectType array is:
878 <literallayout class="monospaced">
879 {XawselectPosition, XawselectWord, XawselectLine, XawselectParagraph, XawselectAll, XawselectNull}
885 The selection array is not copied by the text widgets. The
886 application must allocate space for the array and cannot deallocate or
887 change it until the text widget is destroyed or until a new selection
892 <sect2 id="Default_Translation_Bindings">
893 <title>Default Translation Bindings</title>
897 <!-- Default Translation Bindings -->
899 <!-- .IN "Text widget" "default translations" -->
900 The following translations are defaults built into every Text widget.
901 They can be overridden, or replaced by specifying a new value for the
902 Text widget's <function>translations</function> resource.
907 <literallayout class="monospaced">
908 <!-- .TA .5i 2.5i -->
909 <!-- .ta .5i 2.5i -->
910 Ctrl<Key>A: beginning-of-line() \\n\\
911 Ctrl<Key>B: backward-character() \\n\\
912 Ctrl<Key>D: delete-next-character() \\n\\
913 Ctrl<Key>E: end-of-line() \\n\\
914 Ctrl<Key>F: forward-character() \\n\\
915 Ctrl<Key>G: multiply(Reset) \\n\\
916 Ctrl<Key>H: delete-previous-character() \\n\\
917 Ctrl<Key>J: newline-and-indent() \\n\\
918 Ctrl<Key>K: kill-to-end-of-line() \\n\\
919 Ctrl<Key>L: redraw-display() \\n\\
920 Ctrl<Key>M: newline() \\n\\
921 Ctrl<Key>N: next-line() \\n\\
922 Ctrl<Key>O: newline-and-backup() \\n\\
923 Ctrl<Key>P: previous-line() \\n\\
924 Ctrl<Key>R: search(backward) \\n\\
925 Ctrl<Key>S: search(forward) \\n\\
926 Ctrl<Key>T: transpose-characters() \\n\\
927 Ctrl<Key>U: multiply(4) \\n\\
928 Ctrl<Key>V: next-page() \\n\\
929 Ctrl<Key>W: kill-selection() \\n\\
930 Ctrl<Key>Y: insert-selection(CUT_BUFFER1) \\n\\
931 Ctrl<Key>Z: scroll-one-line-up() \\n\\
932 Ctrl<Key>\\: reconnect-im() \\n\\
933 Meta<Key>B: backward-word() \\n\\
934 Meta<Key>F: forward-word() \\n\\
935 Meta<Key>I: insert-file() \\n\\
936 Meta<Key>K: kill-to-end-of-paragraph() \\n\\
937 Meta<Key>Q: form-paragraph() \\n\\
938 Meta<Key>V: previous-page() \\n\\
939 Meta<Key>Y: insert-selection(PRIMARY, CUT_BUFFER0) \\n\\
940 Meta<Key>Z: scroll-one-line-down() \\n\\
941 :Meta<Key>d: delete-next-word() \\n\\
942 :Meta<Key>D: kill-word() \\n\\
943 :Meta<Key>h: delete-previous-word() \\n\\
944 :Meta<Key>H: backward-kill-word() \\n\\
945 :Meta<Key>\\<: beginning-of-file() \\n\\
946 :Meta<Key>\\>: end-of-file() \\n\\
947 :Meta<Key>]: forward-paragraph() \\n\\
948 :Meta<Key>[: backward-paragraph() \\n\\
949 ~Shift Meta<Key>Delete: delete-previous-word() \\n\\
950 \ Shift Meta<Key>Delete: backward-kill-word() \\n\\
951 ~Shift Meta<Key>Backspace: delete-previous-word() \\n\\
952 \ Shift Meta<Key>Backspace: backward-kill-word() \\n\\
953 <Key>Right: forward-character() \\n\\
954 <Key>Left: backward-character() \\n\\
955 <Key>Down: next-line() \\n\\
956 <Key>Up: previous-line() \\n\\
957 <Key>Delete: delete-previous-character() \\n\\
958 <Key>BackSpace: delete-previous-character() \\n\\
959 <Key>Linefeed: newline-and-indent() \\n\\
960 <Key>Return: newline() \\n\\
961 <Key>: insert-char() \\n\\
962 <Key>Kanji: reconnect-im() \\n\\
963 <FocusIn>: focus-in() \\n\\
964 <FocusOut>: focus-out() \\n\\
965 <Btn1Down>: select-start() \\n\\
966 <Btn1Motion>: extend-adjust() \\n\\
967 <Btn1Up>: extend-end(PRIMARY, CUT_BUFFER0) \\n\\
968 <Btn2Down>: insert-selection(PRIMARY, CUT_BUFFER0) \\n\\
969 <Btn3Down>: extend-start() \\n\\
970 <Btn3Motion>: extend-adjust() \\n\\
971 <Btn3Up>: extend-end(PRIMARY, CUT_BUFFER0) \\n
projects / framework / uifw / xorg / lib / libxaw.git / blob