XmForm(3X)

okay bestie, pull up a chair 💖 because we are about to get into the XmForm(3X) manual page — and yes, the header literally says XmForm(3X) while the page itself is all about the Tree widget class. We don't make the rules, we just read them. 🌸

---

✨ NAME ✨

XmTree — the Tree widget class, no cap. 🌳

---

🌸 SYNOPSIS 🌸

#include <Xm/XTree.h>

---

💖 DESCRIPTION 💖

So the Tree widget is a container, and what it does is show the relationship between its children in a cute little graphical tree-ish format. Every single child of the Tree widget is a node in the Tree. 🫶

And here's the spicy part: the parent-child relationships between those nodes are completely distinct from the widget hierarchy. Like, separate. Unrelated. Different lanes entirely. The hierarchy of nodes gets built by you specifying the tree "parent" of each node as a constraint resource. If a node's parent is NULL, then it's assumed to be a root of the tree. 🌱

And even though each widget can only ever have one parent, the Tree widget supports adding more than one "root" node to a single Tree. Multiple roots! Main character energy from every single one of them. 👑

Note: the Tree widget assumes that it will be totally responsible for mapping and unmapping its children. So literally no child of this widget should ever modify its mappedWhenManaged resource. If a child does modify this resource, the behavior is undefined. Don't do it. We're serious. 😭

---

🎀 User Interaction 🎀

Every node in the tree can be in one of four states: open, closed, always open, and hidden. The state of a node changes how it looks to the user and what actions are available to them. Vibe check per node, basically. ✨

• Open — this node gets an open folder shown to its left, and the user can select it to close this node. When a node is open, all of its children are visible to the user. 🎀
• Closed — this node gets a closed folder shown to its left, and the user can select it to open this node. When a node is closed, none of its children are visible</> to the user. 🙈
• Always Open — this node has no folder button associated with it at all. All of its children are visible to the user. Just permanently unbothered. 💅
• Hidden — this node is not shown to the user at all, and all of its children appear and act exactly as if they were children of this node's parent. To the user, it looks like this node straight up does not exist. 💀

To maintain consistency of the user interface, we have found that it's best to use the node state "Always Open" for nodes with no children. That way the user only ever sees a folder button next to a node that actually has children to display. A folder button associated with a node that has no children has no defined semantics. So like... don't. 🍓

---

✨ Normal Resources ✨

• connectStyle — class ConnectStyle, type unsigned char, initial value XmTreeDirect.
• horizontalNodeSpace — class HorizontalDimension, type Dimension, initial value 20.
• verticalNodeSpace — class VerticalDimension, type Dimension, initial value 2.

All resource names begin with XmN and all resource class names begin with XmC.

connectStyle — the style of the lines that visually connect parent nodes to children nodes. The valid styles are XmTreeDirect or XmTreeLadder. Pick your fighter. 🌈

horizontalNodeSpace, verticalNodeSpace — the amount of space between each node in the tree and its nearest neighbor. Personal space matters bestie. 🫶

---

The following resources are inherited from the XmHierarchy widget:

• autoClose — class AutoClose, type Boolean, initial value True.
• closeFolderPixmap — class Pixmap, type Pixmap, initial value XmUNSPECIFIED_PIXMAP.
• horizontalMargin — class HorizontalDimension, type Dimension, initial value 2.
• openFolderPixmap — class Pixmap, type Pixmap, initial value XmUNSPECIFIED_PIXMAP.
• refigureMode — class Boolean, type Boolean, initial value True.
• verticalMargin — class VerticalDimension, type Dimension, initial value 2.

All resource names begin with XmN and all resource class names begin with XmC.

---

💅 Constraint Resources 💅

• openClosePadding — class OpenClosePadding, type Int, initial value 0.
• lineColor — class Foreground, type Pixel, initial value <dynamic>.
• lineWidth — class LineWidth, type Dimension, initial value 0.

All resource names begin with XmN and all resource class names begin with XmC.

openClosePadding — the number of pixels between the folder button and the node it's associated with. Their little gap. Their boundaries. 🎀

lineColor — the color of the line connecting a node to its parent. The default value for this resource is the foreground color of the Tree widget. Iconic default behavior honestly. ✨

lineWidth — the width of a connection line between a node and its parent. 🌸

---

The following constraint resources are inherited from the XmHierarchy widget:

• insertBefore — class InsertBefore, type Widget, initial value NULL.
• nodeState — class NodeState, type XmHierarchyNodeState, initial value Open.
• parentNode — class ParentNode, type Widget, initial value NULL.

All resource names begin with XmN and all resource class names begin with XmC.

---

🌈 Geometry Management 🌈

The layout is performed by assigning each node a box that's just large enough to contain itself and all of its children. Then a recursive layout happens that centers each node vertically in its box and puts it at the extreme left horizontally. After that, the children's boxes are placed to the right of the node, separated by horizontalNodeSpace from their parent, stacked above each other and separated by verticalNodeSpace. And this whole process gets repeated recursively for each child in the tree. It's giving fractal. 🦋

The preferred size of the entire tree will be just large enough to contain all the nodes in the hierarchy. As the state of nodes changes, the tree will attempt to resize itself to contain its current configuration. 🔥

Now here's the tea: if the tree is forced larger than the desired size, the nodes will be centered vertically and flush to the left edge of the tree widget. But if the tree is forced smaller, some nodes may be moved or drawn outside the end of the tree. For this reason, it's usually desirable to put the tree into a Scrolled Window widget. Protect your nodes bestie, wrap them. 😭

---

🦋 SEE ALSO 🦋

• XmColumn(3X)

---

👑 COPYRIGHT 👑

Copyright (c) 1992 by Integrated Computer Solutions, Inc.

---

and that's the whole page, bestie 🫶✨ this one dropped on 15 July 1992, and the footer is out here repping XmForm(3X) one more time just to keep us on our toes. 💖 no cap, you now know the Tree widget better than half the internet. periodt. 💅🎀