XbaeInput(3)

📦
version 4.60.4 · 2 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💅 XbaeInput(3) 💅

okay so this is the manual page for XbaeInput, and it lives in the Library Functions Manual, bestie. it's long, it's iconic, and we're doing it in parts, so buckle up 🎀

🎀 NAME 🎀

XbaeInput — the Input widget class. that's it. short, sweet, main character energy 👑

🌸 SYNOPSIS 🌸

#include <Xbae/Input.h>

✨ DESCRIPTION ✨

okay so XbaeInput is a text input field that does generic customised data entry and formatting for strings. the way it pulls this off?? a clever XmNmodifyVerifyCallback that gets installed the moment you set the XmNpattern resource. and the XmNpattern value can include optional characters and literals — we'll get into all of that later in this doc, don't worry 🫶

XbaeInput is literally ideal for restricting data input to a digit, an alphanumeric character, or an alphabetic character. and if you set XmNconvertCase, the widget just automatically flips an inserted character to uppercase or lowercase for you. no cap ✨

literal characters can also be baked into the XmNpattern and auto-inserted as the user types — that happens when you set the XmNautofill resource to True. but (and this is important, bestie) optional literals cannot be auto inserted. okay?? noted 📝

so here's a difference from XmText, which this widget is subclassed from: the toggle-overwrite action is bound to the osfInsert key. and XmNoverwriteMode is also there so you can change that resource programmatically. slay 💅

when the XbaeInput widget loses focus, or gets activated the same way an XmText field would be, the callbacks on the XmNvalidateCallback list get invoked. that's your moment to validate the data and reformat the existing string. programmer's choice, honestly 🌈

🦋 Classes 🦋

XbaeInput inherits behavior and resources from the Core, XmPrimitive, and XmText widget classes.

  • the class pointer is xbaeInputWidgetClass
  • the class name is XbaeInput

💖 New Resources 💖

here's the tea: the following table lists the new resources defined by XbaeInput. the codes in the Access column tell you whether the given resource can be set at creation time (C), or set using XtSetValues (S), or retrieved using XtGetValues (G). iykyk 😌

XbaeInput Resource Set:

  • XmNalignment — class XmCAlignment, type unsigned char, default XmALIGNMENT_BEGINNING, access CSG
  • XmNautoFill — class XmCBoolean, type Boolean, default False, access CSG
  • XmNconvertCase — class XmCBoolean, type Boolean, default True, access CSG
  • XmNoverwriteMode — class XmCBoolean, type Boolean, default False, access CSG
  • XmNpattern — class XmCString, type String, default NULL, access CSG
  • XmNvalidateCallback — class XmCCallback, type Callback, default NULL, access CSG
This resource has not been implemented.

🌟 XmNalignment

This resource has not been implemented!

specifies the alignment of the text when it's being edited and displayed. possible values are XmALIGNMENT_BEGINNING and XmALIGNMENT_END. if XmNalignment is set to XmALIGNMENT_END, the text is right justified. if you just leave it at the default XmALIGNMENT_BEGINNING, the text is left justified. cute, right? 💜

🌟 XmNautoFill

the XmNautoFill resource, when set to True, tries to automatically insert a literal if a non-literal is hit in an allowed literal position. for example!! if the XmNpattern resource was set up to accept a date in dd/mm/yyyy format and the user typed "18041999", the resulting string would appear as "18/04/1999". iconic ✨

the default value is False, where the user would have to type the literal themselves. no autofill, no shortcut, you do the work bestie 😭

🌟 XmNconvertCase

this one tells the XbaeInput widget what should be done to alphabetic characters if the [pattern] requires a lowercase or uppercase letter.

  • if XmNconvertCase is set to True (the default), the character is automatically converted to the correct case 💫
  • if set to False, then the user must type the character in the correct case for it to be accepted. strict much?? 🙈

see the EXAMPLE PATTERNS section towards the end of this document for some examples 🎀

🌟 overwriteMode

whether the widget accepts characters in insert mode or overwrite mode is controlled by the resource. setting this resource calls the XmText toggle-overwrite() action routine, so heads up: the Motif toolkit being used must also support this routine. don't come for me, that's just the rules 💀

🌟 XmNpattern

the XmNpattern resource specifies what can be typed into the XbaeInput widget. if you set it to the default value of NULL, any character may be entered — free for all, do whatever 🌈

XmNpattern can be set to a string containing the following characters:

  • a — alphabetic characters only
  • b — both, either digit or character
  • c — any character at all
  • d — digits only
  • U — upperchase character only
  • L — lowercase character only
  • [ — start of optional sequence
  • ] — end of optional sequence
  • \\ — escapes the next character
  • | — next char is an alternative to previous. May be chained.

🧚 Inherited Resources 🧚

the following table lists the resources which XbaeInput inherits from it's superclasses XmText, XmPrimitive, and Core. for a complete description of each resource, go read the man page for that superclass, bestie — they've got the full lore 📚

the codes in the "Access" column tell you whether the given resource can be set at creation time (C), or set using XtSetValues (S), or retrieved using XtGetValues (G). same deal as before 💖

🌸 XmText Resource Set 🌸

okay bestie, buckle up, because this is the whole entire resource table for XmText and it is long. 💖 Every single row has five little things you need to know about it: the Name, the Class, the Type, the Default, and the Access. No cap, that's the whole structure.

And the access column? Every. Single. One. is CSG. All twenty of them. Iconic consistency honestly. 👑

  • XmNautoShowCursorPosition — class XmCAutoShowCursorPosition, type Boolean, default True, access CSG
  • XmNcursorPosition — class XmCCursorPosition, type XmTextPosition, default 0, access CSG
  • XmNeditable — class XmCEditable, type Boolean, default True, access CSG
  • XmNeditMode — class XmCEditMode, type int, default XmSINGLE_LINE_EDIT, access CSG
  • XmNfocusCallback — class XmCCallback, type XtCallbackList, default NULL, access CSG
  • XmNgainPrimaryCallback — class XmCCallback, type XtCallbackList, default NULL, access CSG
  • XmNlosePrimaryCallback — class XmCCallback, type XtCallbackList, default NULL, access CSG
  • XmNlosingFocusCallback — class XmCCallback, type XtCallbackList, default NULL, access CSG
  • XmNmarginHeight — class XmCMarginHeight, type Dimension, default 5, access CSG
  • XmNmarginWidth — class XmCMarginWidth, type Dimension, default 5, access CSG
  • XmNmaxLength — class XmCMaxLength, type int, default largest integer, access CSG
  • XmNmodifyVerifyCallback — class XmCCallback, type XtCallbackList, default NULL, access CSG
  • XmNmodifyVerifyCallbackWcs — class XmCCallback, type XtCallbackList, default NULL, access CSG
  • XmNmotionVerifyCallback — class XmCCallback, type XtCallbackList, default NULL, access CSG
  • XmNsource — class XmCSource, type XmTextSource, default Default source, access CSG
  • XmNtopCharacter — class XmCTextPosition, type XmTextPosition, default 0, access CSG
  • XmNvalue — class XmCValue, type String, default "", access CSG
  • XmNvalueChangedCallback — class XmCCallback, type XtCallbackList, default NULL, access CSG
  • XmNvalueWcs — class XmCvalueWcs, type wchar_t *, default (wchar_t *)"", access CSG
  • XmNverifyBell — class XmCVerifyBell, type Boolean, default dynamic, access CSG

twenty resources, zero skips, we ate that whole table fr fr 💅✨ and bestie we are not done yet, keep scrolling 🦋

🫶 XmPrimitive Resource Set 🫶

okay so real talk bestie — before we even touch the stuff that makes XbaeInput special, it inherits a whole closet full of resources from XmPrimitive first 💅 and every single one of them is laid out in the original with five little columns: Name, Class, Type, Default, and Access. I'm giving you all of them below, one per bullet, zero skipped, no cap. 🔥

And yes, the Access column is CSG for literally every single one of these — that's just the whole table, bestie, every row, uniform. ✨

  • XmNbottomShadowColor — class XmCBottomShadowColor, type Pixel, default dynamic, access CSG. The color of the bottom shadow, the little drama shading underneath. 🎀
  • XmNbottomShadowPixmap — class XmCBottomShadowPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG. A pixmap for that same bottom shadow if you're feeling textured instead of flat. 🦋
  • XmNforeground — class XmCForeground, type Pixel, default dynamic, access CSG. The main character of colors here — the foreground. 👑
  • XmNhighlightColor — class XmCHighlightColor, type Pixel, default dynamic, access CSG. The color used for highlighting. so sparkly, so seen. ⭐
  • XmNhighlightOnEnter — class XmCHighlightOnEnter, type Boolean, default False, access CSG. Whether highlighting turns on when the pointer enters. Default is False, so out of the box it's giving chill, not giving glow. 😌
  • XmNhighlightPixmap — class XmCHighlightPixmap, type Pixmap, default dynamic, access CSG. The pixmap version of that highlight situation. 🌈
  • XmNhighlightThickness — class XmCHighlightThickness, type Dimension, default 2, access CSG. How thick the highlight is. Default 2. slay, a modest little frame. 🎀
  • XmNnavigationType — class XmCNavigationType, type XmNavigationType, default XmNONE, access CSG. Controls the navigation type, and it starts at XmNONE. periodt. 💅
  • XmNshadowThickness — class XmCShadowThickness, type Dimension, default 2, access CSG. How thick the shadow is. Also default 2. twins with the highlight thickness fr fr. 😭
  • XmNtopShadowColor — class XmCTopShadowColor, type Pixel, default dynamic, access CSG. The top shadow color — the light coming from above, the glow-up. 🌸
  • XmNtopShadowPixmap — class XmCTopShadowPixmap, type Pixmap, default dynamic, access CSG. Same energy but as a pixmap for the top shadow. ✨
  • XmNtraversalOn — class XmCTraversalOn, type Boolean, default True, access CSG. Whether traversal is on. Defaults to True, so yes bestie, it's on. 💖
  • XmNunitType — class XmCUnitType, type unsignedChar, default dynamic, access CSG. The unit type, stored as an unsignedChar. the way that's such a specific type 😭 iconic. 🧚
  • XmNuserData — class XmCUserData, type Pointer, default NULL, access CSG. Your own lil pocket for arbitrary user data. It starts as NULL, so it's all yours to fill. 🍓
no cap, that's the entire XmPrimitive set — every Name, every Class, every Type, every Default and every CSG accounted for. nothing got cut, nothing got "cleaned up". 💜

🌈 Core Resource Set 🌈

ok so this is the whole core resource table bestie, every single one, no skips 💅 — name, class, type, default, access, the works. Access codes are exactly what they say they are, i'm not gonna invent lore for them, that's the rules.

  • XmNaccelerators — class XmCAccelerators, type XtAccelerators, default NULL, 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 1, 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 💌

XmNvalidateCallback — the vibe checker for your input 🕵️♀️

Callbacks hanging out on the XmNvalidateCallback list get called when the edits to the XbaeInput widget are activated, or when a losing focus event happens. Every callback function gets handed this struct, exactly this one:

typedef struct
{
        int           reason;
        XEvent        *event;
        String        pattern;
        String        value;
        Boolean       doit;
} XbaeInputValidateCallbackStruct;

ok now let's break down the fields one by one, no skipping:

  • reason — set to XmCR_ACTIVATE if the user caused the callback to be invoked by activating the changes in the cell, or XmCR_LOSING_FOCUS if the callback got called because of a losing focus event 👀
  • event — the event pointer that triggered the callback, the whole reason we're here fr fr
  • pattern — a pointer to the pattern for the XbaeInput widget, or NULL if one doesn't exist. This value is provided as a convenience to the callback. (the manpage said it, not me)
  • value — the value as it appears in the cell at the time of the callback being invoked 📝
  • doit — indicates whether or not the value is valid. Set doit to False and the value will not be accepted 🚫

This callback is literally here so your application can check the validity of the value entered into the XbaeInput widget. Checking the validity of a date may be one such instance. iconic use case honestly.

If the value is verified as valid, all values of the callback may be left unchanged. If the pointer to the value is changed, the new value will be displayed in the cell, and storage for the old value gets deallocated by the XbaeInput widget. Heads up though: the new value's memory is owned by the application, and it is up to the application to use XtFree to deallocate it. Not your widget's problem, bestie, that's on you 🫵

If the value is not considered valid, the doit flag should be set to False, forcing the user to make changes before the value can be accepted. sorry babe, fix your input 💅

🌸 Translations 🌸

XbaeInput inherits translations from XmText. Cute, right? But plot twist: some versions of Motif do not have the

:<Key>osfInsert:           toggle-overstrike()

translation installed by default. If that's the case, XbaeInput automatically registers this translation. so like, it handles it for you. slay ✨

🦋 Type Converters 🦋

XbaeInput does not define any new type converters other than the standard type converters registered by Xt and Motif. That's it. That's the whole section. no extra converters, no secret ones, nothing hiding in the bushes 💜

✨ Public Functions ✨

okay bestie, here are the external entry points to the XbaeInput class methods. they're defined like this:

Widget XbaeCreateInput()
    Widget     parent;
    String     name;
    ArgList    arglist;
    Cardinal   argcount;
  • parent — Specifies the parent widget ID.
  • name — Specifies the name of the created widget
  • arglist — Specifies the argument list
  • argcount — Specifies the number of attribute/value pairs in the argument list (arglist)

XbaeCreateInput() creates an instance of an XbaeInput widget and returns the associated widget ID. slay. 💅

🌸 EXAMPLE PATTERNS 🌸

these are the little pattern moods, bestie:

  • d[d]/d[d]/dd[dd] — a date that would accept 1/1/99, 12/1/99, 1/12/1999, 01/01/2000, etc.
  • U[L][L][L][L][L], U[L][L][L][L][L] — "Surname, Firstname" combination, automatically forcing correct case and allowing between 1 and 6 characters per name.
  • UU-dd[d][d] — a flight number consisting of two uppercase letters and 2 to 4 numbers
  • (ddd) ddd-dddd — an American style phone number
  • UdU[-]dUd — a Canadian postcode with optional dash.

🔮 Virtual Bindings 🔮

The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see VirtualBindings(3X). iykyk 🦋

👑 AUTHOR 👑

Andrew Lister (lister@db.com)

🎀 RELEASE 🎀

This document describes XbaeInput from Xbae Version 4.9.

🌈 SEE ALSO 🌈

Core(3X), XmPrimitive(3X), XmText(3X)

💀 Notice of Limitation 💀

okay so, legal time, but make it cute. The Author, previous and current maintainers of the Xbae widgets (collectively 'authors') provide this information solely to professionals who have the appropriate degree of experience to understand and interpret its contents in accordance with generally accepted engineering or other professional standards and applicable regulations. No recommendations as to products or vendors is made or should be implied. periodt.

While the information contained herein has been prepared from sources deemed to be reliable, the authors reserve the right to revise the information without notice, but have no obligation to do so. Unless the recipient has been expressly granted a license by Bellcore under separate applicable written agreement with Bellcore, no license, expressed or implied, is granted under any patents, copyrights or other intellectual property rights. Use of the information is at your discretion and shall not be deemed an inducement by Bellcore to infringe any existing or later-issued patent, copyrights or other intellectual property right. no cap.

THE AUTHORS MAKE NO REPRESENTATIONS AND EXTENDS NO WARRANTIES, EXPRESS OR IMPLIED, WITH RESPECT TO THE INFORMATION, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ANY PARTICULAR PURPOSE, AND THE WARRANTY AGAINST INFRINGEMENT OF PATENTS OR OTHER INTELLECTUAL PROPERTY RIGHTS. THE INFORMATION IS PROVIDED ``AS IS'', AND IN NO EVENT SHALL THE AUTHORS OR ANY OF ITS AFFILIATES BE LIABLE FOR ANY DAMAGES, INCLUDING ANY LOST PROFITS OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES RELATING TO THE INFORMATION.
Copyright 1999 Andrew Lister.  All Rights Reserved.
Copyright 1999-2002 LessTif Developers

The above no warranty extends to all additions and contributions. No contributor shall be held liable; this work is provided ``as is''. If this is a problem for you, then don't use this software. 🙈

this page is from Xbae version 4.60.4, filed under XbaeInput(3) 💖✨

📦 where this page comes from