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

💖 XmScrolledWindow — the ScrolledWindow widget class 💖

okay bestie, welcome to XmScrolledWindow(library call), the little manual page that's about to change your whole scroll game. this is a library call page, so grab a snack and let's get into it 🫶

✨ SYNOPSIS ✨

#include <Xm/ScrolledW.h>

🌸 DESCRIPTION 🌸

so basically, the ScrolledWindow widget is that girl who takes one or two ScrollBar widgets plus a viewing area and turns them into a visible window onto some other — usually way bigger — data display. you know how you can only see a lil slice of a huge thing at once? yeah. that. and the user can scroll through the bigger display using the ScrollBars. iconic behaviour, no notes 💅

to use ScrolledWindow, an app first creates a ScrolledWindow widget, any ScrollBar widgets it needs, and a widget that's capable of displaying whatever data it wants as the work area of ScrolledWindow. then ScrolledWindow positions that work area widget and shows the ScrollBars if you asked for them. when the user does some action on the ScrollBar, the app gets notified through the normal ScrollBar callback interface. periodt.

ScrolledWindow can be configured to go automatic, meaning it does all the scrolling and display actions itself with literally zero involvement from the application program. OR it can be configured to give you a minimal support framework, where the app is the one responsible for processing all user input and making all the visual changes to the displayed data in response. your call, bestie 🎀

when ScrolledWindow is doing automatic scrolling, it creates a clipping window and automatically creates the scroll bars. conceptually, this window becomes the viewport through which the user examines the larger underlying data area. the app just creates the data it wants, then makes that data the work area of the ScrolledWindow. and when the user moves the slider to change the displayed data, the workspace gets moved under the viewing area so a new portion of the data becomes visible. it's giving magic, honestly ✨

sometimes though, it's just not practical for an app to create a huge data space and display it through a tiny clipping window. like, imagine a text editor — creating one single data area that consisted of a large file would involve an undesirable amount of overhead. 😭 the app still needs a ScrolledWindow (a small viewport onto some larger data), but it also needs to be notified when the user scrolls the viewport so it can pull in more data from storage and update the display area. for these cases, ScrolledWindow can be configured to provide only visual layout support. no clipping window is created, and the application must maintain the data displayed in the work area, as well as respond to user input on the ScrollBars. so like, you're on your own but make it fashion 💀

the user can specify resources in a resource file for the automatically created widgets that contain the horizontal and vertical scrollbars and the clipping area of the ScrolledWindow widget. the names of these widgets are HorScrollBar, VertScrollBar, and ClipWindow respectively, and they stay consistent whether created by XmCreateScrolledList, XmCreateScrolledText or XmCreateScrolledWindow. consistency is the vibe check that matters 🦋

ScrolledWindow uses the XmQTnavigator trait, and holds the XmQTscrollFrame trait.

🎀 Descendants 🎀

ScrolledWindow automatically creates the descendants below. an application can use XtNameToWidget to gain access to the named descendant. plus, a user or an application can use the named descendant when specifying resource values. so many doors open for you, bestie 💜

  • Named Descendant: VertScrollBar — Class: XmScrollBar — Identity: vertical scroll bar
  • Named Descendant: HorScrollBar — Class: XmScrollBar — Identity: horizontal scroll bar
  • Named Descendant: ClipWindow — Class: XmClipWindow — Identity: clip window

👑 Classes 👑

ScrolledWindow inherits behavior, resources, and traits from Core, Composite, Constraint, and XmManager. a whole family tree, fr fr 🌈

  • the class pointer is xmScrolledWindowWidgetClass.
  • the class name is XmScrolledWindow.

🌟 New Resources 🌟

the table below defines a set of widget resources the programmer uses 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 tell you 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)
heads up bestie, the actual resource table is coming in the next part, so don't go anywhere 💖

💅 The Resource Set (yes bestie, all of it) 💅

Okay so here's the full tea on every single resource. Five columns, no skips, no shortcuts: Name, Class, Type, Default, Access. Periodt. ✨

  • XmNautoDragModel — Class XmCAutoDragModel, type XtEnum, default XmAUTO_DRAG_ENABLED, access CSG
  • XmNclipWindow — Class XmCClipWindow, type Widget, default dynamic, access G
  • XmNhorizontalScrollBar — Class XmCHorizontalScrollBar, type Widget, default dynamic, access CSG
  • XmNscrollBarDisplayPolicy — Class XmCScrollBarDisplayPolicy, type unsigned char, default dynamic, access CSG
  • XmNscrollBarPlacement — Class XmCScrollBarPlacement, type unsigned char, default XmBOTTOM_RIGHT, access CSG
  • XmNscrolledWindowMarginHeight — Class XmCScrolledWindowMarginHeight, type Dimension, default 0, access CSG
  • XmNscrolledWindowMarginWidth — Class XmCScrolledWindowMarginWidth, type Dimension, default 0, access CSG
  • XmNscrollingPolicy — Class XmCScrollingPolicy, type unsigned char, default XmAPPLICATION_DEFINED, access CG
  • XmNspacing — Class XmCSpacing, type Dimension, default 4, access CSG
  • XmNtraverseObscuredCallback — Class XmCCallback, type XtCallbackList, default NULL, access CSG
  • XmNverticalScrollBar — Class XmCVerticalScrollBar, type Widget, default dynamic, access CSG
  • XmNvisualPolicy — Class XmCVisualPolicy, type unsigned char, default dynamic, access G
  • XmNworkWindow — Class XmCWorkWindow, type Widget, default NULL, access CSG

🦋 Resource Descriptions 🦋

Time to meet the whole cast, one resource at a time. Sit down, grab a snack, we're doing this properly. 🍓

XmNautoDragModel

Tells you whether automatic drag is turned on — that's XmAUTO_DRAG_ENABLED — or off, which is XmAUTO_DRAG_DISABLED. And the default? Enabled. It's giving "yes, obviously". 💅

XmNclipWindow

This one's the widget ID of the clipping area. ScrolledWindow makes it for you automatically when XmNvisualPolicy is set to XmCONSTANT, and your app can only read it — no writing, bestie.

⚠️ Try to set this resource to a new value and the scrolled window prints a warning message at you. Like, it will call you out.

But if XmNvisualPolicy is set to XmVARIABLE? Then this resource gets set to NULL and no clipping window is created at all. Gone. Ghosted. 💀

XmNhorizontalScrollBar

The widget ID of the horizontal ScrollBar, no cap. ScrolledWindow creates it automatically when XmNscrollingPolicy is initialized to XmAUTOMATIC — otherwise the default is NULL. Simple as that. ✨

XmNscrollBarDisplayPolicy

This controls where the ScrollBars get automatically placed. Two moods:

  • Set it to XmAS_NEEDED, and if XmNscrollingPolicy is XmAUTOMATIC, ScrollBars show up only when the workspace exceeds the clip area in one dimension or both. Very "only here when you need me". 🫶
  • Set it to XmSTATIC, and the ScrolledWindow displays the ScrollBars whenever they are managed — regardless of the relationship between the clip window and the work area. Always showing up, main character energy. 👑
🚨 Important: this resource must be XmSTATIC when XmNscrollingPolicy is XmAPPLICATION_DEFINED. Not optional, not negotiable.

Default situation: XmAS_NEEDED when XmNscrollingPolicy is XmAUTOMATIC, and XmSTATIC in every other case.

XmNscrollBarPlacement

Where do the ScrollBars sit relative to the work window? Pick your vibe:

  • XmTOP_LEFT — the horizontal ScrollBar goes above the work window, and the vertical ScrollBar goes to the left.
  • XmBOTTOM_LEFT — the horizontal ScrollBar goes below the work window, and the vertical ScrollBar goes to the left.
  • XmTOP_RIGHT — the horizontal ScrollBar goes above the work window, and the vertical ScrollBar goes to the right.
  • XmBOTTOM_RIGHT — the horizontal ScrollBar goes below the work window, and the vertical ScrollBar goes to the right.

The actual default depends on what XmNlayoutDirection is set to on the widget. iykyk. 🌈

XmNscrolledWindowMarginHeight

The margin height on the top and bottom of the ScrolledWindow. Now here's the lore: to use the autoscroll drag feature of the Motif drag and drop facility, a user has to be able to hold a drag icon over the margin of a scrolled window.

😭 The thing is — drag and drop will work with the default margin size of zero, but the user may find it genuinely difficult to position the icon precisely enough to actually use the feature easily.

So if you want the autoscroll drag feature in your app, the application programmer should make sure the window margins are set to an adequate size. Do your friend a favor. 🎀

XmNscrolledWindowMarginWidth

The margin width on the right and left sides of the ScrolledWindow. And please — go back and read the warning about the default margin size for XmNscrolledWindowMarginHeight above, because it applies here too. Same energy, different axis. ✨

XmNscrollingPolicy 🌀

Okay so bestie, this resource is the one that decides who's driving. It performs automatic scrolling of the work area with no application interaction — literally zero effort from your app. 🌈

If the value of this resource is XmAUTOMATIC, ScrolledWindow goes full main character and does all of this itself: creates the ScrollBars, attaches callbacks to the ScrollBars, sets the visual policy to XmCONSTANT, and automatically moves the work area through the clip window in response to any user interaction with the ScrollBars. And your application can still add its own callbacks to the ScrollBars on top of that — which means your app gets notified of a scroll event without having to perform any layout procedures. ate. 👑

NOTE: Since the ScrolledWindow adds callbacks to the ScrollBars, an application should not perform an XtRemoveAllCallbacks on any of the ScrollBar widgets. not the vibe, don't do it 💀

When XmNscrollingPolicy is set to XmAPPLICATION_DEFINED, the application is responsible for all aspects of scrolling. The ScrollBars must be created by the application, and it is responsible for performing any visual changes in the work area in response to user input. you wanted the aux cord, you got it 🎧

This resource must be set to the desired policy at the time the ScrolledWindow is created. It cannot be changed through SetValues. no take-backs, no edits, fr fr 🙈

XmNspacing 📏

Specifies the distance that separates the ScrollBars from the work window. personal space matters. 🫶

XmNtraverseObscuredCallback 🔍

Specifies a list of callbacks that is called when traversing to a widget or gadget that is obscured due to its position in the work area relative to the location of the ScrolledWindow viewport. ✨

This resource is valid only when XmNscrollingPolicy is XmAUTOMATIC. If this resource is NULL, an obscured widget cannot be traversed to. The callback reason is XmCR_OBSCURED_TRAVERSAL.

XmNverticalScrollBar ⬆️

Specifies the widget ID of the vertical ScrollBar. This is automatically created by ScrolledWindow when the XmNscrollingPolicy is initialized to XmAUTOMATIC; otherwise, the default is NULL. she builds it for you or she doesn't 💅

XmNvisualPolicy 🦋

Enlarges the ScrolledWindow to match the size of the work area. It can also be used as a static viewport onto a larger data space. 🌸

If the visual policy is XmVARIABLE, the ScrolledWindow forces the ScrollBar display policy to XmSTATIC and allows the work area to grow or shrink at any time and adjusts its layout to accommodate the new size. flexible queen. 💖

When the policy is XmCONSTANT, the work area grows or shrinks as requested, but a clipping window forces the size of the visible portion to remain constant. The only time the viewing area can grow is in response to a resize from the ScrolledWindow's parent.

The default is XmCONSTANT when XmNscrollingPolicy is XmAUTOMATIC, and XmVARIABLE otherwise.

NOTE: This resource must be set to the desired policy at the time the ScrolledWindow is created. It cannot be changed through SetValues. same rule as before, iykyk 😭

XmNworkWindow 🪟

Specifies the widget ID of the viewing area.

And then there's the constraint resource set for it, the XmScrolledWindow Constraint Resource Set, which goes a lil something like:

  • Name — XmNscrolledWindowChildType
  • Class — XmCScrolledWindowChildType
  • Type — unsigned char
  • Default — RESOURCE_DEFAULT
  • Access — CSG

XmNscrolledWindowChildType 🎀

Specifies what the child is. ScrolledWindow supports a number of child types, and the possible values are giving:

  • XmWORK_AREA — Indicates a work area child. This specifies that both ScrollBars are limited to moving the child inside the clipping window. If the scrolling policy is XmAUTOMATIC, the work area child can move in both directions. 🌀
  • XmHOR_SCROLLBAR — Indicates a horizontal child widget; the child must have the XmQTnavigator trait installed. For example, the XmScrollBar widget has the XmQTnavigator trait installed. ⭐
  • XmVERT_SCROLLBAR — Indicates a vertical child widget; the child must have the XmQTnavigator trait installed.
  • XmSCROLL_HOR — Indicates that only the horizontal ScrollBar moves the child. This value is only meaningful if the scrolling policy is XmAUTOMATIC.
  • XmSCROLL_VERT — Indicates that only the vertical ScrollBar moves the child. This value is only meaningful if the scrolling policy is XmAUTOMATIC.
  • XmNO_SCROLL — Indicates that the child does not move with the ScrollBars. This value is only meaningful if the scrolling policy is XmAUTOMATIC. sit still bestie, we're not going anywhere 🙈

🌟 Inherited Resources 🌟

ScrolledWindow inherits behavior and resources from the superclasses described in the following tables. For a complete description of each resource, refer to the reference page for that superclass. go read those too, they're part of the lore 📚✨

Ok bestie, now for the part everyone actually screenshots: the resource sets. This is the receipts section — every resource, its class, its type, its default, and who's allowed to touch it. 💅

✨ XmManager Resource Set ✨

Every widget that inherits from XmManager gets all of these for free, no cap. One bullet per resource, so nothing slips through. 🫶

  • XmNbottomShadowColor — class XmCBottomShadowColor, type Pixel, default is dynamic, access CSG.
  • XmNbottomShadowPixmap — class XmCBottomShadowPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG.
  • XmNforeground — class XmCForeground, type Pixel, default is dynamic, access CSG.
  • XmNhelpCallback — class XmCCallback, type XtCallbackList, default NULL, access C.
  • XmNhighlightColor — class XmCHighlightColor, type Pixel, default is dynamic, access CSG.
  • XmNhighlightPixmap — class XmCHighlightPixmap, type Pixmap, default is dynamic, access CSG.
  • XmNinitialFocus — class XmCInitialFocus, type Widget, default NULL, access CSG.
  • XmNlayoutDirection — class XmCLayoutDirection, type XmDirection, default is 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 is dynamic, access CSG.
  • XmNstringDirection — class XmCStringDirection, type XmStringDirection, default is dynamic, access CG.
  • XmNtopShadowColor — class XmCTopShadowColor, type Pixel, default is dynamic, access CSG.
  • XmNtopShadowPixmap — class XmCTopShadowPixmap, type Pixmap, default is dynamic, access CSG.
  • XmNtraversalOn — class XmCTraversalOn, type Boolean, default True, access CSG.
  • XmNunitType — class XmCUnitType, type unsigned char, default is dynamic, access CSG.
  • XmNuserData — class XmCUserData, type XtPointer, default NULL, access CSG.
Notice how many of those say dynamic for the default, bestie — that's not me being vague, that's literally what the manpage says. The value gets worked out for you. Iconic behaviour honestly. ✨

✨ Composite Resource Set ✨

And if your widget is a Composite on top of all that, you also inherit these three. Short list, big power. 👑

  • 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.
XmNchildren and XmNnumChildren are read-only — access G — so don't even think about setting them yourself. They're the widget's little diary, you just read it. 📖

That's the whole inheritance stack for this one, babes — every single resource accounted for, zero skipped, zero invented. More coming, don't go anywhere. 🦋

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

okay so listen up bestie — if you want to actually hear about user input, your app must use the ScrollBar callbacks. That's the whole vibe. No shortcuts. 👑

ScrolledWindow defines a callback structure for use with XmNtraverseObscuredCallback callbacks. The XmNtraverseObscuredCallback resource is basically the ✨glow-up✨ mechanism that lets traversal reach widgets (or gadgets) that got obscured because of where they're sitting in the work area of a ScrolledWindow. It's giving hidden behind the vibe. 🫣

The XmNtraverseObscuredCallback routine has responsibility for adjusting the position of the work area such that the specified traversal destination widget is positioned within the viewport of the ScrolledWindow. Like, that's literally its job description, no cap. 💅

heads up queen: a NULL XmNtraverseObscuredCallback resource causes obscured widgets within the ScrolledWindow to be nontraversable. So if you leave it NULL, those hidden babes are just… unreachable. 😭 Not the main character energy you want.

So traversal to an obscured widget or gadget requires these conditions to be met, and bestie you need all three, not two out of three, this isn't a vibe check where partial credit exists:

  • the widget or gadget can be obscured only due to its position in the work area of a ScrolledWindow relative to the viewport 🌸
  • the viewport of the associated ScrolledWindow is fully visible, or can be made so by virtue of ancestral XmNtraverseObscuredCallback routines ✨
  • and the XmNtraverseObscuredCallback resource must be non-NULL 🔥

And when ScrolledWindow widgets are nested — you know, windows in windows in windows, very inception core 🌈 — the XmNtraverseObscuredCallback routine for each ScrolledWindow that obscures the traversal destination is called in ascending order within the given hierarchy. Order matters, iykyk. 💜

So like, a pointer to this structure gets passed to callbacks for XmNtraverseObscuredCallback. Here's the whole look:

typedef struct
{
        int reason;
        XEvent *event:
        Widget traversal_destination;
        XmTraversalDirection direction;
} XmTraverseObscuredCallbackStruct;
  • reason — tells you why the callback was invoked, bestie. It's the receipts. 🧾
  • event — points to the XEvent that triggered the callback. That's the moment that started it all. ✨
  • traversal_destination — the widget or gadget you're traversing to. It's gonna be a descendant of the work window. Family tree vibes. 🌳
  • direction — the direction of traversal. For the valid values, go read the description of the direction parameter in the XmProcessTraversal reference page. It's all there, iykyk. 💅

Translations 💫

XmScrolledWindow includes the translations from XmManager. So it's literally borrowing the whole translation vibe. Periodt. 💖

Additional Behavior 🎀

This widget has the following additional behavior:

  • <Key><osfPageUp> — if XmNscrollingPolicy is XmAUTOMATIC, it scrolls the window up the height of the viewport. The distance scrolled may be reduced to provide some overlap. The actual distance scrolled depends on the XmNpageIncrement resource of the vertical ScrollBar. Up up and away! 🎈
  • <Key><osfPageDown> — if XmNscrollingPolicy is XmAUTOMATIC, it scrolls the window down the height of the viewport. The distance scrolled may be reduced to provide some overlap. The actual distance scrolled depends on the XmNpageIncrement resource of the vertical ScrollBar. Going down? Groundbreaking. 😌
  • <Key><osfPageLeft> — if XmNscrollingPolicy is XmAUTOMATIC, it scrolls the window left the width of the viewport. The distance scrolled may be reduced to provide some overlap. The actual distance scrolled depends on the XmNpageIncrement resource of the horizontal ScrollBar. Left, bestie! ⬅️
  • <Key><osfPageRight> — if XmNscrollingPolicy is XmAUTOMATIC, it scrolls the window right the width of the viewport. The distance scrolled may be reduced to provide some overlap. The actual distance scrolled depends on the XmNpageIncrement resource of the horizontal ScrollBar. Right? Right. ➡️
  • <Key><osfBeginLine> — if XmNscrollingPolicy is XmAUTOMATIC, it scrolls the window horizontally to the edge corresponding to the horizontal ScrollBar's minimum value. Start of the line energy. ✨
  • <Key><osfEndLine> — if XmNscrollingPolicy is XmAUTOMATIC, it scrolls the window horizontally to the edge corresponding to the horizontal ScrollBar's maximum value. End of the line, no cap. 💅
  • <Key><osfBeginData> — if XmNscrollingPolicy is XmAUTOMATIC, it scrolls the window vertically to the edge corresponding to the vertical ScrollBar's minimum value. Top of the data, let's go. 🔝
  • <Key><osfEndData> — if XmNscrollingPolicy is XmAUTOMATIC, it scrolls the window vertically to the edge corresponding to the vertical ScrollBar's maximum value. Bottom of the data, we made it. 🎉

Some apps are gonna want to swap these page bindings out for ones that match whatever's inside the scrolled area. And honestly? Valid. Do you. 💖

Virtual Bindings 🧚

Virtual key bindings are vendor specific, so it's giving "everyone's different." Wanna know about virtual buttons and keys? Check VirtualBindings(3). It's the plug. 🔌

You might also vibe with these:

And that's a wrap on the XmScrolledWindow(library call) page, bestie! Source/version is exactly that, and there's no date on this one, but it's still iconic. Catch you in the next man page. Bye! 💅✨

📦 where this page comes from