XMPANED(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

✨ NAME ✨

okay so this is XmPaned (library call) — the Paned widget class. yes bestie, the whole vibe is panes, sashes, and resizing drama. 💅

🎀 SYNOPSIS 🎀

#include <Xm/Paned.h>

💅 DESCRIPTION 💅

The Paned widget manages its children in a vertically or horizontally tiled fashion, with each child living in its own separate pane. The panes can be dynamically resized by the user with "control sashes" that show up between the panes. literally the little grabby bars. iconic.

Application programmers get to control whether sashes and separators are displayed, the preferred size of each pane, and which pane will be forced to absorb size restrictions imposed by the Paned widget's parent. yes, one pane has to take one for the team. 😭

🦋 Geometry Management 🦋

The Paned widget usually resizes its children to their preferred sizes when a new child is managed. It will first attempt to resize itself to contain its panes exactly. If that's not possible, then it will hunt through the children, from bottom to top (or right to left), for a pane to resize. it's giving detective energy. 🔍

The Paned widget will attempt to honor the geometry request of its children. It will first attempt to resize itself to satisfy the request, then go through the layout rules below to satisfy the request. Only if all panes are at their min/max values will a geometry request be refused. If the XmNallowResize resource is False for the child, then all geometry requests will be denied, of course. 💀

🌸 Special Considerations 🌸

When a user resizes a pane with the sashes, the Paned widget assumes that this new size is the preferred size of both the pane above and the pane below — unless the XmNresizeToPreferred constraint resource is True for that pane. so yeah, it remembers. it holds receipts. 📝

⭐ Layout Semantics ⭐

In order to make effective use of the Paned widget, it is helpful to know the rules it uses to determine which child will be resized in any given situation. There are three rules used to determine which child is resized. While these rules are always the same, the panes that are searched can change depending upon what caused the change of layout. iykyk. 👑

👑 Layout Rules 👑

  1. Do not let a pane grow larger than its max or smaller than its min size. In addition, do not let a pane without a sash shrink below its preferred size due to a grip movement of another pane.
  2. Do not adjust panes with XmNskipAdjust set.
  3. Do not adjust panes away from their preferred size, although moving one closer to its preferred size is fine.

When searching the children, the Paned widget looks for panes that satisfy all the rules, and if unsuccessful, then it eliminates rule 3 and then 2. Rule 1 is always enforced. periodt.

If the relayout is due to a resize or change in management, then the panes are searched from bottom to top. If space is needed above the current sash, the panes are searched from bottom to top beginning with the second pane above the grip that was moved. If space is needed below the current sash, the panes are searched from top to bottom beginning with the second pane below the grip that was moved. The Paned widget never wraps its pane resizing. Therefore, if space is needed below the sash, then no widget above the sash will ever be resized. no cap.

Note: If the orientation is horizontal, then substitute "right" for "bottom" and "left" for "top" in the above paragraph. 🫶

💖 Resizing Panes 💖

When the Paned widget is resized, it must determine a new size for each pane. There are two methods of doing this. The Paned widget can either give each pane its preferred size and then resize the panes to fit, or it can use the current sizes and then resize the panes to fit. The XmNresizeToPreferred constraint resource allows the application to tell the Paned widget whether to query the child about its preferred size (subject to the XmNpreferredPaneSize) or to use the current size when refiguring the pane locations after the Paned widget has been resized. choose your fighter. ⚔️

All panes assume they should resize to their preferred size until the Paned widget becomes visible to the user.

🧚 Classes 🧚

Paned inherits behavior and resources from the Core, Composite, Constraint, abd Xmmanager classes. (yes, "abd" is in the original, we're not editing it, bestie. 💅)

The class pointer of xmPanedWidgetClass.

The class name is XmPaned.

🍓 New resources 🍓

The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the XmN or XmC prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 🌈

🎀 XmPaned Resource Set 🎀

okay bestie, here's the full resource roster for XmPaned. Think of this as the group chat member list — every resource, its class, type, default, and access level. No cap, all the deets are here.

  • XmNcursor — Class: XmCursor; Type: tCursor; Default: None; Access: CSG
  • XmNmarginHeight — Class: XmCMarginHeight; Type: Dimension; Default: 3; Access: CSG
  • XmNmarginWidth — Class: XmCMarginWidth; Type: Dimension; Default: 3; Access: CSG
  • XmNorientation — Class: XmCOrientation; Type: unsigned char; Default: XmVERTICAL; Access: CSG
  • XmNrefigureMode — Class: XmCBoolean; Type: Boolean; Default: True; Access: CSG
  • XmNsashHeight — Class: XmCSashHeight; Type: Dimension; Default: 8; Access: CSG
  • XmNsashIndent — Class: XmCSashIndent; Type: Position; Default: -10; Access: CSG
  • XmNsashShadowThickness — Class: XmCShadowThickness; Type: Dimension; Default: dynamic; Access: CSG
  • XmNsashTranslations%Translations%XtTranslations%see below — Class: (none listed); Type: (none listed); Default: (none listed); Access: (none listed)
  • XmNsashWidth — Class: XmCSashWidth; Type: Dimension; Default: 10; Access: CSG
  • XmNseparatorOn — Class: XmCSeparatorOn; Type: Boolean; Default: True; Access: CSG
  • XmNspacing — Class: XmCSpacing; Type: Dimension; Default: 8; Access: CSG

💅 What Each Resource Actually Does 💅

XmNcursor — the cursor image that pops off as the pointer whenever you hover over this widget. If the children don't explicitly set their own cursor attribute, they inherit this one. it's giving main character energy, and the kids are copying it.

XmNmarginHeight — sets the distance between the top and bottom edges of the Paned widget and its children. personal space, but vertical.

XmNmarginWidth — sets the distance between the left and right edges of the Paned widget and its children. personal space, but horizontal.

XmNorientation — tells the layout to be either vertical (using the XmVERTICAL value) or horizontal (using the XmHORIZONTAL value). In the vertical layout, the children are laid out in a vertically tiled format. In the horizontal layout, the children are laid out in a horizontal layout, with the sash moveable along the horizontal axis. pick your vibe, bestie.

XmNrefigureMode — decides whether the panes' positions are recomputed and repositioned when programmatic changes are being made to the Paned widget. Setting this resource to True resets the children to their appropriate positions. it's the "okay everyone back to your seats" button.

XmNsashHeight — specifies the height of the sash. that's it, that's the tweet.

XmNsashIndent — specifies the horizontal placement of the sash along each pane. A positive value causes the sash to be offset from the near (left) side of the Paned widget, and a negative value causes the sash to be offset from the far (right) side of the Paned widget. If the offset is greater than the width of the Paned widget minus the width of the sash, the sash is placed flush against the near side of the Paned widget.

Whether the placement actually corresponds to the left or right side of the Paned widget depends on the XmNlayoutDirection resource of the widget. so yes, it's lowkey direction-dependent, iykyk.

XmNsashTranslations — translation bindings for the sash. See below.

XmNsashShadowThickness — specifies the thickness of the shadows of the sashes. dramatic shadows? iconic.

XmNsashWidth — specifies the width of the sash. simple, clean, slay.

XmNseparatorOn — determines whether a separator is created between each of the panes. Setting this resource to True creates a Separator at the midpoint between each of the panes. cute little divider moment.

  • XmNspacing — the gap between each child pane, bestie. that's the breathing room, the personal space, the no-touchy zone between your panes ✨

🌸 XmPaned Constraint Resource Set 🌸

okay so here's the full rundown of every constraint resource on the Paned widget — name, class, type, default, and access, all of it, no skips 💅

  • XmNallowResize — class XmCBoolean, type Boolean, default False, access CSG
  • XmNpaneMaximum — class XmCPaneMaximum, type Dimension, default 1000, access CSG
  • XmNpaneMinimum — class XmCPaneMinimum, type Dimension, default 1, access CSG
  • XmNskipAdjust — class XmCBoolean, type Boolean, default False, access CSG
  • XmNpreferredPaneSize — class XmCPreferredPaneSize, type Dimension, default XmPanedAskChild
  • XmNresizeToPreferred — class XmCBoolean, type Boolean, default False
  • XmNshowSash — class XmCBoolean, type Boolean, default True
  • XmNallowResize — this one lets your app decide whether the Paned widget is even allowed to let a pane ask to be resized. 🫶 and listen — it only does anything after the Paned widget and its children have been realized, so don't expect magic before that, fr. set it to True and the Paned widget will try its best to honor requests to change the height of the pane. set it to False and it's giving bouncer energy: pane resize requests get denied, every single time. 💀
  • XmNpaneMaximum — lets your app set the biggest size a pane is allowed to be resized to. heads up tho: this value has to be greater than the specified minimum. otherwise it's not it.
  • XmNpaneMinimum — the other end of the vibe: lets your app set the smallest size a pane can be resized to. and this value must be greater than 0 (zero). zero is not an option bestie, that's the rules 😭
  • XmNskipAdjust — set this Boolean resource to True and you're basically telling the Paned widget "girl, leave this pane alone" — it should not automatically resize this pane. iconic boundary-setting behavior honestly. ✨
  • XmNpreferredPaneSize — the preferred size of the pane, as the name so kindly suggests 💅 if you don't set this value, the paned widget will go query the child for a preferred size instead. this resource is the lil door that lets the user or the application hand over a new preferred size.
  • XmNresizeToPreferred — decides whether every pane gets resized to its preferred size when the Paned window gets resized. and if this is False? then only the panes that the user has not resized with the sashes get resized to their preferred size. the ones you touched? hands off. 🙈
  • XmNshowSash — if True, show the Sash below or to the right of this pane. that's the whole thing. sash visibility: on. 🎀

🦋 Inherited Resources 🦋

Paned widget is literally built different — it inherits behavior and resources from the superclasses listed in the tables below. 🧚

and for a complete description of each resource, go read the reference page for that superclass, okay? i'm not doing the whole family tree in here. iykyk 💜

okay so before we get into the OPTIONS energy, we gotta meet the whole XmManager resource set, because every single widget that inherits from XmManager is walking around with this exact luggage. 🧳✨

Each one below goes: resource name, then its class, its type, its default, and its access code — all of it verbatim, no cap, nothing skipped. 💅

  • 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 NULL, 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
  • 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

that's the whole squad, all 17 of them, in the exact order the table serves them. 🌸

real talk: notice how a bunch of these say dynamic for the default — that's literally what the page says, don't come for me, I'm just the messenger 🫶

and yes bestie, the access column is doing its own little thing — CSG, CG, and plain C all show up in there, so keep your eyes peeled when you're reading the rest. 🔥

✨ Core Resource Set ✨

okay bestie this is the table, the one everybody screenshots. every widget class out here inherits these, and I'm giving you all of them — name, class, type, default, access — nothing skipped, nothing merged, nothing invented. we are EATING today 🍓

  • 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

that's the whole core set, all nineteen of them, right there in order 👑 note the access column — you got your C, your G, your S, and every combo the page lists, written exactly as the page writes them, no editorializing from me 💅 and look at how many defaults are just dynamic — the toolkit said "we'll figure it out later" and honestly? relatable.

we are NOT done though, there's still more to go, so stay with me 🦋

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

And that's the last of the resource rows, bestie — classes, types, defaults and access letters all exactly as the page hands them over, no notes from me 💅

✨ Translations ✨

okay so XmPaned does not invent its own translations from scratch — it inherits translations from XmManager. Free hand-me-downs, we love that for us 🫶

The translations for sashes within the Paned widget are a whole separate thing, and they're listed in the table below.

So the key names here are written in the X standard key event translation table syntax — that's the format Motif uses to say "when this key happens, run this widget action." If you want the quick lil overview of the format, go peek at VirtualBindings(3). If you want the full description, the page says to go read the X Toolkit Intrinsics Documentation 📚

∼c ∼s ∼m ∼a <Btn1Down>:
          SashAction(Start)

∼c ∼s ∼m ∼a <Btn1Motion>:
          SashAction(Move)

∼c ∼s ∼m ∼a <Btn1Up>:
          SashAction(Commit)

∼c ∼s ∼m ∼a <Btn2Down>:
          SashAction(Start)

∼c ∼s ∼m ∼a <Btn2Motion>:
          SashAction(Move)

∼c ∼s ∼m ∼a <Btn2Up>:
          SashAction(Commit)

:<Key><osfHelp>:
          Help()

:c <Key><osfUp>:
          SashAction(Key,10,Up)

:<Key><osfUp>:
          SashAction(Key,1,Up)

:c <Key><osfRight>:
          SashAction(Key,10,Right)

:<Key><osfRight>:
          SashAction(Key,1,Right)

:c <Key><osfDown>:
          SashAction(Key,10,Down)

:<Key><osfDown>:
          SashAction(Key,1,Down)

:c <Key><osfLeft>:
          SashAction(Key,10,Left)

:<Key><osfLeft>:
          SashAction(Key,1,Left)

s ∼m ∼a <Key>Tab:
          PrevTabGroup()

∼m ∼a <Key>Tab:
          NextTabGroup()

💅 Action Routines 💅

These are the XmPaned action routines, and there are exactly four of them, so let's go:

  • Help() — calls the callbacks for XmNhelpCallback if any exist. If this widget has no help callbacks, it goes and calls the help callbacks for the nearest ancestor that has them. It's giving "asking a grown-up when mom doesn't pick up" 😭
  • NextTabGroup() — moves the keyboard focus to the next tab group. And by default? Each pane and sash is a tab group. Yes ma'am, every single one 👑
  • PrevTabGroup() — moves the keyboard focus to the previous tab group. Same deal: by default, each pane and sash is a tab group 🎀
  • SashAction(action) or SashAction(Key,increment,direction) — okay this is the big one, stay with me:
    • The Start action activates the interactive placement of the pane's borders ✨
    • The Move action makes the sash track the position of the pointer 🖱️
    • If one of the panes hits its minimum or maximum size, the adjustment continues with the next adjustable pane — it does not just give up, it keeps it moving 💫
    • The Commit action ends sash motion. periodt.

Now, when the sash action is caused by a keyboard event, the sash with the keyboard focus gets moved according to the increment and direction you specified. DefaultIncr adjusts the sash by one line. LargeIncr adjusts the sash by one view region. And direction is specified as either Up, Down, Left, or Right 🧭

⚠️ Note this one, it's important: the SashAction action routine is not a direct action routine of the XmPaned — it's an action of the Sash control created by the XmPaned. So it lives one layer down, iykyk 🫠

🌈 Additional Behavior 🌈

This widget has the following additional behavior, and there's two of them:

  • <FocusIn> — moves the keyboard focus to the sash and highlights it ✨
  • <FocusOut> — unsets the keyboard focus in the sash and unhighlights it 🙈

🦋 Virtual Bindings 🦋

The bindings for virtual keys are vendor specific — so like, your mileage may vary by vendor, no cap 🫶

For info about bindings for virtual buttons and keys, go check VirtualBindings(3).

Here's the squad, all of them, in order:

Composite(3), Constraint(3), Core(3), XmCreatePaned(3), XmManager(3), XmPaneGetpanes(3), XmVaCreatePaned(3), and XmVaCreateManagedPaned(3) 💞

and that's a wrap on this one, bestie 🎀 this whole page is the XmPaned(library call) — the library-call version of the page, so that's your source/version tag right there at the foot of it. no date given on this one, so nothing to report on that front 🙈 go forth and sash, you absolute icon 👑💅

📦 where this page comes from