XMTEXTFIELD(3)

📦
version 2.3.8 · 3 versions
, in arch rolling, centos-stream 9, epel 10, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0

💖 XmTextField 💖

okay bestie, welcome to the library call manual page for XmTextField — she's the TextField class, and she's literally here to make single-line text editing feel iconic. 💅

✨ NAME ✨

XmTextField — The TextField class.

🦋 SYNOPSIS 🦋

#include <Xm/Xm.h>

💅 DESCRIPTION 💅

The TextField widget is a single line text editor for customizing both user and programmatic interfaces. She's used for single-line string entry, and for forms entry with verification procedures. She gives an application a consistent editing system for textual data. Periodt.

TextField provides separate callback lists to verify movement of the insert cursor, modification of the text, and changes in input focus. Each of these callbacks gives the verification function the widget instance, the event that caused the callback, and a data structure specific to the verification type. From this info, the function can verify if the application considers this a legitimate state change, and can signal the widget whether to continue with the action. No cap.

The user interface tailors a new set of actions. Key bindings have been added for insert cursor movement, deletion, insertion, and selection of text.

TextField allows the user to select regions of text. Selection is based on the model specified in the Inter-Client Communication Conventions Manual (ICCCM). TextField supports primary and secondary selection.

TextField uses the XmQTnavigator, XmQTspecifyRenderTable, and XmQTscrollFrame traits, and holds the XmQTaccessTextual XmQTtransfer traits.

If an application or widget calls the setValue trait method of XmQTaccessTextual, then XmTextField will call XmTextFieldSetString to set the string value. Slay.

🌈 Data Transfer Behavior 🌈

TextField supports transfer of the primary, secondary, and clipboard selections and dragging of selected text from the widget. TextField can also be the destination for the primary, secondary, and clipboard selections, and she supports dropping of data being dragged onto the widget. 💖

When the XmNconvertCallback procedures are called, the location_data member of the XmConvertCallbackStruct member is NULL if the selected text is being transferred. If the entire text, not the selected text, is being transferred, the value of this member is the widget ID of the TextField widget.

As a source of data, TextField supports the following targets and associated conversions of data to these targets:

  • UTF8_STRING — The widget transfers the selected text as type UTF8_STRING.
  • locale — If the locale target matches the widget's locale, the widget transfers the selected text in the encoding of the locale.
  • COMPOUND_TEXT — The widget transfers the selected text as type COMPOUND_TEXT.
  • STRING — The widget transfers the selected text as type STRING.
  • TEXT — If the selected text is fully convertible to the encoding of the locale, the widget transfers the selected text in the encoding of the locale. Otherwise, the widget transfers the selected text as type COMPOUND_TEXT.
  • DELETE — The widget deletes the selected text.
  • _MOTIF_CLIPBOARD_TARGETS — The widget transfers, as type ATOM, a list of the targets to which the widget can convert data to be placed on the clipboard immediately. These include the following targets:
    • UTF8_STRING
    • COMPOUND_TEXT
    • The encoding of the locale, if the selected text is fully convertible to the encoding of the locale
    • STRING, if the selected text is fully convertible to STRING
  • _MOTIF_EXPORT_TARGETS — The widget transfers, as type ATOM, a list of the targets to be used as the value of the DragContext's XmNexportTargets in a drag-and-drop transfer. These include COMPOUND_TEXT, the encoding of the locale, STRING, TEXT, UTF8_STRING, BACKGROUND, and FOREGROUND.
  • _MOTIF_LOSE_SELECTION — The widget takes the following actions:
    • When losing the PRIMARY selection, it unhighlights the selected text and calls the XmNlosePrimaryCallback procedures.
    • When losing the SECONDARY selection, it removes the secondary selection highlight.
    • When losing the _MOTIF_DESTINATION selection, if the widget does not have focus it changes the cursor to indicate that the widget is no longer the destination.

As a source of data, TextField also supports the following standard Motif targets:

  • BACKGROUND — The widget transfers XmNbackground as type PIXEL.
  • CLASS — The widget finds the first shell in the widget hierarchy that has a WM_CLASS property and transfers the contents as text in the current locale.
  • CLIENT_WINDOW — The widget finds the first shell in the widget hierarchy and transfers its window as type WINDOW.
  • COLORMAP — The widget transfers XmNcolormap as type COLORMAP.
  • FOREGROUND — The widget transfers XmNforeground as type PIXEL.
  • NAME — The widget finds the first shell in the widget hierarchy that has a WM_NAME property and transfers the contents as text in the current locale.
  • TARGETS — The widget transfers, as type ATOM, a list of the targets it supports. These include the standard targets in this list. These also include COMPOUND_TEXT, the encoding of the locale, STRING, TEXT and UTF8_STRING.
  • TIMESTAMP — The widget transfers the timestamp used to acquire the selection as type INTEGER.
  • _MOTIF_RENDER_TABLE — The widget transfers XmNrenderTable if it exists, or else the default text render table, as type STRING.
  • _MOTIF_ENCODING_REGISTRY — The widget transfers its encoding registry as type STRING. The value is a list of NULL separated items in the form of tag encoding pairs. This target symbolizes the transfer target for the Motif Segment Encoding Registry. Widgets and applications can use this Registry to register text encoding formats for specified render table tags. Applications access this Registry by calling XmRegisterSegmentEncoding and XmMapSegmentEncoding.

As a destination for data, TextField chooses a target and requests conversion of the selection to that target. If the encoding of the locale is present in the list of available targets, TextField chooses a requested target from the available targets in the following order of preference:

  1. TEXT
  2. UTF8_STRING
  3. COMPOUND_TEXT
  4. The encoding of the locale
  5. STRING

If the encoding of the locale is not present in the list of available targets, TextField chooses a requested target from the available targets in the following order of preference:

  1. UTF8_STRING
  2. COMPOUND_TEXT
  3. STRING

👑 Classes 👑

TextField widget inherits behavior, resources, and traits from Core and Primitive.

The class pointer is xmTextFieldWidgetClass.

The class name is XmTextField.

🌸 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).

✨ XmTextField Resource Set ✨

okay bestie, here's the whole roster 💖 — every single resource XmTextField has, with its class, its type, its default, and its access code. we are NOT skipping a single one, we're reading the entire list like the dedicated icons we are 📚✨

heads up on that last column: Access is literally the code the original gives, C or CSG. that's it, that's the data, no editorialising 🫶
  • XmNactivateCallback — class XmCCallback, type XtCallbackList, default NULL, access C — the activate callback slot, sitting at NULL until you give it a job 🎀
  • XmNblinkRate — class XmCBlinkRate, type int, default 500, access CSG — blink speed, defaulting to a chill 500 ✨
  • XmNcolumns — class XmCColumns, type short, default dynamic, access CSG — the width in columns, and the default is dynamic, which is giving "it decides for itself" 💅
  • XmNcursorPosition — class XmCCursorPosition, type XmTextPosition, default 0, access CSG — starts at 0, the very beginning, main character energy from position zero 👑
  • XmNcursorPositionVisible — class XmCCursorPositionVisible, type Boolean, default dynamic, access CSG — whether the cursor shows up, default dynamic
  • XmNdestinationCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNeditable — class XmCEditable, type Boolean, default True, access CSG — yes bestie, by default you can actually type in it, True fr fr ⌨️
  • XmNfocusCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNfontList — class XmCFontList, type XmFontList, default dynamic, access CSG — the font list, defaulting to dynamic 🦋
  • XmNgainPrimaryCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNlosePrimaryCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNlosingFocusCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNmarginHeight — class XmCMarginHeight, type Dimension, default 5, access CSG — breathing room top and bottom, 5 units of it 🌸
  • XmNmarginWidth — class XmCMarginWidth, type Dimension, default 5, access CSG — same deal but sideways, also 5
  • XmNmaxLength — class XmCMaxLength, type int, default largest integer, access CSG — the character limit, and the default is literally largest integer, so no cap on the vibes 😭🔥
  • XmNmodifyVerifyCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNmodifyVerifyCallbackWcs — class XmCCallback, type XtCallbackList, default NULL, access C — the wide-character sibling, same everything else 🧚
  • XmNmotionVerifyCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNpendingDelete — class XmCPendingDelete, type Boolean, default True, access CSG
  • XmNrenderTable — class XmCRenderTable, type XmRenderTable, default dynamic, access CSG
  • XmNresizeWidth — class XmCResizeWidth, type Boolean, default False, access CSG — False by default, so it is NOT out here resizing itself unprompted 💀
  • XmNselectionArray — class XmCSelectionArray, type XtPointer, default default array, access CSG — default is, and I quote, default array ⭐
  • XmNselectionArrayCount — class XmCSelectionArrayCount, type int, default 3, access CSG
  • XmNselectThreshold — class XmCSelectThreshold, type int, default 5, access CSG
  • XmNvalue — class XmCValue, type String, default "", access CSG — the actual text content, empty string "" until you say otherwise 💜
  • XmNvalueChangedCallback — class XmCCallback, type XtCallbackList, default NULL, access C

and that's the table, bestie — every name, every class, every type, every default, every access code, accounted for 💖 keep reading, there's more coming 🫶✨

  • XmNvalueWcs — class XmCValueWcs, type wchar_t *, default (wchar_t *)"", access CSG^1
  • XmNverifyBell — class XmCVerifyBell, type Boolean, default dynamic, access CSG
^1 This resource cannot be specified in a resource file. iykyk.

XmNactivateCallback Specifies the list of callbacks that is called when the user invokes an event that calls the activate() action. The type of the structure whose address is passed to this callback is XmAnyCallbackStruct. The reason sent by the callback is XmCR_ACTIVATE.

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 (that is, the time it will take to blink the insertion cursor on and off will be two times the blink rate). The cursor will not blink when the blink rate is set to 0 (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 width as derived from the specified font. If the em-space value is available, it is used. If not, the width of the numeral "0" is used. If this is not available, the maximum width is used. For proportionate fonts, the actual number of characters that fit on a given line may be greater than the value specified.

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.

XmNcursorPositionVisible If the text widget has an XmPrintShell as one of its ancestors (that is, the widget was created on a print server connection) then the default value is False; otherwise, it is True. 💅

XmNdestinationCallback Specifies a list of callbacks called when the widget is the destination of a transfer operation. The type of the structure whose address is passed to these callbacks is XmDestinationCallbackStruct. The reason is XmCR_OK.

XmNeditable When set to True, indicates that the user can edit the text string. A false value will prohibit the user from editing the text.

When XmNeditable is used on a widget it sets the dropsite to XmDROP_SITE_ACTIVE.

XmNfocusCallback Specifies the list of callbacks called when TextField 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.

XmNfontList Specifies the font list to be used for TextField. The font list is an obsolete structure, and is retained only for compatibility with earlier releases of Motif. Use the render table (XmNrenderTable) instead of font lists wherever possible. If both are specified, the render table will take precedence. If this value is NULL at initialization, the parent hierarchy of the widget is searched for an ancestor that holds the XmQTspecifyRenderTable trait. If such an ancestor is found, the font list is initialized to the XmTEXT_RENDER_TABLE value of the ancestor widget. If no such ancestor is found, the default is implementation dependent.

TextField searches the font list for the first occurrence of a font set that has an 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(3) for more information on a font list structure.

XmNgainPrimaryCallback Specifies the list of callbacks that are called when the user invokes an event that causes the text widget to gain ownership of the primary selection. The callback reason for this callback is XmCR_GAIN_PRIMARY.

XmNlosePrimaryCallback Specifies the list of callbacks that are called when the user invokes an event that cause the text widget to lose ownership of the primary selection. The callback reason for this callback is XmCR_LOSE_PRIMARY.

XmNlosingFocusCallback Specifies the list of callbacks that are called before TextField widget 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 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 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 nonnegative. Strings that are entered using the XmNvalue resource or the XmTextFieldSetString function ignore this resource.

XmNmodifyVerifyCallback Specifies the list of callbacks that is called before text is deleted from or inserted into TextField. 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 TextField 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 is 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 TextField 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 is 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 that is called before the insert cursor is moved to a new position. The type of the structure whose address is passed to this callback is XmTextVerifyCallbackStruct. The reason sent by the callback is XmCR_MOVING_INSERT_CURSOR. It is possible for more than one XmNmotionVerifyCallbacks to be generated from a single action. 😭

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.

XmNrenderTable Specifies the render table to be used in deriving a font set or font for displaying text. If both a render table and a font list are specified, the render table will take precedence. If the value of XmNrenderTable is NULL at initialization, the parent hierarchy of the widget is searched for an ancestor that holds the XmQTspecifyRenderTable trait. If such an ancestor is found, the font list is initialized to the XmTEXT_RENDER_TABLE value of the ancestor widget. If no such ancestor is found, the default is implementation dependent.

TextField searches the render table for the first occurrence of a rendition that has the tag _MOTIF_DEFAULT_LOCALE. If a default element is not found, the first rendition in the table is used. Refer to XmRenderTable(3) for more information on the render table structure.

XmNresizeWidth Indicates that the TextField widget will attempt to resize its width to accommodate all the text contained in the widget when Boolean is True.

  • XmNselectionArray — this is the lil choreography list for when you click a bunch of times 🎀. Every mouse click that lands within some time of the previous click bumps the index into this array up by one and runs whatever action lives at that index. (That "multi-click" window is decided by your operating environment, so it's different on different systems — generally it's some fraction of a second, iykyk.) The actions you can slot in are:
    • XmSELECT_POSITION — resets the insert cursor position ✨
    • XmSELECT_WORD — selects a word
    • XmSELECT_LINE — selects a line of text
  • XmNselectionArrayCount — how many actions are actually defined in the XmNselectionArray resource. Heads up bestie, this value must not be negative 💀
  • XmNselectThreshold — the number of pixels of motion required to select the next character when you're doing selection in click-drag mode. Again, the value must not be negative. This resource is also the one that says whether a drag should be started and how many pixels it takes to start a drag when Btn2Down and Btn1Down are integrated. multitasking queen 💅
  • XmNvalue — the string value of the TextField widget, as a char* data value. It moves the cursor to position 0 unless you explicitly handed over a value of XmNcursorPosition in the argument list. And if XmNvalue and XmNvalueWcs are both defined? Then XmNvalueWcs supersedes XmNvalue, no debate 🫶. XtGetValues returns a copy of the value of the internal buffer, and XtSetValues copies the string values into the internal buffer.
  • XmNvalueChangedCallback — the list of callbacks that fire after text is deleted from or inserted into the TextField. The type of the structure whose address gets passed to this callback is XmAnyCallbackStruct, and the reason sent by the callback is XmCR_VALUE_CHANGED. Important: XmNvalueChangedCallback should occur only in pairs with a XmNmodifyVerifyCallback — assuming the doit flag in the callback structure of the XmNmodifyVerifyCallback is not set to False. they're a matched set, fr fr 👑
  • XmNvalueWcs — the string value of the TextField widget, but as a wchar_t* data value. Like its sibling, it moves the cursor to position 0 unless a value of XmNcursorPosition was explicitly supplied in the argument list.
Okay so real talk: this resource cannot be specified in a resource file. Not negotiable. 🙈

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, and XtSetValues copies the value of the wide character string into the internal buffer. wide character queen behavior 🌈

  • XmNverifyBell — says whether a bell will sound when an action is reversed during a verification callback. The default here isn't fixed — it depends on the value of the ancestor VendorShell's XmNaudibleWarning resource. it's giving inherited personality 😭

🌸 Inherited Resources 🌸

TextField widget inherits behavior and resources from the superclasses in the following tables. For a complete description of these resources, go read the reference page for that superclass — they said what they said 💖

🌸 the XmPrimitive resource set, bestie 🌸

okay so this is the whole inheritance tea — everything XmPrimitive brings to the table. Every row = one resource, and ima give you the full rundown: the name, its class, the type, the default, and the access. no skips, no cuts, we're doing all of them. 💅

  • XmNbottomShadowColor — class XmCBottomShadowColor, type Pixel, default dynamic, access CSG
  • XmNbottomShadowPixmap — class XmCBottomShadowPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG
  • XmNconvertCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNforeground — class XmCForeground, type Pixel, default dynamic, access CSG
  • XmNhelpCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNhighlightColor — class XmCHighlightColor, type Pixel, default dynamic, access CSG
  • XmNhighlightOnEnter — class XmCHighlightOnEnter, type Boolean, default False, access CSG
  • XmNhighlightPixmap — class XmCHighlightPixmap, type Pixmap, default dynamic, access CSG
  • XmNhighlightThickness — class XmCHighlightThickness, type Dimension, default 2, access CSG
  • XmNlayoutDirection — class XmCLayoutDirection, type XmDirection, default dynamic, access CG
  • XmNnavigationType — class XmCNavigationType, type XmNavigationType, default XmTAB_GROUP, access CSG
  • XmNpopupHandlerCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNshadowThickness — class XmCShadowThickness, type Dimension, default 2, access CSG
  • XmNtopShadowColor — class XmCTopShadowColor, type Pixel, default dynamic, access CSG
  • XmNtopShadowPixmap — class XmCTopShadowPixmap, type Pixmap, default dynamic, access CSG
  • XmNtraversalOn — class XmCTraversalOn, type Boolean, default True, access CSG
  • XmNunitType — class XmCUnitType, type unsigned char, default dynamic, access CSG
  • XmNuserData — class XmCUserData, type XtPointer, default NULL, access CSG

and that's the whole set, every last one of them, no crumbs left behind 🫶 note how most of them are CSG coded (the classic little trio of access vibes) while the callback ones keep it minimal at just C, and XmNlayoutDirection is the one solo icon rocking CG like the main character it is. 💜

a bunch of these default to dynamic which basically means the toolkit figures it out for you, and the callback defaults are all sitting pretty at NULL until you wire something up. the two thickness ones — XmNhighlightThickness and XmNshadowThickness — both clock in at 2, cute and consistent. ✨

heads up bestie: this is the XmPrimitive resource set specifically — the classes XmPrimitive gives you — so don't go looking for widget-specific extras here, those live with their own widgets. 😭

more coming, stay tuned 🎀

💖 Core Resource Set 💖

ok so here's the whole menu of core resources, bestie — name, class, type, default, and access, all of it, no skips:

  • XmNaccelerators — class XmCAccelerators, type XtAccelerators, default dynamic, access CSG
  • XmNancestorSensitive — class XmCSensitive, type Boolean, default dynamic, access G
  • XmNbackground — class XmCBackground, type Pixel, default dynamic, access CSG
  • XmNbackgroundPixmap — class XmCPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG
  • XmNborderColor — class XmCBorderColor, type Pixel, default XtDefaultForeground, access CSG
  • XmNborderPixmap — class XmCPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG
  • XmNborderWidth — class XmCBorderWidth, type Dimension, default 0, access CSG
  • XmNcolormap — class XmCColormap, type Colormap, default dynamic, access CG
  • XmNdepth — class XmCDepth, type int, default dynamic, access CG
  • XmNdestroyCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNheight — class XmCHeight, type Dimension, default dynamic, access CSG
  • XmNinitialResourcesPersistent — class XmCInitialResourcesPersistent, type Boolean, default True, access C
  • XmNmappedWhenManaged — class XmCMappedWhenManaged, type Boolean, default True, access CSG
  • XmNscreen — class XmCScreen, type Screen *, default dynamic, access CG
  • XmNsensitive — class XmCSensitive, type Boolean, default True, access CSG
  • XmNtranslations — class XmCTranslations, type XtTranslations, default dynamic, access CSG
  • XmNwidth — class XmCWidth, type Dimension, default dynamic, access CSG
  • XmNx — class XmCPosition, type Position, default 0, access CSG
  • XmNy — class XmCPosition, type Position, default 0, access CSG

🌸 Callback Information 🌸

ok so every single callback gets handed a pointer to this little guy right here:

typedef struct
{
        int reason;
        XEvent * event;
} XmAnyCallbackStruct;
  • reason — spills the tea on why the callback got invoked 👀
  • event — points at the XEvent that triggered the callback

ngl this next bit is important, so lock in 💅 The TextField widget defines a brand new callback structure for use with verification callbacks. And heads up — not all of the fields are relevant for every callback reason. So the app has to peek at the reason field first, and then only touch the structure members that are actually valid for that particular reason. Periodt.

The values startPos, endPos, and text inside the callback structure XmTextVerifyCallbackStruct can be modified when you receive the callback, and those changes will be reflected as the change made to the source of the TextField widget. (Like, for example, all keystrokes can be converted to spaces or NULL characters when a password is entered into a TextField widget. iconic behaviour honestly 🔥) The application programmer should not overwrite the text field — instead, attach data to that pointer. got it? 🫶

A pointer to the following structure is passed to the callbacks for XmNlosingFocusCallback, XmNmodifyVerifyCallback, and XmNmotionVerifyCallback.

okay so here's the struct itself, the one that shows up at your verify callbacks, in all its ✨glory✨:

typedef struct
{
        int reason;
        XEvent *event;
        Boolean doit;
        XmTextPosition currInsert, newInsert;
        XmTextPosition startPos, endPos;
        XmTextBlock text;
} XmTextVerifyCallbackStruct, *XmTextVerifyPtr;

And here's the field-by-field breakdown, because every one of these matters:

  • reason — why the callback got invoked. That's the whole job.
  • event — points to the XEvent that triggered the callback. It can be NULL. For example, when the Text widget gets changed programmatically there's literally no event to hand over to the associated callback, so it's just vibing as NULL.
  • doit — tells you whether the action that invoked the callback is actually gonna happen. Set doit to False and you negate the action. 🛑 But bestie, listen: not every action can be negated. For example, XmCR_LOSING_FOCUS callbacks may be completely beyond the widget's control if they come from mouse clicks. Not everything is yours to cancel, sorry.
  • currInsert — where the insert cursor is sitting right now.
  • newInsert — where the user is trying to put the insert cursor.
  • startPos — the starting position of the text to modify. If the callback isn't a modify verification callback, this value equals currInsert.
  • endPos — the ending position of the text to modify. If nothing gets replaced or deleted, it equals startPos. And again, if the callback isn't a modify verification callback, this equals currInsert.
  • text — points to the following structure of type XmTextBlockRec. This structure holds the textual information that's about to be inserted.
typedef struct
{
        char *ptr;
        int length;
        XmTextFormat format
} XmTextBlockRec, *XmTextBlock;
  • ptr — the text to be inserted. Heads up: ptr points to temporary storage space that gets reused once the callback finishes. So if your application needs to keep that text around, it has to copy it into its own data space. No borrowing, bestie. 🙈
  • length — how long the text to be inserted is.
  • format — the format of the text, either XmFMT_8_BIT or XmFMT_16_BIT.
(and yes, there is no semicolon after format up there — that's exactly how it's written, don't come for me 🫶)

A pointer to the following structure is what gets passed to callbacks for XmNmodifyVerifyCallbackWcs.

typedef struct
{
        int reason;
        XEvent *event;
        Boolean doit;
        XmTextPosition currInsert, newInsert;
        XmTextPosition startPos, endPos;
        XmWcsTextBlock text;
} XmTextVerifyCallbackStructWcs, *XmTextVerifyPtrWcs;
  • reason — why the callback got invoked.
  • event — points to the XEvent that triggered the callback. It can be NULL. For example, changes made to the Text widget programmatically don't have an event that can be passed to the associated callback.
  • doit — whether the action that invoked the callback gets performed. Setting doit to False negates the action. And again, not all actions may be negated. For example, XmCR_LOSING_FOCUS callbacks may be beyond the control of the widget if they're produced by mouse clicks.
  • currInsert — the current position of the insert cursor.
  • newInsert — the position at which the user attempts to position the insert cursor.
  • startPos — 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 — 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 the following 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 — the number of characters to be inserted.

So which fields are even valid depends entirely on the reason. Here's the full vibe check, and remember: the event field will never be valid for XmCR_MOVING_INSERT_CURSOR. Never ever. 💀

  • XmCR_LOSING_FOCUS — valid fields: reason, event, doit
  • XmCR_MODIFYING_TEXT_VALUE — valid fields: reason, event, doit, currInsert, newInsert, startPos, endPos, text
  • XmCR_MOVING_INSERT_CURSOR — valid fields: reason, doit, currInsert, newInsert

A pointer to the following callback structure is what gets passed to the XmNdestinationCallback procedures:

typedef struct
{
        int reason;
        XEvent *event;
        Atom selection;
        XtEnum operation;
        int flags;
        XtPointer transfer_id;
        XtPointer destination_data;
        XtPointer location_data;
        Time time;
} XmDestinationCallbackStruct;
  • reason — why the callback got invoked.
  • event — points to the XEvent that triggered the callback. It can be NULL.
  • selection — the selection for which data transfer is being requested. Possible values are CLIPBOARD, PRIMARY, SECONDARY, and _MOTIF_DROP.
  • operation — the type of transfer operation requested. And it depends on the selection, so buckle up:
    • When the selection is PRIMARY or SECONDARY, possible values are XmMOVE, XmCOPY, and XmLINK.
    • When the selection is CLIPBOARD, possible values are XmCOPY and XmLINK.
    • When the selection is _MOTIF_DROP, possible values are XmMOVE, XmCOPY, XmLINK, and XmOTHER. A value of XmOTHER means the callback procedure must go get further information from the XmDropProcCallbackStruct in the destination_data member.
  • flags — whether or not the destination widget is also the source of the data being transferred. Possible values:
    • XmCONVERTING_NONE — the destination widget is not the source of the data to be transferred.
    • XmCONVERTING_SAME — the destination widget is the source of the data to be transferred.
  • transfer_id — serves as a unique ID to identify the transfer transaction. It's the receipt, basically. 🧾
  • destination_data — contains information about the destination. When the selection is _MOTIF_DROP, the callback procedures are called by the drop site's XmNdropProc, and destination_data is a pointer to the XmDropProcCallbackStruct passed to the XmNdropProc procedure. When the selection is SECONDARY, destination_data is an Atom representing a target recommmended by the selection owner for use in converting the selection. Otherwise, destination_data is NULL.
  • location_data — contains information about the location where data is to be transferred. The value is always NULL when the selection is CLIPBOARD. If the value is NULL, the data is to be inserted at the widget's cursor position. Otherwise, the value is a pointer to an XPoint structure containing the x and y coordinates at the location where the data is to be transferred. 🚨 And once XmTransferDone procedures start to be called, location_data will no longer be stable. Do not hold onto it.
  • time — the time when the transfer operation began. ⏰

✨ Translations ✨

The XmTextField translations are described in the list below. The actions represent the effective behavior of the associated events, and they may differ in a right-to-left language environment.

The following key names are listed in the X standard key event translation table syntax. This format is the one Motif uses to specify the widget actions corresponding to a given key. There's a brief overview of the format over in VirtualBindings(3). For a complete description of the format, please refer to the X Toolkit Instrinsics Documentation. 📚

  • ∼c s ∼m ∼a <Btn1Down>: — extend-start()
  • c ∼s ∼m ∼a <Btn1Down>: — move-destination()
  • ∼c ∼s ∼m ∼a <Btn1Down>: — grab-focus()
  • ∼c ∼m ∼a <Btn1Motion>: — extend-adjust()
  • ∼c ∼m ∼a <Btn1Up>: — extend-end()
  • <Btn2Down>: — process-bdrag()
  • m ∼a <Btn2Motion>: — secondary-adjust()
  • ∼m a <Btn2Motion>: — secondary-adjust()
  • s c <Btn2Up>: — link-to()
  • ∼s <Btn2Up>: — copy-to()
  • ∼c <Btn2Up>: — move-to()
  • :m <Key><osfPrimaryPaste>: — cut-primary()
  • :a <Key><osfPrimaryPaste>: — cut-primary()
  • :<Key><osfPrimaryPaste>: — copy-primary()
  • :m <Key><osfCut>: — cut-primary()
  • :a <Key><osfCut>: — cut-primary()
  • :<Key><osfCut>: — cut-clipboard()
  • :<Key><osfPaste>: — paste-clipboard()
  • :m <Key><osfCopy>: — copy-primary()
  • :a <Key><osfCopy>: — copy-primary()
  • :<Key><osfCopy>: — copy-clipboard()
:s <Key><osfBeginLine>:
          beginning-of-line(extend)

:<Key><osfBeginLine>:
          beginning-of-line()

:s <Key><osfEndLine>:
          end-of-line(extend)

:<Key><osfEndLine>:
          end-of-line()

:s <Key><osfPageLeft>:
          page-left(extend)

:<Key><osfPageLeft>:
          page-left()

:s c<Key><osfPageUp>:
          page-left(extend)

:c <Key><osfPageUp>:
          page-left()

:s <Key><osfPageRight>:
          page-right(extend)

:<Key><osfPageRight>:
          page-right()

s c <Key><osfPageDown>:
          page-right(extend)

:c <Key><osfPageDown>:
          page-right()

:<Key><osfClear>:
          clear-selection()

:<Key><osfBackSpace>:
          delete-previous-character()

:s m <Key><osfDelete>:
          cut-primary()

:s a <Key><osfDelete>:
          cut-primary()

:s <Key><osfDelete>:
          cut-clipboard()

:c <Key><osfDelete>:
          delete-to-end-of-line()

:<Key><osfDelete>:
          delete-next-character()

:c m <Key><osfInsert>:
          copy-primary()

:c a <Key><osfInsert>:
          copy-primary()

:s <Key><osfInsert>:
          paste-clipboard()

:c <Key><osfInsert>:
          copy-clipboard()

:<Key><osfInsert>:
          toggle-overstrike()

:s <Key><osfSelect>:
          key-select()

:<Key><osfSelect>:
          set-anchor()

:<Key><osfSelectAll>:
          select-all()

:<Key><osfDeselectAll>:
          deselect-all()

:<Key><osfActivate>:
          activate()

:<Key><osfAddMode>:
          toggle-add-mode()

:<Key><osfHelp>:
          Help()

:<Key><osfCancel>:
          process-cancel()

:s c <Key><osfLeft>:
          backward-word(extend)

:c <Key><osfLeft>:
          backward-word()

:s <Key><osfLeft>:
          key-select(left)

:<Key><osfLeft>:
          backward-character()

:s c <Key><osfRight>:
          forward-word(extend)

:c <Key><osfRight>:
          forward-word()

:s <Key><osfRight>:
          key-select(right)

:<Key><osfRight>:
          forward-character()

:<Key><osfUp>:
          traverse-prev()

:<Key><osfDown>:
          traverse-next()

c ∼m ∼a <Key>slash:
          select-all()

c ∼m ∼a <Key>backslash:
          deselect-all()

s ∼m ∼a <Key>Tab:
          prev-tab-group()

∼m ∼a <Key>Tab:
          next-tab-group()

∼s ∼m ∼a <Key>Return:
          activate()

c ∼s ∼m ∼a <Key>space:
          set-anchor()

c s ∼m ∼a <Key>space:
          key-select()

s ∼c ∼m ∼a <Key>space:
          self-insert()

<Key>:    self-insert()

okay so plot twist time 🎀 the TextField button event translations get modified when Display's XmNenableBtn1Transfer resource does not have a value of XmOFF — in other words, when it's either XmBUTTON2_TRANSFER or XmBUTTON2_ADJUST. This option is the whole reason selection and transfer can be integrated on <Btn1>, which is giving "one button to rule them all" ngl. 💅

And bestie, the <Btn1> actions defined above still apply whenever the <Btn1> event happens over text that is not selected. The following actions apply when the <Btn1> event happens over text that is selected:

<Btn1Down>:
          process-bdrag().

<Shift><Btn1Down>:
          process-bdrag().

<Btn1Down><Shift><Btn1Up>:
          grab-focus(), extend-end.

<Shift><Btn1Down><Shift><Btn1Up>:
          extend-start(), extend-end().

<Ctrl><Btn1Down><Shift><Btn1Up>:
          move-destination().

<Ctrl><Btn1Down>:
          process-bdrag().

And when Display's XmNenableBtn1Transfer resource has a value of XmBUTTON2_ADJUST, these are the ones that apply:

<Btn2Down>:
          extend-start().

<Btn2Motion>:
          extend-adjust().

<Btn2Up>: extend-end().

✨ Action Routines ✨

The XmTextField action routines are... okay buckle up, here's the whole roster 🫶

💖 activate()

Calls the callbacks for XmNactivateCallback. And if the parent is a manager, it passes the event to the parent. That's the whole job description, no notes.

💖 backward-character(extend)

Moves the insertion cursor one character to the left. Heads up though — this action may have different behavior in a right-to-left language environment. 👀

If you call it with an argument of extend, it moves the insertion cursor just like the no-argument case and extends the current selection.

The backward-character() action produces calls to the XmNmotionVerifyCallback procedures with reason value XmCR_MOVING_INSERT_CURSOR. If it's called with the extend argument, the backward-character() action may produce calls to the XmNgainPrimaryCallback procedures. Peep the callback description for the full tea. 🍓

💖 backward-word(extend)

Call it with no argument and it 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, it moves the insertion cursor to the beginning of the previous word. Also, heads up: this action may have different behavior in a locale other than the C locale. 🌈

If you call it with an argument of extend, it moves the insertion cursor just like the no-argument case and extends the current selection.

The backward-word() action produces calls to the XmNmotionVerifyCallback procedures with reason value XmCR_MOVING_INSERT_CURSOR. If it's called with the extend argument, the backward-word() action may produce calls to the XmNgainPrimaryCallback procedures. See the callback description for more info. 🧚

💖 beginning-of-line(extend)

With no argument? It moves the insertion cursor to the beginning of the line. Periodt. ✨

With an argument of extend? It moves the insertion cursor just like the no-argument case and extends the current selection.

The beginning-of-line() action produces calls to the XmNmotionVerifyCallback with reason value XmCR_MOVING_INSERT_CURSOR. If it's called with the extend argument, the beginning-of-line() action may produce calls to the XmNgainPrimaryCallback procedures. See the callback description for more. 💜

💖 clear-selection()

Clears the current selection by replacing each character — except <Return> — with a <space> character. So like, every char gets swapped for a space, and <Return> stays exactly where it is, iconic behavior honestly. 🎀

The clear-selection() action produces calls to the XmNmodifyVerifyCallback procedures with reason value XmCR_MODIFYING_TEXT_VALUE and the XmNvalueChangedCallback procedures with reason value XmCR_VALUE_CHANGED.

💖 copy-clipboard()

If this widget owns the primary selection, this action copies the selection to the clipboard. It calls the XmNconvertCallback procedures — possibly multiple times — for the CLIPBOARD selection. 💅

💖 copy-primary()

Copies the primary selection to just before the insertion cursor. This action calls the XmNdestinationCallback procedures for the PRIMARY selection and the XmCOPY operation. It also calls the selection owner's XmNconvertCallback procedures — possibly multiple times — for the PRIMARY selection.

On top of all that, the copy-primary() action produces calls to the XmNmodifyVerifyCallback procedures with reason value XmCR_MODIFYING_TEXT_VALUE, the XmNvalueChangedCallback with reason value XmCR_VALUE_CHANGED, and the XmNmotionVerifyCallback procedures with reason value XmCR_MOVING_INSERT_CURSOR. The copy-primary() action may produce calls to the XmNgainPrimaryCallback procedures. See the callback description for more information. 🔥

💖 copy-to()

If a secondary selection exists, this action copies the secondary selection to the insertion position of the destination component. And if the primary selection is in the destination widget, it gets deselected. Otherwise? No effect at all on the primary selection, she's unbothered. 😌

This action calls the destination's XmNdestinationCallback procedures for the SECONDARY selection and the XmCOPY operation. The destination's XmNdestinationCallback procedures — or the destination component itself — invokes the selection owner's XmNconvertCallback procedures, possibly multiple times, for the SECONDARY selection.

If no secondary selection exists, this action copies the primary selection to the pointer position instead. This action calls the XmNdestinationCallback procedures for the PRIMARY selection and the XmCOPY operation. It calls the selection owner's XmNconvertCallback procedures, possibly multiple times, for the PRIMARY selection.

And in addition, the copy-to() action produces calls to the XmNmodifyVerifyCallback procedures with reason value XmCR_MODIFYING_TEXT_VALUE, the XmNvalueChangedCallback procedures with reason value XmCR_VALUE_CHANGED, and the XmNmotionVerifyCallback procedures with reason value XmCR_MOVING_INSERT_CURSOR. If there is no secondary selection, the copy-to() action may produce calls to the XmNgainPrimaryCallback procedures. See the callback description for more information. 🦋

💖 cut-clipboard()

If this widget owns the primary selection, this action cuts the selection to the clipboard. It calls the XmNconvertCallback procedures — possibly multiple times — for the CLIPBOARD selection. And if the transfer is successful? Then it calls the XmNconvertCallback procedures for the CLIPBOARD selection and the DELETE target. two for one, we love to see it 💅

On top of that, the cut-clipboard() action produces calls to the XmNmodifyVerifyCallback procedures with reason value XmCR_MODIFYING_TEXT_VALUE, and the XmNvalueChangedCallback procedures with reason value XmCR_VALUE_CHANGED.

cut-primary() ✂️💖

okay bestie, this one is the cut-and-paste main character. It cuts the PRIMARY selection and pastes it just before the insertion cursor. It calls the XmNdestinationCallback procedures for the PRIMARY selection and the XmMOVE operation. It also calls the selection owner's XmNconvertCallback procedures, possibly multiple times, for the PRIMARY selection. If the transfer is successful, this action then calls the selection owner's XmNconvertCallback procedures for the PRIMARY selection and the DELETE target.

In addition, the cut-primary() action produces calls to the XmNmotionVerifyCallback procedures with reason value XmCR_MOVING_INSERT_CURSOR, the XmNmodifyVerifyCallback procedures with reason value XmCR_MODIFYING_TEXT_VALUE, and the XmNvalueChangedCallback procedures with reason value XmCR_VALUE_CHANGED.

delete-next-character() 🗑️✨

normal mode vs add mode, bestie. Here's the tea:

  • In normal mode, if there is a nonnull selection, deletes the selection; otherwise, deletes the character following the insertion cursor.
  • In add mode, if there is a nonnull 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.

The delete-next-character() action produces calls to the XmNmodifyVerifyCallback procedures with reason value XmCR_MODIFYING_TEXT_VALUE, and the XmNvalueChangedCallback procedures with reason value XmCR_VALUE_CHANGED.

delete-next-word() 🗑️📝

same normal/add mode energy, but word edition:

  • In normal mode, if there is a nonnull 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 nonnull 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.

The delete-next-word() action produces calls to the XmNmodifyVerifyCallback procedures with reason value XmCR_MODIFYING_TEXT_VALUE, and the XmNvalueChangedCallback procedures with reason value XmCR_VALUE_CHANGED.

delete-previous-character() 🗑️⬅️

normal/add mode again:

  • In normal mode, if there is a nonnull selection, deletes the selection; otherwise, deletes the character of text immediately preceding the insertion cursor.
  • In add mode, if there is a nonnull 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.

The delete-previous-character() action produces calls to the XmNmodifyVerifyCallback procedures with reason value XmCR_MODIFYING_TEXT_VALUE, the XmNvalueChangedCallback procedures with reason value XmCR_VALUE_CHANGED, and the XmNmotionVerifyCallback procedures with reason value XmCR_MOVING_INSERT_CURSOR.

delete-previous-word() 🗑️⏪

  • In normal mode, if there is a nonnull selection, deletes the selection; otherwise, deletes the characters preceding the insertion cursor to the next space, tab or beginning-of-line character.
  • In add mode, if there is a nonnull 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.

The delete-previous-word() action produces calls to the XmNmodifyVerifyCallback procedures with reason value XmCR_MODIFYING_TEXT_VALUE, the XmNvalueChangedCallback procedures with reason value XmCR_VALUE_CHANGED, and the XmNmotionVerifyCallback procedures with reason value XmCR_MOVING_INSERT_CURSOR.

delete-selection() ✨🗑️

Deletes the current selection. That's it, that's the vibe.

The delete-selection() action produces calls to the XmNmodifyVerifyCallback procedures with reason value XmCR_MODIFYING_TEXT_VALUE, the XmNvalueChangedCallback procedures with reason value XmCR_VALUE_CHANGED, and the XmNmotionVerifyCallback procedures with reason value XmCR_MOVING_INSERT_CURSOR.

delete-to-end-of-line() 🗑️➡️

  • In normal mode, if there is a nonnull 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 nonnull 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.

The delete-to-end-of-line() action produces calls to the XmNmodifyVerifyCallback procedures with reason value XmCR_MODIFYING_TEXT_VALUE, and the XmNvalueChangedCallback procedures with reason value XmCR_VALUE_CHANGED.

delete-to-start-of-line() 🗑️⬅️

  • In normal mode, if there is a nonnull 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 nonnull 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.

The delete-to-start-of-line() action produces calls to the XmNmodifyVerifyCallback procedures with reason value XmCR_MODIFYING_TEXT_VALUE, the XmNvalueChangedCallback procedures with reason value XmCR_VALUE_CHANGED, and the XmNmotionVerifyCallback procedures with reason value XmCR_MOVING_INSERT_CURSOR.

deselect-all() 🚫💅

Deselects the current selection. No callbacks, no drama.

The deselect-all() action produces no callbacks.

end-of-line(extend) ⏭️🌸

  • If this action is called with no argument, moves the insertion cursor to the end of the line.
  • If called with an argument of extend, moves the insertion cursor as in the case of no argument and extends the current selection.

The end-of-line() action produces calls to the XmNmotionVerifyCallback procedures with reason value XmCR_MOVING_INSERT_CURSOR. If called with the extend argument, the end-of-line() action may produce calls to the XmNgainPrimaryCallback procedures. See callback description for more information.

extend-adjust() 🌈✨

Selects text from the anchor to the pointer position and deselects text outside that range.

The extend-adjust() action produces calls to the XmNmotionVerifyCallback procedures with reason value XmCR_MOVING_INSERT_CURSOR. The extend-adjust() action may produce calls to the XmNgainPrimaryCallback procedures. See callback description for more information.

extend-end() 🎯💖

Moves the insertion cursor to the position of the pointer. The extend-end() action is used to commit the selection. After this action has been done, process-cancel() will no longer cancel the selection.

The extend-end() action produces calls to the XmNmotionVerifyCallback procedures with reason value XmCR_MOVING_INSERT_CURSOR. The extend-end() action may produce calls to the XmNgainPrimaryCallback procedures. See callback description for more information.

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.

The extend-start() action can produce no callbacks, however, it may produce calls to the XmNgainPrimaryCallback and XmNmotionVerifyCallback procedures. See callback description for more information.

forward-character(extend) ➡️🦋

Moves the insertion cursor one character to the right. This action may have different behavior in a right-to-left language environment.

If called with an argument of extend, moves the insertion cursor as in the case of no argument and extends the current selection.

The forward-character() action produces calls to the XmNmotionVerifyCallback procedures with reason value XmCR_MOVING_INSERT_CURSOR. If called with the extend argument, the forward-character() action may produce calls to the XmNgainPrimaryCallback procedures. See callback description for more information.

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. 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.

The forward-word() action produces calls to the XmNmotionVerifyCallback procedures with reason value XmCR_MOVING_INSERT_CURSOR. If called with the extend argument, the forward-word() action may produce calls to the XmNgainPrimaryCallback procedures. See callback description for more information.

grab-focus()

okay so this key binding performs the action defined in XmNselectionArray, and which action depends on the number of multiple mouse clicks. the default selection array ordering is: one click → moves the insertion cursor to the pointer position, two clicks → selects a word, and three clicks → selects a line of text. a single click also deselects any selected text and sets the anchor at the pointer position. also, heads up bestie, this action may have different behavior in a locale other than the C locale. 🌀

the grab-focus() action produces calls to the XmNmotionVerifyCallback procedures with reason value XmCR_MOVING_INSERT_CURSOR.

Help()

calls the callbacks for XmNhelpCallback if any exist. and if this widget has, like, no help callbacks? it goes and calls the help callbacks for the nearest ancestor that has them. found family energy fr. 🫶

key-select(right|left)

  • call it with an argument of right → moves the insertion cursor one character to the right and extends the current selection.
  • call it with an argument of left → moves the insertion cursor one character to the left and extends the current selection.
  • call it with no argument → extends the current selection.
note bestie: after a key-select action, the selection will still begin at the original anchor, and will extend to the position indicated in the action call. if this new position is on the opposite side of the selection anchor from the previous selection boundary, the original selection will be deselected. 😭

the key-select() action produces calls to the XmNmotionVerifyCallback procedures with reason value XmCR_MOVING_INSERT_CURSOR. the key-select() action may also produce calls to the XmNgainPrimaryCallback procedures. see callback description for more information.

places a link to the primary selection just before the insertion cursor. this action calls the XmNdestinationCallback procedures for the PRIMARY selection and the XmLINK operation. but plot twist — the TextField widget itself performs no transfers. the XmNdestinationCallback procedures are the ones responsible for inserting the link to the primary selection and for taking any related actions. 💅

if a secondary selection exists, this action places a link to the secondary selection at the insertion position of the destination component. this action calls the destination's XmNdestinationCallback procedures for the SECONDARY selection and the XmLINK operation.

if no secondary selection exists, this action places a link to the primary selection at the pointer position. this action calls the XmNdestinationCallback procedures for the PRIMARY selection and the XmLINK operation.

and again, the TextField widget itself performs no transfers — the XmNdestinationCallback procedures are responsible for inserting the link to the primary or secondary selection and for taking any related actions.

move-destination()

moves the insertion cursor to the pointer position without changing any existing current selection. if there is a current selection, it sets the widget as the destination widget. it also moves the widget focus to match the insertion cursor.

the move-destination() action produces calls to the XmNmotionVerifyCallback procedures with reason value XmCR_MOVING_INSERT_CURSOR.

move-to()

if a secondary selection exists, this action moves the secondary selection to the insertion position of the destination component. if the secondary selection is in the destination widget, and the secondary selection and the primary selection overlap, the result is undefined — like, do not do this. 💀 this action calls the destination's XmNdestinationCallback procedures for the SECONDARY selection and the XmCOPY operation. the destination's XmNdestinationCallback procedures or the destination component itself invokes the selection owner's XmNconvertCallback procedures, possibly multiple times, for the SECONDARY selection. if the transfer is successful, this action then calls the selection owner's XmNconvertCallback procedures for the SECONDARY selection and the DELETE target.

if no secondary selection exists, this action moves the primary selection to the pointer position. this action calls the XmNdestinationCallback procedures for the PRIMARY selection and the XmMOVE operation. it calls the selection owner's XmNconvertCallback procedures, possibly multiple times, for the PRIMARY selection. if the transfer is successful, this action then calls the selection owner's XmNconvertCallback procedures for the PRIMARY selection and the DELETE target.

in addition, the move-to() action produces calls to the XmNmodifyVerifyCallback procedures with reason value XmCR_MODIFYING_TEXT_VALUE, the XmNvalueChangedCallback procedures with reason value XmCR_VALUE_CHANGED, and the XmNmotionVerifyCallback procedures with reason value XmCR_MOVING_INSERT_CURSOR. this action may also produce calls to the XmNgainPrimaryCallback procedures.

next-tab-group()

traverses to the next tab group.

the next-tab-group() action produces no callbacks, unless it results in the widget losing focus, in which case, the XmNlosingFocusCallback procedures are called with reason value XmCR_LOSING_FOCUS.

page-left()

scrolls the viewing window left one page of text.

the page-left() action produces no callbacks. so chill.

page-right()

scrolls the viewing window right one page of text.

the page-right() action produces no callbacks either. balanced, as all things should be. ✨

paste-clipboard()

pastes the contents of the clipboard before the insertion cursor. this action calls the XmNdestinationCallback procedures for the CLIPBOARD selection and the XmCOPY operation.

the paste-clipboard() action produces calls to the XmNmodifyVerifyCallback procedures with reason value XmCR_MODIFYING_TEXT_VALUE, the XmNvalueChangedCallback procedures with reason value XmCR_VALUE_CHANGED, and the XmNmotionVerifyCallback procedures with reason value XmCR_MOVING_INSERT_CURSOR.

prev-tab-group()

traverses to the previous tab group.

the prev-tab-group() action produces no callbacks, unless it results in the widget losing focus, in which case, the XmNlosingFocusCallback procedures are called with reason value XmCR_LOSING_FOCUS.

process-bdrag()

if the pointer is within the selection, this action starts a drag operation for the selection. this action sets the XmNconvertProc of the DragContext to a function that calls the XmNconvertCallback procedures, possibly multiple times, for the _MOTIF_DROP selection.

if no selection exists or the pointer is outside the selection, this action prepares to start a secondary selection at the pointer position.

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, it passes the event to the parent. very "never mind, forget I said anything" of it. 🙈

secondary-adjust()

extends the secondary selection to the pointer position.

the secondary-adjust() action produces no callbacks.

secondary-start()

marks the beginning of a secondary selection.

the secondary-start() action produces no callbacks.

select-all()

selects all text. 🎉

the select-all() action can produce no callbacks, however, it may produce calls to the XmNgainPrimaryCallback and XmNmotionVerifyCallback procedures. see callback description for more information.

self-insert()

if XmNpendingDelete is True and the cursor is not disjoint from the current selection, deletes the entire selection. then inserts the character associated with the key pressed before the insertion cursor.

the self-insert() action produces calls to the XmNmodifyVerifyCallback procedures with reason value XmCR_MODIFYING_TEXT_VALUE, the XmNvalueChangedCallback procedures with reason value XmCR_VALUE_CHANGED, and the XmNmotionVerifyCallback procedures with reason value XmCR_MOVING_INSERT_CURSOR.

set-anchor()

resets the anchor point for extended selections. also resets the destination of secondary selection actions.

the set-anchor() action produces no callbacks.

toggle-add-mode()

toggles the state of Add Mode.

the toggle-add-mode() action produces no callbacks.

toggle-overstrike()

toggles the state of the text insertion mode. by default, characters typed into the TextField widget are inserted before the position of the insertion cursor. in overstrike mode, characters entered into the TextField widget replace the characters that directly follow the insertion cursor. and in overstrike mode, when the end of a line is reached, characters are appended to the end of the line. no cap. 👑

the following traversal actions generate no callbacks unless they result in the loss of focus by the widget in question, as when XmNnavigationType is XmNONE. in this case, they produce calls to the XmNlosingFocusCallback procedures, with reason value XmCR_FOCUS_MOVED.

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.

Additional Behavior

this widget has the following additional behavior, bestie:

  • <FocusIn> — draws the insertion cursor as solid and starts blinking the cursor. main character energy, honestly. ✨
  • <FocusOut> — draws the insertion cursor as a stippled I-beam… unless it's the destination widget, in which case bestie, it just sits there looking normal 🙈

🦋 Virtual Bindings 🦋

The tea on virtual key bindings? They're <strong>vendor specific</strong> — every vendor does their own thing, no universal rules, iykyk. So if you wanna know about the bindings for virtual buttons and keys, go read VirtualBindings(3). That's the one that actually spills. ✨

okay so here's the whole friend group 💖 every single one of these is canon and you should absolutely go meet them:

and that's the whole page, bestie, we made it to the end 🎀✨ the very last line down there is the footer, and it's giving <pink>XmTextField(library call)</pink> — so that's your source/version and date vibes, all official, all iconic, no cap. go forth and text-field responsibly 👑💅🦋

📦 where this page comes from