XmText(3X) OSF/Motif XmText(3X)NAMEXmText - 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 spe‐
cific 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 Man‐
ual (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 trans‐
fer, or secondary transfer. Text also provides a Drag and Drop facil‐
ity that enables the user to copy or move data within Text or to a dif‐
ferent widget. When keyboard focus policy is set to EXPLICIT, the wid‐
get 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 insen‐
sitive, 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, indicat‐
ing 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 pro‐
grammer to specify data. The programmer can also set the resource val‐
ues 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).
XmText Resource Set
─────────────────────────────────────────────────────────────────
Name Default Access
Class Type
─────────────────────────────────────────────────────────────────
─────────────────────────────────────────────────────────────────
XmNactivateCallback NULL C
XmCCallback XtCallbackList
─────────────────────────────────────────────────────────────────
XmNautoShowCursorPosition True CSG
XmCAutoShowCursorPosition Boolean
─────────────────────────────────────────────────────────────────
XmNcursorPosition 0 CSG
XmCCursorPosition XmTextPosition
─────────────────────────────────────────────────────────────────
XmNeditable True CSG
XmCEditable Boolean
─────────────────────────────────────────────────────────────────
XmNeditMode XmSINGLE_LINE_EDIT CSG
XmCEditMode int
─────────────────────────────────────────────────────────────────
XmNfocusCallback NULL C
XmCCallback XtCallbackList
─────────────────────────────────────────────────────────────────
XmNgainPrimaryCallback NULL C
XmCCallback XtCallbackList
─────────────────────────────────────────────────────────────────
XmNlosePrimaryCallback NULL C
XmCCallback XtCallbackList
─────────────────────────────────────────────────────────────────
XmNlosingFocusCallback NULL C
XmCCallback XtCallbackList
─────────────────────────────────────────────────────────────────
XmNmarginHeight 5 CSG
XmCMarginHeight Dimension
─────────────────────────────────────────────────────────────────
XmNmarginWidth 5 CSG
XmCMarginWidth Dimension
─────────────────────────────────────────────────────────────────
XmNmaxLength largest integer CSG
XmCMaxLength int
─────────────────────────────────────────────────────────────────
XmNmodifyVerifyCallback NULL C
XmCCallback XtCallbackList
─────────────────────────────────────────────────────────────────
XmNmodifyVerifyCallbackWcs NULL C
XmCCallback XtCallbackList
─────────────────────────────────────────────────────────────────
XmNmotionVerifyCallback NULL C
XmCCallback XtCallbackList
─────────────────────────────────────────────────────────────────
XmNsource Default source CSG
XmCSource XmTextSource
─────────────────────────────────────────────────────────────────
XmNtopCharacter 0 CSG
XmCTextPosition XmTextPosition
─────────────────────────────────────────────────────────────────
XmNvalue "" CSG
XmCValue String
─────────────────────────────────────────────────────────────────
XmNvalueChangedCallback NULL C
XmCCallback XtCallbackList
─────────────────────────────────────────────────────────────────
XmNvalueWcs (wchar_t *)"" CSG*
XmCvalueWcs wchar_t *
─────────────────────────────────────────────────────────────────
XmNverifyBell dynamic CSG
XmCVerifyBell Boolean
─────────────────────────────────────────────────────────────────
* This resource cannot be set in a resource file. 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. Ensures that the visible text contains the
insert cursor when set to True. If the insert cursor changes, the con‐
tents of Text may scroll in order to bring the insertion point into the
window. Indicates the position in the text where the current insert
cursor is to be located. Position is determined by the number of char‐
acters from the beginning of the text. The first character position is
0. Indicates that the user can edit the text string when set to True.
Prohibits the user from editing the text when set to False. Specifies
the set of keyboard bindings used in Text. The default keyboard bind‐
ings (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. Specifies the
list of callbacks called when Text accepts input focus. The type of
the structure whose address is passed to this callback is XmAnyCall‐
backStruct. The reason sent by the callback is XmCR_FOCUS. 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 call‐
back is XmCR_GAIN_PRIMARY. Specifies the list of callbacks called when
an event causes the Text widget to lose ownership of the primary selec‐
tion. The reason sent by the callback is XmCR_LOSE_PRIMARY. Specifies
the list of callbacks called before Text loses input focus. The type
of the structure whose address is passed to this callback is XmTextVer‐
ifyCallbackStruct. The reason sent by the callback is XmCR_LOS‐
ING_FOCUS. 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. Specifies the distance between the left edge of the wid‐
get window and the text, and between the right edge of the widget win‐
dow and the text. 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. 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 reg‐
istered 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. 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 ini‐
tiates the source change will generate the XmNmodifyVerifyCallbackWcs.
If both XmNmodifyVerifyCallback and XmNmodifyVerifyCallbackWcs are reg‐
istered 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. 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 pos‐
sible for more than one XmNmotionVerifyCallbacks to be generated from a
single action. 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. 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 shift‐
ing 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. 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. Specifies the list of call‐
backs 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 XmN‐
valueChangedCallback. 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 XmNmodifyVerify‐
Callback is not set to False. 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.
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.
XmText Input Resource Set
─────────────────────────────────────────────────────────
Name Default Access
Class Type
─────────────────────────────────────────────────────────
─────────────────────────────────────────────────────────
XmNpendingDelete True CSG
XmCPendingDelete Boolean
─────────────────────────────────────────────────────────
XmNselectionArray default array CSG
XmCSelectionArray XtPointer
─────────────────────────────────────────────────────────
XmNselectionArrayCount 4 CSG
XmCSelectionArrayCount int
─────────────────────────────────────────────────────────
XmNselectThreshold 5 CSG
XmCSelectThreshold int
─────────────────────────────────────────────────────────
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. Defines the actions for multiple mouse
clicks. The value of the resource is an array of XmTextScanType ele‐
ments. 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 posi‐
tion XmSELECT_WORD—selects a word XmSELECT_LINE—selects a line of text
XmSELECT_ALL—selects all of the text Indicates the number of elements
in the XmNselectionArray resource. The value must not be negative.
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.
XmText Output Resource Set
────────────────────────────────────────────────────────────
Name Default Access
Class Type
────────────────────────────────────────────────────────────
────────────────────────────────────────────────────────────
XmNblinkRate 500 CSG
XmCBlinkRate int
────────────────────────────────────────────────────────────
XmNcolumns dynamic CSG
XmCColumns short
────────────────────────────────────────────────────────────
XmNcursorPositionVisible True CSG
XmCCursorPositionVisible Boolean
────────────────────────────────────────────────────────────
XmNfontList dynamic CSG
XmCFontList XmFontList
────────────────────────────────────────────────────────────
XmNresizeHeight False CSG
XmCResizeHeight Boolean
────────────────────────────────────────────────────────────
XmNresizeWidth False CSG
XmCResizeWidth Boolean
────────────────────────────────────────────────────────────
XmNrows dynamic CSG
XmCRows short
────────────────────────────────────────────────────────────
XmNwordWrap False CSG
XmCWordWrap Boolean
────────────────────────────────────────────────────────────
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. 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 charac‐
ter 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 speci‐
fied the default is 20. Indicates that the insert cursor position is
marked by a blinking text cursor when the Boolean value is True. Spec‐
ifies the font list to be used for Text. If this value is NULL at ini‐
tialization, 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 imple‐
mentation 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. Indi‐
cates 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 wid‐
get and when XmNscrollVertical is True. 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 XmNword‐
Wrap is True. 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. 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.
XmText ScrolledText Resource Set
──────────────────────────────────────────────
Name Default Access
Class Type
──────────────────────────────────────────────
──────────────────────────────────────────────
XmNscrollHorizontal True CG
XmCScroll Boolean
──────────────────────────────────────────────
XmNscrollLeftSide dynamic CG
XmCScrollSide Boolean
──────────────────────────────────────────────
XmNscrollTopSide False CG
XmCScrollSide Boolean
──────────────────────────────────────────────
XmNscrollVertical True CG
XmCScroll Boolean
──────────────────────────────────────────────
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 XmNscrolling‐
Policy set to XmAUTOMATIC. 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. Indicates that the horizontal ScrollBar should be placed on
the top side of the scrolled text window when the Boolean value is
True. 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.
XmPrimitive Resource Set
───────────────────────────────────────────────────────────────
Name Default Access
Class Type
───────────────────────────────────────────────────────────────
───────────────────────────────────────────────────────────────
XmNbottomShadowColor dynamic CSG
XmCBottomShadowColor Pixel
───────────────────────────────────────────────────────────────
XmNbottomShadowPixmap XmUNSPECIFIED_PIXMAP CSG
XmCBottomShadowPixmap Pixmap
───────────────────────────────────────────────────────────────
XmNforeground dynamic CSG
XmCForeground Pixel
───────────────────────────────────────────────────────────────
XmNhelpCallback NULL C
XmCCallback XtCallbackList
───────────────────────────────────────────────────────────────
XmNhighlightColor dynamic CSG
XmCHighlightColor Pixel
───────────────────────────────────────────────────────────────
XmNhighlightOnEnter False CSG
XmCHighlightOnEnter Boolean
───────────────────────────────────────────────────────────────
XmNhighlightPixmap dynamic CSG
XmCHighlightPixmap Pixmap
───────────────────────────────────────────────────────────────
XmNhighlightThickness 2 CSG
XmCHighlightThickness Dimension
───────────────────────────────────────────────────────────────
XmNnavigationType XmTAB_GROUP CSG
XmCNavigationType XmNavigationType
───────────────────────────────────────────────────────────────
XmNshadowThickness 2 CSG
XmCShadowThickness Dimension
───────────────────────────────────────────────────────────────
XmNtopShadowColor dynamic CSG
XmCTopShadowColor Pixel
───────────────────────────────────────────────────────────────
XmNtopShadowPixmap dynamic CSG
XmCTopShadowPixmap Pixmap
───────────────────────────────────────────────────────────────
XmNtraversalOn True CSG
XmCTraversalOn Boolean
───────────────────────────────────────────────────────────────
XmNunitType dynamic CSG
XmCUnitType unsigned char
───────────────────────────────────────────────────────────────
XmNuserData NULL CSG
XmCUserData XtPointer
───────────────────────────────────────────────────────────────
Core Resource Set
─────────────────────────────────────────────────────────────────────
Name Default Access
Class Type
─────────────────────────────────────────────────────────────────────
─────────────────────────────────────────────────────────────────────
XmNaccelerators dynamic CSG
XmCAccelerators XtAccelerators
─────────────────────────────────────────────────────────────────────
XmNancestorSensitive dynamic G
XmCSensitive Boolean
─────────────────────────────────────────────────────────────────────
XmNbackground dynamic CSG
XmCBackground Pixel
─────────────────────────────────────────────────────────────────────
XmNbackgroundPixmap XmUNSPECIFIED_PIXMAP CSG
XmCPixmap Pixmap
─────────────────────────────────────────────────────────────────────
XmNborderColor XtDefaultForeground CSG
XmCBorderColor Pixel
─────────────────────────────────────────────────────────────────────
XmNborderPixmap XmUNSPECIFIED_PIXMAP CSG
XmCPixmap Pixmap
─────────────────────────────────────────────────────────────────────
XmNborderWidth 0 CSG
XmCBorderWidth Dimension
─────────────────────────────────────────────────────────────────────
XmNcolormap dynamic CG
XmCColormap Colormap
─────────────────────────────────────────────────────────────────────
XmNdepth dynamic CG
XmCDepth int
─────────────────────────────────────────────────────────────────────
XmNdestroyCallback NULL C
XmCCallback XtCallbackList
─────────────────────────────────────────────────────────────────────
XmNheight dynamic CSG
XmCHeight Dimension
─────────────────────────────────────────────────────────────────────
XmNinitialResourcesPersistent True C
XmCInitialResourcesPersistent Boolean
─────────────────────────────────────────────────────────────────────
XmNmappedWhenManaged True CSG
XmCMappedWhenManaged Boolean
─────────────────────────────────────────────────────────────────────
XmNscreen dynamic CG
XmCScreen Screen *
─────────────────────────────────────────────────────────────────────
XmNsensitive True CSG
XmCSensitive Boolean
─────────────────────────────────────────────────────────────────────
XmNtranslations dynamic CSG
XmCTranslations XtTranslations
─────────────────────────────────────────────────────────────────────
XmNwidth dynamic CSG
XmCWidth Dimension
─────────────────────────────────────────────────────────────────────
XmNx 0 CSG
XmCPosition Position
─────────────────────────────────────────────────────────────────────
XmNy 0 CSG
XmCPosition Position
─────────────────────────────────────────────────────────────────────
Callback Information
A pointer to the following structure is passed to each callback: type‐
def struct { int reason; XEvent * event; } XmAny‐
CallbackStruct; Indicates why the callback was invoked Points to the
XEvent that triggered the callback
The Text widget defines a new callback structure for use with verifica‐
tion callbacks. Note that not all fields are relevant for every call‐
back reason. The application must first look at the reason field and
use only the structure members that are valid for the particular rea‐
son. 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 spa‐
ces 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 XmNlos‐
ingFocusCallback, XmNmodifyVerifyCallback, and XmNmotionVerifyCallback.
typedef struct { int reason; XEvent * event; Bool‐
ean doit; XmTextPosition currInsert, newInsert; XmTextPosition
startPos, endPos; XmTextBlock text; } XmTextVerifyCallbackStruct,
*XmTextVerifyPtr; Indicates why the callback was invoked. 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. Indicates whether the
action that invoked the callback is performed. Setting doit to False
negates the action. Indicates the current position of the insert cur‐
sor. Indicates the position at which the user attempts to position the
insert cursor. 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. 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. 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; Points to the
text to be inserted. Specifies the length of the text to be inserted.
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 XmNmod‐
ifyVerifyCallbackWcs. typedef struct { int reason;
XEvent *event; Boolean doit; XmTextPosition currIn‐
sert, newInsert; XmTextPosition startPos, endPos; XmTextBlockWcs
text; } XmTextVerifyCallbackStructWcs, *XmTextVerifyPtrWcs; Indicates
why the callback was invoked. Points to the XEvent that triggered the
callback. It can be NULL. For example, changes made to the Text wid‐
get programmatically do not have an event that can be passed to the
associated callback. Indicates whether the action that invoked the
callback is performed. Setting doit to False negates the action.
Indicates the current position of the insert cursor. Indicates the
position at which the user attempts to position the insert cursor.
Indicates the starting position of the text to modify. If the callback
is not a modify verification callback, this value is the same as cur‐
rInsert. 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. 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; Points to the wide character text to be inserted.
Specifies the number of characters to be inserted.
The following table describes the reasons why the individual verifica‐
tion callback structure fields are valid:
Reason Valid Fields
───────────────────────────────────────────────────────
XmCR_LOSING_FOCUS reason, event, doit, cur‐
rInsert, newInsert, start‐
Pos, endPos
XmCR_MODIFYING_TEXT_VALUE reason, event, doit, cur‐
rInsert, newInsert, start‐
Pos, endPos, text
XmCR_MOVING_INSERT_CURSOR reason, event, doit, cur‐
rInsert, 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-para‐
graph(extend)
KDown: process-down() MShift KDown: process-shift-down() MCtrl
KDown: forward-paragraph() MShift MCtrl KDown:forward-para‐
graph(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() KPre‐
vField: 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() KSe‐
lect: set-anchor() KExtend: key-select() MAny KCan‐
cel: process-cancel() KClear: clear-selection() KSelec‐
tAll: select-all() KDeselectAll: deselect-all()
KCut: cut-clipboard() KCopy: copy-clipboard()
KPaste: paste-clipboard()
KPrimaryCut: cut-primary() KPrimaryCopy: copy-primary() KPrimary‐
Paste: copy-primary()
KHelp: Help()
KAny: self-insert()
Action Routines
The XmText action routines are described below: Calls the callbacks for
XmNactivateCallback. If the parent is a manager, passes the event to
the parent. 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. 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 Selec‐
tion" 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 Selec‐
tion" section. 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. Causes the terminal to beep. 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 navi‐
gation 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. If this action is called with no argu‐
ment, 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. Clears the current selection by replac‐
ing each character except <Return> with a <space> character. Copies
the current selection to the clipboard. Copies the primary selection
to just before the insertion cursor. 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. Cuts the current selection to the clipboard. Cuts
the primary selection to just before the insertion cursor. 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. In normal mode if there is a non-null selec‐
tion, 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 dis‐
joint 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. 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 cur‐
sor. This may impact the selection. 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 pre‐
ceding the insertion cursor to the next space, tab or beginning of line
character.. This may impact the selection. This action may have dif‐
ferent behavior in a locale other than the C locale. Deletes the cur‐
rent selection. 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. 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 selec‐
tion, the cursor is not disjoint from the selection and XmNpend‐
ingDelete 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. Deselects the current
selection. If this action is called with no argument, moves the inser‐
tion cursor to the end of the text. For other effects, see the
description of navigation operations in the "Keyboard Selection" sec‐
tion.
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. If this action is called with no argu‐
ment, 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. 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. Moves the insertion cursor to the position of the
pointer. Adjusts the anchor using the balance-beam method. Selects
text from the anchor to the pointer position and deselects text outside
that range. 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. 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 begin‐
ning 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 Selec‐
tion" section. If this action is called with no argument, moves the
insertion cursor to the first whitespace character or end of line fol‐
lowing 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. 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 differ‐
ent behavior in a locale other than the C locale. 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. If XmNpendingDelete is True and the cursor is
not disjoint from the current selection, deletes the entire selection.
Inserts string before the insertion cursor. 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 naviga‐
tion operations and KExtend" in the "Keyboard Selection" section. 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 XmNpend‐
ingDelete 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. 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 cur‐
sor 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.
In normal mode if there is a non-null selection, deletes the selection,
otherwise kills the character immediately preceding the insertion cur‐
sor 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.
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 charac‐
ters 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 pre‐
ceding 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. Kills the currently selected text and
stores the text in the cut buffer. 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. 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 XmNpend‐
ingDelete 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. Moves the insertion cursor to the pointer position
without changing any existing current selection. If there is no cur‐
rent selection, sets the widget as the destination widget. If a sec‐
ondary selection exists, cuts the secondary selection to the insertion
cursor. If no secondary selection exists, cuts the primary selection
to the pointer location. 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. 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 cur‐
sor and repositions the insertion cursor to the end of the line before
the newline. If XmNpendingDelete is True and the cursor is not dis‐
joint 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. Moves the insertion cursor to
the next line. For other effects, see the description of navigation
operations in the "Keyboard Selection" section. 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. Traverses to the next tab group.
Scrolls the viewing window left one page of text. Scrolls the viewing
window right one page of text. Pastes the contents of the clipboard
before the insertion cursor. Traverses to the previous tab group.
Moves the insertion cursor to the previous line. For other effects,
see the description of navigation operations in the "Keyboard Selec‐
tion" section. 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. 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 posi‐
tion 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 posi‐
tioned 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. Cancels the current extend-adjust(),
secondary-adjust() or process-bdrag() operation and leaves the selec‐
tion state as it was before the operation, otherwise, and if the parent
is a manager, passes the event to the parent. If XmNeditMode is XmSIN‐
GLE_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 opera‐
tions in the "Keyboard Selection" section. 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
XmNeditMode is XmSINGLE_LINE_EDIT, calls the callbacks for XmNactivate‐
Callback, and if the parent is a manager, passes the event to the par‐
ent. If XmNeditMode is XmMULTI_LINE_EDIT, inserts a newline. 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. 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. If XmNeditMode is XmSINGLE_LINE_EDIT, traverses to
the next tab group. If XmNeditMode is XmMULTI_LINE_EDIT, inserts a
tab. 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. Redraws the contents of the text
window. Scrolls the line containing the insertion cursor vertically to
an intermediate position in the visible window based on an input per‐
centage. 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. Scrolls the text area down one line. Scrolls the text area
up one line. Extends the secondary selection to the pointer position.
Copies the secondary selection to the insertion cursor of the destina‐
tion widget. Marks the beginning of a secondary selection. Extends
the current selection. The amount of text selected depends on the num‐
ber of mouse clicks, as specified by the XmNselectionArray resource.
Selects all text. Extends the current selection. The amount of text
selected depends on the number of mouse clicks, as specified by the
XmNselectionArray resource. Marks the beginning of a new selection
region. 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.
Resets the anchor point for extended selections. Resets the destina‐
tion of secondary selection actions. Sets the insertion position.
Sets the text source and location of the current selection. Toggles
the state of Add Mode. 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 fol‐
low the insertion cursor. In overstrike mode, when the end of a line
is reached, characters are appended to the end of the line. Traverses
to the first widget in the tab group. Traverses to the next widget in
the tab group. Traverses to the previous widget in the tab group.
Restores last killed text to the position of the insertion cursor.
Additional Behavior
This widget has the additional behavior described below: Draws the
insertion cursor as solid and starts blinking the cursor. Displays the
insertion cursor as a stippled I-beam unless it is the destination wid‐
get.
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 Bindings
───────────────────────────────────
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 Virtu‐
alBindings(3X).
RELATED INFORMATIONCore(3X), XmCreateScrolledText(3X), XmCreateText(3X), XmFontList(3X),
XmFontListAppendEntry(3X), XmPrimitive(3X), XmTextClearSelection(3X),
XmTextCopy(3X), XmTextCut(3X), XmTextEnableRedisplay(3X), XmTextDis‐
ableRedisplay(3X), XmTextField(3X), XmTextFindString(3X), XmTextFind‐
StringWcs(3X), XmTextGetBaseline(3X), XmTextGetEditable(3X),
XmTextGetInsertionPosition(3X), XmTextGetLastPosition(3X), XmTextGet‐
MaxLength(3X), XmTextGetSelection(3X), XmTextGetSelectionWcs(3X),
XmTextGetSelectionPosition(3X), XmTextGetSource(3X), XmTextGet‐
String(3X), XmTextGetStringWcs(3X), XmTextGetSubstring(3X), XmTextGet‐
SubstringWcs(3X), XmTextGetTopCharacter(3X), XmTextInsert(3X), XmTex‐
tInsertWcs(3X), XmTextPaste(3X), XmTextPosToXY(3X), XmTextPosition(3X),
XmTextRemove(3X), XmTextReplace(3X), XmTextReplaceWcs(3X),
XmTextScroll(3X), XmTextSetAddMode(3X), XmTextSetEditable(3X),
XmTextSetHighlight(3X), XmTextSetInsertionPosition(3X), XmTextSet‐
MaxLength(3X), XmTextSetSelection(3X), XmTextSetSource(3X), XmTextSet‐
String(3X), XmTextSetStringWcs(3X), XmTextSetTopCharacter(3X),
XmTextShowPosition(3X), and XmTextXYToPos(3X).
XmText(3X)