Prima::Outlines(3)

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

✨ NAME ✨

Prima::Outlines — tree view widgets. Yep bestie, this is the Prima::Outlines(3) page from the User Contributed Perl Documentation, and it's all about making tree-shaped stuff show up in Prima 💖

🌈 SYNOPSIS 🌈

use Prima qw(Outlines Application);
my $outline = Prima::StringOutline-> create(
        items => [
                [ 'Simple item' ],
                [ 'Embedded items', [['#1'], ['#2']]],
        ],
);
$outline-> expand_all;
run Prima;

my $outline = Prima::StringOutline-> create(
        iconStyle => 'triangle',
        ...
);

🦋 DESCRIPTION 🦋

Okay so this module hands you a whole set of widget classes made for displaying tree-like structures. Prima::OutlineViewer is the generic one — it has the basic functionality and defines the interface for its descendants, which are Prima::StringOutline, Prima::Outline, and Prima::DirectoryOutline. Slay 🌸

🌳 Prima::OutlineViewer 🌳

This bad boy presents a generic interface for browsing tree-like lists. Each node in the linked list represents an item. The node format is already predefined, and it's an anonymous array with these index definitions:

  • #0 — Item id in an unspecified format. The simplest implementation, Prima::StringOutline, treats the scalar as a text string. The more complex classes store references to arrays or hashes here. See the items article of a concrete class for the format of the node record.
  • #1 — Reference to a child node. undef if there is none.
  • #2 — A boolean flag that selects if the node is to be shown as expanded, e.g. all of its immediate children are visible.
  • #3 — Width of an item in pixels.
Indices above 3 should not be used, because eventual changes to the implementation of the class may use these. The general idea is that the data at index #0 should be self-sufficient to define an item. No cap 💅

To support a custom format of the node, these notifications should be overloaded: DrawItem, MeasureItem, and Stringify. Since DrawItem is called for every item, a gross method draw_items can be overloaded instead. See also Prima::StringOutline and Prima::Outline.

The class employs two ways to address an item: index-wise and item-wise. The index-wise one counts only the visible ( non-expanded ) items and is represented by an integer index. The item-wise addressing cannot be expressed by an integer index, and the full node structure is used as a reference. It is important to use a valid reference here, since the class does not always perform the check if the node belongs to the internal node list — due to speed reasons 👀

Prima::OutlineViewer is a descendant of Prima::Widget::GroupScroller and Prima::Widget::MouseScroller, so some of their properties and methods are not described here.

Heads up bestie: this class is not usable directly 🫶

🎀 Properties 🎀

  • autoHeight INTEGER — If set to 1, changes itemHeight automatically according to the widget font height. If 0, it does not influence anything. When itemHeight is set explicitly, this value changes to 0. Default value: 1 ✨
  • dragable BOOLEAN — If 1, allows the items to be dragged interactively by pressing the Control key together with the left mouse button. If 0, item dragging is disabled. Default value: 1
  • drawLines BOOLEAN — If 1, draws dotted tree lines left of the items. Default value: 1
  • extendedSelect BOOLEAN — Manages the way the user selects multiple items, and it's only actual when multiSelect is 1. If 0, the user must click each item to mark it as selected. If 1, the user can drag the mouse or use the Shift key plus arrow keys to perform range selection; the Control key can be used to select individual items. Default value: 0
  • focusedItem INTEGER — Selects the focused item index. If -1, no item is focused. It's mostly a run-time property, but it can be set during the widget creation stage given that the item list is accessible at this stage too.
  • iconCollapsed ICON — Sets the image that is displayed when a tree branch is collapsed.
  • iconExpanded ICON — Sets the image that is displayed when a tree branch is expanded.
  • iconStyle STYLE — Sets visual style, one of: default, plusminus, or triangle. The default style is set in $Prima::Outlines::default_style and is currently 'plusminus', but it can be overridden by skin. The default style for the current default skin flat is 'triangle'.
  • indent INTEGER — Width in pixels of the indent between item levels. Default value: 12
  • itemHeight INTEGER — Selects the height of the items in pixels. Since the outline classes do not support items with various heights, changes to this property affect all items. Default value: default font height
  • items ARRAY — Provides access to the items as an anonymous array. The format of an item is described in the opening article ( see Prima::OutlineViewer ). Default value: []
  • multiSelect BOOLEAN — If 0, the user can only select one item, which is also reported by the focusedItem property. If 1, the user can select more than one item. In this case, the focusedItem'th item is not necessarily selected. To access the selected item list, use the selectedItems property. Default value: 0
  • offset INTEGER — Horizontal offset of the item list in pixels.
  • selectedItems ARRAY — ARRAY is an array of integer indices of the selected items. Note that these are the items visible on the screen only. The property doesn't handle the selection status of the collapsed items. The widget keeps the selection status on each node, visible and invisible ( e.g. the node is invisible if its parent node is collapsed ). However, selectedItems accounts for the visible nodes only; to manipulate the node status or both visible and invisible nodes, use the select_item, unselect_item, and toggle_item methods.
  • showItemHint BOOLEAN — If 1, allows activation of a hint label when the mouse pointer is hovered above an item that does not fit horizontally into the widget inferiors. If 0, the hint is never shown. See also: makehint. Default value: 1
  • topItem INTEGER — Selects the first item drawn.

💅 Methods 💅

  • add_selection ARRAY, FLAG — Sets item indices from ARRAY in selected or deselected state, depending on the FLAG value, correspondingly 1 or 0. Note that these are the items visible on the screen only. The method doesn't handle the selection status of the collapsed items. Only for the multi-select mode.
  • adjust INDEX, EXPAND — Performs expansion ( 1 ) or collapse ( 0 ) of the INDEXth item, depending on the EXPAND boolean flag value.
  • calibrate — Recalculates the node tree and item dimensions. Used internally.
  • delete_items [ NODE = undef, OFFSET = 0, LENGTH = undef ] — Deletes LENGTH children items of NODE at OFFSET. If NODE is undef, the root node is assumed. If LENGTH is undef, all items after OFFSET are deleted.
  • delete_item NODE — Deletes NODE from the item list.
  • deselect_all — Removes selection from all items. Only for multi-select mode.
  • draw_items CANVAS, PAINT_DATA — Called from within the Paint notification to draw items. The default behavior is to call the DrawItem notification for every visible item. PAINT_DATA is an array of arrays, where each consists of the parameters passed to the DrawItem notification. This method is overridden in some descendant classes, to increase the speed of the drawing routine. See DrawItem for PAINT_DATA parameters description.
  • get_index NODE — Traverses all items for NODE and finds if it is visible. If it is, returns two integers: the first is the item index and the second is the item depth level. If the node is not visible, -1, undef is returned.
  • get_index_text INDEX — Returns the text string associated with the INDEXth item. Since the class does not assume the item storage organization, the text is queried via the Stringify notification.
  • get_index_width INDEX — Returns the width in pixels of the INDEXth item, which is a cached result of the MeasureItem notification, stored under index #3 in a node.
  • get_item INDEX — Returns two scalars corresponding to the INDEXth item: the node reference and its depth level. If INDEX is outside the list boundaries, an empty array is returned.
  • get_item_parent NODE — Returns two scalars, corresponding to the NODE: its parent node reference and offset of the NODE in the parent's immediate children list.
  • get_item_text NODE — Returns the text string associated with the NODE. Since the class does not assume the item storage organization, the text is queried via the Stringify notification.
  • get_item_width NODE — Returns width in pixels of the INDEXth item, which is a cached result of the MeasureItem notification, stored under index #3 in a node.
  • expand_all [ NODE = undef ]. — Expands all nodes under NODE. If NODE is undef, the root node is assumed. If the tree is large, the execution can take a significant amount of time ⏳
  • insert_items NODE, OFFSET, @ITEMS — Inserts one or more ITEMS under NODE with OFFSET. If NODE is undef, the root node is assumed.
  • iterate ACTION, FULL — Traverses the item tree and calls the ACTION subroutine on each node. If the FULL boolean flag is 1, all nodes are traversed. If 0, only the expanded nodes are traversed. ACTION subroutine is called with the following parameters:
    • #0 — Node reference
    • #1 — Parent node reference; if undef, the node is the root.
    • #2 — Node offset in the parent item list.
    • #3 — Node index.
    • #4 — Node depth level. 0 means the root node.
    • #5 — A boolean flag, set to 1 if the node is the last child in the parent node list, set to 0 otherwise.
    • #6 — Visibility index. When iterate is called with FULL = 1, the index is the item index as seen on the screen. If the item is not visible, the index is undef. When iterate is called with FULL = 1, the index is always the same as node index.
  • is_selected INDEX, ITEM — Returns 1 if an item is selected, 0 if it is not. The method can address the item either directly ( ITEM ) or by its INDEX in the screen position.
  • makehint SHOW, INDEX — okay so this one controls the hint label of the INDEXth item. If the boolean flag SHOW is 1, the showItemHint property is 1, and the item index does not fit horizontally in the widget inferiors, then the hint label is shown. By default the label is removed automatically as soon as the user moves the mouse pointer away from the item. If SHOW is 0, the hint label is hidden immediately. periodt 💅
  • point2item Y, [ HEIGHT ] — returns the index of the item that occupies the horizontal axis at Y in the widget coordinates. If HEIGHT is specified, it must be the widget height; if it is not, the value is fetched by calling Prima::Widget::height. If the value is known, passing it to point2item thus achieves some speed-up. literally free speed ⚡
  • select_all — selects all items. Only for multi-select mode. ✨
  • set_item_selected INDEX, ITEM, FLAG — sets the selection flag of an item. If FLAG is 1, the item is selected. If 0, it is deselected. The method can address the item either directly ( ITEM ) or by its INDEX. Only for the multi-select mode. 🫶
  • select_item INDEX, ITEM — selects an item. The method can address the item either directly ( ITEM ) or by its INDEX. Only for the multi-select mode. 🎀
  • toggle_item INDEX, ITEM — toggles selection of an item. The method can address the item either directly ( ITEM ) or by its INDEX. Only for the multi-select mode. 🔁
  • unselect_item INDEX, ITEM — deselects an item. The method can address the item either directly ( ITEM ) or by its INDEX. Only for the multi-select mode. 🙈
  • validate_items ITEMS — traverses an array of ITEMS and changes every node so that eventual scalars above index #3 are deleted. It also adds default values to a node if it contains less than 3 scalars. cleanup era 🧹

💫 Events 💫

  • Expand NODE, EXPAND — called when NODE is expanded ( 1 ) or collapsed ( 0 ). The EXPAND boolean flag reflects the action taken. 🌸
  • DragItem OLD_INDEX, NEW_INDEX — called when the user finishes the drag of an item from OLD_INDEX to NEW_INDEX position. The default action rearranges the item list according to the dragging action. 🚚
  • DrawItem CANVAS, NODE, X1, Y1, X2, Y2, INDEX, SELECTED, FOCUSED, PRELIGHT — called when the INDEXth item contained in NODE is to be drawn on CANVAS. X1, Y1, X2, Y2 coordinates define the exterior rectangle of the item in widget coordinates. SELECTED, FOCUSED, and PRELIGHT boolean flags are set to 1 if the item is selected, focused, or pre-lighted, respectively; 0 otherwise. 🎨
  • MeasureItem NODE, LEVEL, REF — stores the width of the NODE item in pixels into the REF scalar reference. LEVEL is the node depth as returned by get_item for the reference. This notification must be called from within the begin_paint_info/end_paint_info block. 📏
  • SelectItem [[INDEX, ITEM, SELECTED], [INDEX, ITEM, SELECTED], ...] — called when an item gets selected or deselected. The array passed contains a set of arrays for each item where each contains either an integer INDEX or the ITEM, or both. In case the INDEX is undef, the item is invisible; if the ITEM is undef, then the caller didn't bother to call get_item for speed reasons, and the receiver should call this function. The SELECTED flag contains the new value of the item. 🫶
  • Stringify NODE, TEXT_REF — stores text string associated with the NODE item into the TEXT_REF scalar reference. 📝

🌸 Prima::StringOutline 🌸

A descendant of the Prima::OutlineViewer class, provides a standard single-text-item widget. The items can be defined by supplying a text as the first scalar in the node array structure:

$string_outline-> items([ 'String', [ 'Descendant' ]]);

🦋 Prima::Outline 🦋

A variant of Prima::StringOutline, with the only difference that the text is stored not in the first scalar in a node but as a first scalar in an anonymous array, which in turn is the first node scalar. The class does not define either format or the number of scalars in the array, and as such presents a half-abstract class. main character energy, but abstract 🫠

🗂️ Prima::DirectoryOutline 🗂️

Provides a standard widget with the item tree mapped to the directory structure, so that each item is mapped to a directory. Depending on the type of the host OS, there is either a single root directory ( unix ), or one or more disk drive root items ( win32 ). 🖥️

The node format is defined as follows:

  • #0 — Directory name, string.
  • #1 — Parent path; an empty string for the root items.
  • #2 — Icon width in pixels, integer.
  • #3 — Drive icon; defined only for the root items under Windows to reflect the drive type ( hard, floppy, etc ).

💖 Properties 💖

  • closedGlyphs INTEGER — the number of horizontal equal-width images in the closedIcon property. Default value: 1.
  • closedIcon ICON — provides an icon representation for the collapsed items.
  • openedGlyphs INTEGER — the number of horizontal equal-width images in the openedIcon property. Default value: 1.
  • openedIcon OBJECT — provides an icon representation for the expanded items.
  • path STRING — runtime-only property. Selects the current file system path.
  • showDotDirs BOOLEAN — selects if the directories with the first dot character are shown in the tree view. The treatment of the dot-prefixed names as hidden is traditional to unix and is of doubtful use under Windows. Default value: 0.

🛠️ Methods 🛠️

  • files [ FILE_TYPE ] — if the FILE_TYPE value is not specified, the list of all files in the current directory is returned. If FILE_TYPE is given, only the files of the types are returned. The FILE_TYPE is a string, one of those returned by Prima::Utils::getdir ( see getdir in Prima::Utils ). 📁
  • get_directory_tree PATH — reads the file structure under PATH and returns a newly created hierarchy structure in the class node format. If the showDotDirs property value is 0, the dot-prefixed names are not included. Used internally inside the Expand notification. 🌳

👑 AUTHOR 👑

Dmitry Karasik, <dmitry@karasik.eu.org>. 👑

🌈 SEE ALSO 🌈

Prima, Prima::Widget, <examples/outline.pl>. 🌟

and that’s the whole page, bestie 🫶 source/version: perl v5.42.0, date: 2024-08-20 — Prima::Outlines(3) out 💅✨

📦 where this page comes from