 |
Index for
Section 3X |
|
 |
Alphabetical
listing for X |
|
 |
Bottom of
page |
|
XmText(3X)
OSF/Motif
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).
XmText Resource Set
XmNactivateCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNautoShowCursorPosition
Class: XmCAutoShowCursorPosition
Default: True
Type: Boolean
Access: CSG
XmNcursorPosition
Class: XmCCursorPosition
Default: 0
Type: XmTextPosition
Access: CSG
XmNeditable
Class: XmCEditable
Default: True
Type: Boolean
Access: CSG
XmNeditMode
Class: XmCEditMode
Default: XmSINGLE_LINE_EDIT
Type: int
Access: CSG
XmNfocusCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNgainPrimaryCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNlosePrimaryCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNlosingFocusCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNmarginHeight
Class: XmCMarginHeight
Default: 5
Type: Dimension
Access: CSG
XmNmarginWidth
Class: XmCMarginWidth
Default: 5
Type: Dimension
Access: CSG
XmNmaxLength
Class: XmCMaxLength
Default: largest integer
Type: int
Access: CSG
XmNmodifyVerifyCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNmodifyVerifyCallbackWcs
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNmotionVerifyCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNreconnectable
Class: XmCReconnectable
Default: False
Type: Boolean
Access: CSG
XmNsource
Class: XmCSource
Default: Default source
Type: XmTextSource
Access: CSG
XmNtopCharacter
Class: XmCTextPosition
Default: 0
Type: XmTextPosition
Access: CSG
XmNvalue
Class: XmCValue
Default: ""
Type: String
Access: CSG
XmNvalueChangedCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNvalueWcs
Class: XmCvalueWcs
Default: (wchar_t *)""
Type: wchar_t *
Access: CSG*
XmNverifyBell
Class: XmCVerifyBell
Default: dynamic
Type: Boolean
Access: CSG
* This resource cannot be set in a resource file.
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 XmNmotionVerifyCallback to be generated from a single action.
XmNreconnectable
Specifies that the XmText widget can reconnect to an Asian Input Method
server. When the resource value is set to True, reconnection is
allowed. When the resource value is set to False, the default,
reconnection is prohibited. (That is, the application must start after
the Input Method server is running.) The X11R6 standard callback
IMInstantiateCallback notifies the application when the Input Method
server is ready to accept client connections.
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.
XmText Input Resource Set
XmNpendingDelete
Class: XmCPendingDelete
Default: True
Type: Boolean
Access: CSG
XmNselectionArray
Class: XmCSelectionArray
Default: default array
Type: XtPointer
Access: CSG
XmNselectionArrayCount
Class: XmCSelectionArrayCount
Default: 4
Type: int
Access: CSG
XmNselectThreshold
Class: XmCSelectThreshold
Default: 5
Type: int
Access: CSG
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.
XmText Output Resource Set
XmNblinkRate
Class: XmCBlinkRate
Default: 500
Type: int
Access: CSG
XmNcolumns
Class: XmCColumns
Default: dynamic
Type: short
Access: CSG
XmNcursorPositionVisible
Class: XmCCursorPositionVisible
Default: True
Type: Boolean
Access: CSG
XmNfontList
Class: XmCFontList
Default: dynamic
Type: XmFontList
Access: CSG
XmNresizeHeight
Class: XmCResizeHeight
Default: False
Type: Boolean
Access: CSG
XmNresizeWidth
Class: XmCResizeWidth
Default: False
Type: Boolean
Access: CSG
XmNrows
Class: XmCRows
Default: dynamic
Type: short
Access: CSG
XmNwordWrap
Class: XmCWordWrap
Default: False
Type: Boolean
Access: CSG
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.
XmText ScrolledText Resource Set
XmNscrollHorizontal
Class: XmCScroll
Default: True
Type: Boolean
Access: CG
XmNscrollLeftSide
Class: XmCScrollSide
Default: dynamic
Type: Boolean
Access: CG
XmNscrollTopSide
Class: XmCScrollSide
Default: False
Type: Boolean
Access: CG
XmNscrollVertical
Class: XmCScroll
Default: True
Type: Boolean
Access: CG
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.
XmPrimitive Resource Set
XmNbottomShadowColor
Class: XmCBottomShadowColor
Default: dynamic
Type: Pixel
Access: CSG
XmNbottomShadowPixmap
Class: XmCBottomShadowPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
XmNforeground
Class: XmCForeground
Default: dynamic
Type: Pixel
Access: CSG
XmNhelpCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNhighlightColor
Class: XmCHighlightColor
Default: dynamic
Type: Pixel
Access: CSG
XmNhighlightOnEnter
Class: XmCHighlightOnEnter
Default: False
Type: Boolean
Access: CSG
XmNhighlightPixmap
Class: XmCHighlightPixmap
Default: dynamic
Type: Pixmap
Access: CSG
XmNhighlightThickness
Class: XmCHighlightThickness
Default: 2
Type: Dimension
Access: CSG
XmNnavigationType
Class: XmCNavigationType
Default: XmTAB_GROUP
Type: XmNavigationType
Access: CSG
XmNshadowThickness
Class: XmCShadowThickness
Default: 2
Type: Dimension
Access: CSG
XmNtopShadowColor
Class: XmCTopShadowColor
Default: dynamic
Type: Pixel
Access: CSG
XmNtopShadowPixmap
Class: XmCTopShadowPixmap
Default: dynamic
Type: Pixmap
Access: CSG
XmNtraversalOn
Class: XmCTraversalOn
Default: True
Type: Boolean
Access: CSG
XmNunitType
Class: XmCUnitType
Default: dynamic
Type: unsigned char
Access: CSG
XmNuserData
Class: XmCUserData
Default: NULL
Type: XtPointer
Access: CSG
Core Resource Set
XmNaccelerators
Class: XmCAccelerators
Default: dynamic
Type: XtAccelerators
Access: CSG
XmNancestorSensitive
Class: XmCSensitive
Default: dynamic
Type: Boolean
Access: G
XmNbackground
Class: XmCBackground
Default: dynamic
Type: Pixel
Access: CSG
XmNbackgroundPixmap
Class: XmCPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
XmNborderColor
Class: XmCBorderColor
Default: XtDefaultForeground
Type: Pixel
Access: CSG
XmNborderPixmap
Class: XmCPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
XmNborderWidth
Class: XmCBorderWidth
Default: 0
Type: Dimension
Access: CSG
XmNcolormap
Class: XmCColormap
Default: dynamic
Type: Colormap
Access: CG
XmNdepth
Class: XmCDepth
Default: dynamic
Type: int
Access: CG
XmNdestroyCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNheight
Class: XmCHeight
Default: dynamic
Type: Dimension
Access: CSG
XmNinitialResourcesPersistent
Class: XmCInitialResourcesPersistent
Default: True
Type: Boolean
Access: C
XmNmappedWhenManaged
Class: XmCMappedWhenManaged
Default: True
Type: Boolean
Access: CSG
XmNscreen
Class: XmCScreen
Default: dynamic
Type: Screen *
Access: CG
XmNsensitive
Class: XmCSensitive
Default: True
Type: Boolean
Access: CSG
XmNtranslations
Class: XmCTranslations
Default: dynamic
Type: XtTranslations
Access: CSG
XmNwidth
Class: XmCWidth
Default: dynamic
Type: Dimension
Access: CSG
XmNx
Class: XmCPosition
Default: 0
Type: Position
Access: CSG
XmNy
Class: XmCPosition
Default: 0
Type: Position
Access: CSG
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 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
VirtualBindings(3X).
SEE ALSO
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),
XmTextXYToPos(3X)
|
Index for
Section 3X |
|
|
Alphabetical
listing for X |
|
 |
Top of
page |
|