Prima::Lists(3)

📦
version 1.74000 · 5 versions
, in opensuse-leap 16.0

💖 NAME 💖

Prima::Lists(3) — okay bestie, this page is literally about Prima::Lists, aka list widgets. We're gonna get you comfy with the listbox family, no cap. 🎀

🦋 DESCRIPTION 🦋

So this module hands you several listbox classes, and the whole glow-up between them is how the items in the list widget are associated with data. The class hierarchy is giving family tree realness:

        AbstractListViewer
                AbstractListBox
                ListViewer
                        ProtectedListBox
                        ListBox

The root class Prima::AbstractListViewer gives you a common interface, but ngl it’s not usable directly — it’s more like the blueprint, the main character energy without the full fit. 💅

The main differences between the classes are centered around the way the items are stored. The simplest organization of a text-only item list is provided by Prima::ListBox — it stores an array of text scalars in a widget. Cute, minimal, does the job. ✨ More elaborated storage and representation types are not realized, and the programmer is urged to use the more abstract classes to derive their own mechanisms. So like, if you want fancier storage, you’re lowkey invited to build your own thing on top of the abstract classes. 🫶

For example, for a list of items that contain text strings and icons, see Prima::DirectoryListBox in Prima::Dialog::FileDialog. Iconic behavior, literally. 🌈

To organize an item storage different from Prima::ListBox, it’s usually enough to overload either the Stringify, MeasureItem, and DrawItem events, or their method counterparts: get_item_text, get_item_width, and draw_items. That’s the whole little override squad — very slay, very “make it yours.” 💜

💖 Prima::AbstractListViewer 💖

ok so Prima::AbstractListViewer is a descendant of Prima::Widget::GroupScroller (bestie, that means some of its properties are literally not described here, they live in the parent page, so don't @ me).

This class is the whole vibe for generic list browsing, plus extra sparkle for text-oriented lists. But heads up — you can't use this class directly, it's giving abstract base class energy, iykyk. 🧚

✨ Properties ✨

  • autoHeight BOOLEAN — if it's 1, the item height auto-changes when the widget font changes, which is lowkey perfect for text items. If it's 0, the item height stays put, which is the move for non-text items. Default: 1. 🎀
  • count INTEGER — an integer property that gives you access to the number of items in the list. Since this is tied to how the item storage is organized (and therefore whether you can even change the item count), this property is often declared as read-only in descendants of Prima::AbstractListViewer. fr fr read the fine print.
  • dragable BOOLEAN — if 1, you can drag items interactively by holding the Control key together with the left mouse button. If 0, dragging is off. Default: 0. 🖱️
  • drawGrid BOOLEAN — if 1, vertical grid lines between columns get drawn with gridColor. Only actual in multi-column mode, bestie. Default: 1.
  • extendedSelect BOOLEAN — controls how the user selects multiple items, and it only matters when multiSelect is 1. If 0, you gotta click each item individually to mark it selected. If 1, you can drag the mouse or use the Shift key + arrow keys to do range selection, and the Control key selects individual items. Default: 0. 💅
  • focusedItem INDEX — selects the focused item's index. If it's -1, nothing is focused. It's mostly a run-time property, but you can set it during widget creation given that the item list is also accessible at that stage. Default: -1.
  • gridColor COLOR — the color used for drawing those vertical divider lines in multi-column list widgets. The list classes also support setting the grid color indirectly, just like the widget does, via the colorIndex property. To pull that off, the ci::Grid constant is declared (for more detail peep colorIndex in Prima::Widget). Default: cl::Black. 🖤
  • integralHeight BOOLEAN — if 1, only items that fully fit vertically in the widget interior get drawn. If 0, the partially visible ones get drawn too. Default: 0.
  • integralWidth BOOLEAN — if 1, only items that fully fit horizontally in the widget interior get drawn. If 0, partially visible items are drawn too. Only actual in multi-column mode. Default: 0.
  • itemHeight INTEGER — picks the height of items in pixels. Since list classes don't support items with variable heights, changing this affects all the items, no cap. Default: default font height. 📏
  • itemWidth INTEGER — picks the width of items in pixels. Same deal — no variable widths supported, so changes affect all items. Default: default widget width.
  • multiSelect BOOLEAN — if 0, the user can only select one item, and that's reported by the focusedItem property. If 1, the user can select more than one item. In that case, the focusedItem'th item isn't necessarily selected, which is a lil unhinged but that's the design. To access the selected item list, use the selectedItems property. Default: 0. 🌸
  • multiColumn BOOLEAN — if 0, items are arranged vertically in a single column and the main scroll bar is vertical. If 1, items are arranged in several columns, each itemWidth pixels wide, and the main scroll bar is horizontal. Periodt.
  • offset INTEGER — horizontal offset of an item list, in pixels.
  • topItem INTEGER — selects the first item drawn. 👑
  • selectedCount INTEGER — a read-only property, returns the number of selected items. (Don't try to write to it, she's read-only for a reason.)
  • selectedItems ARRAY — ARRAY is an array of integer indices of selected items. 🦋
  • vertical BOOLEAN — sets the general direction of items in multi-column mode. If 1, items increase down-to-right. Otherwise, right-to-down. Doesn't have any effect in single-column mode. Default: 1.

🛠️ Methods 🛠️

  • add_selection ARRAY, FLAG — sets item indices from ARRAY into selected or deselected state depending on FLAG, which is correspondingly 1 or 0. Only for the multi-select mode.
  • deselect_all — clears the selection. Only for the multi-select mode. bye bye selections 👋
  • draw_items CANVAS, ITEM_DRAW_DATA — called from within the Paint notification to draw items. The default behavior calls the DrawItem notification for every item in the ITEM_DRAW_DATA array. ITEM_DRAW_DATA is an array of arrays, where each array is the parameters passed to the DrawItem notification.

This method is overridden in some descendant classes to speed up drawing. For example, std_draw_text_items is the optimized routine for drawing text-based items — it's used in the Prima::ListBox class. See DrawItem for the description of the parameters.

  • draw_text_items CANVAS, FIRST, LAST, STEP, X, Y, OFFSET, CLIP_RECT — called by std_draw_text_items to draw a sequence of text items with indices from FIRST to LAST, by STEP, on CANVAS, starting at point X, Y, and incrementing the vertical position with OFFSET. CLIP_RECT is a reference to an array of four integers given in inclusive-inclusive coordinates that represent the active clipping rectangle.
⚠️ note that OFFSET must be an integer, otherwise you'll see bad effects when text is drawn below Y=0. like, don't do it bestie 😭
  • get_item_text INDEX — returns the text string assigned to the INDEXth item. Since the class doesn't assume how items are stored, the text is queried via the Stringify notification.
  • get_item_width INDEX — returns the width in pixels of the INDEXth item. Since the class doesn't assume the item storage organization, the value is queried via the MeasureItem notification.
  • is_selected INDEX — returns 1 if the INDEXth item is selected, 0 otherwise. simple as that 💅
  • item2rect INDEX, [ WIDTH, HEIGHT ] — calculates and returns four integers with the rectangle coordinates of the INDEXth item. WIDTH and HEIGHT are optional parameters with pre-fetched dimensions of the widget; if they're not set, the dimensions get queried by calling the size property. If they are set though, the size property isn't called, so you get a lil speed-up. ⚡
  • point2item X, Y — returns the index of the item containing the point at (X,Y). If the point belongs to an item outside the widget's interior, it returns the index of the first item outside the widget's interior in the direction of the point. wild but true.
  • redraw_items INDICES — redraws all items in the INDICES array.
  • select_all — selects all items. Only for the multi-select mode. ✨
  • set_item_selected INDEX, FLAG — sets the selection flag on the INDEXth item. If FLAG is 1, the item is selected. If 0, it's deselected. Only for the multi-select mode.
  • select_item INDEX — selects the INDEXth item. Only for the multi-select mode.
  • std_draw_text_items CANVAS, ITEM_DRAW_DATA — an optimized method that draws text-based items. It's fully compatible with the draw_items interface and is used in the Prima::ListBox class.

The optimization comes from the assumption that items share common background and foreground colors, and only differ between selected and non-selected states. The routine groups drawing requests for selected and non-selected items, then draws items with fewer calls to the color property. The background is drawn by the routine itself, while the foreground (usually text) is delegated to the draw_text_items method, so text positioning and any eventual decorations are easier to implement. 🎨

ITEM_DRAW_DATA is an array of arrays of scalars, where each array contains parameters of the DrawItem notification. See DrawItem for the description of the parameters.

  • toggle_item INDEX — toggles selection of the INDEXth item. Only for the multi-select mode. 🔁
  • unselect_item INDEX — deselects the INDEXth item. Only for the multi-select mode.

🎉 Events 🎉

  • Click — called when the user presses the return key or double-clicks on an item. The index of the item is stored in focusedItem.
  • DragItem OLD_INDEX, NEW_INDEX — called when the user finishes dragging an item from OLD_INDEX to NEW_INDEX position. The default action rearranges the item list according to the dragging action. slay 💫
  • DrawItem CANVAS, INDEX, X1, Y1, X2, Y2, SELECTED, FOCUSED, PRELIGHT, COLUMN — called when the INDEXth item is to be drawn on CANVAS. X1, Y1, X2, Y2 define the item rectangle in widget coordinates where the item is to be drawn. SELECTED, FOCUSED, and PRELIGHT are boolean flags, for whether the item must be drawn correspondingly in selected and focused states, with or without the prelight effect.
  • MeasureItem INDEX, REF — stores the width in pixels of the INDEXth item into the REF scalar reference. This notification must be called from within the begin_paint_info/end_paint_info block. no exceptions 🫶
  • SelectItem INDEX, FLAG — called when an item changes its selection state. INDEX is the index of the item, FLAG is its new selection state: 1 if it's selected, 0 if it's not.
  • Stringify INDEX, TEXT_REF — stores the text string associated with the INDEXth item into the TEXT_REF scalar reference.

💜 Prima::AbstractListBox 💜

The same as its ascendant Prima::AbstractListViewer except that it does not propagate the DrawItem message, because it's assuming all items must be drawn as text strings. iconic, honestly 👑

💖 Prima::ListViewer 💖

Okay so, Prima::ListViewer implements an item storage mechanism, but it leaves the definition of the format of the item to the programmer. The items are accessible via the items property and several other helper routines. Slay.

The class also defines user navigation by accepting character keyboard input and jumping to the items that have text assigned with the first letter that matches the input. And yes: Prima::ListViewer is derived from Prima::AbstractListViewer. Periodt.

✨ Properties ✨

  • autoWidth BOOLEAN — selects if the item width must be recalculated automatically when either the font or the item list is changed. Default value: 1 💅
  • count INTEGER — a read-only property; returns the number of items. Read-only, so no editing shenanigans, okay?
  • items ARRAY — accesses the storage array of the items. The format of items is not defined; it is merely treated as one scalar per index. It’s giving “one scalar per index” energy.

💅 Methods 💅

  • add_items ITEMS — appends an array of ITEMS to the end of the item list. Boom, appended.
  • calibrate — recalculates all item widths. Adjusts itemWidth if autoWidth is set. ✨
  • delete_items INDICES — deletes items from the list. INDICES can be either an array or a reference to an array of item indices. Bye-bye, items.
  • get_item_width INDEX — returns the width in pixels of the INDEXth item from the internal cache. Pixels, bestie.
  • get_items INDICES — returns an array of items. INDICES can be either an array or a reference to an array of item indices. Depending on the caller context, the results are different: in the array context the item list is returned; in scalar, only the first item from the list. Context really said “plot twist.”
  • insert_items OFFSET, ITEMS — inserts an array of items at the OFFSET index in the list. Offset must be a valid index; to insert items at the end of the list use the add_items method. ITEMS can be either an array or a reference to an array of items. Valid index only, no cap.
  • replace_items OFFSET, ITEMS — replaces existing items at the OFFSET index in the list. The offset must be a valid index. ITEMS can be either an array or a reference to an array of items. Swap era.

🛡️ Prima::ProtectedListBox 🛡️

A semi-demonstrational class derived from Prima::ListViewer, implementing certain protections for every item during drawing. Assuming that several item drawing algorithms can be used in the same widget, Prima::ProtectedListBox provides a safety layer between these. If an algorithm selects a font or a color and does not restore the old value, this does not affect the outlook of other items. Safety layer supremacy.

This functionality is implemented by overloading the draw_items method and also all graphic properties. iykyk.

👑 Prima::ListBox 👑

Descendant of Prima::ListViewer, declares that an item must be a single text string. Incorporating all the functionality of its predecessors, provides the standard workhorse listbox widget. Main character energy.

🎀 Synopsis 🎀

               my $lb = Prima::ListBox-> create(
                       items       => [qw(First Second Third)],
                       focusedItem => 2,
                       onClick     => sub {
                               print $_[0]-> get_items( $_[0]-> focusedItem), " is selected\n";
                       }
               );

🧚 Methods 🧚

  • get_item_text INDEX — returns the text string associated with the INDEXth item. Since the item storage organization is implemented, does so without calling the Stringify notification. No Stringify call needed, bestie.

💌 AUTHOR 💌

Dmitry Karasik, <dmitry@karasik.eu.org>. The icon behind it all ✨

🔎 SEE ALSO 🔎

  • Prima
  • Prima::Widget
  • Prima::ComboBox
  • Prima::Dialog::FileDialog
  • examples/editor.pl

💖 That’s the whole Prima::Lists(3) page, bestie — from Perl v5.42.0, dated 2024-08-20. Go have the slayest listbox era. 💅✨

📦 where this page comes from