[Contents]
[Index]
[Next]
[Previous]
XmText
NAME
XmText - The Text widget class
SYNOPSIS
#include <Xm/Text.h>
DESCRIPTION
Text provides a single-line and multiline text editor for
customizing both user and programmatic interfaces. It can be used for
single-line string entry, forms entry with verification procedures,
and full-window editing. It provides an application with a consistent
editing system for textual data. The screen's textual data adjusts to
the application writer's needs.
Text provides separate callback lists to verify movement of the
insert cursor, modification of the text, and changes in input
focus. Each of these callbacks provides the verification function with
the widget instance, the event that caused the callback, and a data
structure specific to the verification type. From this information the
function can verify if the application considers this to be a
legitimate state change and can signal the widget whether to continue
with the action.
The user interface tailors a new set of translations. The default
translations provide key bindings for insert cursor movement,
deletion, insertion, and selection of text.
Text allows the user to select regions of text. Selection is based
on the model specified in the Inter-Client Communication
Conventions Manual (ICCCM). Text supports primary and secondary
selection.
Mouse Selection
The Text widget allows text to be edited, inserted, and selected.
The user can cut, copy, and paste text using the clipboard, primary
transfer, or secondary transfer. Text also provides a Drag and Drop
facility that enables the user to copy or move data within Text or to
a different widget. When keyboard focus policy is set to EXPLICIT,
the widget that receives focus is the destination widget. In POINTER
mode, any keyboard or mouse operation (except secondary selection) in
an editable widget establishes that widget as the destination.
If a destination widget becomes insensitive or uneditable, it
forfeits its destination status. In EXPLICIT mode, when a widget
becomes insensitive, the focus moves to another widget. If that widget
is editable, it becomes the destination widget; otherwise, there is no
destination widget. The text of any insensitive Text widget is
stippled, indicating its state to the user.
The insertion cursor, displayed as an I-beam, shows where input is
inserted. Input is inserted just before the insertion cursor.
Classes
Text inherits behavior and resources from Core and Primitive
classes.
The class pointer is xmTextWidgetClass.
The class name is XmText.
New Resources
The following table defines a set of widget resources used by the
programmer to specify data. The programmer can also set the resource
values for the inherited classes to set attributes for this widget. To
reference a resource by name or by class in a .Xdefaults
file, remove the XmN or XmC prefix
and use the remaining letters. To specify one of the defined values
for a resource in a .Xdefaults file, remove the
Xm prefix and use the remaining letters (in either
lowercase or uppercase, but include any underscores between words).
The codes in the access column indicate if the given resource can be
set at creation time (C), set by using XtSetValues
(S), retrieved by using XtGetValues (G), or is not
applicable (N/A).
- XmNactivateCallback
- Specifies the list of callbacks that is called when the user
invokes an event that calls the Activate() function.
The type of the structure whose address is passed to this callback is
XmAnyCallbackStruct. The reason sent by the callback
is XmCR_ACTIVATE.
- XmNautoShowCursorPosition
- Ensures that the visible text contains the insert cursor when
set to True. If the insert cursor changes, the contents of Text may
scroll in order to bring the insertion point into the window.
- XmNcursorPosition
- Indicates the position in the text where the current insert
cursor is to be located. Position is determined by the number of
characters from the beginning of the text. The first character
position is 0.
- XmNeditable
- Indicates that the user can edit the text string when set to
True. Prohibits the user from editing the text when set to False.
- XmNeditMode
- Specifies the set of keyboard bindings used in Text. The
default keyboard bindings (XmSINGLE_LINE_EDIT)
provides the set of key bindings to be used in editing single-line
text. The multiline bindings (XmMULTI_LINE_EDIT)
provides the set of key bindings to be used in editing multiline text.
The results of placing a Text widget inside a ScrolledWindow when
the Text's XmNeditMode is
XmSINGLE_LINE_EDIT are undefined.
- XmNfocusCallback
- Specifies the list of callbacks called when Text accepts input
focus. The type of the structure whose address is passed to this
callback is XmAnyCallbackStruct. The reason sent by
the callback is XmCR_FOCUS.
- XmNgainPrimaryCallback
- Specifies the list of callbacks called when an event causes the
Text widget to gain ownership of the primary selection. The reason
sent by the callback is XmCR_GAIN_PRIMARY.
- XmNlosePrimaryCallback
- Specifies the list of callbacks called when an event causes the
Text widget to lose ownership of the primary selection. The reason
sent by the callback is XmCR_LOSE_PRIMARY.
- XmNlosingFocusCallback
- Specifies the list of callbacks called before Text loses input
focus. The type of the structure whose address is passed to this
callback is XmTextVerifyCallbackStruct. The reason
sent by the callback is XmCR_LOSING_FOCUS.
- XmNmarginHeight
- Specifies the distance between the top edge of the widget
window and the text, and between the bottom edge of the widget window
and the text.
- XmNmarginWidth
- Specifies the distance between the left edge of the widget
window and the text, and between the right edge of the widget window
and the text.
- XmNmaxLength
- Specifies the maximum length of the text string that can be
entered into text from the keyboard. This value must be non-negative.
Strings that are entered using the XmNvalue resource
or the XmTextSetString function
ignore this resource.
- XmNmodifyVerifyCallback
- Specifies the list of callbacks called before text is deleted
from or inserted into Text. The type of the structure whose address
is passed to this callback is
XmTextVerifyCallbackStruct. The reason sent by the
callback is XmCR_MODIFYING_TEXT_VALUE. When multiple
Text widgets share the same source, only the widget that initiates the
source change will generate the
XmNmodifyVerifyCallback.
If both XmNmodifyVerifyCallback and XmNmodifyVerifyCallbackWcs
are registered callback lists, the procedure(s) in the
XmNmodifyVerifyCallback list are always executed
first; and the resulting data, which may have been modified, is passed
to the XmNmodifyVerifyCallbackWcs
callback routines.
- XmNmodifyVerifyCallbackWcs
- Specifies the list of callbacks called before text is deleted
from or inserted into Text. The type of the structure whose address is
passed to this callback is
XmTextVerifyCallbackStructWcs. The reason sent by the
callback is XmCR_MODIFYING_TEXT_VALUE. When multiple
Text widgets share the same source, only the widget that initiates the
source change will generate the
XmNmodifyVerifyCallbackWcs.
If both XmNmodifyVerifyCallback
and XmNmodifyVerifyCallbackWcs are registered
callback lists, the procedure(s) in the XmNmodifyVerifyCallback
list are always executed first; and the resulting data, which may have
been modified, is passed to the
XmNmodifyVerifyCallbackWcs callback routines.
- XmNmotionVerifyCallback
- Specifies the list of callbacks called before the insert cursor
is moved to a new position. The type of the structure whose address
is passed to this callback is
XmTextVerifyCallbackStruct. The reason sent by the
callback is XmCR_MOVING_INSERT_CURSOR. It is
possible for more than one XmNmotionVerifyCallbacks
to be generated from a single action.
- XmNsource
- Specifies the source with which the widget displays text. If
no source is specified, the widget creates a default string source.
This resource can be used to share text sources between Text widgets.
- XmNtopCharacter
- Displays the position of text at the top of the window.
Position is determined by the number of characters from the beginning
of the text. The first character position is 0.
If the XmNeditMode is
XmMULTI_LINE_EDIT, the line of text that contains the
top character is displayed at the top of the widget without shifting
the text left or right. XtGetValues for
XmNtopCharacter returns the position of the first
character in the line that is displayed at the top of the widget.
- XmNvalue
- Specifies the string value of the Text widget as a
char* data value. XmNvalue and
XmNvalueWcs are both
defined, the value of XmNvalueWcs supersedes that of
XmNvalue. XtGetValues returns a copy
of the value of the internal buffer and XtSetValues
copies the string values into the internal buffer.
- XmNvalueChangedCallback
- Specifies the list of callbacks called after text is deleted
from or inserted into Text. The type of the structure whose address
is passed to this callback is XmAnyCallbackStruct.
The reason sent by the callback is
XmCR_VALUE_CHANGED. When multiple Text widgets share
the same source, only the widget that initiates the source change will
generate the XmNvalueChangedCallback. This callback
represents a change in the source in the Text, not in the Text
widget. The XmNvalueChangedCallback should occur only
in pairs with a XmNmodifyVerifyCallback,
assuming that the doit flag in the callback structure of the
XmNmodifyVerifyCallback
is not set to False.
- XmNvalueWcs
- Specifies the string value of the Text widget as a
wchar_t* data value. This resource cannot be
specified in a resource file.
If XmNvalue and
XmNvalueWcs are both defined, the value of
XmNvalueWcs supersedes that of XmNvalue. XtGetValues
returns a copy of the value of the internal buffer encoded as a wide
character string. XtSetValues copies the value of the
wide character string into the internal buffer.
- XmNverifyBell
- Specifies whether the bell should sound when the verification
returns without continuing the action. The default depends on the
value of the ancestor VendorShell's
XmNaudibleWarning
resource.
- XmNpendingDelete
- Indicates that pending delete mode is on when the Boolean value
is True. Pending deletion is defined as deletion of the selected text
when an insertion is made.
- XmNselectionArray
- Defines the actions for multiple mouse clicks. The value of
the resource is an array of XmTextScanType elements.
XmTextScanType is an enumeration indicating possible
actions. Each mouse click performed within half a second of the
previous mouse click increments the index into this array and performs
the defined action for that index. The possible actions in the order
they occur in the default array are:
- XmSELECT_POSITION - resets the insert cursor position
- XmSELECT_WORD - selects a word
- XmSELECT_LINE - selects a line of text
- XmSELECT_ALL - selects all of the text
- XmNselectionArrayCount
- Indicates the number of elements in the
XmNselectionArray resource. The value must not be
negative.
- XmNselectThreshold
- Specifies the number of pixels of motion that is required to
select the next character when selection is performed using the
click-drag mode of selection. The value must not be negative.
- XmNblinkRate
- Specifies the blink rate of the text cursor in milliseconds.
The time indicated in the blink rate relates to the time the cursor is
visible and the time the cursor is invisible (that is, the time it
takes to blink the insertion cursor on and off is twice the blink
rate). The cursor does not blink when the blink rate is set to zero.
The value must not be negative.
- XmNcolumns
- Specifies the initial width of the text window as an integer
number of characters. The width equals the number of characters
specified by this resource multiplied by the maximum character width
of the associated font. For proportionate fonts, the actual number of
characters that fit on a given line may be greater than the value
specified. The value must be greater than 0. The default value
depends on the value of the XmNwidth resource. If no
width is specified the default is 20.
- XmNcursorPositionVisible
-
Indicates that the insert cursor position is marked by a blinking text
cursor when the Boolean value is True.
- XmNfontList
- Specifies the font list to be used for Text. If this value is
NULL at initialization, the font list is initialized by looking up the
parent hierarchy of the widget for an ancestor that is a subclass of
the XmBulletinBoard or VendorShell widget class. If such an
ancestor is found, the font list is initialized to the XmNtextFontList
of the ancestor widget. If no such ancestor is found, the default is
implementation dependent.
Text searches the font list for the first occurrence of a font set
that has a XmFONTLIST_DEFAULT_TAG. If a default
element is not found, the first font set in the font list is used. If
the list contains no font sets, the first font in the font list will
be used. Refer to XmFontList(3X) for more
information on a font list structure.
- XmNresizeHeight
- Indicates that Text attempts to resize its height to
accommodate all the text contained in the widget when the Boolean
value is True. If the Boolean value is set to True, the text is always
displayed starting from the first position in the source, even if
instructed otherwise. This attribute is ignored when the application
uses a ScrolledText widget and when XmNscrollVertical
is True.
- XmNresizeWidth
- Indicates that Text attempts to resize its width to accommodate
all the text contained in the widget when the Boolean value is True.
This attribute is ignored if XmNwordWrap is True.
- XmNrows
- Specifies the initial height of the text window measured in
character heights. This attribute is ignored if the text widget
resource XmNeditMode is
XmSINGLE_LINE_EDIT. The value must be greater than
0. The default value depends on the value of the XmNheight resource. If no
height is specified the default is 1.
- XmNwordWrap
- Indicates that lines are to be broken at word breaks (that is,
the text does not go off the right edge of the window) when the
Boolean value is True. Words are defined as a sequence of characters
separated by white space. White space is defined as a space, tab, or
newline. This attribute is ignored if the text widget resource
XmNeditMode is XmSINGLE_LINE_EDIT.
The following resources are used only when text is created in a
ScrolledWindow. See the man page for XmCreateScrolledText.
- XmNscrollHorizontal
- Adds a ScrollBar that allows the user to scroll horizontally
through text when the Boolean value is True. This resource is forced
to False when the Text widget is placed in a ScrolledWindow with
XmNscrollingPolicy
set to XmAUTOMATIC.
- XmNscrollLeftSide
- Indicates that the vertical ScrollBar should be placed on the
left side of the scrolled text window when the Boolean value is
True. This attribute is ignored if XmNscrollVertical is False or
the Text resource XmNeditMode is
XmSINGLE_LINE_EDIT. The default value may depend on
the value of the XmNstringDirection
resource.
- XmNscrollTopSide
- Indicates that the horizontal ScrollBar should be placed on the
top side of the scrolled text window when the Boolean value is True.
- XmNscrollVertical
- Adds a ScrollBar that allows the user to scroll vertically
through text when the Boolean value is True. This attribute is
ignored if the Text resource XmNeditMode is
XmSINGLE_LINE_EDIT. This resource is forced to False
when the Text widget is placed in a ScrolledWindow with XmNscrollingPolicy
set to XmAUTOMATIC.
Inherited Resources
Text inherits behavior and resources from the following
superclasses. For a complete description of each resource, refer to
the man page for that superclass.
Callback Information
A pointer to the following structure is passed to each callback:
typedef struct
{
int reason;
XEvent * event;
} XmAnyCallbackStruct;
- reason
- Indicates why the callback was invoked
- event
- Points to the XEvent that triggered the
callback
The Text widget defines a new callback structure for use with
verification callbacks. Note that not all fields are relevant for
every callback reason. The application must first look at the
reason field and use only the structure members that are
valid for the particular reason. The values startPos,
endPos, and text in the callback structure
XmTextVerifyCallbackStruct may be modified upon
receiving the callback, and these changes will be reflected as the
change made to the source of the Text widget. (For example, all
keystrokes can be converted to spaces or NULL characters when a
password is entered into a Text widget.) The application programmer
should not overwrite the text field, but should attach data
to that pointer.
A pointer to the following structure is passed to callbacks for
XmNlosingFocusCallback,
XmNmodifyVerifyCallback, and
XmNmotionVerifyCallback.
typedef struct
{
int reason;
XEvent * event;
Boolean doit;
XmTextPosition currInsert, newInsert;
XmTextPosition startPos, endPos;
XmTextBlock text;
} XmTextVerifyCallbackStruct, *XmTextVerifyPtr;
- reason
- Indicates why the callback was invoked.
- event
- Points to the XEvent that triggered the
callback. It can be NULL. For example, changes made to the Text
widget programmatically do not have an event that can be passed to the
associated callback.
- doit
- Indicates whether the action that invoked the callback is
performed. Setting doit to False negates the action.
- currInsert
- Indicates the current position of the insert cursor.
- newInsert
- Indicates the position at which the user attempts to position
the insert cursor.
- startPos
- Indicates the starting position of the text to modify. If the
callback is not a modify verification callback, this value is the same
as currInsert.
- endPos
- Indicates the ending position of the text to modify. If no text
is replaced or deleted, the value is the same as startPos. If
the callback is not a modify verification callback, this value is the
same as currInsert.
- text
- Points to a structure of type
XmTextBlockRec. This structure holds the textual
information to be inserted.
typedef struct
{
char *ptr;
int length;
XmTextFormat format;
} XmTextBlockRec, *XmTextBlock;
- ptr
- Points to the text to be inserted.
- length
- Specifies the length of the text to be inserted.
- format
- Specifies the format of the text, either
XmFMT_8_BIT or XmFMT_16_BIT.
A pointer to the following structure is passed to callbacks for
XmNmodifyVerifyCallbackWcs.
typedef struct
{
int reason;
XEvent *event;
Boolean doit;
XmTextPosition currInsert, newInsert;
XmTextPosition startPos, endPos;
XmTextBlockWcs text;
} XmTextVerifyCallbackStructWcs, *XmTextVerifyPtrWcs;
- reason
- Indicates why the callback was invoked.
- event
- Points to the XEvent that triggered the
callback. It can be NULL. For example, changes made to the Text
widget programmatically do not have an event that can be passed to the
associated callback.
- doit
- Indicates whether the action that invoked the callback is
performed. Setting doit to False negates the action.
- currInsert
- Indicates the current position of the insert cursor.
- newInsert
- Indicates the position at which the user attempts to position
the insert cursor.
- startPos
- Indicates the starting position of the text to modify. If the
callback is not a modify verification callback, this value is the same
as currInsert.
- endPos
- Indicates the ending position of the text to modify. If no text
is replaced or deleted, the value is the same as startPos. If
the callback is not a modify verification callback, this value is the
same as currInsert.
- text
- Points to a structure of type
XmTextBlockRecWcs. This structure holds the textual
information to be inserted.
typedef struct
{
wchar_t *wcsptr;
int length;
} XmTextBlockRecWcs, *XmTextBlockWcs;
- wcsptr
- Points to the wide character text to be inserted.
- length
- Specifies the number of characters to be inserted.
The following table describes the reasons why the individual
verification callback structure fields are valid:
Reason Valid Fields
XmCR_LOSING_FOCUS reason, event, doit, currInsert, newInsert, startPos, endPos
XmCR_MODIFYING_TEXT_VALUE reason, event, doit, currInsert, newInsert, startPos, endPos, text
XmCR_MOVING_INSERT_CURSOR reason, event, doit, currInsert, newInsert
Translations
XmText includes translations from XmPrimitive. The XmText translations
are listed below. These translations may not directly correspond to a
translation table. The actions represent the effective behavior of
the associated events, and they may differ in a right-to-left language
environment.
BSelect Press: grab-focus()
BSelect Motion: extend-adjust()
BSelect Release: extend-end()
BExtend Press: extend-start()
BExtend Motion: extend-adjust()
BExtend Release: extend-end()
BToggle Press: move-destination()
BDrag Press: process-bdrag()
BDrag Motion: secondary-adjust()
BDrag Release: copy-to()
MCtrl BDrag Press: process-bdrag()
MCtrl BDrag Motion: secondary-adjust()
MCtrl BDrag Release: copy-to()
MAlt BDrag Press: process-bdrag()
MAlt BDrag Motion: secondary-adjust()
MAlt BDrag Release: copy-to()
MShift BDrag Press: process-bdrag()
MShift BDrag Motion: secondary-adjust()
MShift BDrag Release: move-to()
MAlt MCtrl BDrag Release: copy-to()
MAlt MShift BDrag Release: move-to()
KUp: process-up()
MShift KUp: process-shift-up()
MCtrl KUp: backward-paragraph()
MShift MCtrl KUp: backward-paragraph(extend)
KDown: process-down()
MShift KDown: process-shift-down()
MCtrl KDown: forward-paragraph()
MShift MCtrl KDown: forward-paragraph(extend)
KLeft: backward-character()
MShift KLeft: key-select(left)
MCtrl KLeft: backward-word()
MShift MCtrl KLeft: backward-word(extend)
KRight: forward-character()
MShift KRight: key-select(right)
MCtrl KRight: forward-word()
MShift MCtrl KRight: forward-word(extend)
KPageUp: previous-page()
MShift KPageUp: previous-page(extend)
KPageDown: next-page()
MShift KPageDown: next-page(extend)
KPageLeft: page-left()
KPageRight: page-right()
KBeginLine: beginning-of-line()
MShift KBeginLine: beginning-of-line(extend)
KEndLine: end-of-line()
MShift KEndLine: end-of-line(extend)
KBeginData: beginning-of-file()
MShift KBeginData: beginning-of-file(extend)
KEndData: end-of-file()
MShift KEndData: end-of-file(extend)
KTab: process-tab()
KNextField: next-tab-group()
KPrevField: prev-tab-group()
KEnter: process-return()
KActivate: activate()
KDelete: delete-next-character()
KBackSpace: delete-previous-character()
KAddMode: toggle-add-mode()
KSpace: self-insert()
MShift KSpace: self-insert()
KSelect: set-anchor()
KExtend: key-select()
MAny KCancel: process-cancel()
KClear: clear-selection()
KSelectAll: select-all()
KDeselectAll: deselect-all()
KCut: cut-clipboard()
KCopy: copy-clipboard()
KPaste: paste-clipboard()
KPrimaryCut: cut-primary()
KPrimaryCopy: copy-primary()
KPrimaryPaste: copy-primary()
KHelp: Help()
KAny: self-insert()
Action Routines
The XmText action routines are described below:
- activate():
- Calls the callbacks for XmNactivateCallback.
If the parent is a manager, passes the event to the parent.
- backward-character():
- Moves the insertion cursor one character to the left. For
other effects, see the description of navigation operations in the
"Keyboard Selection" section. This action may have different behavior
in a right-to-left language environment.
- backward-paragraph(extend):
- If XmNeditMode is
XmMULTI_LINE_EDIT and this action is called with no
argument, moves the insertion cursor to the first non-whitespace
character following the first previous blank line or beginning of the
text. If the insertion cursor is already at the beginning of a
paragraph, moves the insertion cursor to the beginning of the previous
paragraph. For other effects, see the description of navigation
operations in the "Keyboard Selection" section.
If XmNeditMode is
XmMULTI_LINE_EDIT and this action is called with an
argument of extend, moves the insertion cursor as in
the case of no argument and extends the current selection. For other
effects, see the description of shifted navigation operations in the
"Keyboard Selection" section.
- backward-word(extend):
- If this action is called with no argument, moves the insertion
cursor to the first non-whitespace character after the first
whitespace character to the left or after the beginning of the line.
If the insertion cursor is already at the beginning of a word, moves
the insertion cursor to the beginning of the previous word. For other
effects, see the description of navigation operations in the "Keyboard
Selection" section. This action may have different behavior in a
locale other than the C locale.
If called with an argument of extend, moves the
insertion cursor as in the case of no argument and extends the current
selection. For other effects, see the description of shifted
navigation operations in the "Keyboard Selection" section.
- beep():
- Causes the terminal to beep.
- beginning-of-file(extend):
- If this action is called with no argument, moves the insertion
cursor to the beginning of the text. For other effects, see the
description of navigation operations in the "Keyboard Selection"
section.
If called with an argument of extend, moves the
insertion cursor as in the case of no argument and extends the current
selection. For other effects, see the description of shifted
navigation operations in the "Keyboard Selection" section.
- beginning-of-line(extend):
- If this action is called with no argument, moves the insertion
cursor to the beginning of the line. For other effects, see the
description of navigation operations in the "Keyboard Selection"
section.
If called with an argument of extend, moves the
insertion cursor as in the case of no argument and extends the current
selection. For other effects, see the description of shifted
navigation operations in the "Keyboard Selection" section.
- clear-selection():
- Clears the current selection by replacing each character except
<Return> with a <Space> character.
- copy-clipboard():
- Copies the current selection to the clipboard.
- copy-primary():
- Copies the primary selection to just before the insertion
cursor.
- copy-to():
- If a secondary selection exists, copies the secondary selection
to just before the insertion cursor. If no secondary selection
exists, copies the primary selection to the pointer location.
- cut-clipboard():
- Cuts the current selection to the clipboard.
- cut-primary():
- Cuts the primary selection to just before the insertion cursor.
- delete-next-character():
- In normal mode if there is a non-null selection, deletes the
selection, otherwise deletes the character following the insertion
cursor. In add mode if there is a non-null selection, the cursor is
not disjoint from the selection and XmNpendingDelete
is set to True, deletes the selection, otherwise deletes the character
following the insertion cursor. This may impact the selection.
- delete-next-word():
- In normal mode if there is a non-null selection, deletes the
selection, otherwise deletes the characters following the insertion
cursor to the next space, tab or end of line character. In add mode
if there is a non-null selection, the cursor is not disjoint from the
selection and XmNpendingDelete is set to True,
deletes the selection, otherwise deletes the characters following the
insertion cursor to the next space, tab or end of line character.
This may impact the selection. This action may have different
behavior in a locale other than the C locale.
- delete-previous-character():
- In normal mode if there is a non-null selection, deletes the
selection, otherwise deletes the character of text immediately
preceding the insertion cursor. In add mode if there is a non-null
selection, the cursor is not disjoint from the selection and
XmNpendingDelete is set to True, deletes the
selection, otherwise deletes the character of text immediately
preceding the insertion cursor. This may impact the selection.
- delete-previous-word():
- In normal mode if there is a non-null selection, deletes the
selection, otherwise deletes the characters preceding the insertion
cursor to the next space, tab or beginning of the line character. In
add mode if there is a non-null selection, the cursor is not disjoint
from the selection and XmNpendingDelete is set to
True, deletes the selection, otherwise deletes the characters
preceding the insertion cursor to the next space, tab or beginning of
line character.. This may impact the selection. This action may have
different behavior in a locale other than the C locale.
- delete-selection():
- Deletes the current selection.
- delete-to-end-of-line():
- In normal mode if there is a non-null selection, deletes the
selection, otherwise deletes the characters following the insertion
cursor to the next end of line character. In add mode if there is a
non-null selection, the cursor is not disjoint from the selection and
XmNpendingDelete is set to True, deletes the
selection, otherwise deletes the characters following the insertion
cursor to the next end of line character. This may impact the
selection.
- delete-to-start-of-line():
- In normal mode if there is a non-null selection, deletes the
selection, otherwise deletes the characters preceding the insertion
cursor to the previous beginning of line character. In add mode if
there is a non-null selection, the cursor is not disjoint from the
selection and XmNpendingDelete is set to True,
deletes the selection, otherwise deletes the characters preceding the
insertion cursor to the previous beginning of line character. This
may impact the selection.
- deselect-all():
- Deselects the current selection.
- end-of-file(extend):
- If this action is called with no argument, moves the insertion
cursor to the end of the text. For other effects, see the description
of navigation operations in the "Keyboard Selection" section.
If called with an argument of extend, moves the
insertion cursor as in the case of no argument and extends the current
selection. For other effects, see the description of shifted
navigation operations in the "Keyboard Selection" section.
- end-of-line(extend):
- If this action is called with no argument, moves the insertion
cursor to the end of the line. For other effects, see the description
of navigation operations in the "Keyboard Selection" section. If
called with an argument of extend, moves the
insertion cursor as in the case of no argument and extends the current
selection. For other effects, see the description of shifted
navigation operations in the "Keyboard Selection" section.
- extend-adjust():
- Selects text from the anchor to the pointer position and
deselects text outside that range. Moving the pointer over several
lines selects text from the anchor to the end of each line the pointer
moves over and up to the pointer position on the current line.
- extend-end():
- Moves the insertion cursor to the position of the pointer.
- extend-start():
- Adjusts the anchor using the balance-beam method. Selects text
from the anchor to the pointer position and deselects text outside
that range.
- forward-character():
- Moves the insertion cursor one character to the right. For
other effects, see the description of navigation operations in the
"Keyboard Selection" section. This action may have different behavior
in a right-to-left language environment.
- forward-paragraph(extend):
- If XmNeditMode is
XmMULTI_LINE_EDIT, and this action is called with no
argument, moves the insertion cursor to the first non-whitespace
character following the next blank line. If the insertion cursor is
already at the beginning of a paragraph, moves the insertion cursor to
the beginning of the next paragraph. For other effects, see the
description of navigation operations in the "Keyboard Selection"
section.
If XmNeditMode is
XmMULTI_LINE_EDIT and this action is called with an
argument of extend, moves the insertion cursor as in
the case of no argument and extends the current selection. For other
effects, see the description of shifted navigation operations in the
"Keyboard Selection" section.
- forward-word(extend):
- If this action is called with no argument, moves the insertion
cursor to the first whitespace character or end of line following the
next non-whitespace character. If the insertion cursor is already at
the end of a word, moves the insertion cursor to the end of the next
word. For other effects, see the description of navigation operations
in the "Keyboard Selection" section. This action may have different
behavior in a locale other than the C locale.
If called with an argument of extend, moves the
insertion cursor as in the case of no argument and extends the current
selection. For other effects, see the description of shifted
navigation operations in the "Keyboard Selection" section.
- grab-focus():
- This key binding performs the action defined in the
XmNselectionArray, depending on the number of
multiple mouse clicks. The default selection array ordering is one
click to move the insertion cursor to the pointer position, two clicks
to select a word, three clicks to select a line of text, and four
clicks to select all text. A single click also deselects any selected
text and sets the anchor at the pointer position. This action may
have different behavior in a locale other than the C locale.
- Help():
- Calls the callbacks for XmNhelpCallback
if any exist. If there are no help callbacks for this widget, this
action calls the help callbacks for the nearest ancestor that has
them.
- insert-string(string):
- If XmNpendingDelete is True and the
cursor is not disjoint from the current selection, deletes the entire
selection. Inserts string before the insertion cursor.
- key-select(direction):
- If called with an argument of right, moves the
insertion cursor one character to the right and extends the current
selection. If called with an argument of left, moves
the insertion cursor one character to the left and extends the current
selection. If called with no argument, extends the current selection.
For other effects, see the description of shifted navigation
operations and KExtend in the "Keyboard Selection"
section.
- kill-next-character():
- In normal mode if there is a non-null selection, deletes the
selection, otherwise kills the character following the insertion
cursor and stores the character in the cut buffer. In add mode if
there is a non-null selection, the cursor is not disjoint from the
selection and XmNpendingDelete is set to True,
deletes the selection, otherwise kills the character following the
insertion cursor and stores the character in the cut buffer. This may
impact the selection.
- kill-next-word():
- In normal mode if there is a non-null selection, deletes the
selection, otherwise kills the characters following the insertion
cursor to the next space, tab or end of line character, and stores the
characters in the cut buffer. In add mode if there is a non-null
selection, the cursor is not disjoint from the selection and
XmNpendingDelete is set to True, deletes the
selection, otherwise kills the characters following the insertion
cursor to the next space, tab or end of line character, and stores the
characters in the cut buffer. This may impact the selection. This
action may have different behavior in a locale other than the C
locale.
- kill-previous-character():
- In normal mode if there is a non-null selection, deletes the
selection, otherwise kills the character immediately preceding the
insertion cursor and stores the character in the cut buffer. In add
mode if there is a non-null selection, the cursor is not disjoint from
the selection and XmNpendingDelete is set to True,
deletes the selection, otherwise kills the character immediately
preceding the insertion cursor and stores the character in the cut
buffer. This may impact the selection.
- kill-previous-word():
- In normal mode if there is a non-null selection, deletes the
selection, otherwise kills the characters preceding the insertion
cursor up to the next space, tab or beginning of line character, and
stores the characters in the cut buffer. In add mode if there is a
non-null selection, the cursor is not disjoint from the selection and
XmNpendingDelete is set to True, deletes the
selection, otherwise kills the characters preceding the insertion
cursor up to the next space, tab or beginning of line character, and
stores the characters in the cut buffer. This may impact the
selection. This action may have different behavior in a locale other
than the C locale.
- kill-selection():
- Kills the currently selected text and stores the text in the
cut buffer.
- kill-to-end-of-line():
- In normal mode if there is a non-null selection, deletes the
selection, otherwise kills the characters following the insertion
cursor to the next end of line character and stores the characters in
the cut buffer. In add mode if there is a non-null selection, the
cursor is not disjoint from the selection and
XmNpendingDelete is set to True, deletes the
selection, otherwise kills the characters following the insertion
cursor to the next end of line character and stores the characters in
the cut buffer. This may impact the selection.
- kill-to-start-of-line():
- In normal mode if there is a non-null selection, deletes the
selection, otherwise kills the characters preceding the insertion
cursor to the next beginning of line character and stores the
characters in the cut buffer. In add mode if there is a non-null
selection, the cursor is not disjoint from the selection and
XmNpendingDelete is set to True, deletes the
selection, otherwise kills the characters preceding the insertion
cursor to the next beginning of line character and stores the
characters in the cut buffer. This may impact the selection.
- move-destination():
- Moves the insertion cursor to the pointer position without
changing any existing current selection. If there is no current
selection, sets the widget as the destination widget.
- move-to():
- If a secondary selection exists, cuts the secondary selection
to the insertion cursor. If no secondary selection exists, cuts the
primary selection to the pointer location.
- newline():
- If XmNpendingDelete is True and the cursor is
not disjoint from the current selection, deletes the entire selection.
Inserts a newline before the insertion cursor.
- newline-and-backup():
- If XmNpendingDelete is True and the cursor is
not disjoint from the current selection, deletes the entire selection.
Inserts a newline just before the insertion cursor and repositions the
insertion cursor to the end of the line before the newline.
- newline-and-indent():
- If XmNpendingDelete is True and the cursor is
not disjoint from the current selection, deletes the entire selection.
Inserts a newline and then the same number of whitespace characters as
at the beginning of the previous line.
- next-line():
- Moves the insertion cursor to the next line. For other
effects, see the description of navigation operations in the "Keyboard
Selection" section.
- next-page(extend):
- If this action is called with no argument, moves the insertion
cursor forward one page. For other effects, see the description of
navigation operations in the "Keyboard Selection" section.
If called with an argument of extend, moves the
insertion cursor as in the case of no argument and extends the current
selection. For other effects, see the description of shifted
navigation operations in the "Keyboard Selection" section.
- next-tab-group():
- Traverses to the next tab group.
- page-left():
- Scrolls the viewing window left one page of text.
- page-right():
- Scrolls the viewing window right one page of text.
- paste-clipboard():
- Pastes the contents of the clipboard before the insertion
cursor.
- prev-tab-group():
- Traverses to the previous tab group.
- previous-line():
- Moves the insertion cursor to the previous line. For other
effects, see the description of navigation operations in the "Keyboard
Selection" section.
- previous-page(extend):
- If this action is called with no argument, moves the insertion
cursor back one page. For other effects, see the description of
navigation operations in the "Keyboard Selection" section.
If called with an argument of extend, moves the
insertion cursor as in the case of no argument and extends the current
selection. For other effects, see the description of shifted
navigation operations in the "Keyboard Selection" section.
- process-bdrag()
- The result of this action is determined by several factors:
position of the location cursor, movement of the location cursor, and
the interval between a BDrag press and release.
This action copies the current selection to the insertion cursor if
text is selected, the location cursor is disjoint from the current
selection, and no motion is detected within a given time interval.
It performs a secondary selection and copies the selection to the
position where the text was last edited if the cursor is disjoint from
a current selection (if one exists), the time interval is exceeded,
and movement of the location cursor is detected.
The action drags the current selection if the location cursor is
positioned on the selection, the time interval is exceeded, and
movement of the location cursor is detected. This action creates a
DragContext object whose XmNexportTargets
resource value includes target types of COMPOUND_TEXT, STRING, and
TEXT.
- process-cancel():
- Cancels the current extend-adjust(),
secondary-adjust() or
process-bdrag() operation and leaves the selection
state as it was before the operation, otherwise, and if the parent is
a manager, passes the event to the parent.
- process-down():
- If XmNeditMode is
XmSINGLE_LINE_EDIT and XmNnavigationType
is XmNONE, traverses to the widget below the current
one in the tab group.
If XmNeditMode is
XmMULTI_LINE_EDIT, moves the insertion cursor down
one line. For other effects, see the description of navigation
operations in the "Keyboard Selection" section.
- process-home():
- Moves the insertion cursor to the beginning of the line. For
other effects, see the description of navigation operations in the
"Keyboard Selection" section.
- process-return():
- If XmNeditMode is
XmSINGLE_LINE_EDIT, calls the callbacks for
XmNactivateCallback, and if
the parent is a manager, passes the event to the parent. If
XmNeditMode is
XmMULTI_LINE_EDIT, inserts a newline.
- process-shift-down():
- If XmNeditMode is
XmMULTI_LINE_EDIT, moves the insertion cursor down
one line. For other effects, see the description of navigation
operations in the "Keyboard Selection" section.
- process-shift-up():
- If XmNeditMode is
XmMULTI_LINE_EDIT, moves the insertion cursor up one
line. For other effects, see the description of navigation operations
in the "Keyboard Selection" section.
- process-tab():
- If XmNeditMode is
XmSINGLE_LINE_EDIT, traverses to the next tab group.
If XmNeditMode is XmMULTI_LINE_EDIT,
inserts a tab.
- process-up():
- If XmNeditMode is
XmSINGLE_LINE_EDIT and XmNnavigationType
is XmNONE, traverses to the widget above the current
one in the tab group.
If XmNeditMode is
XmMULTI_LINE_EDIT, moves the insertion cursor up one
line. For other effects, see the description of navigation operations
in the "Keyboard Selection" section.
- redraw-display():
- Redraws the contents of the text window.
- scroll-cursor-vertically(percentage):
- Scrolls the line containing the insertion cursor vertically to
an intermediate position in the visible window based on an input
percentage. A value of 0 indicates the top of the window; a value of
100, the bottom of the window. If this action is called with no
argument, the line containing the insertion cursor is scrolled
vertically to a new position designated by the y position of
the event passed to the routine.
- scroll-one-line-down():
- Scrolls the text area down one line.
- scroll-one-line-up():
-
Scrolls the text area up one line.
- secondary-adjust():
- Extends the secondary selection to the pointer position.
- secondary-notify():
- Copies the secondary selection to the insertion cursor of the
destination widget.
- secondary-start():
- Marks the beginning of a secondary selection.
- select-adjust():
- Extends the current selection. The amount of text selected
depends on the number of mouse clicks, as specified by the
XmNselectionArray resource.
- select-all():
- Selects all text.
- select-end():
- Extends the current selection. The amount of text selected
depends on the number of mouse clicks, as specified by the
XmNselectionArray resource.
- select-start():
- Marks the beginning of a new selection region.
- self-insert():
- If XmNpendingDelete is True and the cursor is
not disjoint from the current selection, deletes the entire selection.
Inserts the character associated with the key pressed at the insertion
cursor.
- set-anchor():
- Resets the anchor point for extended selections. Resets the
destination of secondary selection actions.
- set-insertion-point():
- Sets the insertion position.
- set-selection-hint():
- Sets the text source and location of the current selection.
- toggle-add-mode():
- Toggles the state of Add Mode.
- toggle-overstrike():
- Toggles the state of the text insertion mode. By default,
characters typed into the Text widget are inserted at the position of
the insertion cursor. In overstrike mode, characters entered into the
Text widget replace the characters that directly follow the insertion
cursor. In overstrike mode, when the end of a line is reached,
characters are appended to the end of the line.
- traverse-home():
- Traverses to the first widget in the tab group.
- traverse-next():
- Traverses to the next widget in the tab group.
- traverse-prev():
- Traverses to the previous widget in the tab group.
- unkill():
- Restores last killed text to the position of the insertion
cursor.
Additional Behavior
This widget has the additional behavior described below:
- <FocusIn>:
- Draws the insertion cursor as
solid and starts blinking the cursor.
- <FocusOut>:
- Displays the insertion cursor as
a stippled I-beam unless it is the destination widget.
Virtual Bindings
The bindings for virtual keys are vendor specific. The following
table lists the Text-specific bindings of virtual keys to actual key
event descriptions in 1/Motif:
Virtual Key Actual Key Events
KActivate Ctrl<Key>Return
<Key>osfActivate
KExtend Ctrl Shift<Key>space
Shift<Key>osfSelect
KNextField Ctrl<Key>Tab
KSelect Ctrl<Key>space
<Key>osfSelect
For information about bindings for virtual buttons and keys, see
VirtualBindings(3X).
RELATED INFORMATION
Core(3X),
XmCreateScrolledText(3X),
XmCreateText(3X),
XmFontList(3X),
XmFontListAppendEntry(3X),
XmPrimitive(3X),
XmTextClearSelection(3X),
XmTextCopy(3X),
XmTextCut(3X),
XmTextEnableRedisplay(3X),
XmTextDisableRedisplay(3X),
XmTextField(3X),
XmTextFindString(3X),
XmTextFindStringWcs(3X),
XmTextGetBaseline(3X),
XmTextGetEditable(3X),
XmTextGetInsertionPosition(3X),
XmTextGetLastPosition(3X),
XmTextGetMaxLength(3X),
XmTextGetSelection(3X),
XmTextGetSelectionWcs(3X),
XmTextGetSelectionPosition(3X),
XmTextGetSource(3X),
XmTextGetString(3X),
XmTextGetStringWcs(3X),
XmTextGetSubstring(3X),
XmTextGetSubstringWcs(3X),
XmTextGetTopCharacter(3X),
XmTextInsert(3X),
XmTextInsertWcs(3X),
XmTextPaste(3X),
XmTextPosToXY(3X),
XmTextPosition(3X),
XmTextRemove(3X),
XmTextReplace(3X),
XmTextReplaceWcs(3X),
XmTextScroll(3X),
XmTextSetAddMode(3X),
XmTextSetEditable(3X),
XmTextSetHighlight(3X),
XmTextSetInsertionPosition(3X),
XmTextSetMaxLength(3X),
XmTextSetSelection(3X),
XmTextSetSource(3X),
XmTextSetString(3X),
XmTextSetStringWcs(3X),
XmTextSetTopCharacter(3X),
XmTextShowPosition(3X), and
XmTextXYToPos(3X).