XMSPINBOX(3)

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

💖 XmSpinBox 💖

okay so bestie, we're reading the manual page for XmSpinBox, and it lives in the library call section of the docs. sit down, grab a snack, this one's a whole journey 🫶

🎀 NAME 🎀

XmSpinBox — the SpinBox widget class ✨

🌸 SYNOPSIS 🌸

#include <Xm/SpinB.h>

🦋 DESCRIPTION 🦋

So what even is a SpinBox? SpinBox lets the user pick a value out of a ring of related but mutually exclusive choices, and it shows them one after another — like a little carousel of options 🎠. Every SpinBox always has an increment arrow, a decrement arrow, and one or more other children. The choices get displayed one at a time inside a traversable text child (that's XmText or XmTextField). The user clicks <Btn1> on an arrow to show the next (or the previous) item in the ring. And if they press and hold <Btn1> on an arrow? It just keeps cycling through the choices, over and over, no cap 🔁.

The traversable children in a SpinBox can be of type XmNUMERIC or XmSTRING, as defined by the XmNspinBoxChildType constraint resource. And here's how each one's ring of choices gets built:

  • For numeric children, the ring is defined by minimum, maximum, incremental, and decimal point values.
  • For string children, the ring is defined by an array of compound strings.

The application programmer can put multiple traversable children in the SpinBox. Like, for example, a SpinBox might be a pair of arrows plus month, day, and year text fields 🌙☀️📅. The arrows only spin the child that currently has focus — they're loyal like that 💅.

Arrow size is specified by the SpinBox resource XmNarrowSize. That value sets both the width and the height of each arrow, in pixels.

The programmer can display SpinBox arrows in one of several layouts, as specified by the XmNarrowLayout resource:

  • XmARROWS_BEGINNING — places a pair of left and right arrows before the children.
  • XmARROWS_END — places a pair of left and right arrows after the children.
  • XmARROWS_SPLIT — places one arrow on each side of the children.
  • XmARROWS_FLAT_BEGINNING — places a pair of arrows side by side before the XmSpinBox children.
  • XmARROWS_FLAT_BEGINNING — places a pair of arrows side by side after the XmSpinBox children.
bestie I'm just gonna say it: yes, that last one is written as XmARROWS_FLAT_BEGINNING twice in the original. I am not about to go editing the source material 💀 that's exactly what the page says.

Positions for XmARROWS_BEGINNING and XmARROWS_END are dependent on the VendorShell resource XmNlayoutDirection. When layout direction is left-to-right, beginning arrows are positioned to the left of the children. When layout direction is right-to-left, beginning arrows are positioned to the right.

The actions of the arrows are also determined by the VendorShell resource XmNlayoutDirection:

  • For left-to-right layouts, the right arrow is the increment arrow and the left arrow is the decrement arrow.
  • For right-to-left layouts, the right arrow is the decrement arrow and the left arrow is the increment arrow.

For a numeric type child, the increment arrow increases the displayed value by the incremental value, up to the maximum. The decrement arrow decreases the displayed value by the given incremental value, down to the minimum. ➕➖

The increment arrow for a string type child moves toward the last entry of the array of compound strings (by increasing the SpinBox constraint resource XmNposition). The decrement arrow moves toward the first entry of the compound string array.

The programmer can also control the sensitivity of each arrow in the SpinBox. Sensitive arrows spin choices; insensitive arrows do not spin choices. Arrow sensitivity is set for the SpinBox widget by using the XmNdefaultArrowSensitivity resource, but it can be modified on a per-child basis by using the XmNarrowSensitivity constraint resource. Slay, options ✨

SpinBox provides two callbacks to application programmers. (Also, the callbacks of the SpinBox's children may be invoked — don't forget them!) Each of these callbacks receives a pointer to XmSpinBoxCallbackStruct:

  • The XmNmodifyVerifyCallback procedures are called before a new choice is displayed.
  • The XmNvalueChangedCallback procedures are called after a new choice is displayed.

XmNmodifyVerifyCallback tells the application what the new position will be in the ring of choices. This callback can be used to make the SpinBox stop at the upper and lower limits, or to jump to a different, nonconsecutive choice. The application allows the change in position by leaving the doit member set to True. The application can spin to a position other than the next consecutive position by leaving doit set to True and by changing the position member to the desired position. And when doit is set to False by an application, there is no change in the choice displayed.

After a new choice is displayed, the XmNvalueChangedCallback procedure is called. The application can use this procedure to do tasks when specific values are reached or when boundaries are crossed. For example, if the user spins from January back to December, the application could change to the previous year. If the user spins from December to January, the application could change to the next year. 🗓️ iconic behavior honestly

SpinBox dimensions can be set using the Core resources XmNheight and XmNwidth. If dimensions are not specified, the SpinBox size is determined by the sizes of its arrows and children. The SpinBox will attempt to grow so that the arrows and all children are visible. it's giving main character energy, it wants everyone on screen 💅

SpinBox uses the XmQTaccessTextual trait and holds the XmQTnavigator trait.

👑 Classes 👑

SpinBox inherits behavior, resources, and traits from the Core, Composite, Constraint, and XmManager classes.

  • The class pointer is xmSpinBoxWidgetClass.
  • The class name is XmSpinBox.

💅 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 whether 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).

XmSpinBox Resource Set 🎀

  • XmNarrowLayout — class XmCArrowLayout, type unsigned char, default XmARROWS_BEGINNING, access CSG
  • XmNarrowOrientation — class XmCArrowOrientation, type unsigned char, default XmARROWS_VERTICAL, access CSG
  • XmNarrowSize — class XmCArrowSize, type Dimension, default 16, access CSG
  • XmNdefaultArrowSensitivity — class XmCDefaultArrowSensitivity, type unsigned char, default XmARROWS_SENSITIVE, access CSG
  • XmNdetailShadowThickness — class XmCDetailShadowThickness, type Dimension, default 2, access CSG
  • XmNinitialDelay — class XmCInitialDelay, type unsigned int, default 250 ms, access CSG
  • XmNmarginHeight — class XmCMarginHeight, type Dimension, default dynamic, access CSG
  • XmNmarginWidth — class XmCMarginWidth, type Dimension, default dynamic, access CSG
  • XmNmodifyVerifyCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNrepeatDelay — class XmCRepeatDelay, type unsigned int, default 200 ms, access CSG
  • XmNspacing — class XmCSpacing, type Dimension, default dynamic, access CSG
  • XmNvalueChangedCallback — class XmCCallback, type XtCallbackList, default NULL, access C

XmNarrowLayout

Specifies placement of the two arrows in the widget. Possible layouts are as follows:

  • XmARROWS_BEGINNING — places left and right arrows beside each other, before the child(ren). Positioning for this layout is dependent on the VendorShell resource XmNlayoutDirection.
  • XmARROWS_END — places left and right arrows beside each other, after the child(ren). Positioning for this layout is dependent on the VendorShell resource XmNlayoutDirection.
  • XmARROWS_FLAT_BEGINNING — places a pair of arrows side by side before the XmSpinBox children. Positioning for this layout is dependent on the VendorShell resource XmNlayoutDirection.
  • XmARROWS_FLAT_END — places a pair of arrows side by side after the XmSpinBox children. Positioning for this layout is dependent on the VendorShell resource XmNlayoutDirection.
  • XmARROWS_SPLIT — places a left arrow on the left side and a right arrow on the right side of the child(ren).

XmNarrowSize

Specifies both the width and height of the arrow in pixels. 📏

XmNdefaultArrowSensitivity

Specifies the default sensitivity of the arrows in the widget. Insensitive arrows change color, cannot be depressed, and perform no action. (This resource may be overridden by the constraint resource XmNarrowSensitivity for individual traversable text children of the SpinBox.) Possible default sensitivity values are as follows:

  • XmARROWS_SENSITIVE — both arrows are sensitive.
  • XmARROWS_DECREMENT_SENSITIVE — only the decrement arrow (as determined by XmNlayoutDirection) is sensitive. The increment arrow is insensitive.
  • XmARROWS_INCREMENT_SENSITIVE — only the increment arrow (as determined by XmNlayoutDirection) is sensitive. The decrement arrow is insensitive.
  • XmARROWS_INSENSITIVE — both arrows are insensitive.

XmNdetailShadowThickness

Specifies the thickness of the inside arrow shadows. The default thickness is 2 pixels.

XmNinitialDelay

Specifies how long, in milliseconds, the mouse button must be held down before automatic spinning begins. In other words, when the user selects the increment or decrement arrow and keeps it depressed, this delay occurs before the choices start spinning. If XmNinitialDelay is 0, then XmNrepeatDelay is used as the initial delay. ⏳

XmNmarginHeight

Specifies the amount of blank space between the top edge of the SpinBox widget and the first item in each column, and the bottom edge of the SpinBox widget and the last item in each column.

  • XmNmarginWidth — how much blank space sits between the left edge of the SpinBox widget and the first item in each row, and between the right edge and the last item in each row. It's giving breathing room 💨
  • XmNmodifyVerifyCallback — okay so this one fires before the SpinBox position actually changes (peep the Constraint resource XmNposition). Your app can use it to set the next position, change SpinBox resources, or straight up cancel the impending action. Like, you could use it to stop the spinning right before it wraps at the upper and lower position boundaries. If the doit member is set to False, nothing happens — nada. Otherwise the position changes. The reasons this callback sends are XmCR_SPIN_NEXT, XmCR_SPIN_PRIOR, XmCR_SPIN_FIRST, or XmCR_SPIN_LAST.
  • XmNrepeatDelay — when the user selects an arrow button and keeps it depressed by pressing and holding <Btn1>, the spinning begins. After the time specified in XmNinitialDelay elapses, the SpinBox position changes automatically until the arrow button is released. This resource specifies the delay in milliseconds between each automatic change. And heads up: if XmNrepeatDelay is set to 0 (zero), automatic spinning is turned off and XmNinitialDelay is just ignored. periodt 💅
  • XmNspacing — the horizontal and vertical spacing between items contained within the SpinBox widget.
  • XmNvalueChangedCallback — this one gets called n+1 times for n SpinBox position changes (again, see the Constraint resource XmNposition). The reasons it sends are XmCR_OK, XmCR_SPIN_NEXT, XmCR_SPIN_PRIOR, XmCR_SPIN_FIRST, or XmCR_SPIN_LAST. The other members are detailed in the callback structure description, iykyk.

🎀 XmSpinBox Constraint Resource Set 🎀

Every child of the SpinBox gets these. Buckle up bestie, here's the whole lineup 💖

  • XmNarrowSensitivity — Class: XmCArrowSensitivity, Type: unsigned char, Default: XmARROWS_DEFAULT_SENSITIVITY, Access: CSG
  • XmNdecimalPoints — Class: XmCDecimalPoints, Type: short, Default: 0, Access: CSG
  • XmNincrementValue — Class: XmCIncrementValue, Type: int, Default: 1, Access: CSG
  • XmNmaximumValue — Class: XmCMaximumValue, Type: int, Default: 10, Access: CSG
  • XmNminimumValue — Class: XmCMinimumValue, Type: int, Default: 0, Access: CSG
  • XmNnumValues — Class: XmCNumValues, Type: int, Default: 0, Access: CSG
  • XmNposition — Class: XmCPosition, Type: int, Default: 0, Access: CSG
  • XmNpositionType — Class: XmCPositionType, Type: char, Default: XmPOSITION_VALUE, Access: CG
  • XmNspinBoxChildType — Class: XmSpinBoxChildType, Type: unsigned char, Default: XmSTRING, Access: CG
  • XmNvalues — Class: XmCValues, Type: XmStringTable, Default: NULL, Access: CSG

✨ The constraint resources, explained ✨

  • XmNarrowSensitivity — says how sensitive the arrows are for a SpinBox child. By using this resource in the definition of a SpinBox child, the application programmer can override the default SpinBox sensitivity (which is set by XmNdefaultArrowSensitivity) for one particular child. That means every traversable child can have its own ✨unique✨ arrow sensitivity. The arrow sensitivity values are:
    • XmARROWS_SENSITIVE — both arrows are sensitive.
    • XmARROWS_DECREMENT_SENSITIVE — only the decrement arrow (as determined by XmNlayoutDirection) is sensitive.
    • XmARROWS_INCREMENT_SENSITIVE — only the increment arrow (as determined by XmNlayoutDirection) is sensitive.
    • XmARROWS_INSENSITIVE — both arrows are insensitive. RIP to them 🪦
    • XmARROWS_DEFAULT_SENSITIVITY — use the sensitivity specified in the XmNdefaultArrowSensitivity resource.
  • XmNdecimalPoints — how many decimal places get used when displaying the value of a SpinBox numeric type child. If the number of decimal places you specify is greater than the number of digits in a displayed value, the value gets padded with 0 (zeros). For example, when XmNinitialValue is 1 and XmNmaximumValue is 1000 and XmNdecimalPoints is 3, the range of values displayed in the SpinBox is 0.001 to 1.000. This is used only when XmNspinBoxChildType is XmNUMERIC.
  • XmNincrementValue — the amount by which to increment or decrement a SpinBox numeric type child. Used only when XmNspinBoxChildType is XmNUMERIC.
  • XmNmaximumValue — the highest possible value for a numeric SpinBox. Used only when XmNspinBoxChildType is XmNUMERIC.
  • XmNminimumValue — the lowest possible value for a numeric SpinBox. Used only when XmNspinBoxChildType is XmNUMERIC.
  • XmNnumValues — the number of strings in XmNvalues. The application must change this value when strings are added to or removed from XmNvalues. Used only when XmNspinBoxChildType is XmSTRING.
  • XmNposition — the position of the currently displayed item. How you read XmNposition depends entirely on the value of the XmNpositionType resource. Let's break it down 🫶

When XmNpositionType is XmPOSITION_INDEX, the XmNposition value is interpreted like this:

  • For XmSpinBox children of type XmNUMERIC, XmNposition is interpreted as an index into an array of items. The minimum allowable value for XmNposition is 0. The maximum allowable value for XmNposition is (XmNmaximumValue-XmNminimumValue)/XmNincrementValue. The value displayed by the XmSpinBox child is XmNminimumValue+(XmNposition*XmNincrementValue).
  • For XmSpinBox children of type XmSTRING, XmNposition is interpreted as an index into an array of XmNnumValues items. The minimum allowable value for XmNposition is 0. The maximum allowable value for XmNposition is XmNnumValues - 1. The value displayed by the XmSpinBox is the XmNposition'th value in the XmNvalues array.

When XmNpositionType is XmPOSITION_VALUE, the XmNposition value is interpreted like this:

  • For XmSpinBox children of type XmNUMERIC, XmNposition is interpreted as the actual value to be displayed. The minimum allowable value for XmNposition is XmNminimumValue. The maximum allowable value for XmNposition is XmNmaximumValue. The value displayed by the XmSpinBox child is XmNposition.
  • For XmSpinBox children of type XmSTRING, the interpretation is the same for XmPOSITION_VALUE as for XmPOSITION_INDEX.
Position values falling outside the specified range are invalid. When an application assigns a value to XmNposition which is less than the minimum, XmNposition is set to the minimum and an error message is displayed. When an application assigns a value to XmNposition which is greater than the maximum, XmNposition is set to the maximum and an error message is displayed. So like, the widget clamps you and then yells at you about it 😭
  • XmNpositionType — specifies how values of the XmNposition resource are to be interpreted. Valid values include XmPOSITION_INDEX and XmPOSITION_VALUE.
  • XmNspinBoxChildType — the type of data displayed in the child:
    • XmNUMERIC — the SpinBox choice range is defined by numeric minimum, maximum, and incremental values.
    • XmSTRING — the SpinBox choices are alphanumeric.
  • XmNvalues — the array of XmStrings to be displayed in a SpinBox string type child. The application must change XmNnumValues when strings are added to or removed from XmNvalues. Used only when XmNspinBoxChildType is XmSTRING.

Inherited Resources 💖

okay bestie, so SpinBox doesn't just invent its whole personality from scratch — it inherits behavior and resources from its superclasses, and they're all listed in the tables below. for the full tea on each resource, go read the reference page for that superclass, mwah 💅

XmManager Resource Set ✨

  • XmNbottomShadowColor — class XmCBottomShadowColor, type Pixel, default dynamic, access CSG
  • XmNbottomShadowPixmap — class XmCBottomShadowPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG
  • 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
  • XmNhighlightPixmap — class XmCHighlightPixmap, type Pixmap, default dynamic, access CSG
  • XmNinitialFocus — class XmCInitialFocus, type Widget, default dynamic, 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 0, access CSG
  • XmNstringDirection — class XmCStringDirection, type XmStringDirection, default dynamic, access CG
  • 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

Composite Resource Set 🦋

  • XmNchildren — class XmCReadOnly, type WidgetList, default NULL, access G
  • XmNinsertPosition — class XmCInsertPosition, type XtOrderProc, default NULL, access CSG
  • XmNnumChildren — class XmCReadOnly, type Cardinal, default 0, access G

Core Resource Set 🎀

  • 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 🎀

A pointer to the following structure is passed to each callback:

typedef struct
{
        int reason;
        XEvent * event;
        Widget widget;
        Boolean doit;
        int position;
        XmString value;
        Boolean crossed_boundary;
} XmSpinBoxCallbackStruct;
  • reason — tells you why the callback was invoked. reasons may be the following:
    • XmCR_OK — spinning has stopped because the SpinBox arrow has been disarmed. XmCR_OK is either the last or only call. 💅
    • XmCR_SPIN_NEXT — the increment arrow has been armed and position is increasing. further callbacks will come. for a numeric type child, the values displayed are approaching the maximum. for a string SpinBox, the values displayed are approaching the last entry in the array of XmString s. ✨
    • XmCR_SPIN_PRIOR — the decrement arrow has been armed and position is decreasing. further callbacks will come. for a numeric type child, the values displayed are approaching the minimum. for a string type child, the values displayed are approaching the first entry in the array of XmStrings. 🌸
    • XmCR_SPIN_FIRST — the begin data (<osfBeginData>) key sequence has been pressed. the SpinBox is at its first position, displaying the lowest value or the first entry in the array of XmStrings. 🫶
    • XmCR_SPIN_LAST — the end data (<osfEndData>) key sequence has been pressed. the SpinBox is at its last position, displaying the highest value or the last entry in the array of XmStrings. 🔥
  • event — points to the XEvent that triggered this callback.
  • widget — specifies the child widget affected by this callback.
  • doit — when the callback is XmNmodifyVerifyCallback, doit indicates whether or not an action will be performed before the SpinBox position changes. if the callback leaves doit set to True (the default), the spinning action is performed. if the callback sets doit to False, the spinning action is not performed. when the callback is XmNvalueChangedCallback, doit is ignored.
  • position — specifies the next value of the SpinBox position (same as XmNposition). this is an output field for the XmNmodifyVerifyCallback, which may change the next position as dictated by the needs of an application.
  • value — specifies the new XmString value in the text child widget. the user program must copy this string if it is to be used outside the callback routine.
  • crossed_boundary — specifies whether or not the SpinBox has crossed the upper or lower boundary (the last or first compound string, or the maximum or minimum value). the crossed_boundary value is True if the SpinBox has just crossed a boundary, and False if it has not.

Translations 🌈

The XmSpinBox translations are as follows:

The following key names are listed in the X standard key event translation table syntax. This format is the one used by Motif to specify the widget actions corresponding to a given key. A brief overview of the format is provided under VirtualBindings(3). For a complete description of the format, please refer to the X Toolkit Instrinsics Documentation.

<Btn1Down>:
          SpinBArm()

<Btn1Up>: SpinBDisarm()

:<Key><osfUp> :
          SpinBPrior()

:<Key><osfDown> :
          SpinBNext()

:<Key><osfLeft> :
          SpinBLeft()

:<Key><osfRight> :
          SpinBRight()

:<Key><osfBeginData> :
          SpinBFirst()

:<Key><osfEndData> :
          SpinBLast()

Accelerators 💫

The XmNaccelerators resource of a SpinBox are added to each traversable text child. The default XmNaccelerators are defined in the following list. The bindings for <Key><osfUp> and <Key><osfDown> cannot be changed.

<Key> <osfUp>:
          SpinBPrior()

<Key> <osfDown>:
          SpinBNext()

<KeyUp> <osfUp>:
          SpinBDisarm()

<KeyUp> <osfDown>:
          SpinBDisarm()

<Key> <osfLeft>:
          SpinBLeft()

<Key> <osfRight>:
          SpinBRight()

<KeyUp> <osfLeft>:
          SpinBDisarm()

<KeyUp> <osfRight>:
          SpinBDisarm()

<Key> <osfBeginData>:
          SpinBFirst()

<Key> <osfEndData>:
          SpinBLast()

Action Routines 🔥

The XmSpinBox action routines are as follows:

  • SpinBArm() — visually arms the SpinBox by drawing the armed arrow so that it appears to be depressed. this action is initiated when the user presses <Btn1> while the pointer is within the boundaries of either the increment or decrement arrow. the arrow remains visually armed as long as <Btn1> remains depressed. 👑

if the time period specified by XmNrepeatDelay is not greater than zero milliseconds, nothing else happens while <Btn1> remains depressed.

if the time period specified by XmNrepeatDelay is greater than zero milliseconds, and the arrow is disarmed before the time period specified by XmNinitialDelay has elapsed, nothing else happens in this action.

if the time period specified by XmNrepeatDelay is greater than zero milliseconds, and the arrow is still armed after the time period specified by XmNinitialDelay has elapsed, the following occurs:

  • The reason member of the SpinBox callback structure, XmSpinBoxCallbackStruct, is set to XmCR_SPIN_NEXT if the increment arrow is armed, or to XmCR_SPIN_PRIOR if the decrement arrow is armed.
  • The position member is set to the next position.
  • The doit member is set to True.
  • XmNmodifyVerifyCallback, if it exists, is invoked. The application may change the value of position and doit. If the application sets doit to False, nothing else happens until the XmNrepeatDelay period has elapsed, or until <Btn1> is released.

If doit stays True (iconic behavior, we love to see it), here's the whole sequence:

  • The value of XmNposition is changed to the value of position in the SpinBox callback structure.
  • The text corresponding to the new position is displayed in the traversable text child that currently has focus.
  • The reason member of the SpinBox callback structure is set to XmCR_SPIN_NEXT if the increment arrow is armed, or XmCR_SPIN_PRIOR if the decrement arrow is armed.
  • The position member is set to the current (new) value of XmNposition.
  • XmNvalueChangedCallback, if it exists, is called. SpinBox ignores any changes to position or doit members made by XmNvalueChangedCallback.

These events are repeated each time the XmNrepeatDelay period elapses and the arrow remains armed. 🔁

SpinBDisarm() 💅

Visually disarms the SpinBox by drawing the previously armed arrow so that it no longer appears to be depressed. Un-pressing, if you will. 🫶

If the time period specified by XmNrepeatDelay is not greater than zero milliseconds, or the time period specified by XmNinitialDelay has not elapsed, the following then occurs:

  • The reason member of the SpinBox callback structure, XmSpinBoxCallbackStruct, is set to XmCR_SPIN_NEXT if the increment arrow is armed, or to XmCR_SPIN_PRIOR if the decrement arrow is armed.
  • The position member is set to the next position.
  • The doit member is set to True.
  • The XmNmodifyVerifyCallback, if there is one, is invoked. The application may change the value of position and doit. If the application sets doit to False, nothing else happens until the XmNrepeatDelay period has elapsed, or until <Btn1> is released.

If doit remains set to True, the following occurs:

  • The value of XmNposition is changed to the value of position in the SpinBox callback structure.
  • The text corresponding to the new position is displayed in the traversable text child that currently has focus.
  • The reason member of the SpinBox callback structure is set to XmCR_SPIN_NEXT if the increment arrow is armed, or XmCR_SPIN_PRIOR if the decrement arrow is armed.
  • The position member is set to the current (new) value of XmNposition.
  • XmNvalueChangedCallback, if it exists, is called. SpinBox ignores any changes to position or doit members made by an XmNvalueChangedCallback.

If an XmNvalueChangedCallback procedure is issued after the button has been armed, regardless of the value of XmNrepeatDelay or whether the XmNinitialDelay has expired:

  • The reason member of the SpinBox callback structure is set to XmCR_OK.
  • The position member is set to the current value of XmNposition.
  • XmNvalueChangedCallback, if it exists, is called.

SpinBFirst() ⭐

The following occurs:

  • The reason member of the SpinBox callback structure, XmSpinBoxCallbackStruct, is set to XmCR_SPIN_FIRST.
  • The position member is set to the first (0) position.
  • The doit member is set to True.
  • XmNmodifyVerifyCallback, if it exists, is invoked. The application may change the value of position and doit. If the application sets doit to False, nothing else happens until the XmNrepeatDelay period has elapsed, or until <Btn1> is released.

If doit remains set to True, the following occurs:

  • The value of XmNposition is changed to the value of position in the SpinBox callback structure.
  • The text corresponding to the new position is displayed in the traversable text child that currently has focus.
  • The reason member of the SpinBox callback structure is set to XmCR_SPIN_FIRST.
  • The position member is set to the current (new) value of XmNposition.
  • XmNvalueChangedCallback, if it exists, is called.
  • The reason member of the SpinBox callback structure is set to XmCR_OK.
  • The position member is set to the current (new) XmNposition value.
  • The XmNvalueChangedCallback is called again. SpinBox ignores any changes to position or doit members made by XmNvalueChangedCallback.

SpinBLast() 🌸

The following occurs:

  • The reason member of the SpinBox callback structure, XmSpinBoxCallbackStruct, is set to XmCR_SPIN_LAST.
  • The position member is set to the last position.
  • The doit member is set to True.
  • XmNmodifyVerifyCallback, if it exists, is invoked. The application may change the value of position and doit. If the application sets doit to False, nothing else happens until the XmNrepeatDelay period has elapsed, or until <Btn1> is released.

If doit remains set to True, the following occurs:

  • The value of XmNposition is changed to the value of position in the SpinBox callback structure.
  • The text corresponding to the new position is displayed in the traversable text child that currently has focus.
  • The reason member of the SpinBox callback structure is set to XmCR_SPIN_LAST.
  • The position member is set to the current (new) value XmNposition.
  • XmNvalueChangedCallback, if it exists, is called.
  • The reason member of the SpinBox callback structure is set to XmCR_OK.
  • The position member is set to the current (new) of XmNposition.
  • XmNvalueChangedCallback is called again. SpinBox ignores any changes to the position or doit members made by XmNvalueChangedCallback.

SpinBLeft() 🦋

If the VendorShell resource XmNlayoutDirection is left-to-right, the SpinBPrior action is invoked. Otherwise, the SpinBNext action is invoked.

SpinBNext() 🔥

Visually arms the SpinBox by drawing the increment arrow so that it appears to be depressed. The following occurs:

  • The reason member of the SpinBox callback structure, XmSpinBoxCallbackStruct, is set to XmCR_SPIN_NEXT.
  • The position member is set to the next position.
  • The doit member is set to True.
  • XmNmodifyVerifyCallback, if it exists, is invoked. The application may change the value of position and doit. If the application sets doit to False, nothing else happens until the XmNrepeatDelay period has elapsed, or until <Btn1> is released.

If doit remains set to True, the following occurs:

  • The value of XmNposition is changed to the value of position in the SpinBox callback structure.
  • The text corresponding to the new position is displayed in the traversable text child that currently has focus.
  • The reason member of the SpinBox callback structure is set to XmCR_SPIN_NEXT.
  • The position member is set to the current (new) value of XmNposition.
  • XmNvalueChangedCallback, if it exists, is called.
  • The reason member of the SpinBox callback structure is set to XmCR_OK.
  • The position member is set to the current (new) XmNposition.
  • The XmNvalueChangedCallback is called again. SpinBox ignores any changes to position or doit members made by XmNvalueChangedCallback.

SpinBPrior() 💖

Visually arms the SpinBox by drawing the decrement arrow so that it appears to be depressed. The following occurs:

  • The reason member of the SpinBox callback structure, XmSpinBoxCallbackStruct, is set to XmCR_SPIN_PRIOR.
  • The position member is set to the next position.
  • The doit member is set to True.
  • XmNmodifyVerifyCallback, if it exists, is invoked. The application may change the value of position and doit. If the application sets doit to False, nothing else happens until the XmNrepeatDelay period has elapsed, or until <Btn1> is released.

If doit remains set to True, the following occurs:

  • The value of XmNposition is changed to the value of position in the SpinBox callback structure.
  • The text corresponding to the new position is displayed in the traversable text child that currently has focus.
  • The reason member of the SpinBox callback structure is set to XmCR_SPIN_PRIOR.
  • The position member is set to the current (new) value of XmNposition.
  • XmNvalueChangedCallback, if it exists, is called.
  • The reason member of the SpinBox callback structure is set to XmCR_OK.
  • The position member is set to the current (new) value of XmNposition.
  • XmNvalueChangedCallback is called again. SpinBox ignores any changes to position or doit members made by XmNvalueChangedCallback.
  • SpinBRight() — okay so this one's a lil choose-your-own-adventure 👀 if the VendorShell resource XmNlayoutDirection is set to left-to-right, then the SpinBNext action gets invoked. Otherwise? The SpinBPrior action gets invoked instead. That's it, that's the whole vibe — it just reads the layout direction and picks a lane. 🎀

like bestie these are the siblings, the extended fam, the ones you also need to know about if you're gonna be messing with this 💖

and that's the whole page, no cap ✨ we did it — every last flag, action and cross-reference, all of it. go forth and spin those boxes, you absolute icon 👑💅

this has been XmSpinBox(library call) — iconic library-call energy, periodt 🫶🌸

📦 where this page comes from