XmText(3Xm) XmText(3Xm)
NAME
XmText - the Text widget class.
AES SUPPORT LEVEL
full-use
SYNOPSIS
#include <Xm/Text.h>
DESCRIPTION
Text provides a single 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 Interclient Communication
Conventions (lCCC) selection model. Text supports
primary selection.
Primitive's resource XmNtraversalOn is always True in
Text.
Classes
Text inherits behavior and resources from Core and
Primitive classes.
The class pointer is xmTextWidgetClass.
The class name is XmText.
- 1 -
XmText(3Xm) XmText(3Xm)
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
lower case or upper case, 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 Class Type Default Access
____________________________________________________________________________________________________
XmNactivateCallback XmCCallback XtCallbackList NULL C
XmNautoShowCursorPosition XmCAutoShowCursorPosition Boolean True CSG
XmNcursorPosition XmCCursorPosition XmTextPosition 0 CSG
XmNeditable XmCEditable Boolean True CSG
XmNeditMode XmCEditMode int XmSINGLE_LINE_EDIT CSG
XmNfocusCallback XmCCallback XtCallbackList NULL C
XmNlosingFocusCallback XmCCallback XtCallbackList NULL C
XmNmarginHeight XmCMarginHeight short 3 CSG
XmNmarginWidth XmCMarginWidth short 3 CSG
XmNmaxLength XmCMaxLength int MAXINT CSG
XmNmodifyVerifyCallback XmCCallback XtCallbackList NULL C
XmNmotionVerifyCallback XmCCallback XtCallbackList NULL C
XmNtopPosition XmCTextPosition XmTextPosition 0 CSG
XmNvalue XmCValue String "" CSG
XmNvalueChangedCallback XmCCallback XtCallbackList NULL C
XmNactivateCallback
Specifies the list of callbacks that is called
when the user invokes an event that calls the
Activate() function. The structure returned by
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
- 2 -
XmText(3Xm) XmText(3Xm)
is determined by the number of characters from the
beginning of the text.
XmNeditable
Indicates that the user can edit the text string
when set to True. A false value will prohibit the
user from editing the text.
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.
XmNfocusCallback
Specifies the list of callbacks that is called
before Text has accepted input focus. The
structure returned by this callback is
XmAnyCallbackStruct. The reason sent by the
callback is XmCR_FOCUS.
XmNlosingFocusCallback
Specifies the list of callbacks that is called
before Text loses input focus. The structure
returned by 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 the bottom edge of
the widget window and the text. This resource is
forced to True when the Text widget is placed in a
ScrolledWindow with XmNscrollingPolicy set to
XmAUTOMATIC.
XmNmarginWidth
Specifies the distance between the left edge of
the widget window and the text, and the right edge
of the widget window and the text. This resource
is forced to True when the Text widget is placed
in a ScrolledWindow with XmNscrollingPolicy set to
XmAUTOMATIC.
XmNmaxLength
Specifies the maximum length of the text string
that can be entered into text from the keyboard.
Strings that are entered using the XmNvalue
resource or the XmTextSetString function ignore
- 3 -
XmText(3Xm) XmText(3Xm)
this resource.
XmNmodifyVerifyCallback
Specifies the list of callbacks that is called
before text is deleted from or inserted into Text.
The structure returned by this callback is
XmTextVerifyCallbackStruct. The reason sent by
the callback is XmCR_MODIFYING_TEXT_VALUE.
XmNmotionVerifyCallback
Specifies the list of callbacks that is called
before the insert cursor is moved to a new
position. The structure returned by this callback
is XmTextVerifyCallbackStruct. The reason sent
by the callback is XmCR_MOVING_INSERT_CURSOR.
XmNtopPosition
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.
XmNvalue
Displays the string value. XtGetValues returns
the value of the internal buffer and XtSetValues
copies the string values into the internal buffer.
XmNvalueChangedCallback
Specifies the list of callbacks that is called
after text is deleted from or inserted into Text.
The structure returned by this callback is
XmAnyCallbackStruct. The reason sent by the
callback is XmCR_VALUE_CHANGED.
XmText Input Resource Set
Name Class Type Default Access
____________________________________________________________________
XmNpendingDelete XmCPendingDelete Boolean True CSG
XmNselectionArray XmCSelectionArray Pointer sarray CSG
XmNselectThreshold XmCSelectThreshold int 5 CSG
XmNpendingDelete
Indicates that pending delete mode is on when the
Boolean 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.
Each mouse click performed within a half of a
second of the previous mouse click will increment
the index into this array and perform the defined
- 4 -
XmText(3Xm) XmText(3Xm)
action for that index. The possible actions are:
⊕ XmSELECT_POSITIONS - resets the insert cursor
position.
⊕ XmSELECT_WORD - selects a word.
⊕ XmSELECT_LINE - selects a line of text.
⊕ XmSELECT_ALL - selects all of the text.
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.
XmText Output Resource Set
Name Class Type Default Access
___________________________________________________________________________________
XmNblinkRate XmCBlinkRate int 500 CSG
XmNcolumns XmCColumns short 20 CSG
XmNcursorPositionVisible XmCCursorPositionVisible Boolean True CSG
XmNfontList XmCFontList XmFontList fixed CSG
XmNresizeHeight XmCResizeHeight Boolean False CSG
XmNresizeWidth XmCResizeWidth Boolean False CSG
XmNrows XmCRows short 1 CSG
XmNwordWrap XmCWordWrap Boolean False CSG
XmNblinkRate
Specifies the blink rate of the text cursor in
milliseconds. The time indicated in the blink rate
relates to the length of time the cursor is visible
and the time the cursor is invisible (i.e., the time
it will take to blink the insertion cursor on and
off will be 2 times the blink rate). The cursor
will not blink when the blink rate is set to zero.
XmNcolumns
Specifies the initial width of the text window
measured in character spaces.
XmNfontList
Specifies the font list to be used for Text.
XmNinsertionPointVisible
Indicates that the insert cursor position is marked
by a blinking text cursor when the Boolean is True.
XmNresizeHeight
Indicates that Text will attempt to resize its
height to accommodate all the text contained in the
- 5 -
XmText(3Xm) XmText(3Xm)
widget when Boolean is True. If set to True, the
text will always be displayed starting from the
first position in the source, even if instructed
otherwise. This attribute is ignored when using a
ScrolledText widget and when XmNscrollVertical is
True.
XmNresizeWidth
Indicates that Text will attempt to resize its width
to accommodate all the text contained in the widget
when Boolean 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.
XmNwordWrap
Indicates that lines are to be broken at word breaks
(i.e., the text does not go off the right edge of
the window) when Boolean 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 only used when text is
created in a ScrolledWindow. See the man page for
XmCreateScrolledText.
XmText ScrolledText Resource Set
Name Class Type Default Access
________________________________________________________________
XmNscrollHorizontal XmCScroll Boolean True CG
XmNscrollLeftSide XmCScrollSide Boolean False CG
XmNscrollTopSide XmCScrollSide Boolean False CG
XmNscrollVertical XmCScroll Boolean True CG
XmNscrollHorizontal
Adds a ScrollBar that allows the user to scroll
horizontally through text when Boolean 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.
- 6 -
XmText(3Xm) XmText(3Xm)
XmNscrollLeftSide
Indicates that the vertical ScrollBar should be
placed on the left side of the scrolled text window
when Boolean is True. This attribute is ignored if
XmNscrollVertical is False or the Text resource
XmNeditMode is XmSINGLE_LINE_EDIT.
XmNscrollTopSide
Indicates that the horizontal ScrollBar should be
placed on the top side of the scrolled text window
when Boolean is True.
XmNscrollVertical
Adds a ScrollBar that allows the user to scroll
vertically through text when Boolean is True. 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 these
resources, refer to the man page for that superclass.
XmPrimitive Resource Set
Name Class Type Default Access
______________________________________________________________________________________________
XmNbottomShadowColor XmCForeground Pixel dynamic CSG
XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNforeground XmCForeground Pixel dynamic CSG
XmNhelpCallback XmCCallback XtCallbackList NULL CSG
XmNhighlightColor XmCForeground Pixel Black CSG
XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG
XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG
XmNhighlightThickness XmCHighlightThickness short 0 CSG
XmNshadowThickness XmCShadowThickness short 2 CSG
XmNtopShadowColor XmCBackground Pixel dynamic CSG
XmNtopShadowPixmap XmCTopShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNtraversalOn XmCTraversalOn Boolean True N/A
XmNuserData XmCUserData caddr_t NULL CSG
Core Resource Set
Name Class Type Default Access
____________________________________________________________________________________________
XmNaccelerators XmCAccelerators XtTranslations NULL CSG
XmNancestorSensitive XmCSensitive Boolean True G
XmNbackground XmCBackground Pixel dynamic CSG
XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
- 7 -
XmText(3Xm) XmText(3Xm)
XmNborderColor XmCBorderColor Pixel Black CSG
XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNborderWidth XmCBorderWidth Dimension 0 CSG
XmNcolormap XmCColormap Colormap XtCopyFromParent CG
XmNdepth XmCDepth int XtCopyFromParent CG
XmNdestroyCallback XmCCallback XtCallbackList NULL C
XmNheight XmCHeight Dimension 0 CSG
XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG
XmNscreen XmCScreen Pointer XtCopyScreen CG
XmNsensitive XmCSensitive Boolean True CSG
XmNtranslations XmCTranslations XtTranslations NULL CSG
XmNwidth XmCWidth Dimension 0 CSG
XmNx XmCPosition Position 0 CSG
XmNy XmCPosition Position 0 CSG
Callback Information
The following structure is returned with 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 of the 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 following structure is
returned with XmNlosingFocusCallbacks,
XmNmodifyVerifyCallbacks, and
XmNmotionVerifyCallbacks.
typedef struct
{
int reason;
XEvent * event;
Boolean doit;
XmTextPosition currInsert, newInsert;
XmTextPosition startPos, endPos;
XmTextBlock text;
} XmTextVerifyCallbackStruct, *XmTextVerifyPtr;
- 8 -
XmText(3Xm) XmText(3Xm)
reason Indicates why the callback was invoked.
event Points to the XEvent that triggered the
callback.
doit Indicates whether that action that invoked the
callback will be 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, then
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 (e.g.,
FMT8BIT).
The following table describes the reasons for
which the individual verification callback
- 9 -
XmText(3Xm) XmText(3Xm)
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_TEXT_CURSOR | reason, event, doit, |
| | currInsert, |
| | newInsert |
|||
Behavior
The behavior for the Text widget is determined by the
XmNeditMode resource. Depending on how this resource
is set, some of the key bindings will perform different
actions. The possible values for XmNeditMode are
XmSINGLE_LINE_EDIT and XmMULTI_LINE_EDIT. The following
describes the key bindings for these edit modes.
Default Behavior (Single-line Text Edit)
<Btn1Down>:
This key binding performs the action defined in
the selection array depending on the number of
multiple mouse clicks. The default selection
array ordering is one click to move the insertion
cursor position, two clicks to select a word, and
three clicks to select a line of text.
It also begins text selection. Primary selected
text that was previously selected becomes
unselected.
Button1 <PtrMoved>:
Text is selected in the direction of the pointer
cursor movement. While the pointer cursor is
moved along the text, the text is selected from
the point the mouse button 1 was pressed to the
present position of the pointer cursor. Moving
the pointer cursor back over previously selected
text while mouse button 1 is pressed deselects the
text. Primary selected text is shown visibly by
inverted text.
- 10 -
XmText(3Xm) XmText(3Xm)
<Btn1Up>:
The selected text becomes the primary selection
(i.e., the selection is committed).
Shift <Btn1Down>:
The end points of the selection move to the point
where the pointer cursor is located when the
shifted mouse button 1 is pressed. If the pointer
cursor is located at a position where text is
already selected, the text following this position
becomes unselected.
<Btn2Up>:
The text is copied from the primary selection to
the insertion point located at the insert cursor.
This is shown visibly by underlined text.
CTRL <Btn2Up>:
The text is copied and cut from the primary
selection and is pasted to the insertion point
located at the insert cursor.
<Key> Right:
The insert cursor moves one character to the
right.
Shift <Key> Right:
The text character to the right of the insert
cursor is selected and inverted (i.e., primary
selection). If there is already selected text to
the right of the insert cursor, this text becomes
unselected one character at a time.
CTRL <Key> Right:
The insert cursor moves to the end of the line.
<Key> Left:
The insert cursor moves one character to the left.
Shift <Key> Left:
The text character to the left of the insert
cursor is selected and inverted. If there is
already selected text to the left of the insert
cursor, this text becomes unselected one character
at a time.
CTRL <Key> Left:
The insert cursor moves to the beginning of the
line.
<Key> Backspace:
The character of text immediately preceding the
- 11 -
XmText(3Xm) XmText(3Xm)
insert cursor is deleted.
<Key> Delete:
The character of text immediately following the
insert cursor is deleted.
Any <Key>:
This key binding inserts the character, associated
with the key pressed, into the text of the Text
widget.
<Key> Return:
Calls the callbacks for XmNactivateCallback.
Multiline Text Edit
Button1 <PtrMoved>:
Text is selected in the direction of the pointer
cursor movement. While the pointer cursor is
moved along the text, the text is selected from
the point that mouse button 1 was pressed to the
present position of the pointer cursor. Moving
the cursor over several lines selects text to the
end of each line passed over and up to the
position of the pointer cursor on the current
line. Moving the pointer cursor back over
previously selected text while mouse button 1 is
pressed deselects the text.
<Key> Up:
The insert cursor moves to the line directly above
the current line where the insert cursor is
residing.
<Key> Down:
The insert cursor moves to the line directly below
the current line where the insert cursor is
residing.
<Key> Return:
Inserts a new line at the point where the insert
cursor is positioned.
Default Translations
Default translations for Text are:
Shift<Key>Tab: prev-tab-group()
<Key>Tab: next-tab-group()
<Key>Up: traverse-prev()
<Key>Down: traverse-next()
- 12 -
XmText(3Xm) XmText(3Xm)
<Key>Home: traverse-home()
Ctrl<Key>Right:backward-word()
Shift<Key>Right:key-select(right)
<Key>Right: forward-character()
Ctrl<Key>Left: forward-word()
Shift<Key>Left:key-select(left)
<Key>Left: backward-character()
Shift<Key>BackSpace:delete-previous-word()
<Key>BackSpace:delete-previous-character()
<Key>Return: activate()
<Key>: self-insert()
Shift<Btn1Down>:extend-start()
<Btn1Down>: grab-focus()
Button1<PtrMoved>:extend-adjust()
<Btn1Up>: extend-end()
Ctrl<Btn3Up>: move-to()
<Btn3Up>: copy-to()
<LeaveWindow>: leave()
<FocusIn>: focusIn()
<FocusOut>: focusOut()
<Unmap>: unmap()
Shift<Key>Delete:delete-next-word()
<Key>Delete: delete-next-character()
The following default translations override the above
default translations when using Multiline Text Edit:
<Key>Tab: self-insert()
<Key>Up: previous-line()
<Key>Down: next-line()
<Key>Home: beginning-of-file()
<Key>Return: newline()
When changing from Multiline Text Edit to Single-line
Text Edit, the following default translations override
the Multiline Text Edit default translations.
<Key>Tab: next-tab-group()
<Key>Up: traverse-prev()
<Key>Down: traverse-next()
<Key>Home: traverse-home()
<Key>Return: activate()
Keyboard Traversal
Multiline Text Edit differs from standard traversal in
the following manner:
Up or Down Arrow - moves the insert cursor between
- 13 -
XmText(3Xm) XmText(3Xm)
lines.
Tab - inserts a tab.
Home - moves the insert cursor to the first
position (top) of the file.
Return - adds a new line.
Both Single-line and Multiline Text Edit differs
from standard traversal in the following manner:
Right or Left Arrows - moves the insert cursor to
the right or to the left.
For more information on keyboard traversal, see
the man page for XmPrimitive(3X) and its sections
on behavior and default translations.
RELATED INFORMATION
Core(3X), XmCreateScrolledText(3X), XmCreateText(3X),
XmPrimitive(3X), XmTextClearSelection(3X),
XmTextGetEditable(3X), XmTextGetMaxLength(3X),
XmTextGetSelection(3X), XmTextGetString(3X),
XmTextReplace(3X), XmTextSetEditable(3X),
XmTextSetMaxLength(3X), XmTextSetSelection(3X), and
XmTextSetString(3X).
- 14 -