Tickit...rWidget(3pm)

💖 Tickit::ContainerWidget 💖

okay so bestie, this is the manual page for Tickit::ContainerWidget, straight out of the perl documentation (3pm, the module section, you know the vibe) 🌸 it's a whole abstract base class situation and honestly? she's iconic.

---

✨ NAME ✨

Tickit::ContainerWidget — abstract base class for widgets that contain other widgets 🫶

---

🌈 SYNOPSIS 🌈

TODO

not me leaving the synopsis as TODO... anyway it's literally in the original, we move 💅

---

🦋 DESCRIPTION 🦋

so basically this class is the abstract base class for widgets that contain at least one other widget object. that's her whole job. she provides storage for a hash of options that are associated with each child widget. lowkey simple, highkey essential, no cap.

---

🎀 STYLE 🎀

these are the style tags she uses:

• :focus-child — gets set whenever a child widget inside the container has the input focus 👑

---

🧚 CONSTRUCTOR 🧚

new

$widget = Tickit::ContainerWidget->new( %args );

constructs a brand new Tickit::ContainerWidget object ✨ but listen, you must call this on a subclass that actually implements the required methods — go read the SUBCLASS METHODS section below, fr fr, don't skip it 🙈

---

💅 METHODS 💅

add

$widget->add( $child, %opts );

sets the child widget's parent, stores the options for that child, and calls the children_changed method. your concrete implementation is gonna have to handle the actual storage of this child widget, that part's on you bestie.

returns the container $widget itself, so you can chain your little heart out 🔥

remove

$widget->remove( $child_or_index );

removes the child widget's parent, and calls the children_changed method. again, the concrete implementation has to remove this child from its storage.

returns the container $widget itself. chaining. we love to see it 💖

child_opts

%opts = $widget->child_opts( $child );

$opts = $widget->child_opts( $child );

returns the options currently set for the given child — as a key/value list in list context, or as a HASH reference in scalar context.

and here's the tea 🍓: in scalar context, that HASH reference is the actual hash used to store the options. so if you modify it, your modifications are preserved. it's giving direct access, not a copy. periodt.

set_child_opts

$widget->set_child_opts( $child, %newopts );

sets new options on the given child. any option whose value is given as undef gets deleted — so passing undef is how you yeet an option out of existence 💀

find_child

$child = $widget->find_child( $how, $other, %args );

returns a child widget. the $how argument decides how that happens, relative to the child widget given by $other:

• first — the first child returned by children ($other is ignored)
• last — the last child returned by children ($other is ignored)
• before — the child widget just before $other in the order given by children
• after — the child widget just after $other in the order given by children

and she also takes these named arguments:

• where => CODE — optional. if defined, this gives you a filter function that filters the list of children before searching for the one you want. it gets invoked once per child, with the child widget set as $_; it should return a boolean value to say whether that child should be included in the search. so basically a vibe check for children ✅

focus_next

$widget->focus_next( $how, $other );

moves the input focus to the next widget in the widget tree, by searching in the direction given by $how relative to the widget given by $other (and heads up — $other must be an immediate child of $widget).

the direction $how has to be one of these four values:

• first
• last — moves focus to the first or last child widget that can take focus. it recurses into child widgets that are themselves containers. $other is ignored.
• after
• before — moves focus to the next or previous child widget in tree order from the one given by $other. recurses into child widgets that are themselves containers, and out into parent containers 🌀

these searches wrap around the widget tree — moving "after" the last node in the widget tree will move to the first, and vice versa. it's a loop bestie, she comes back around 🔁

this differs from find_child because it performs a full tree search through the widget tree, considering parents and children. if a "before" or "after" search falls off the end of one node, it recurses up to its parent and searches within the next child, and so on.

usually you'd use it via the widget itself, like:

$self->parent->focus_next( $how => $self );

---

👑 SUBCLASS METHODS 👑

children

@children = $widget->children;

required. should return a list of all the contained child widgets. the order is not specified, but it should be in some stable order that makes sense given the layout of the widget's children.

this method is used by window_lost to remove the windows from all the child widgets automatically, and by find_child to obtain a child relative to another given one 🫡

children_for_focus

@children = $widget->children_for_focus;

optional. if implemented, this method gets called to obtain a list of child widgets to perform a child search on when changing focus using the focus_next method. if it's not implemented, the regular children method gets called instead.

normally this method shouldn't be used, but it can be useful on container widgets that also display "helper" widgets that shouldn't be considered part of the main focus set. this method can then exclude them. like, not every child gets main character energy, and that's okay 🌈

children_changed

$widget->children_changed;

optional. if implemented, this method gets called after any change of the contained child widgets or their options. typically you'd use it to set windows on them by sub-dividing the window of the parent.

if it's not overridden, the base implementation calls reshape. automatic bestie behaviour ✨

child_resized

$widget->child_resized( $child );

optional. if implemented, this method gets called after a child widget changes, or may have changed, its size requirements. typically you'd use it to adjust the windows allocated to children.

if it's not overridden, the base implementation calls reshape. same energy, different trigger 💜

---

🌸 AUTHOR 🌸

Paul Evans <leonerd@leonerd.org.uk> — thank you for your service, king 🫶

---

and that's the whole page bestie, no notes 💖 this was perl v5.40.0, dated 2024-09-16, and it's the Tickit...rWidget(3pm) page — slay, ate, left absolutely no crumbs 👑✨