NAME

Tickit::Widget::Tree - tree widget implementation for Tickit

VERSION

version 0.114

SYNOPSIS

use Tickit::Widget::Tree;
my $tree = Tickit::Widget::Tree->new(root => Tree::DAG_Node->new);

DESCRIPTION

NOTE: Versions 0.003 and below used a custom graph management implementation which had various problems with rendering glitches and performance. This version has been rewritten from scratch to use Tree::DAG_Node to handle the tree structure, and as such is not backward compatible.

STYLES

The following style keys are recognised, in addition to base styling which will be applied to the tree lines:

• line_style - which line type to use, default 'single', other options include 'thick' or 'double'

• expand_style - 'boxed' is the only option for now, to select a Unicode +/- boxed icon

• highlight_(fg|bg|b|rv) - highlight styling

• highlight_full_row - if true, will apply highlighting to the entire width of the widget, rather than just the text

Key bindings are currently:

• previous_row - move up a line, stepping into open nodes, default Up

• next_row - move down a line, stepping into open nodes, default Down

• up_tree - move to the parent, default Left

• down_tree - move to the first child, opening the current node if necessary, default Right

• open_node - opens the current node, default +

• close_node - closes the current node, default -

• activate - activates the current node, default Enter

• first_row - jump to the first node in the tree, default Home

• last_row - jump to the last node in the tree, default End

calculate_size

Calculate the minimum size needed to contain the full tree with all nodes expanded.

Used internally.

new

Instantiate. Takes the following named parameters:

• root - the root Tree::DAG_Node

• on_activate - coderef to call when a node has been activated (usually via 'enter' keypress)

• data - if provided, this will be used as a data structure to build the initial tree.

Example usage:

 Tickit:Widget::Tree->new(
  data => [
 	node1 => [
		qw(some nodes here)
	],
	node2 => [
		qw(more nodes in this one),
		and => [
			qw(this has a few child nodes too)
		]
	],
  ];
 );

You can get "live" nodes by attaching an Adapter::Async::OrderedList instance:

 Tickit:Widget::Tree->new(
  data => [
    live => my $adapter = Adapter::Async::OrderedList::Array->new(data => [ ]),
 	static => [
		qw(some static nodes here that will not change)
	],
  ];
 );
 ( # and this is where the magic happens...
  Future::Utils::repeat {
   my $item = shift;
   $loop->delay_future(
    after => 0.5
   )->then(sub {
    $adapter->push([ $item ]) 
   })
  } foreach => [qw(live changes work like this)]
 )->get;

Normally the adapter would come from somewhere else - database cursor, Tangence property, etc. - rather than being instantiated in-place like this. See examples/adapter.pl for a simple example of a manually-driven adapter.

add_item_under_parent

Adds the given item under a parent node.

Takes the following parameters:

• $parent - which Tree::DAG_Node to add this item to

• $item - a thing to add

Currently this supports:

• plain strings - will be used directly as the node label

• String::Tagged instances - used as the node label, standard formatting (b/fg/bg)

• arrayrefs

• Adapter::Async::OrderedList instances - "live" nodes that autoupdate

Probably returns the $node that was just added, but don't count on it.

nodes_from_data

Given a scalar:

• $item - a thing to add

this will generate zero or more nodes that can be added to the tree.

Currently this supports:

• plain strings - will be used directly as the node label

• String::Tagged instances - used as the node label, standard formatting (b/fg/bg)

• arrayrefs -

• hashrefs - one text node will be created for each key, using the key as the name, and the content will be generated recursively using this method again

• Adapter::Async::OrderedList instances - "live" nodes that autoupdate

Probably returns the $node that was just added, but don't count on it.

root

Accessor for the root node. If given a parameter, will set the root node accordingly (and mark the tree for redraw), returning $self.

Otherwise, returns the root node - or undef if we do not have one.

window_gained

Work out our size, when we have a window to fit in.

set_scrolling_extents

Called by Tickit::Widget::ScrollBox or other scroll-capable containers to set up the extent objects which determine the drawable viewport offset.

scrolled

Called by Tickit::Widget::ScrollBox or other scroll-capable containers to indicate when scroll actions have occurred.

render_to_rb

Render method. Used internally.

adapter_for_node

Returns or sets an Adapter::Async::OrderedList for the given node.

This is the primary mechanism for making a node "live" - once it has been attached to an adapter, the child nodes will update according to events on the adapter.

$node = $tree->node;
$node->adapter_for_node->push([1,2,3]);

position_adapter

Returns the "position" adapter. This is an Adapter::Async::OrderedList::Array indicating where we are in the tree - it's a list of all the nodes leading to the currently-highlighted one.

Note that this will return Tree::DAG_Node items. You'd probably want the "name" in Tree::DAG_Node method to get something printable.

Example usage:

my $tree = Tickit::Widget::Tree->new(...);
my $where_am_i = Tickit::Widget::Breadcrumb->new(
 item_transformations => sub {
  shift->name
 }
);
$where_am_i->adapter($tree->position_adapter);

reshape

Workaround to avoid warnings from Tickit::Window. This probably shouldn't be here, pretend you didn't see it.

on_mouse

Mouse callback. Used internally.

key_first_row

Jump to the first row. Normally bound to the Home key.

key_last_row

Jump to the last row. Normally bound to the End key.

key_previous_row

Go up a node.

key_next_row

Move down a node.

key_up_tree

Going "up" the tree means the parent of the current node.

key_down_tree

Going "down" the tree means the first child node, if we have one and we're open.

highlight_node

Change the currently highlighted node.

key_open_node

Open this node.

key_close_node

Close this node.

key_activate

Call the on_activate coderef if we have it.

TODO

Plenty of features and bugfixes left on the list, in no particular order:

• Avoid full redraw when moving highlight or opening/closing nodes

• Support nested widgets

• Node reordering

• Detect changes to the underlying Tree::DAG_Node structure

INHERITED METHODS

Tickit::Widget

get_style_pen, get_style_text, get_style_values, key_focus_next_after, key_focus_next_before, on_pen_changed, parent, pen, redraw, requested_cols, requested_lines, requested_size, resized, set_parent, set_pen, set_requested_size, set_style, set_style_tag, set_window, style_classes, take_focus, window, window_lost

Mixin::Event::Dispatch

add_handler_for_event, clear_event_handlers, event_handlers, invoke_event, subscribe_to_event, unsubscribe_from_event

AUTHOR

Tom Molesworth <cpan@perlsite.co.uk>

LICENSE

Copyright Tom Molesworth 2011-2015. Licensed under the same terms as Perl itself.

cpanm Tickit::Widget::Tree

perl -MCPAN -e shell
install Tickit::Widget::Tree