ListBrowser.pm untested

filter: Statementstmt 0.0% 0 / 1765 Branchbran 0.0% 0 / 772 Conditioncond 0.0% 0 / 135 MC/DCmcdc 0.0% 0 / 82 Subroutinesub 0.0% 0 / 175 Podpod 0.0% 0 / 160 totaltotal 0.0% 0 / 3089 CC 387 SCAR 52.8
CC
387
Cov
0%
KeyPress
1722.0
add
506.0
KeyArrowNavig
380.0
CRAP 196.6
1 package Tk::ListBrowser;
2  
3 =head1 NAME
4  
5 Tk::ListBrowser - Canvas based chameleon list box.
6  
7 =cut
8  
9 use strict;
10 use warnings;
11 use Carp;
12 use vars qw($VERSION);
13 $VERSION = '0.17';
14  
15 use base qw(Tk::Derived Tk::Frame);
16  
17 Construct Tk::Widget 'ListBrowser';
18  
19 use Math::Round;
20 use Tk;
21 require Tk::PopList;
22 require Tk::ListBrowser::Entry;
23 require Tk::ListBrowser::FilterEntry;
24 require Tk::ListBrowser::HashList;
25 require Tk::ListBrowser::Item;
26 require Tk::ListBrowser::LBCanvas;
27 require Tk::ListBrowser::LBHeader;
28 require Tk::ListBrowser::SideColumn;
29  
30 #available refresh handlers
31 my %handlers = (
32 bar => 'Bar',
33 column => 'Column',
34 list => 'List',
35 hlist => 'HList',
36 row => 'Row',
37 tree => 'Tree',
38 );
39 my %columnCapable = (
40 list => 1,
41 hlist => 1,
42 tree => 1,
43 );
44  
45 my $minusimg = '#define indicatorclose_width 11
46 #define indicatorclose_height 11
47 static unsigned char indicatorclose_bits[] = {
48 0xff, 0x07, 0x01, 0x04, 0x01, 0x04, 0x01, 0x04, 0x01, 0x04, 0xfd, 0x05,
49 0x01, 0x04, 0x01, 0x04, 0x01, 0x04, 0x01, 0x04, 0xff, 0x07 };
50 ';
51  
52 my $plusimg = '#define indicatoropen_width 11
53 #define indicatoropen_height 11
54 static unsigned char indicatoropen_bits[] = {
55 0xff, 0x07, 0x01, 0x04, 0x21, 0x04, 0x21, 0x04, 0x21, 0x04, 0xfd, 0x05,
56 0x21, 0x04, 0x21, 0x04, 0x21, 0x04, 0x01, 0x04, 0xff, 0x07 };
57 ';
58  
59 =head1 SYNOPSIS
60  
61 require Tk::ListBrowser;
62 my $ib= $window->ListBrowser(@options)->pack;
63 $ib->add('item_1', -image => $image1, -text => $text1);
64 $ib->add('item_2', -image => $image2, -text => $text2);
65 $ib->refresh;
66  
67 =head1 DESCRIPTION
68  
69 B<Tk::ListBrowser> began as an inspiration on L<Tk::IconList>.
70 Nice, column oriented arrangement, but how about row oriented
71 arrangement. And while we are at it, also list bar hlist and tree
72 oriented arrangement. Scrollbars work automatically. Efforts have been
73 made to follow the conventions of the Tk hierarchical list
74 family as close as possible.
75  
76 Screenshots:
77 L<https://www.perlgui.org/all/tklistbrowser-screenshots/>
78  
79 This module features:
80  
81 =head3 Arrange modes
82  
83 Available arrange modes are 'bar', 'column', 'hlist', 'list'
84 and 'tree'. You can switch between arrange modes through the
85 I<-arrange> option while retaining data.
86  
87 The 'hlist' and 'tree' modes provide a hierarchical list
88 interface. For it to work properly the I<-separator> option
89 must be set to a non empty string of one character.
90  
91 =head3 Sorting
92  
93 This module allows sorting your list on all kinds of paramenters,
94 like sorting on column, ascending or descending. Furthemore you
95 can choose sort fields like '-data', '-name', or '-text'.
96  
97 =head3 Headers
98  
99 Headers are shown in the 'hlist', 'list' and 'tree' modes. You can
100 create and configure them in any mode. They are resizable and can
101 be made sortable. You can drag headers left or right with your
102 mouse to change the column ordering.
103  
104 =head3 Side columns
105  
106 Side columns are shown in the 'hlist', 'list' and tree modes. You can create and configure them in any mode.
107  
108 =head3 Filtering
109  
110 The keyboard shortcut CTFL+F opens a filter entry at the bottom of the widget. Filtering is case insensitive.
111 The filter will start updating when I<-filterdelay> milliseconds have past after your last keystroke.
112 You can choose which data to filter with the I<-filterfield> option. Filtering can be done on the main list
113 as well as on the side columns.
114  
115 =head1 OPTIONS
116  
117 Tk::ListBrowser uses the following standard options: B<-background>, B<-font>,
118 B<-foreground>, B<-selectbackground>, B<-selectforeground>. In addition the
119 following options are supported.
120  
121 =over 4
122  
123 =item Switch B<-arrange>
124  
125 Default value I<row>. This option specifies the layout of your list. If you change this
126 option on the fly you have to call I<refresh> to see the changes. You can set the
127 following values:
128  
129 =over 4
130  
131 =item B<bar>
132  
133 Presents a one row, horizontal list.
134  
135 =item B<column>
136  
137 Presents a column centered two dimensional list.
138  
139 =item B<hlist>
140  
141 Presents a L<Tk::HList> like hierarchical interface.
142  
143 =item B<list>
144  
145 Presents a one column vertical list.
146  
147 =item B<row>
148  
149 Presents a row centered two dimensional list.
150  
151 =item B<tree>
152  
153 Presents a L<Tk::Tree> like hierarchical interface.
154  
155 =back
156  
157 =item Switch B<-autorefresh>
158  
159 Default value 0. If set B<refreshPurge> is called every time you add or remove an entry.
160 You have to make sure the cell dimensions are correctly set in the I<-cell....> options.
161 See also the B<cellSize> method.
162  
163 =item Switch B<-browsecmd>
164  
165 Callback, called when an is selected. Gets the selection list as parameters.
166  
167 =item Switch B<-cellheight>
168  
169 Sets the cell height. Default value is 0. See also the B<cellSize> method.
170  
171 =item Switch B<-cellimageheight>
172  
173 Sets the height of the image in every cell. Default value is 0. See also the B<cellSize> method.
174  
175 =item Switch B<-cellimagewidth>
176  
177 Sets the width of the image in every cell. Default value is 0. See also the B<cellSize> method.
178  
179 =item Switch B<-celltextheight>
180  
181 Sets the height of the text in every cell. Default value is 0. See also the B<cellSize> method.
182 Text can be a multiline string.
183  
184 =item Switch B<-celltextwidth>
185  
186 Sets the width of the text in every cell. Default value is 0. See also the B<cellSize> method.
187 Text can be a multiline string.
188  
189 =item Switch B<-cellwidth>
190  
191 Sets the cell width. Default value is 0. See also the B<cellSize> method.
192  
193 =item Switch B<-command>
194  
195 Callback, called when an entry is double clicked or return was pressed. Gets the selection list as parameters.
196  
197 =item Switch B<-entryclass>
198  
199 Default value I<Tk::ListBrowser::Entry>. You can set it to any class that inherits this.
200  
201 =item Switch B<-filtercolumns>
202  
203 By default false. If you set it a button will appear
204 next to the filter entry that allows you to select
205 a column.
206  
207 =item Switch B<-filterdelay>
208  
209 Default value 300 miliseconds. When the filter bar is active this is the wait time
210 between a keystroke and a corresponding filter action. If a key is pressed before
211 time out, the timer is reset.
212  
213 =item Switch B<-filterfield>
214  
215 Default value I<name>. Possible values are I<name>, I<text> and I<data>.
216 Specifies on what data the filter should work.
217  
218 =item Switch B<-filterforce>
219  
220 Default value I<false>. If set the filter entry will allways be visible.
221  
222 =item Switch B<-filteron>
223  
224 Default value I<main>, which is the main entry list. You may also set it to a valid column.
225  
226 =item Switch B<-font>
227  
228 =item Name B<guideColor>
229  
230 =item Class B<GuideColor>
231  
232 =item Switch B<-guidecolor>
233  
234 The color in which the guides in hlist and tree mode are drawn.
235 The default is #7F7F7F.
236  
237 =item Name B<headerBorderWidth>
238  
239 =item Class B<headerBorderWidth>
240  
241 =item Switch B<-headerborderwidth>
242  
243 Default value 2.
244  
245 =item Name B<headerHeight>
246  
247 =item Class B<HeaderHeight>
248  
249 =item Switch B<-headerheight>
250  
251 Default value 32.
252  
253 =item Name B<headerRelief>
254  
255 =item Class B<HeaderRelief>
256  
257 =item Switch B<-headerrelief>
258  
259 Default value 'raised'.
260  
261 =item Switch B<-indicatorprecmd>
262  
263 =item Switch B<-indicatorpostcmd>
264  
265 Callback, executed when the user click in indicator in
266 tree mode. Gets the name of the entry as parameter.
267  
268 =item Switch B<-indicatorminusimg>
269  
270 Specifies the image of the minus indicator when I<-arrange> is set to 'tree'.
271 By default an internal image is loaded.
272  
273 =item Switch B<-indicatorplusimg>
274  
275 Specifies the image of the plus indicator when I<-arrange> is set to 'tree'.
276 By default an internal image is loaded.
277  
278 =item Name B<indent>
279  
280 =item Class B<Indent>
281  
282 =item Switch B<-indent>
283  
284 Default value 22. Specifies the indent with when I<-arrange> is set to 'hlist' or 'tree'.
285  
286 =item Name B<itemPadX>
287  
288 =item Class B<ItemPadX>
289  
290 =item Switch B<-itempadx>
291  
292 Internal padding in x direction in entries and column items.
293  
294 =item Name B<itemPadY>
295  
296 =item Class B<ItemPadY>
297  
298 =item Switch B<-itempady>
299  
300 Internal padding in y direction in entries and column items.
301  
302 =item Switch B<-itemtype>
303  
304 Default value I<imagetext>. Can be I<image>, I<imagetext> or I<text>.
305  
306 =item Name B<marginBottom>
307  
308 =item Class B<MarginBottom>
309  
310 =item Switch B<-marginbottom>
311  
312 Default value 0. Expands the scrollable canvas size on the bottom.
313  
314 =item Name B<marginLeft>
315  
316 =item Class B<MarginLeft>
317  
318 =item Switch B<-marginleft>
319  
320 Default value 0. Expands the scrollable canvas size to the left.
321  
322 =item Name B<marginRight>
323  
324 =item Class B<MarginRight>
325  
326 =item Switch B<-marginright>
327  
328 Default value 0. Expands the scrollable canvas size to the right.
329  
330 =item Name B<marginTop>
331  
332 =item Class B<MarginTop>
333  
334 =item Switch B<-margintop>
335  
336 Default value 0. Expands the scrollable canvas size to the top.
337  
338 =item Switch B<-motionselect>
339  
340 Default value I<false>. Only works when I<-selectmode> is set to single.
341 Automatically selects an entry when the pointer is hovering over it.
342  
343 =item Switch B<-nofilter>
344  
345 Default value I<false>. If set the filter entry is not available.
346 This option supercedes the I<-filterforce> option.
347  
348 =item Switch B<-refreshentriespercycle>
349  
350 Default value 10. Specifies how many entries are refreshed during
351 one refresh loop cycle.
352  
353 =item Switch B<-refreshinterval>
354  
355 Default value 1 milisecond. Specifies the interval between refresh
356 loop cycles.
357  
358 =item Switch B<-scrollbars>
359  
360 Only available at create time. Default value I<osoe>.
361  
362 =item Switch B<-selectmode>
363  
364 Default value I<single>. Can either be I<single>, I<multiple> or I<exclusive>.
365  
366 In single mode only one entry in the list can be selected at all times.
367  
368 In multiple mode more than one entry can be selected.
369  
370 In exclusive mode also only
371 one entry can be selected. However, after initial selection is set one entry will
372 be selected at all times.
373  
374 =item Switch B<-selectstyle>
375  
376 Default value I<anchor>. Can either be I<anchor> or I<simple>.
377 This option specifies how the arrow keys work. When set to anchor,
378 the arrow keys only move the anchor, space or enter will select.
379 When set to simple the arrow keys also make a single mode selection.
380  
381 =item Switch B<-separator>
382  
383 Default value is an empty string. When set to one character, hierarchy mode is enabled.
384 When I<-arrange> is set to any other than 'hlist' or 'tree', only the root list is shown when hierarchy
385 mode is enabled.
386  
387 =item Switch B<-sizesample>
388  
389 Default value is undef. You can set it to an instance of the entry class. B<refresh> will
390 try to obtain a cell size through this sample. Everytime you assing a sample, the B<cellSizeKnown>
391 flag is cleared.
392  
393 =item Switch B<-sortbottom>
394  
395 Default value -(10**32). Used while sorting whenever a column item is found that requires
396 numerical sort, but the item itself is not defined. A ridiculous low value is used instead.
397 Are you handling even lower numbers? You can adjust it here.
398  
399 =item Switch B<-sortcase>
400  
401 Default value false. You can set it if you require case dependent sort.
402  
403 =item Switch B<-sortfield>
404  
405 Default value '-name'. Possible values are '-name', '-text' and '-data'.
406 Specifies which attribute of an entry is used for sorting.
407  
408 =item Switch B<-sortnumerical>
409  
410 Default value false. You can set it if you require numerical sorting.
411  
412 =item Switch B<-sorton>
413  
414 Default value is an empty string. That means sorting is done on the main entry list.
415 You can set it to a column name for sorting on column content.
416  
417 =item Switch B<-sortorder>
418  
419 Default value 'ascending'.
420  
421 =item Switch B<-textanchor>
422  
423 Default value empty string. This value centers the text in it's cativy.
424 Besides an empty string the possible values are I<n>, I<ne>, I<nw>, I<s>,
425 I<se>, I<sw>, I<e> and I<w>. The letters stand for the first letter of the
426 wind directions. They tell where to position the text in it's cavity.
427  
428 =item Switch B<-textjustify>
429  
430 Default value I<center>. Can be I<center>, I<left> or I<right>. Specifies
431 how multiline or wrapped text is justified.
432  
433 =item Switch B<-textlength>
434  
435 Default value I<0>. If you set it to a positive integer it shortens the text by leaving out the middle part.
436 The unit is characters.
437  
438 =item Switch B<-textside>
439  
440 Default value I<bottom>. Possible values are I<bottom>, I<top>, I<left>, I<right>,
441 or I<none>. It sets at which side the text should appear next to the icon.
442 If you change this option on the fly you have to call I<refresh>
443 to see the changes. This option only has meaning when I<-itemtype> is set to 'imagetext'.
444  
445 =item Switch B<-wraplength>
446  
447 Default value 0. You can set it to a positive integer of at least 40 to invoke word or
448 character wrapping. The value determines the maximum width in pixels of a text block. It
449 will attempt a word wrap and will do a character wrap if that fails.
450  
451 If you change this option on the fly you have to call I<refresh> to see the changes.
452  
453 If you try to set it to a lower value than 40, you will be overruled.
454 This is to prevent the wrap length to become smaller that the with of one character, which
455 would freeze your application. This also means watching out for using very big fonts.
456  
457 The unit is pixels.
458  
459 =back
460  
461 =cut
462  
463 =head1 STANDARD OPTIONS
464  
465 A number of the options above can also be used when you call the
466 I<add>, I<columnCreate>, I<add> and I<itemCreate> methods.
467 These are I<-background>, I<-font>, I<-foreground>, I<-itempadx>,
468 I<-itempady>, I<-itemtype>, I<-textanchor>, I<-textjustify>,
469 I<-textside>, and I<-wraplength>.
470  
471 =head1 METHODS
472  
473 =over 4
474  
475 =cut
476  
477 sub Populate {
478 my ($self,$args) = @_;
479
480 my $width = delete $args->{'-width'};
481 $width = 100 unless defined $width;
482 my $height = delete $args->{'-height'};
483 $height = 80 unless defined $height;
484 my $scrollbars = delete $args->{'-scrollbars'};
485 $scrollbars = 'osoe' unless defined $scrollbars;
486
487 $self->SUPER::Populate($args);
488
489 #create the canvas
490 my $canv = $self->Scrolled('LBCanvas',
491 -keycall => ['KeyPress', $self],
492 -scrollbars => 'osoe',
493 -width => $width,
494 -height => $height,
495 )->pack(-expand => 1, -fill => 'both');
496 my $c = $canv->Subwidget('scrolled');
497 $c->configure(
498 -takefocus => 1,
499 );
500  
501 #horizontal scroll for headers
502 my $xscroll = $canv->Subwidget('xscrollbar');
503 $self->Advertise('XScrollbar', $xscroll);
504 if (defined $xscroll) {
505 my $call = $xscroll->cget('-command');
506 $xscroll->configure(-command => sub {
507 $call->Call(@_);
508 $self->headerPlace;
509 $self->xScrollCheck(@_);
510 });
511 }
512 #keep track of verticle scroll
513 my $yscroll = $canv->Subwidget('yscrollbar');
514 $self->Advertise('YScrollbar', $yscroll);
515  
516 $self->Advertise('Canvas', $c);
517
518 #create the header frame;
519 my $hf = $c->Frame;
520 $self->Advertise('HeaderFrame', $hf);
521  
522 #mouse bindings
523 $c->Tk::bind('<ButtonPress-1>', [ $self, 'Button1', Ev('x'), Ev('y') ]);
524 $c->Tk::bind('<Control-Button-1>', [ $self, 'Button1Control', Ev('x'), Ev('y') ]);
525 $c->Tk::bind('<Double-Button-1>', [ $self, 'Button1Double', Ev('x'), Ev('y') ]);
526 $c->Tk::bind('<Shift-Button-1>', [ $self, 'Button1Shift', Ev('x'), Ev('y') ]);
527 $c->Tk::bind('<Control-f>', [$self, 'filterFlip']);
528 $c->Tk::bind('<Button-2>', [ $self, 'Button2', Ev('x'), Ev('y') ]);
529 $c->Tk::bind('<B2-Motion>', [ $self, 'Button2Motion', Ev('x'), Ev('y') ]);
530 $c->Tk::bind('<ButtonRelease-2>', [ $self, 'Button2Release', Ev('x'), Ev('y') ]);
531 $c->Tk::bind('<Motion>', [ $self, 'Motion', Ev('x'), Ev('y') ]);
532  
533 $self->{ARRANGE} = undef;
534 $self->{CELLSIZEKNOWN} = 0;
535 $self->{COLUMNS} = [];
536 $self->{HANDLER} = undef;
537 $self->{POOL} = new Tk::ListBrowser::HashList;
538 $self->{SCROLLREGION} = [0,0];
539 $self->{SORTACTIVE} = '';
540 $self->geoSave(0,0);
541 $self->listWidth(100);
542 $self->priorityMax(0);
543 $self->refreshLoopActive(0);
544 $self->refreshPos(0);
545  
546 $self->bind('<Configure>', [ $self, 'OnConfigure' ]);
547  
548 my $minusbmp = $self->Bitmap(-data => $minusimg);
549 my $plusbmp = $self->Bitmap(-data => $plusimg);
550 $self->ConfigSpecs(
551  
552 #general
553 -arrange => ['METHOD', undef, undef, 'row'],
554 -autorefresh => ['PASSIVE', undef, undef, 0],
555 -borderwidth => [$c, 'borderWidth', 'BorderWidth', 1],
556 -browsecmd => ['CALLBACK'],
557 -command => ['CALLBACK'],
558 -entryclass => ['PASSIVE', undef, undef, 'Tk::ListBrowser::Entry'],
559 -font => ['PASSIVE', 'font', 'Font', 'Arial 9'],
560 -indent => ['PASSIVE', 'indent', 'Indent', 22],
561 -motionselect => ['PASSIVE', undef, undef, ''],
562 -refreshentriespercycle => ['PASSIVE', undef, undef, 10],
563 -refreshinterval => ['PASSIVE', 'refreshInterval', 'RefreshInterval', 1],
564 -relief => [$c, 'relief', 'Relief', 'sunken'],
565 -scrollregion => [$c],
566 -selectmode => ['PASSIVE', undef, undef, 'single'],
567 -selectstyle => ['PASSIVE', undef, undef, 'anchor'],
568 -separator => ['PASSIVE', undef, undef, ''],
569  
570 #sizes
571 -cellwidth => ['METHOD', undef, undef, 0],
572 -cellheight => ['METHOD', undef, undef, 0],
573 -cellimagewidth => ['PASSIVE', undef, undef, 0],
574 -cellimageheight => ['PASSIVE', undef, undef, 0],
575 -celltextwidth => ['PASSIVE', undef, undef, 0],
576 -celltextheight => ['PASSIVE', undef, undef, 0],
577 -height => [$c, 'height', 'Height', $height],
578 -sizesample => ['METHOD'],
579 -width => [$c, 'width', 'Width', $width],
580  
581 #colors
582 -background => [$c, 'background', 'Background', '#E8E8E8'],
583 -foreground => [$c, 'foreground', 'Foreground', '#3C3C3C'],
584 -guidecolor => ['PASSIVE', 'guideColor', 'GuideColor', '#7F7F7F'],
585 -selectbackground => ['PASSIVE', 'selectBackground', 'SelectBackground', '#A0A0FF'],
586 -selectforeground => ['PASSIVE', 'selectForeground', 'SelectForeground', '#FAF9EA'],
587  
588 #filter
589 -nofilter => ['PASSIVE', undef, undef, ''],
590 -filtercolumns => ['PASSIVE', undef, undef, ''], #boolean
591 -filterdelay => ['PASSIVE', undef, undef, 300], #boolean
592 -filterfield => ['PASSIVE', undef, undef, 'name'],
593 -filterforce => ['PASSIVE', undef, undef, ''], #boolean
594 -filteron => ['PASSIVE', undef, undef, 'main'],
595  
596 #headers
597 -headerborderwidth => ['PASSIVE', 'headerBorderWidth', 'HeaderBorderWidth', 2],
598 -headerheight => ['PASSIVE', 'headerHeight', 'HeaderHeight', 32],
599 -headerrelief => ['PASSIVE', 'headerRelief', 'HeaderRelief', 'raised'],
600  
601 #indicators
602 -indicatorprecmd => ['CALLBACK'],
603 -indicatorpostcmd => ['CALLBACK'],
604 -indicatorminusimg => ['PASSIVE', undef, undef, $minusbmp],
605 -indicatorplusimg => ['PASSIVE', undef, undef, $plusbmp],
606  
607 #items
608 -itempadx => ['PASSIVE', 'itemPadX', 'ItemPadX', 2],
609 -itempady => ['PASSIVE', 'itemPadY', 'ItemPadY', 0],
610 -itemtype => ['PASSIVE', undef, undef, 'imagetext'],
611  
612 #margins & sizes
613 -fixedcellheight => ['PASSIVE'],
614 -fixedcellwidth => ['PASSIVE'],
615 -marginleft => ['PASSIVE', 'marginLeft', 'MarginLeft', 0],
616 -marginright => ['PASSIVE', 'marginRight', 'MarginRight', 0],
617 -margintop => ['PASSIVE', 'marginTop', 'MarginTop', 0],
618 -marginbottom => ['PASSIVE', 'marginBottom', 'MarginBottom', 0],
619  
620 #sort
621 -sortbottom => ['PASSIVE', undef, undef, -(10**32)],
622 -sortcase => ['PASSIVE', undef, undef, 'name'],
623 -sortfield => ['PASSIVE', undef, undef, 'name'],
624 -sorton => ['PASSIVE', undef, undef, ''],
625 -sortnumerical => ['PASSIVE', undef, undef, ''], #boolean
626 -sortorder => ['PASSIVE', undef, undef, 'ascending'],
627  
628 #text
629 -textanchor => ['PASSIVE', undef, undef, ''],
630 -textlength => ['PASSIVE', undef, undef, 0],
631 -textjustify => ['PASSIVE', undef, undef, 'center'],
632 -textside => ['PASSIVE', undef, undef, 'bottom'],
633 -wraplength => ['METHOD', undef, undef, 0],
634  
635 DEFAULT => [ $self ],
636 );
637 $self->Delegates(
638  
639 #canvas
640 CanvasFocus => $c,
641 canvasx => $c,
642 canvasy => $c,
643 createImage => $c,
644 createRectangle => $c,
645 createText => $c,
646 xview => $c,
647 yview => $c,
648 xviewScroll => $c,
649 yviewScroll => $c,
650  
651 DEFAULT => $self,
652 );
653 $self->after(1, sub {
654 my @bmpopt = (-foreground => $c->cget('-foreground'), -background => $c->cget('-background'));
655 for ($plusbmp, $minusbmp) {
656 $_->configure(@bmpopt)
657 };
658 $self->filterShow if $self->cget('-filterforce');
659 });
660 return $self
661 }
662  
663 sub handler { return $_[0]->{HANDLER} }
664  
665 =item B<add>I<(?$name?, %options)>
666  
667 Adds I<$name> to the list with I<%options>. I<$name> must not yet exist.
668 If you do not specify standard options, the main settings
669 will be used. Besides the standard options you can also use:
670  
671 =over 4
672  
673 =item B<-after>
674  
675 Insert I<$name> after the entry name held by this option.
676  
677 =item B<-before>
678  
679 Insert I<$name> before the entry name held by this option.
680  
681 =item B<-data>
682  
683 Assign an arbitray scalar value to this entry.
684  
685 =item B<-hidden>
686  
687 Tag the entry as hidden. If you do not specify this option
688 the entry is shown after I<refresh>
689  
690 =item B<-image>
691  
692 A valid L<Tk::Image> class assigned to this entry.
693  
694 =item B<-priority>
695  
696 Default priority is 0. Entries with the highest priorities are shown first.
697  
698 =item B<-text>
699  
700 Text assigned to this entry.
701  
702 =back
703  
704 After a call to I<add> you must call I<refresh> to see your changes.
705 Returns a reference to the created item object.
706  
707 =cut
708  
709 sub add {
710 my ($self, $name, %options) = @_;
711 if ($self->infoExists($name)) {
712 croak "Entry '$name' already exists";
713 return
714 }
715  
716 my $sep = $self->separator;
717 my $after = $options{'-after'};
718 my $before = $options{'-before'};
719 my $parent;
720 my @c;
721  
722 my $priority = $options{'-priority'};
723 $priority = 0 unless defined $priority;
724 $self->prioritySet($priority);
725  
726  
727 #some show stoppers
728 if ((defined $after) and (not $self->infoExists($after))) {
729 croak "Invalid -after option. Entry $after does not exist";
730 return
731 }
732 if ((defined $before) and (not $self->infoExists($before))) {
733 croak "Invalid -before option. Entry $before does not exist";
734 return
735 }
736  
737 if ($sep ne '') { #hierarchy
738 if (my $parent = $self->decodeParent($name)) {
739 #some show stoppers
740 unless ($self->infoExists($parent)) {
741 croak "Parent for $name does not exist";
742 return
743 }
744 if (my $a = $options{'-after'}) {
745 my $p = $self->infoParent($a);
746 if ($p ne $parent) {
747 croak "Invalid '-after' option, $name and $a do not share the same parent";
748 return
749 }
750 }
751 if (my $b = $options{'-before'}) {
752 my $p = $self->infoParent($b);
753 if ($p ne $parent) {
754 croak "Invalid '-before' option, $name and $b do not share the same parent";
755 return
756 }
757 }
758  
759 #go to work
760 if ((defined $after) and ($self->get($after)->priority eq $priority)) {
761 #do nothing
762 } elsif ((defined $before) and ($self->get($before)->priority eq $priority)) {
763 #do nothing
764 } else {
765 my @c = $self->infoChildren($parent);
766 my ($pos, $peer) = $self->addGrep($priority, '-after', \@c);
767 if (defined $pos) {
768 $options{$pos} = $peer;
769 } else {
770 my $last = $self->infoLastOffspring($parent);
771 if (defined $last) {
772 $options{'-after'} = $last;
773 } else {
774 $options{'-after'} = $parent
775 }
776 }
777 }
778 } else { #no parent found
779 my @c = $self->infoRoot;
780 my ($pos, $peer) = $self->addGrep($priority, '-before', \@c);
781 if (defined $pos) {
782 $options{$pos} = $peer;
783 }
784 }
785 } else { #no hierarchy
786 if ($self->priorityMax) {
787 my @c = $self->infoList;
788 my ($pos, $peer) = $self->addGrep($priority, '-after', \@c);
789 if (defined $pos) {
790 $options{$pos} = $peer;
791 }
792 }
793 }
794  
795 $after = delete $options{'-after'};
796 $before = delete $options{'-before'};
797  
798 my $class = $self->cget('-entryclass');
799 my $item = new $class(
800 %options,
801 -listbrowser => $self,
802 -name => $name,
803 );
804 my $pool = $self->pool;
805 my $index;
806 if (defined $after) {
807 $index = $self->index($after)+ 1;
808 } elsif (defined $before) {
809 $index = $self->index($before);
810 }
811 $pool->add($item, $index);
812 $self->refreshCheck($item, $index) if $self->cget('-autorefresh');
813 return $item
814 }
815  
816 sub addGrep {
817 my ($self, $priority, $pos, $l) = @_;
818 my @list = @$l;
819 my @g = grep {$priority > $self->get($_)->priority } @list;
820 if (@g) {
821 my $i = shift @g;
822 return ('-before', $self->get($i)->name);
823 }
824 my @le = grep { $priority <= $self->get($_)->priority } @list;
825 if (@le) {
826 my $i = $list[@le + 1];
827 return ($pos, $self->get($i)->name) if defined $i;
828 }
829 return ()
830 }
831  
832 sub anchor {
833 my $self = shift;
834 my $a = $self->{ANCHOR};
835 unless (defined $a) {
836 $a = $self->createRectangle(0, 0, 1, 1,
837 -fill => undef,
838 -dash => [3, 2],
839 );
840 $self->{ANCHOR} = $a
841 }
842 return $a
843 }
844  
845  
846 =item B<anchorClear>
847  
848 Clears the keyboard anchor.
849  
850 =cut
851  
852 sub anchorClear {
853 my $self = shift;
854 my @pool = $self->getAll;
855 for (@pool) {
856 $_->anchor(0)
857 }
858 }
859 =item B<anchorGet>
860  
861 Returns a reference to the L<Tk::ImageBrowser::Icon> object
862 that currently holds the anchor.
863  
864 =cut
865  
866 sub anchorGet {
867 my $self = shift;
868 my @pool = $self->getAll;
869 for (0 .. @pool - 1) {
870 my $obj = $pool[$_];
871 return $obj if $obj->anchored
872 }
873 return undef
874 }
875  
876 sub anchorInitialize {
877 my $self = shift;
878 my $i = $self->anchorGet;
879 unless (defined $i) {
880 my $a = $self->anchor;
881 my $name = $self->infoFirstVisible;
882 $self->anchorSet($name) unless defined $self->anchorGet;
883 $self->selectionSingle($name) if $self->cget('-selectstyle') eq 'simple';
884 $self->see($name);
885 return 1
886 }
887 return ''
888 }
889  
890 #sub anchorRaise {
891 # my ($self, $canvitem) = @_;
892 # my $i = $self->anchorGet;
893 # return unless defined $i;
894 # my $c = $self->Subwidget('Canvas');
895 # $c->raise($i->canchor, $canvitem);
896 #}
897 #
898 sub anchorRefresh {
899 my $self = shift;
900 my $a = $self->anchorGet;
901 $a->drawAnchor if defined $a;
902 }
903  
904 =item B<anchorSet>I<($name)>
905  
906 Sets the keyboard anchor to I<$name>
907  
908 =cut
909  
910 sub anchorSet {
911 my ($self, $name) = @_;
912 my $item = $self->get($name);
913 if ((defined $item) and (not $item->hidden)) {
914 $self->anchorClear;
915 $item->anchor(1);
916 return 1
917 }
918 return ''
919 }
920  
921 sub anchorSetColumnRow {
922 my ($self, $column, $row) = @_;
923 my $index = $self->indexColumnRow($column, $row);
924 if (defined $index) {
925 return $self->anchorSet($self->getIndex($index)->name);
926 }
927 return ''
928 }
929  
930 sub arrange {
931 my $self = shift;
932 if (@_) {
933 my $arr = shift;
934 my $mod = $handlers{$arr};
935 unless (defined $mod) {
936 croak "Invalid handler $arr";
937 return
938 }
939 $self->{ARRANGE} = $arr;
940 my $modname = "Tk::ListBrowser::$mod";
941 my $error = '';
942 eval "use $modname;";
943 my $hf = $self->Subwidget('HeaderFrame');
944 if (($arr eq 'row') or ($arr eq 'column')) {
945 $self->headerClear;
946 } else {
947 $self->headerPlace;
948 }
949 $error = $@;
950 unless ($error) {
951 $self->clear;
952 my $h = $modname->new($self);
953 $self->{HANDLER} = $h;
954 } else {
955 croak $error
956 }
957 }
958 return $self->{ARRANGE}
959 }
960  
961 sub Button1 {
962 my ($self, $x, $y) = @_;
963 $self->CanvasFocus;
964 my $c = $self->Subwidget('Canvas');
965  
966 #return if an indicator was clicked
967 my @ind = $c->find('withtag', 'indicator');
968 for (@ind) {
969 my ($ix, $iy) = $c->coords($_);
970 my $img = $self->cget('-indicatorplusimg');
971 my $half = int($img->width / 2) + 2;
972 my ($x1, $y1, $x2, $y2) = $c->coords($_);
973 return if ($ix - $half <= $x) and ($ix + $half >= $x)
974 and ($iy - $half <= $y) and ($iy + $half >= $y);
975 }
976  
977 my $item = $self->initem($x, $y);
978 if (defined $item) {
979 $self->anchorSet($item->name);
980 return if $item->selected;
981 $self->selectionClear;
982 $item->select(1);
983 $self->Callback('-browsecmd', $item->name);
984 return
985 } else {
986 $self->selectionClear unless $self->cget('-selectmode') eq 'exclusive';
987 }
988 }
989  
990 sub Button1Control {
991 my ($self, $x, $y) = @_;
992 $self->CanvasFocus;
993 return $self->Button1($x, $y) if ($self->cget('-selectmode') eq 'single') or ($self->cget('-selectmode') eq 'exclusive');
994 my $item = $self->initem($x, $y);
995 if (defined $item) {
996 if ($item->selected) {
997 $item->select(0)
998 } else {
999 $item->select(1)
1000 }
1001 $self->anchorSet($item->name);
1002 } else {
1003 $self->selectionClear;
1004 }
1005 }
1006  
1007 sub Button1Double {
1008 my ($self, $x, $y) = @_;
1009 my $item = $self->initem($x, $y);
1010 if (defined $item) {
1011 $self->Callback('-command', $item->name);
1012 } else {
1013 $self->selectionClear unless $self->cget('-selectmode') eq 'exclusive';
1014 }
1015 }
1016  
1017 sub Button1Shift {
1018 my ($self, $x, $y) = @_;
1019 return $self->Button1($x, $y) if ($self->cget('-selectmode') eq 'single') or ($self->cget('-selectmode') eq 'exclusive');
1020 my $item = $self->initem($x, $y);
1021 $self->CanvasFocus;
1022 if (defined $item) {
1023 my @pool = $self->getAll;
1024 $self->anchorSet($item->name);
1025 my @sel = $self->selectionGet;
1026 unless (@sel) {
1027 my $start = $pool[0]->name;
1028 $self->selectionSet($pool[0]->name, $item->name);
1029 return
1030 }
1031 if ($self->index($item->name) < $self->index($sel[0])) {
1032 $self->selectionSet($item->name, $sel[0]);
1033 return
1034 }
1035 if ($self->index($item->name) > $self->index($sel[@sel - 1])) {
1036 $self->selectionSet($sel[@sel - 1], $item->name);
1037 return
1038 }
1039 $self->selectionClear;
1040 }
1041 }
1042  
1043 sub Button2 {
1044 my ($self, $x, $y) = @_;
1045 $self->configure(-cursor => 'fleur');
1046 $self->{'mouse_pos'} = [$x, $y];
1047 }
1048  
1049 sub Button2Motion {
1050 my ($self, $x, $y) = @_;
1051  
1052 my $mousepos = $self->{'mouse_pos'};
1053 my ($mx, $my) = @$mousepos;
1054 $self->{'mouse_pos'} = [$x, $y];
1055  
1056 my $dx = $mx - $x;
1057 my $dy = $my - $y;
1058  
1059 $self->xviewScroll(-$dx, 'units') if $self->handler->scroll eq 'horizontal';
1060 $self->yviewScroll(-$dy, 'units') if $self->handler->scroll eq 'vertical';
1061 }
1062  
1063 sub Button2Release {
1064 my $self = shift;
1065 $self->configure(-cursor => 'arrow');
1066 delete $self->{'mouse_pos'};
1067 }
1068  
1069 sub canvasSize {
1070 my $self = shift;
1071 my $c = $self->Subwidget('Canvas');
1072 my $offset = $c->cget('-highlightthickness') + (2 * $c->cget('-borderwidth')) + 2;
1073 return ($c->width - $offset, $c->height - $offset);
1074 }
1075  
1076 sub cellheight {
1077 my $self = shift;
1078 $self->{CELLHEIGHT} = shift if @_;
1079 if ($self->listMode) {
1080 my $fh = $self->forceHeight;
1081 return $fh if defined $fh;
1082 }
1083 return $self->{CELLHEIGHT}
1084 }
1085  
1086 sub cellwidth {
1087 my $self = shift;
1088 $self->{CELLWIDTH} = shift if @_;
1089 if ($self->listMode) {
1090 my $fw = $self->forceWidth;
1091 return $fw if defined $fw;
1092 }
1093 return $self->{CELLWIDTH}
1094 }
1095  
1096 =item B<cellSize>I<(?$entryobj?)>
1097  
1098 Calculates the optimal cell size for the list and sets the config variables
1099 I<-cellheight>, I<-cellimageheight>, I<-cellimagewidth>, I<-celltextheight>,
1100 I<-celltextwidth> and I<-cellwidth>.
1101  
1102 If you specify I<$entryobj> it will use it as the sample to calculate the cell size.
1103  
1104 If you do not specify I<$entryobj> it will look for a sample in the config variable I<-sizesample>.
1105  
1106 If it finds nothing there it will iterate over the whole list.
1107  
1108 =cut
1109  
1110 sub cellSize {
1111 my ($self, $item) = @_;
1112  
1113 $item = $self->cget('-sizesample') unless defined $item;
1114  
1115 my $cellheight = 0;
1116 my $cellwidth = 0;
1117 my $imageheight = 0;
1118 my $imagewidth = 0;
1119 my $textheight = 0;
1120 my $textwidth = 0;
1121  
1122 my @pool;
1123 if (defined $item) {
1124 push @pool, $item
1125 } else {
1126 @pool = $self->getPool
1127 }
1128 for (@pool) {
1129 my $entry = $_;
1130 my ($cw, $ch, $iw, $ih, $tw, $th) = $entry->requestedSize;
1131
1132 $cellheight = $ch if $ch > $cellheight;
1133 $cellwidth = $cw if $cw > $cellwidth;
1134 $imageheight = $ih if $ih > $imageheight;
1135 $imagewidth = $iw if $iw > $imagewidth;
1136 $textheight = $th if $th > $textheight;
1137 $textwidth = $tw if $tw > $textwidth;
1138 for ($self->columnList) {
1139 my $col = $_;
1140 my $type = $self->columnCget($col, '-itemtype');
1141 my $item = $self->itemGet($entry->name, $col);
1142 if (defined $item) {
1143 my ($cw, $ch, $iw, $ih, $tw, $th) = $item->requestedSize;
1144 $imageheight = $ih if $ih > $imageheight;
1145 $textheight = $th if $th > $textheight;
1146 }
1147
1148 }
1149 }
1150 $self->configure(-cellheight => $cellheight);
1151 $self->configure(-cellwidth => $cellwidth);
1152 $self->configure(-cellimageheight => $imageheight);
1153 $self->configure(-cellimagewidth => $imagewidth);
1154 $self->configure(-celltextheight => $textheight);
1155 $self->configure(-celltextwidth => $textwidth);
1156 $self->listWidth($cellwidth);
1157 $self->cellSizeKnown(1);
1158 return ($cellwidth, $cellheight)
1159 }
1160  
1161 =item B<cellSizeColumns>
1162  
1163 Walks through every side column and determines it's best cell width by iterating over every entry.
1164 The cell height of side columns is determined by the entry.
1165  
1166 =cut
1167  
1168 sub cellSizeColumns {
1169 my $self = shift;
1170 if ($self->listMode) {
1171 my @columns = $self->columnList;
1172 for (@columns) {
1173 my $col = $self->columnGet($_)->cellSize;
1174 }
1175 }
1176 }
1177  
1178 =item B<cellSizeKnown>I<(?$b?)>
1179  
1180 Sets and returns the flag to indicate wether cell size is known or should be calculated.
1181  
1182 =cut
1183  
1184 sub cellSizeKnown {
1185 my $self = shift;
1186 $self->{CELLSIZEKNOWN} = shift if @_;
1187 return $self->{CELLSIZEKNOWN}
1188 }
1189  
1190  
1191 =item B<clear>
1192  
1193 Clears the display. Does not delete data.
1194  
1195 =cut
1196  
1197 sub clear {
1198 my $self = shift;
1199  
1200 $self->anchorClear;
1201  
1202 grep { $_->clear } $self->getAll;
1203  
1204 my @columns = $self->columnList;
1205 for (@columns) {
1206 $self->columnGet($_)->clear;
1207 }
1208  
1209 my $c = $self->Subwidget('Canvas');
1210 $c->xview(moveto => 0);
1211 $c->yview(moveto => 0);
1212 $c->configure(-scrollregion => [0, 0, 0, 0]);
1213 }
1214  
1215 =item B<close>I<($entry)>
1216  
1217 Hides all children of $entry.
1218 Call I<refresh> or I<refreshPurge> to see changes.
1219 Only works when I<-arrange> is set to 'tree'.
1220  
1221 =cut
1222  
1223 sub close {
1224 my ($self, $entry) = @_;
1225 return unless $self->cget('-arrange') eq 'tree';
1226 my $i = $self->get($entry);
1227 unless (defined $i) {
1228 croak "Entry $entry not found";
1229 return
1230 }
1231 $i->opened(0);
1232 $self->selectionClearChildren($entry);
1233 }
1234  
1235 =item B<closeAll>
1236  
1237 Closes all entries.
1238 Call I<refresh> or I<refreshPurge> to see changes.
1239  
1240 =cut
1241  
1242 sub closeAll {
1243 my $self = shift;
1244 my @list = $self->infoList;
1245 for (@list) {
1246 $self->close($_) if $self->infoChildren($_);
1247 }
1248 }
1249  
1250 =item B<columnCget>I<($name, $option)>
1251  
1252 Returns the value of $option in column $name
1253  
1254 =cut
1255  
1256 sub columnCget {
1257 my ($self, $name, $option) = @_;
1258 my $col = $self->columnGet($name);
1259 unless (defined $col) {
1260 croak "Column '$name' not found";
1261 return
1262 }
1263 return $col->cget($option)
1264 }
1265  
1266 =item B<columnConfigure>I<($name, %options)>
1267  
1268 Configures options in column I<$name>.
1269  
1270 =cut
1271  
1272 sub columnConfigure {
1273 my ($self, $name, %options) = @_;
1274 my $col = $self->columnGet($name);
1275 unless (defined $col) {
1276 croak "Column '$name' not found";
1277 return
1278 }
1279 for (keys %options) {
1280 $col->configure($_, $options{$_})
1281 }
1282 }
1283  
1284 =item B<columnCreate>I<($name, %options)>
1285  
1286 Creates a new side column object. Besides the standard options
1287 you can use the following:
1288  
1289 =over 4
1290  
1291 =item B<-after>
1292  
1293 Specify a column name.
1294  
1295 =item B<-before>
1296  
1297 Specify a column name.
1298  
1299 =back
1300  
1301 =cut
1302  
1303 sub columnCreate {
1304 my ($self, $name, %options) = @_;
1305  
1306 if ($self->columnExists($name)) {
1307 croak "Column '$name' already exists";
1308 return
1309 }
1310  
1311 my $after = delete $options{'-after'};
1312 my $before = delete $options{'-before'};
1313 my $item = new Tk::ListBrowser::SideColumn(
1314 %options,
1315 -listbrowser => $self,
1316 -name => $name,
1317 );
1318 my $columns = $self->{COLUMNS};
1319 if (defined $after) {
1320 my $index = $self->columnIndex($after);
1321 splice(@$columns, $index + 1, 0, $item) if defined $index;
1322 croak "Column for -after '$after' not found" unless defined $index;
1323 } elsif (defined $before) {
1324 my $index = $self->columnIndex($before);
1325 splice(@$columns, $index, 0, $item) if defined $index;
1326 croak "Column for -before '$before' not found" unless defined $index;
1327 } else {
1328 push @$columns, $item
1329 }
1330 return $item
1331 }
1332  
1333 =item B<columnExists>I<($name)>
1334  
1335 Returns true if column $name exists.
1336  
1337 =cut
1338  
1339 sub columnExists {
1340 my ($self, $name) = @_;
1341 my $columns = $self->{COLUMNS};
1342 my @hit = grep { $_->name eq $name } @$columns;
1343 return defined $hit[0]
1344 }
1345  
1346 =item B<columnGet>I<($name)>
1347  
1348 Returns a reference to the L<Tk::ListBrowser::SideColumn> object of I<$name>.
1349  
1350 =cut
1351  
1352 sub columnGet {
1353 my ($self, $name) = @_;
1354 my $columns = $self->{COLUMNS};
1355 my @hit = grep { $_->name eq $name } @$columns;
1356 croak "Column '$name' not found" unless @hit;
1357 return $hit[0]
1358 }
1359  
1360 =item B<columnIndex>I<($name)>
1361  
1362 Returns the place of column I<$name> inf the viewing order. The first one has index 0.
1363  
1364 =cut
1365  
1366 sub columnIndex {
1367 my ($self, $name) = @_;
1368 my $columns = $self->{COLUMNS};
1369 my ($index) = grep { $columns->[$_]->name eq $name } 0 .. @$columns - 1;
1370 return $index
1371 }
1372  
1373 =item B<columnList>
1374  
1375 Returns the names all available columns.
1376  
1377 =cut
1378  
1379 sub columnList {
1380 my $self = shift;
1381 my $columns = $self->{COLUMNS};
1382 my @l;
1383 for (@$columns) {
1384 push @l, $_->name
1385 }
1386 return @l
1387 }
1388  
1389 =item B<columnMove>I<($column, $index)>
1390  
1391 Moves $column to $index.
1392  
1393 =cut
1394  
1395 sub columnMove {
1396 my ($self, $column, $index) = @_;
1397 my $columns = $self->{COLUMNS};
1398 return if $index > @$columns - 1;
1399 return if $index < 0;
1400 my $place = $self->columnIndex($column);
1401 my $t = splice(@$columns, $place, 1);
1402 splice(@$columns, $index, 0, $t);
1403 }
1404  
1405 sub columnNext {
1406 my ($self, $name) = @_;
1407 my $columns = $self->{COLUMNS};
1408 my $next;
1409 if ($name eq '') {
1410 my $col = $columns->[0];
1411 $next = $col->name if defined $col;
1412 } else {
1413 my $i = $self->columnIndex($name);
1414 $next = $columns->[$i + 1];
1415 $next = $next->name if defined $next
1416 }
1417 return $next;
1418 }
1419  
1420 =item B<columnRemove>I<($name)>
1421  
1422 Removes column I<$name> and all its associated data.
1423  
1424 =cut
1425  
1426 sub columnRemove {
1427 my ($self, $name) = @_;
1428 my $columns = $self->{COLUMNS};
1429 my $index = $self->columnIndex($name);
1430 if (defined $index) {
1431 my ($del) = splice(@$columns, $index, 1);
1432 $del->clear;
1433 return
1434 }
1435 croak "Column '$name' not found"
1436 }
1437  
1438 =item B<columnWidth>I<($name, $width)>
1439  
1440 By default the main list and all side columns are sized so no information
1441 is lost and no unused space is created. The widths may vary when you add,
1442 remove or modify data. Once you make a call to this method the width of
1443 the column or main list becomes fixed. This works exactly as in L<Tk::HList>.
1444  
1445 Specify I<$name> as an empty string for the main list. Otherwise specify a
1446 column name.
1447  
1448 =cut
1449  
1450 sub columnWidth {
1451 my ($self, $col, $width) = @_;
1452 if ($col eq '') {
1453 $self->forceWidth($width)
1454 } else {
1455 my $c = $self->columnGet($col);
1456 $c->forceWidth($width)
1457 }
1458 }
1459  
1460 sub decodeParent {
1461 my ($self, $name) = @_;
1462 my $sep = $self->separator;
1463 $sep = quotemeta($sep);
1464 my $parent;
1465 if ($name =~ /$sep/) {
1466 $name =~ /^(.*)$sep/;
1467 $parent = $1 if defined $1;
1468 }
1469 return $parent
1470 }
1471  
1472 =item B<delete>I<(?$name?)>
1473  
1474 Deletes entry I<$name>. Call I<refresh> or refreshPurge to see your changes.
1475  
1476 =cut
1477  
1478 sub delete {
1479 my ($self, $name) = @_;
1480 my $index = $self->index($name);
1481 if (defined $index) {
1482 my $del = $self->get($name);
1483 my $noshow = $del->noshow;
1484 $del->clear;
1485 my @columns = $self->columnList;
1486 for (@columns) {
1487 $self->itemRemove($name, $_);
1488 }
1489 $self->pool->delete($name);
1490 if ($self->cget('-autorefresh')) {
1491 $self->refreshPurge($index) unless $noshow
1492 }
1493 return
1494 }
1495 croak "Entry '$name' not found"
1496 }
1497  
1498 =item B<deleteAll>
1499  
1500 Deletes all entries.
1501  
1502 =cut
1503  
1504 sub deleteAll {
1505 my $self = shift;
1506 $self->clear;
1507 $self->{POOL} = new Tk::ListBrowser::HashList;
1508 }
1509  
1510 =item B<entryCget>I<($name, $option)>
1511  
1512 Returns the value of I<$option> held by $name. Valid
1513 options are I<-data>, I<-hidden>, I<-image> and I<-text>.
1514  
1515 =cut
1516  
1517 sub entryCget {
1518 my ($self, $name, $option) = @_;
1519 my $i = $self->get($name);
1520 unless (defined $i) {
1521 croak "Entry '$name' not found";
1522 return
1523 }
1524 my $val = $i->cget($option);
1525 if (exists $self->{'insort'}) {
1526 unless (defined $val) {
1527 if ($self->cget('-sortnumerical')) {
1528 $val = $self->cget('-sortbottom')
1529 } else {
1530 $val = ''
1531 }
1532 }
1533 }
1534 return $val
1535 }
1536  
1537 =item B<entryConfigure>I<($name, %options)>
1538  
1539 Sets the value of I<%options> held by $name. Valid
1540 options are I<-data>, I<-hidden>, I<-image> and I<-text>.
1541 You can specify multiple options.
1542  
1543 =cut
1544  
1545 sub entryConfigure {
1546 my ($self, $name, %options) = @_;
1547 my $i = $self->get($name);
1548 unless (defined $i) {
1549 croak "Entry '$name' not found";
1550 return
1551 }
1552 for (keys %options) {
1553 $i->configure($_, $options{$_})
1554 }
1555 }
1556  
1557 sub filter {
1558 my ($self, $filter, $value) = @_;
1559 return 1 if $filter eq '';
1560 return '' unless (defined $value) and ($value ne '');
1561 $filter = quotemeta($filter);
1562 return 1 if $value eq '';
1563 return $value =~ /$filter/i;
1564 }
1565  
1566 sub filterFlip {
1567 my $self = shift;
1568 return if $self->cget('-nofilter');
1569 my $f = $self->Subwidget('FilterFrame');
1570 if ((defined $f) and ($f->ismapped)) {
1571 unless ($self->cget('-filterforce')) {
1572 $self->filterHide;
1573 $self->CanvasFocus;
1574 }
1575 } else {
1576 $self->filterShow;
1577 my $e = $self->Subwidget('FilterEntry');
1578 $e->focus;
1579 }
1580 }
1581  
1582 sub filterEscape {
1583 my $self = shift;
1584 my $e = $self->Subwidget('FilterEntry');
1585 $e->reset;
1586 # $e->filter;
1587 $self->filterFlip unless $self->cget('-filterforce');
1588 $self->filterRefresh;
1589 $self->CanvasFocus;
1590 }
1591  
1592 sub filterHide {
1593 my $self = shift;
1594 return if $self->cget('-nofilter');
1595 my $e = $self->Subwidget('FilterEntry');
1596 my $f = $self->Subwidget('FilterFrame');
1597 $e->delete(0, 'end');
1598 $self->filterRefresh;
1599 $f->packForget;
1600 }
1601  
1602 sub filterRefresh {
1603 my $self = shift;
1604 my @pool = $self->getAll;
1605 my $filter = $self->Subwidget('FilterEntry')->get;
1606 my $filterfield = $self->cget('-filterfield');
1607 my $filteron = $self->cget('-filteron');
1608 for (@pool) {
1609 my $item;
1610 if ($filteron eq 'main') {
1611 $item = $_;
1612 $filterfield = $self->cget('-filterfield');
1613 } else {
1614 $filterfield = $self->columnCget($filteron, '-filterfield');
1615 $item = $self->itemGet($_->name, $filteron);
1616 }
1617 if ($self->filter($filter, $item->$filterfield)) {
1618 $_->hidden('');
1619 if ($self->hierarchy) {
1620 my $par = $self->infoParent($_->name);
1621 while (defined $par) {
1622 my $p = $self->get($par);
1623 $p->hidden('');
1624 $par = $self->infoParent($p->name);
1625 }
1626 }
1627 } else {
1628 $_->hidden(1)
1629 }
1630 }
1631 delete $self->{'filter_id'};
1632 $self->refreshPurge(0);
1633 }
1634  
1635 sub filterShow {
1636 my $self = shift;
1637 return if $self->cget('-nofilter');
1638  
1639 my $f = $self->Subwidget('FilterFrame');
1640 unless (defined $f) {
1641 $f = $self->Frame;
1642 $self->Advertise('FilterFrame', $f);
1643 }
1644  
1645 my $e = $self->Subwidget('FilterEntry');
1646 my $flag = 1;
1647 unless (defined $e) {
1648 $e = $f->FilterEntry(
1649 -filterdelay => $self->cget('-filterdelay'),
1650 -command => ['filterRefresh', $self],
1651 )->pack(-side => 'left', -pady => 2, -expand => 1, -fill => 'x');
1652 $flag = '';
1653 $self->Advertise('FilterEntry', $e);
1654 $e->bind('<Control-f>', [$self, 'filterFlip']);
1655 $e->bind('<Escape>', [$self, 'filterEscape']);
1656 }
1657 $e->reset if $flag;
1658  
1659 my $cf = $self->Subwidget('FilterColumn');
1660 if ($self->cget('-filtercolumns')) {
1661 unless (defined $cf) {
1662 my @menu = ();
1663 my $filteron = $self->cget('-filteron');
1664 $filteron = $self->headerCget('', '-text') if $self->headerAvailable and $filteron eq 'main';
1665 $cf = $f->Frame;
1666 $cf->Label(-text => 'On:')->pack(-side => 'left');
1667 my $fl;
1668 my $fb = $cf->Button(
1669 -command => sub {
1670 my $name = 'main';
1671 $name = $self->headerCget('', '-text') if $self->headerAvailable;
1672 my @list = ($name, $self->columnList);
1673 $fl->configure(-values => \@list);
1674 $fl->popUp;
1675 },
1676 -textvariable => \$filteron,
1677 -relief => 'flat'
1678 )->pack(-side => 'right');
1679 $fl = $self->PopList(
1680 -relief => 'raised',
1681 -popdirection => 'up',
1682 -confine => 1,
1683 -selectcall => sub {
1684 $filteron = shift;
1685 my $name = 'main';
1686 $name = $self->headerCget('', '-text') if $self->headerAvailable;
1687 $filteron = 'main' if $filteron eq $name;
1688 $self->configure(-filteron => $filteron)
1689 },
1690 -widget => $fb,
1691 );
1692 $self->Advertise('FilterColumn', $cf);
1693 }
1694 $cf->pack(-side => 'left');
1695 } else {
1696 $cf->packForget if defined $cf;
1697 }
1698 $f->pack(-fill => 'x');
1699 }
1700  
1701 sub focus { $_[0]->CanvasFocus }
1702  
1703 sub forceHeight {
1704 my $self = shift;
1705 $self->{FORCEHEIGHT} = shift if @_;
1706 return $self->{FORCEHEIGHT}
1707 }
1708  
1709 sub forceWidth {
1710 my $self = shift;
1711 $self->{FORCEWIDTH} = shift if @_;
1712 return $self->{FORCEWIDTH}
1713 }
1714  
1715 sub geoSave {
1716 my $self = shift;
1717 $self->{GEOSAVE} = \@_ if @_;
1718 my $gs = $self->{GEOSAVE};
1719 return @$gs;
1720 }
1721  
1722 =item B<get>I<(?$name?)>
1723  
1724 Returns a reference to the L<Tk::ListBrowser::Icon> object of I<$name>.
1725  
1726 =cut
1727  
1728 sub get {
1729 my ($self, $name) = @_;
1730 return $self->pool->get($name)
1731 }
1732  
1733 =item B<getAll>I<(?$name?)>
1734  
1735 Returns a list of all L<Tk::ListBrowser::Item> objects.
1736  
1737 =cut
1738  
1739 sub getAll { return $_[0]->pool->getAll }
1740  
1741 =item B<getChildren>I<(?$parent?)>
1742  
1743 Returns a list of L<Tk::ListBrowser::Item> objects that are children of I<$parent>.
1744  
1745 =cut
1746  
1747 sub getChildren {
1748 my ($self, $name) = @_;
1749 my $sep = quotemeta($self->cget('-separator'));
1750 my $test = quotemeta($name) . $sep;
1751 my @pool = $self->getAll;
1752 my @r;
1753 my $index = $self->index($name) + 1;
1754 return @r if $index > $self->indexLast;
1755 my $item = $self->getIndex($index);
1756 my $nm = $item->name;
1757 while ($nm =~/^$test(.*)/) {
1758 push @r, $item unless $1 =~ /$sep/;
1759 $index ++;
1760 return @r if $index > $self->indexLast;
1761 $item = $self->getIndex($index);
1762 $nm = $item->name;
1763 }
1764 return @r;
1765 }
1766  
1767 =item B<getColumn>I<($column)>
1768  
1769 Returns a reference to the L<Tk::ListBrowser::SideColumn> object of column I<$column>.
1770 Only practical when I<-arrange> is set to 'column' or 'row'.
1771  
1772 =cut
1773  
1774 sub getColumn {
1775 my ($self, $col) = @_;
1776 my @hits = grep { (defined $_->column) and ($_->column eq $col) } $self->getAll;
1777 return @hits
1778 }
1779  
1780 =item B<getIndex>I<($index)>
1781  
1782 Returns a reference to the L<Tk::ListBrowser::Item> object at index I<$index>.
1783  
1784 =cut
1785  
1786 sub getIndex {
1787 my ($self, $index) = @_;
1788 return $self->pool->getIndex($index)
1789 }
1790  
1791 sub getPool {
1792 my $self = shift;
1793 my @pool;
1794 if ($self->hierarchy) {
1795 my @root = $self->infoRoot;
1796 for (@root) {
1797 push @pool, $self->get($_);
1798 }
1799 } else {
1800 @pool = $self->getAll;
1801 }
1802 return @pool;
1803 }
1804  
1805 =item B<getRoot>
1806  
1807 Returns a list of L<Tk::ListBrowser::Entry> objects that are root.
1808  
1809 =cut
1810  
1811 sub getRoot {
1812 my $self = shift;
1813 my @pool = $self->getAll;
1814 my $sep = $self->separator;
1815 $sep = quotemeta($sep);
1816 return grep { not $_->name =~ /$sep/ } @pool;
1817 }
1818  
1819 =item B<getRow>I<($row)>
1820  
1821 Returns a list of references to all L<Tk::ListBrowser::Icon> objects in row I<$row>.
1822 Only practical when I<-arrange> is set to 'column' or 'row'.
1823  
1824 =cut
1825  
1826 sub getRow {
1827 my ($self, $row) = @_;
1828 my @hits = grep { (defined $_->row ) and ($_->row eq $row) } $self->getAll;
1829 return @hits
1830 }
1831  
1832 sub header {
1833 my $self = shift;
1834 $self->{HEADER} = shift if @_;
1835 return $self->{HEADER}
1836 }
1837  
1838 =item B<headerAvailable>
1839  
1840 Returns true if headers have been defined.
1841  
1842 =cut
1843  
1844 sub headerAvailable {
1845 my $self = shift;
1846 my $a = $self->cget('-arrange');
1847 return '' if (($a eq 'column') or ($a eq 'row'));
1848 return 1 if defined $self->header;
1849 my @columns = $self->columnList;
1850 for (@columns) {
1851 return 1 if defined $self->headerGet($_)
1852 }
1853 return ''
1854 }
1855  
1856 =item B<headerCget>I<($column, $option)>
1857  
1858 Returns the value of $option in header $name.
1859  
1860 Specify I<$column> as an empty string for the main list. Otherwise specify a column name.
1861  
1862 =cut
1863  
1864 sub headerCget {
1865 my ($self, $col, $option) = @_;
1866 my $h;
1867 if ($col eq '') {
1868 $h = $self->header
1869 } else {
1870 my $c = $self->columnGet($col);
1871 $h = $c->header
1872 }
1873 return $h->cget($option) if defined $h
1874 }
1875  
1876 sub headerClear {
1877 my $self = shift;
1878 $self->Subwidget('HeaderFrame')->packForget;
1879 }
1880  
1881 =item B<headerConfigure>I<($column, $option, $value)>
1882  
1883 Configures options in header $name.
1884  
1885 Specify $name as an empty string for the main list. Otherwise specify a column name.
1886  
1887 =cut
1888  
1889 sub headerConfigure {
1890 my ($self, $col, $option, $value) = @_;
1891 my $h;
1892 if ($col eq '') {
1893 $h = $self->header
1894 } else {
1895 my $c = $self->columnGet($col);
1896 $h = $c->header
1897 }
1898 $h->configure($option, $value) if defined $h
1899 }
1900  
1901 =item B<headerCreate>I<($column, %options)>
1902  
1903 Creates a new header object. You can use the following options:
1904  
1905 =over 4
1906  
1907 =item B<-contextcall>
1908  
1909 Callback executed when you right click the header.
1910  
1911 =item B<-image>
1912  
1913 Image to display on the header. This option precedes the I<-text> option.
1914  
1915 =item B<-sortable>
1916  
1917 Only available at create time. If set to true the list is sorted by clicking on the header.
1918 By default sorting is disabled.
1919  
1920 =item B<-text>
1921  
1922 Text to display on the header.
1923  
1924 =back
1925  
1926 Specify I<$column> as an empty string for the main list. Otherwise specify a column name.
1927  
1928 =cut
1929  
1930 sub headerCreate {
1931 my ($self, $col, %options) = @_;
1932 if ($self->headerExists($col)) {
1933 croak "Header '$col' already exists";
1934 return
1935 }
1936
1937 my $sortable = delete $options{'-sortable'};
1938 $options{'-sortcall'} = ['sortMode', $self] if (defined $sortable) and $sortable;
1939 my $hf= $self->Subwidget('HeaderFrame');
1940 my $h = $hf->LBHeader(
1941 -motioncall => ['headerMotion', $self],
1942 -releasecall => ['refreshPurge', $self],
1943 -relief => $self->cget('-headerrelief'),
1944 -borderwidth => $self->cget('-headerborderwidth'),
1945 -listbrowser => $self,
1946 -column => $col,
1947 %options,
1948 );
1949 if ($col eq '') {
1950 $self->header($h)
1951 } else {
1952 my $c = $self->columnGet($col);
1953 $c->header($h) if defined $c
1954 }
1955 }
1956  
1957 =item B<headerExists>I<($column)>
1958  
1959 Returns true if column I<$name> exists.
1960  
1961 Specify I<$column> as an empty string for the main list. Otherwise specify a column name.
1962  
1963 =cut
1964  
1965 sub headerExists {
1966 my ($self, $col) = @_;
1967 return defined $self->headerGet($col)
1968 }
1969  
1970 sub headerGet {
1971 my ($self, $col) = @_;
1972 my $h;
1973 if ($col eq '') {
1974 $h = $self->header
1975 } else {
1976 my $c = $self->columnGet($col);
1977 $h = $c->header if defined $c
1978 }
1979 return $h
1980 }
1981  
1982 sub headerMotion {
1983 my ($self, $column, $x) = @_;
1984 return if $column eq '';
1985 my $c = $self->headerGet($column);
1986 my ($right, $target);
1987 my $index = $self->columnIndex($column);
1988 my $columns = $self->{COLUMNS};
1989 if ($x > 0) {
1990 $right = 1;
1991 return if $index >= @$columns - 1;
1992 $target = $columns->[$index + 1];
1993 } else {
1994 $right = '';
1995 return if $index <= 0;
1996 $target = $columns->[$index - 1];
1997 }
1998 $target = $self->headerGet($target->name);
1999 my $t = $target->x + int($target->width / 2);
2000 $x = $x + $c->x;
2001 if ($right) {
2002 if ($x > $t) {
2003 $self->columnMove($column, $index + 1);
2004 $self->headerPlace;
2005 }
2006 } else {
2007 if ($x < $t) {
2008 $self->columnMove($column, $index - 1);
2009 $self->headerPlace;
2010 }
2011 }
2012 }
2013  
2014 sub headerPlace {
2015 my $self = shift;
2016 return unless $self->listMode;
2017 return unless $self->headerAvailable;
2018  
2019 my $hf = $self->Subwidget('HeaderFrame');
2020 my $hheight = $self->cget('-headerheight');
2021 $hf->configure(-height => $hheight);
2022 $hf->pack(-fill, 'x');
2023  
2024 my $width = $self->cget('-scrollregion');
2025 $width = $width->[2];
2026  
2027 my ($fract) = $self->Subwidget('Canvas')->xview;
2028 my $x = - int($width * $fract);
2029  
2030 #configure left margin
2031 my $lm = $self->cget('-marginleft');
2032 if ($lm > 0) {
2033 my $frame = $self->Subwidget("LMFrame");
2034 unless (defined $frame) {
2035 $frame = $hf->Frame(
2036 -borderwidth => $self->cget('-headerborderwidth'),
2037 -relief => $self->cget('-headerrelief'),
2038 );
2039 $self->Advertise('LMFrame', $frame)
2040 }
2041 $frame->place(-x => $x, -y => 0, -height => $hheight, -width => $lm - 1);
2042 $x = $x + $lm;
2043 } else {
2044 my $frame = $self->Subwidget("LMFrame");
2045 $frame->placeForget if defined $frame
2046 }
2047  
2048 #configure main header
2049 if (my $h = $self->headerGet('')) {
2050 $h->place(-x => $x, -y => 0, -height => $hheight, -width => $self->listWidth);
2051 }
2052 $x = $x + $self->listWidth + 1;
2053  
2054 #configure columns
2055 my @columns = $self->columnList;
2056 for (@columns) {
2057 my $col = $self->columnGet($_);
2058 my $w = $col->cget('-cellwidth');
2059 if (my $h = $self->headerGet($_)) {
2060 $h->place(-x => $x, -y => 0, -height => $hheight, -width => $w);
2061 }
2062 $x = $x + $w + 1;
2063 }
2064  
2065 #configure right margin
2066 my ($cw) = $self->canvasSize;
2067 my $rm = $self->cget('-marginright');
2068 if ($x < $cw) {
2069 my $frame = $self->Subwidget("RMFrame");
2070 unless (defined $frame) {
2071 $frame = $hf->Frame(
2072 -borderwidth => $self->cget('-headerborderwidth'),
2073 -relief => $self->cget('-headerrelief'),
2074 );
2075 $self->Advertise('RMFrame', $frame)
2076 }
2077 $frame->place(-x => $x, -y => 0, -height => $hheight, -width => $cw - $x + 3);
2078 } else {
2079 my $frame = $self->Subwidget("RMFrame");
2080 $frame->placeForget if defined $frame
2081 }
2082 }
2083  
2084 =item B<headerRemove>I<($column)>
2085  
2086 Removes the header for column I<$column>.
2087  
2088 Specify I<$column> as an empty string for the main list. Otherwise specify a column name.
2089  
2090 =cut
2091  
2092 sub headerRemove {
2093 my ($self, $col) = @_;
2094 my $h;
2095 if ($col eq '') {
2096 $h = $self->header;
2097 $self->header(undef);
2098 } else {
2099 my $c = $self->columnGet($col);
2100 if (defined $c) {
2101 $h = $c->header;
2102 $c->header(undef)
2103 }
2104 }
2105 $h->destroy if defined $h;
2106 }
2107  
2108 =item B<hide>I<($name)>
2109  
2110 Hides entry I<$name>. Call I<refresh> or I<refreshPurge> to see changes.
2111  
2112 =cut
2113  
2114 sub hide {
2115 my ($self, $name) = @_;
2116 my $a = $self->get($name);
2117 return unless defined $a;
2118 $a->hidden(1);
2119 }
2120  
2121 sub hierarchy { return $_[0]->cget('-separator') ne '' }
2122  
2123 =item B<index>
2124  
2125 Returns the numerical index of entry I<$name>.
2126  
2127 =cut
2128  
2129 sub index {
2130 my ($self, $name) = @_;
2131 return $self->pool->index($name)
2132 }
2133  
2134 =item B<indexColumnRow>I<($column, $row)>
2135  
2136 Returns the numerical index of the entry at I<$column>, I<$row>.
2137  
2138 =cut
2139  
2140 sub indexColumnRow {
2141 my ($self, $column, $row) = @_;
2142 my @pool = $self->getAll;
2143 my ($index) = grep {
2144 (defined $pool[$_]->column) and
2145 (defined $pool[$_]->row) and
2146 ($pool[$_]->column eq $column) and
2147 ($pool[$_]->row eq $row)
2148 } 0 .. @pool - 1;
2149 return $index
2150 }
2151  
2152 =item B<indexLast>
2153  
2154 Returns the numerical index of the last entry in the list.
2155  
2156 =cut
2157  
2158 sub indexLast {
2159 my $self = shift;
2160 return $self->pool->indexLast
2161 }
2162  
2163 sub indicatorActivate {
2164 my ($self, $entry) = @_;
2165 my $obj = $self->get($entry);
2166 if ($obj->opened) {
2167 $self->Callback('-indicatorprecmd', $entry, 'close');
2168 $self->close($entry);
2169 $self->refreshPurge($self->index($entry), 1);
2170 $self->Callback('-indicatorpostcmd', $entry, 'close');
2171 } else {
2172 $self->Callback('-indicatorprecmd', $entry, 'open');
2173 $self->open($entry);
2174 $self->refreshPurge($self->index($entry), 1);
2175 $self->Callback('-indicatorpostcmd', $entry, 'open');
2176 }
2177 }
2178  
2179 =item B<infoAnchor>
2180  
2181 Returns the name of the entry that holds the anchor.
2182 Returns undef if the anchor is not held.
2183  
2184 =cut
2185  
2186 sub infoAnchor {
2187 my $self = shift;
2188 my $a = $self->anchorGet;
2189 return $a->name if defined $a;
2190 return undef
2191 }
2192  
2193 =item B<infoChildren>I<($parent)>
2194  
2195 Returns a list with the names of the children of I<$parent>.
2196  
2197 =cut
2198  
2199 sub infoChildren {
2200 my ($self, $name) = @_;
2201 my $sep = quotemeta($self->cget('-separator'));
2202 my $test = quotemeta($name) . $sep;
2203 my @pool = $self->getAll;
2204 my @r;
2205 my $index = $self->index($name) + 1;
2206 return @r if $index > $self->indexLast;
2207 my $item = $self->getIndex($index);
2208 my $nm = $item->name;
2209 while ($nm =~/^$test(.*)/) {
2210 push @r, $nm unless $1 =~ /$sep/;
2211 $index ++;
2212 return @r if $index > $self->indexLast;
2213 $item = $self->getIndex($index);
2214 $nm = $item->name;
2215 }
2216 return @r;
2217 }
2218  
2219 =item B<infoData>I<($name)>
2220  
2221 Returns the data associated with entry I<$name>
2222  
2223 =cut
2224  
2225 sub infoData {
2226 my ($self, $name) = @_;
2227 my $a = $self->get($name);
2228 return $a->data if defined $a;
2229 croak "Entry '$name' not found";
2230 return undef
2231 }
2232  
2233 =item B<infoExists>I<($name)>
2234  
2235 Returns a boolean value indicating if entry I<$name> exists.
2236  
2237 =cut
2238  
2239 sub infoExists {
2240 my ($self, $name) = @_;
2241 return $self->pool->exist($name)
2242 }
2243  
2244 =item B<infoFirst>
2245  
2246 Returns the name of the first entry in the list.
2247  
2248 =cut
2249  
2250 sub infoFirst {
2251 my $self = shift;
2252 my $f = $self->pool->first;
2253 return $f->name if defined $f;
2254 return undef;
2255 }
2256  
2257 =item B<infoFirstVisible>
2258  
2259 Returns the name of the first entry in the list that is not hidden.
2260  
2261 =cut
2262  
2263 sub infoFirstVisible {
2264 my $self = shift;
2265 my @pool = $self->getAll;
2266 for (@pool) {
2267 return $_->name unless $_->noshow
2268 }
2269 return undef
2270 }
2271  
2272 =item B<infoHidden>I<($name)>
2273  
2274 Returns the boolean hidden state of entry I<$name>.
2275  
2276 =cut
2277  
2278 sub infoHidden {
2279 my ($self, $name) = @_;
2280 my $a = $self->get($name);
2281 return $a->hidden if defined $a;
2282 croak "Entry '$name' not found";
2283 return undef
2284 }
2285  
2286 =item B<infoLast>
2287  
2288 Returns the name of the last entry in the list.
2289  
2290 =cut
2291  
2292 sub infoLast {
2293 my $self = shift;
2294 my $l = $self->pool->last;
2295 return $l->name if defined $l;
2296 return undef
2297 }
2298  
2299 sub infoLastChild {
2300 my ($self, $name) = @_;
2301 my @c = $self->infoChildren($name);
2302 return pop @c if @c;
2303 return undef
2304 }
2305  
2306 sub infoLastOffspring {
2307 my ($self, $name) = @_;
2308 my $last = $self->infoLastChild($name);
2309 if (defined $last) {
2310 my $lo = $self->infoLastOffspring($last);
2311 return $lo if defined $lo;
2312 }
2313 return $last
2314 }
2315  
2316 =item B<infoLastVisible>
2317  
2318 Returns the name of the last entry in the list that is not hidden.
2319  
2320 =cut
2321  
2322 sub infoLastVisible {
2323 my $self = shift;
2324 my @pool = $self->getAll;
2325 for (reverse @pool) {
2326 return $_->name if $_->ismapped
2327 }
2328 return undef
2329 }
2330  
2331 =item B<infoList>
2332  
2333 Returns a list of all entry names in the list.
2334  
2335 =cut
2336  
2337 sub infoList {
2338 my ($self, $flag) = shift;
2339 my @pool = $self->getAll;
2340 my @list;
2341 for (@pool) {
2342 push @list, $_->name;
2343 }
2344 return @list
2345 }
2346  
2347 =item B<infoNext>I<($name, ?$flag>?)>
2348  
2349 The parameter I<$flag> is only usefull in hierarchy mode.
2350 By default it is set to true. You can overwrite that by
2351 specifying it as false.
2352  
2353 If I<$flag> is set in hierarchy mode the next peer is returned,
2354 or undef if I<$name> is the last peer amoung it's peers.
2355  
2356 In non hierarchy mode it returns the name of the next entry of
2357 I<$name> or undef if I<$name> is the last entry in the list.
2358  
2359 =cut
2360  
2361 sub infoNext {
2362 my ($self, $name, $flag) = @_;
2363 $flag = 1 unless defined $flag;
2364 my $a = $self->index($name);
2365 unless (defined $a) {
2366 croak "Entry '$name' not found";
2367 return undef
2368 }
2369 my $last = $self->infoLast;
2370 return undef if $a eq $last;
2371 if ($self->hierarchy and $flag) {
2372 my $cur = $self->get($name);
2373 my @c = $self->infoChildren($name);
2374 if (@c) {
2375 my $last = pop @c;
2376 my $li = $self->index($last);
2377 $a = $li if $li < $self->infoSize;
2378 }
2379 }
2380 return undef if $a eq $self->indexLast;
2381 return $self->getIndex($a + 1)->name;
2382 }
2383  
2384 =item B<infoNextVisible>I<($name)>
2385  
2386 Returns the name of the first next entry of I<$name> that is not hidden.
2387 Returns undef if I<$name> is the last entry in the list.
2388  
2389 =cut
2390  
2391 sub infoNextVisible {
2392 my ($self, $name) = @_;
2393 my @pool = $self->getAll;
2394 my $a = $self->index($name);
2395 unless (defined $a) {
2396 croak "Entry '$name' not found";
2397 return
2398 }
2399 for ($a .. @pool - 1) {
2400 return $pool[$_]->name if $pool[$_]->ismapped
2401 }
2402 return undef
2403 }
2404  
2405 =item B<infoParent>I<($name)>
2406  
2407 Returns the name of parent of I<$name>. Returns undef
2408 if no parent is found.
2409  
2410 =cut
2411  
2412 sub infoParent {
2413 my ($self, $name) = @_;
2414 unless ($self->infoExists($name)) {
2415 croak "Entry '$name' does not exist";
2416 return
2417 }
2418 my $parent = $self->decodeParent($name);
2419 return undef unless defined $parent;
2420 return $parent if $self->infoExists($parent);
2421 return undef
2422 }
2423  
2424 =item B<infoPev>I<($name, ?$flag?)>
2425  
2426 The parameter I<$flag> is only usefull in hierarchy mode.
2427 By default it is set to true. You can overwrite that by
2428 specifying it as false.
2429  
2430 If I<$flag> is set in hierarchy mode the previous peer is returned,
2431 or undef if I<$name> is the first peer amoung it's peers.
2432  
2433 In non hierarchy mode it returns the name of the previous entry of
2434 I<$name> or undef if I<$name> is the first entry in the list.
2435  
2436 =cut
2437  
2438 sub infoPrev {
2439 my ($self, $name, $flag) = @_;
2440 $flag = 1 unless defined $flag;
2441 my @pool = $self->getAll;
2442 my $a = $self->index($name);
2443 unless (defined $a) {
2444 croak "Entry '$name' not found";
2445 return
2446 }
2447 return undef if $a eq 0;
2448 if ($self->hierarchy and $flag) {
2449 my $cur = $self->get($name);
2450 my @c = $self->infoChildren($name);
2451 if (@c) {
2452 my $first = shift @c;
2453 my $fi = $self->index($first);
2454 $a = $fi;
2455 }
2456 }
2457 return undef if $a eq 0;
2458 return $self->getIndex($a - 1)->name;
2459 }
2460  
2461 =item B<infoPrevVisible>I<($name)>
2462  
2463 Returns the name of the first previous entry of I<$name> that is not hidden.
2464 Returns undef if I<$name> is the first entry in the list.
2465  
2466 =cut
2467  
2468 sub infoPrevVisible {
2469 my ($self, $name) = @_;
2470 my @pool = $self->getAll;
2471 my $a = $self->index($name);
2472 unless (defined $a) {
2473 croak "Entry '$name' not found";
2474 return
2475 }
2476 for (reverse 0 .. $a) {
2477 return $pool[$_]->name if $pool[$_]->ismapped
2478 }
2479 return undef
2480 }
2481  
2482 =item B<infoRoot>
2483  
2484 Returns a list of root entry names.
2485  
2486 =cut
2487  
2488 sub infoRoot {
2489 my $self = shift;
2490 my @pool = $self->getAll;
2491 my $sep = $self->cget('-separator');
2492 $sep = quotemeta($sep);
2493 my @root;
2494 for (@pool) {
2495 my $name = $_->name;
2496 push @root, $name unless $name =~ /$sep/;
2497 }
2498 return @root
2499 }
2500  
2501 =item B<infoSelection>
2502  
2503 Same as I<selectionGet>.
2504  
2505 =cut
2506  
2507 sub infoSelection { return $_[0]->selectionGet }
2508  
2509 sub infoSize { return $_[0]->pool->size }
2510  
2511 sub inIndicator {
2512 my ($self, $x, $y) = @_;
2513 my $c = $self->Subwidget('Canvas');
2514  
2515 my @ind = $c->find('withtag', 'indicator');
2516 for (@ind) {
2517 my ($ix, $iy) = $c->coords($_);
2518 my $img = $self->cget('-indicatorplusimg');
2519 my $half = int($img->width / 2) + 2;
2520 my ($x1, $y1, $x2, $y2) = $c->coords($_);
2521 return $_ if ($ix - $half <= $x) and ($ix + $half >= $x) and ($iy - $half <= $y) and ($iy + $half >= $y);
2522 }
2523 return undef
2524 }
2525  
2526 sub initem {
2527 my ($self, $x, $y) = @_;
2528 $x = int($self->canvasx($x));
2529 $y = int($self->canvasy($y));
2530 my @pool = $self->getAll;
2531 for (@pool) {
2532 if ($_->inregion($x, $y)) {
2533 return $_;
2534 }
2535  
2536 }
2537 return undef
2538 }
2539  
2540 =item B<insert>I<($entryobj, ?$index?)>
2541  
2542 Directly inject a list element object into the list. If I<$index> is
2543 ommitted the object is added to the end of the list.
2544  
2545 =cut
2546  
2547 sub insert {
2548 my ($self, $item, $index) = @_;
2549 $self->pool->add($item, $index);
2550 $self->refreshCheck($item, $index) if $self->cget('-autorefresh');
2551 }
2552  
2553 =item B<itemCget>I<($name, $column, $option)>
2554  
2555 Returns the value of $option of item I<$name> in column I<$column>.
2556  
2557 =cut
2558  
2559 sub itemCget {
2560 my ($self, $entry, $column, $option) = @_;
2561 my $i = $self->itemGet($entry, $column);
2562 my $val;
2563 if (defined $i) {
2564 $val = $i->cget($option);
2565 }
2566 if ($self->sortActive) {
2567 unless (defined $val) {
2568 if ($i->owner->cget('-sortnumerical')) {
2569 $val = $self->cget('-sortbottom');
2570 } else {
2571 $val = ''
2572 }
2573 }
2574 }
2575 return $val
2576 }
2577  
2578 =item B<itemConfigure>I<($name, $column, %options)>
2579  
2580 Configures the options item of I<$name> in column I<$column>.
2581  
2582 =cut
2583  
2584 sub itemConfigure {
2585 my ($self, $entry, $column, %options) = @_;
2586 my $i = $self->itemGet($entry, $column);
2587 if (defined $i) {
2588 $i->configure(%options)
2589 }
2590 }
2591  
2592 =item B<itemCreate>I<($name, $column, %options)>
2593  
2594 Creates a new item object for I<$name> in column I<$column>. You can use the standard options as well as:
2595  
2596 =over 4
2597  
2598 =item B<-data>
2599  
2600 Data to be assigned to this item item.
2601  
2602 =item B<-image>
2603  
2604 Image to display in the item.
2605  
2606 =item B<-text>
2607  
2608 Text to display in the item.
2609  
2610 =back
2611  
2612 Once an item has been created there is no need to call I<refresh> when you update it's text or image.
2613  
2614 =cut
2615  
2616 sub itemCreate {
2617 my ($self, $entry, $column, %options) = @_;
2618 my $col = $self->columnGet($column);
2619 my $item = new Tk::ListBrowser::Item(
2620 %options,
2621 -listbrowser => $self,
2622 -name => $entry,
2623 -owner => $col,
2624 );
2625 $col->itemAdd($entry, $item)
2626 }
2627  
2628 =item B<itemExists>I<($name, $column)>
2629  
2630 Returns true if item for I<$name> in column I<$column> has been created.
2631  
2632 =cut
2633  
2634 sub itemExists {
2635 my ($self, $entry, $column) = @_;
2636 my $col = $self->columnGet($column);
2637 return $col->itemExists($entry)
2638 }
2639  
2640 =item B<itemGet>I<($name, $column)>
2641  
2642 Returns a reference to the L<Tk::ListBrowser::Item> object for I<$name> in column I<$column>.
2643  
2644 =cut
2645  
2646 sub itemGet {
2647 my ($self, $entry, $column) = @_;
2648 my $col = $self->columnGet($column);
2649 return $col->itemGet($entry)
2650 }
2651  
2652 =item B<itemRemove>I<($name, $column)>
2653  
2654 Removes the item for I<$name> in column I<$column> and it's data.
2655  
2656 =cut
2657  
2658 sub itemRemove {
2659 my ($self, $entry, $column) = @_;
2660 my $col = $self->columnGet($column);
2661 $col->itemRemove($entry)
2662 }
2663  
2664 sub lastScrollRegion {
2665 my $self = shift;
2666 $self->{SCROLLREGION} = [@_] if @_;
2667 my $r = $self->{SCROLLREGION};
2668 return @$r;
2669 }
2670  
2671  
2672 sub KeyArrowNavig {
2673 my ($self, $dcol, $drow) = @_;
2674 return undef if $self->anchorInitialize;
2675 my $i = $self->anchorGet;
2676 my $target;
2677 if ($drow eq 0) { #horizontal move
2678 my $flag = 1;
2679 if ($self->hierarchy and ($self->cget('-arrange') eq 'tree')) {
2680 my $a = $self->anchorGet;
2681 if (defined $a) {
2682 my $n = $a->name;
2683 my $o = $a->opened;
2684 my @ch = $self->infoChildren($a->name);
2685 if ($dcol eq 1) { #move to the right
2686 if ((! $a->opened) and (@ch)) {
2687 my $nm = $a->name;
2688 my $i = $self->index($nm);
2689 $self->open($nm);
2690 $self->refreshPurge($i, 1);
2691 $flag = '';
2692 }
2693 } else { #move to the left
2694 if (($a->opened) and (@ch)) {
2695 my $nm = $a->name;
2696 my $i = $self->index($nm);
2697 $self->close($nm);
2698 $self->refreshPurge($i, 1);
2699 $flag = '';
2700 } else {
2701 if (my $parent = $self->infoParent($a->name)) {
2702 $a = $self->get($parent);
2703 $flag = '';
2704 }
2705 }
2706 }
2707 $self->anchorSet($a->name);
2708 $self->selectionSingle($a->name) if $self->cget('-selectstyle') eq 'simple';
2709 }
2710 }
2711 if ($flag) {
2712 my $rown = $i->row;
2713 my @row = $self->getRow($rown);
2714 if (($dcol > 0) and ($i->column >= @row - 1)) {
2715 $target = $self->moveRow(1);
2716 } elsif (($dcol < 0) and ($i->column <= 0)) {
2717 $target = $self->moveRow(-1);
2718 } else {
2719 my $ti = $self->indexColumnRow($i->column + $dcol, $rown);
2720 $target = $self->getIndex($ti) if defined $ti;
2721 }
2722 }
2723 } else { #vertical move
2724 my $coln = $i->column;
2725 my @column = $self->getColumn($coln);
2726 if (($drow > 0) and ($i->row >= @column - 1)) {
2727 $target = $self->moveColumn(1);
2728 } elsif (($drow < 0) and ($i->row <= 0)) {
2729 $target = $self->moveColumn(-1);
2730 } else {
2731 my $ti = $self->indexColumnRow($coln, $i->row + $drow);
2732 $target = $self->getIndex($ti) if defined $ti;
2733 }
2734 }
2735 if (defined $target) {
2736 my $name = $target->name;
2737 $self->anchorSet($name);
2738 my $style = $self->cget('-selectstyle');
2739 $self->selectionSingle($name) if $style eq 'simple';
2740 $self->see($name);
2741 return 1
2742 }
2743 return ''
2744 }
2745  
2746 sub KeyArrowSelect {
2747 my ($self, $dcol, $drow) = @_;
2748 return if $self->anchorInitialize;
2749 my $p = $self->anchorGet;
2750 if ($self->KeyArrowNavig($dcol, $drow)) {
2751 my $new = $self->anchorGet->name;
2752 if ($p->selected) {
2753 $self->selectionSet($new)
2754 } else {
2755 $self->selectionUnSet($new)
2756 }
2757 }
2758 }
2759  
2760  
2761 sub KeyLastColumn {
2762 my $self = shift;
2763 return if $self->anchorInitialize;
2764 my $i = $self->anchorGet;
2765 my $row = $i->row;
2766 my $col = $self->lastColumnInRow($row);
2767 unless ($self->anchorSetColumnRow($col, $row)) {
2768 my $flag = '';
2769 while ((not $flag) and ($col >= 0)) {
2770 $col --;
2771 my $index = $self->indexColumnRow($col, $row);
2772 my $name = $self->getIndex($index)->name;
2773 $flag = $self->anchorSet($name);
2774 $self->see($name) if $flag;
2775 }
2776 }
2777 }
2778  
2779 sub KeyPress {
2780 my ($self, $key) = @_;
2781 my @pool = $self->getAll;
2782 my $h = $self->handler;
2783 return unless @pool;
2784  
2785 if ($key eq 'Return') {
2786 return if $self->anchorInitialize;
2787 my $i = $self->anchorGet;
2788 my $name = $i->name;
2789 $self->selectionSet($name);
2790 $self->Callback('-command', $name);
2791 return
2792 }
2793 if ($key eq 'Escape') {
2794 my $e = $self->Subwidget('FilterEntry');
2795 if ((defined $e) and ($e->ismapped) and (! $self->cget('-filterforce'))) {
2796 $self->filterFlip
2797 } else {
2798 $self->selectionClear unless $self->cget('-selectmode') eq 'exclusive';
2799 $self->anchorClear;
2800 }
2801 return
2802 }
2803  
2804 #keyboard navigation
2805 if ($key eq 'Down') {
2806 $self->KeyArrowNavig(0, 1);
2807 return
2808 }
2809 if ($key eq 'End') {
2810 $self->KeyLastColumn;
2811 return
2812 }
2813 if ($key eq 'Control-End') {
2814 my $name = $self->infoLastVisible;
2815 $self->see($name);
2816 return
2817 }
2818 if ($key eq 'Home') {
2819 return if $self->anchorInitialize;
2820 my $i = $self->anchorGet;
2821 my $row = $i->row;
2822 my $index = $self->indexColumnRow(0, $row);
2823 my $name = $pool[$index]->name;
2824 $self->anchorSet($name);
2825 $self->see($name);
2826 return
2827 }
2828 if ($key eq 'Control-Home') {
2829 my $name = $self->infoFirstVisible;
2830 $self->anchorSet($name);
2831 $self->see($name);
2832 return
2833 }
2834 if ($key eq 'Left') {
2835 $self->KeyArrowNavig(-1, 0);
2836 return
2837 }
2838 if ($key eq 'Right') {
2839 $self->KeyArrowNavig(1, 0);
2840 return
2841 }
2842 if ($key eq 'Up') {
2843 $self->KeyArrowNavig(0, -1);
2844 return
2845 }
2846  
2847 #manipulating selections
2848 if ($key eq 'space') {
2849 return if $self->anchorInitialize;
2850 my $i = $self->anchorGet;
2851 my $name = $i->name;
2852 if ($self->cget('-selectmode') eq 'exclusive') {
2853 $self->selectionSet($name);
2854 } else {
2855 $self->selectionFlip($name);
2856 }
2857 $self->Callback('-browsecmd', $name) if $i->selected;
2858 return
2859 }
2860 if ($key eq 'Shift-Down') {
2861 return $self->KeyArrowSelect(0, 1)
2862 }
2863 if ($key eq 'Shift-End') {
2864 return if $self->anchorInitialize;
2865 my $i = $self->anchorGet;
2866 my $column = $i->column;
2867 my $row = $i->row;
2868 my @items = $self->getRow($row);
2869 if ($self->KeyLastColumn) {
2870 for (@items) {
2871 if ($self->cget('-selectmode') eq 'multiple') {
2872 $self->selectionFlip($_->name)
2873 }
2874 }
2875 }
2876 }
2877 if ($key eq 'Control-Shift-End') {
2878 return if $self->anchorInitialize;
2879 my $begin = $self->anchorGet;
2880 my $name = $self->infoLastVisible;
2881 if ($self->anchorSet($name)) {
2882 my $end = $self->anchorGet;
2883 if ($begin->selected) {
2884 $self->selectionClear if $self->cget('-selectmode') eq 'single';
2885 $self->selectionSet($begin->name, $end->name);
2886 } else {
2887 $self->selectionClear if $self->cget('-selectmode') eq 'single';
2888 $self->selectionUnSet($begin->name, $end->name);
2889 }
2890 $self->see($name);
2891 }
2892 }
2893 if ($key eq 'Shift-Home') {
2894 return if $self->anchorInitialize;
2895 my $i = $self->anchorGet;
2896 my $column = $i->column;
2897 my $row = $i->row;
2898 my @items = $self->getRow($row);
2899 if ($self->anchorSetColumnRow(0, $row)) {
2900 for (@items) {
2901 $self->selectionFlip($_->name)
2902 }
2903 }
2904 return
2905 }
2906 if ($key eq 'Control-Shift-Home') {
2907 return if $self->anchorInitialize;
2908 my $begin = $self->anchorGet;
2909 if ($self->anchorSet($self->infoFirstVisible)) {
2910 my $end = $self->anchorGet;
2911 if ($begin->selected) {
2912 $self->selectionSet($begin->name, $end->name);
2913 } else {
2914 $self->selectionUnSet($begin->name, $end->name);
2915 }
2916 }
2917 return
2918 }
2919 if ($key eq 'Shift-Left') {
2920 return $self->KeyArrowSelect(-1, 0)
2921 }
2922 if ($key eq 'Shift-Right') {
2923 return $self->KeyArrowSelect(1, 0)
2924 }
2925 if ($key eq 'Shift-Up') {
2926 return $self->KeyArrowSelect(0, -1)
2927 }
2928 }
2929  
2930 =item B<lastColumnInRow>I<($row)>
2931  
2932 Returns the number of the last column in I<$row>.
2933  
2934 =cut
2935  
2936 sub lastColumnInRow {
2937 my ($self, $row) = @_;
2938 my @row = $self->getRow($row);
2939 return $row[@row - 1]->column;
2940 }
2941  
2942 =item B<lastRowInColumn>I<($column)>
2943  
2944 Returns the number of the last row in I<$column>.
2945  
2946 =cut
2947  
2948 sub lastRowInColumn {
2949 my ($self, $column) = @_;
2950 my @column = $self->getColumn($column);
2951 return $column[@column - 1]->row;
2952 }
2953  
2954 =item B<listMode>
2955  
2956 Returns true if I<-arrange> is set to 'hlist', 'list' or 'tree'.
2957  
2958 =cut
2959  
2960 sub listMode {
2961 my $self = shift;
2962 my $arr = $self->cget('-arrange');
2963 return '' unless defined $arr;
2964 return (($arr ne 'column') and ($arr ne 'row') and ($arr ne 'bar'));
2965 }
2966  
2967 sub listWidth {
2968 my $self = shift;
2969 $self->{LISTWIDTH} = shift if @_;
2970 my $fw = $self->forceWidth;
2971 return $fw if defined $fw;
2972 return $self->{LISTWIDTH}
2973 }
2974  
2975 sub Motion {
2976 my ($self, $x, $y) = @_;
2977 return unless $self->cget('-selectmode') eq 'single';
2978 return unless $self->cget('-motionselect');
2979 my $item = $self->initem($x, $y);
2980 if (defined $item) {
2981 $self->selectionSet($item->name);
2982 }
2983 }
2984  
2985 sub moveColumn {
2986 my ($self, $delta) = @_;
2987 my $i = $self->anchorGet;
2988 my $column = $i->column;
2989 my $row = $i->row;
2990 my @c = $self->getColumn($column);
2991 my $lastrow = @c - 1;
2992 $row = $row + $delta;
2993 if ($row >= $lastrow) {
2994 $column ++;
2995 $row = 0;
2996 } elsif ($column <= 0) {
2997 $column --;
2998 my @nc = $self->getColumn($column);
2999 $row = @nc - 1;
3000 }
3001 my $target;
3002 my $index = $self->indexColumnRow($column, $row);
3003 $target = $self->getIndex($index) if defined $index;
3004 return $target;
3005 }
3006  
3007 sub moveRow {
3008 my ($self, $delta) = @_;
3009 my $i = $self->anchorGet;
3010 my $column = $i->column;
3011 my $row = $i->row;
3012 my @r = $self->getRow($row);
3013 my $lastcolumn = @r - 1;
3014 $column = $column + $delta;
3015 if ($column >= $lastcolumn) {
3016 $column = 0;
3017 $row ++;
3018 } elsif ($column <= 0) {
3019 $row --;
3020 my @nr = $self->getRow($row);
3021 $column = @nr - 1;
3022 }
3023 my $target;
3024 my $index = $self->indexColumnRow($column, $row);
3025 $target = $self->getIndex($index) if defined $index;
3026 return $target;
3027 }
3028  
3029 sub OnConfigure {
3030 my ($self, $timer) = @_;
3031  
3032 #limit ourself to resize events.
3033 my ($sx, $sy) = $self->geoSave;
3034 my ($x, $y) = $self->canvasSize;
3035 return if ($sx eq $x) and ($sy eq $y);
3036 $self->geoSave($x, $y);
3037  
3038 if (my $id = $self->{'timer_id'}) {
3039 $self->afterCancel($id);
3040 my $nid = $self->after(100, ['OnConfigureTimer', $self]);
3041 $self->{'timer_id'} = $nid;
3042 }
3043  
3044 unless (defined $timer) {
3045 my $id = $self->after(100, ['OnConfigureTimer', $self]);
3046 $self->{'timer_id'} = $id;
3047 return
3048 }
3049  
3050 #catch and clear selection
3051 my @sel = $self->selectionGet;
3052 $self->selectionClear;
3053  
3054 if ($self->listMode) {
3055 $self->headerPlace;
3056 } else {
3057 $self->refreshPurge;
3058 }
3059  
3060 #redraw selection
3061 for (@sel) {
3062 $self->selectionSet($_)
3063 }
3064 }
3065  
3066 sub OnConfigureTimer {
3067 my $self = shift;
3068 delete $self->{'timer_id'};
3069 $self->OnConfigure(1);
3070 }
3071  
3072  
3073  
3074 =item B<open>I<($name)>
3075  
3076 Shows all children of I<$name>. Call I<refresh> or I<refreshPurge> to see your changes.
3077 Only works when I<-arrange> is set to 'tree'.
3078  
3079 =cut
3080  
3081 sub open {
3082 my ($self, $entry) = @_;
3083 return unless $self->cget('-arrange') eq 'tree';
3084 my $i = $self->get($entry);
3085 unless (defined $i) {
3086 croak "Entry $entry not found";
3087 return
3088 }
3089 $i->opened(1);
3090 }
3091  
3092 =item B<openAll>
3093  
3094 Opens all entries.
3095  
3096 =cut
3097  
3098 sub openAll {
3099 my $self = shift;
3100 my @list = $self->infoList;
3101 for (@list) {
3102 $self->open($_) if $self->infoChildren($_);
3103 }
3104 }
3105  
3106 sub pool {
3107 my $self = shift;
3108 $self->{POOL} = shift if @_;
3109 return $self->{POOL}
3110 }
3111  
3112 sub priorityMax {
3113 my $self = shift;
3114 $self->{PRIORITYMAX} = shift if @_;
3115 return $self->{PRIORITYMAX}
3116 }
3117  
3118 sub prioritySection {
3119 my ($self, $priority, $list) = @_;
3120  
3121 my $start;
3122 my $p = $list->[0]->priority;
3123 $start = 0 if $p eq $priority;
3124 return (undef, undef) if $p < $priority; # section not available
3125  
3126 unless (defined $start) {
3127 my $first = 0;
3128 my $last = @$list - 1;
3129 while (not defined $start) {
3130 my $middle = int(($last - $first)/2) + $first;
3131 #$middle is inside or past requested section
3132 if ($list->[$middle]->priority <= $priority) {
3133 $last = $middle
3134 #$middle is before requested section
3135 } elsif ($list->[$middle]->priority > $priority) {
3136 $first = $middle
3137 }
3138 if ($last - $first == 1) {
3139 $start = $last if $list->[$last]->priority == $priority;
3140 $start = $first if $list->[$first]->priority == $priority;
3141 last;
3142 }
3143 }
3144 }
3145  
3146 my $last = @$list - 1;
3147 return ($start, $last) if $priority eq 0;
3148 return ($start, $last) if $priority eq $list->[$last]->priority;
3149
3150 my $first = $start;
3151  
3152 my $end;
3153 while (not defined $end) {
3154 my $middle = int(($last - $first)/2) + $first;
3155 #middle is past requested section
3156 if ($list->[$middle]->priority < $priority) {
3157 $last = $middle
3158 #middle is inside requested section
3159 } elsif ($list->[$middle]->priority == $priority) {
3160 $first = $middle
3161 }
3162 if ($last - $first == 1) {
3163 $end = $first if $list->[$first]->priority == $priority;
3164 $end = $last if $list->[$last]->priority == $priority;
3165 last;
3166 }
3167 }
3168  
3169 return ($start, $end);
3170 }
3171  
3172 sub prioritySet {
3173 my ($self, $priority) = @_;
3174 my $max = $self->priorityMax;
3175 $self->priorityMax($priority) if $max < $priority;
3176 }
3177  
3178 =item B<refresh>I<(?$entrysample?)>
3179  
3180 Clears the canvas and rebuilds it. Call this method if option I<-autorefresh> if not enabled
3181 after you are done making changes.
3182  
3183 If you specify I<$entrsample> it will use it to obtain a cell size unless cell size is known.
3184  
3185 If you do not specify I<$entrysample> and cell size is not known it will try to obtain a cell size
3186 through the sample stored in the option I<-sizesample>.
3187  
3188 If that also fails it will iterate the list to obtain a cell size if cell size is not known.
3189  
3190 After establishing a cell size it calls B<refreshPurge>.
3191  
3192 =cut
3193  
3194 sub refresh {
3195 my ($self, $sizeitem) = @_;
3196  
3197 $self->cellSize($sizeitem) unless $self->cellSizeKnown;
3198  
3199 my $anch = $self->anchorGet;
3200 $self->refreshSaveView;
3201  
3202 $self->refreshPurge;
3203
3204  
3205 $self->refreshRestoreView;
3206 $self->anchorSet($anch) if defined $anch;
3207  
3208 $self->headerPlace if $self->listMode;
3209 }
3210  
3211 sub refreshCheck {
3212 my ($self, $entry, $index) = @_;
3213 return if $entry->noshow;
3214 $self->refreshPurge($index);# if $self->cget('-autorefresh');
3215 }
3216  
3217 sub refreshLoop {
3218 my $self = shift;
3219 my $handler = $self->handler;
3220 my $epc = $self->cget('-refreshentriespercycle');
3221 for (1 .. $epc) {
3222 my $pos = $self->refreshPos;
3223 if ($pos <= $self->indexLast) {
3224 $self->refreshLoopActive(1);
3225 my $entry = $self->getIndex($pos);
3226 unless ($entry->noshow) {
3227 my @params = $self->refreshParams;
3228 my $sel;
3229 my $entry = $self->getIndex($pos);
3230 my $name = $entry->name;
3231 $handler->draw($entry, @params);
3232 @params = $handler->nextPosition(@params);
3233 $self->refreshParams(@params);
3234 }
3235 $pos ++;
3236 $self->refreshPos($pos);
3237 } else {
3238 $self->setScrollRegion;
3239 $self->refreshLoopActive(0);
3240 $self->refreshPos(0);
3241 $self->refreshRestoreView;
3242 if ($self->listMode) {
3243 my $last = $self->infoLastVisible;
3244 my $l = $self->get($last);
3245 }
3246 }
3247 last unless $self->refreshLoopActive;
3248 }
3249 $self->after($self->cget('-refreshinterval'), ['refreshLoop', $self]) if $self->refreshLoopActive;
3250 }
3251  
3252 sub refreshLoopActive {
3253 my $self = shift;
3254 $self->{REFRESHLOOPACTIVE} = shift if @_;
3255 return $self->{REFRESHLOOPACTIVE}
3256 }
3257  
3258 sub refreshParams {
3259 my $self = shift;
3260 $self->{REFRESHPAR} = [@_] if @_;
3261 my $p = $self->{REFRESHPAR};
3262 return @$p
3263 }
3264  
3265 sub refreshPos {
3266 my $self = shift;
3267 $self->{REFRESHPOS} = shift if @_;
3268 return $self->{REFRESHPOS}
3269 }
3270  
3271 =item B<refreshPurge>I<(?$index?, ?$nosave?)>
3272  
3273 Same as refresh, but does not calculate cell sizes. Can be used after
3274 an initializing call to I<refresh> has been made. If you specify I<$index>
3275 the refresh is done from the entry at the index, going downward. It is
3276 operated in a non blocking background job cycle.
3277  
3278 if the I<$nosave> flag is set, the xview and yview of the canvas are not saved
3279 before the refresh starts.
3280  
3281 =cut
3282  
3283 sub refreshPurge {
3284 my ($self, $index, $nosave) = @_;
3285  
3286 return if $self->pool->size eq 0;
3287  
3288 $index = 0 unless defined $index;
3289 my $pos = $self->refreshPos;
3290 return if ($index > $pos) and $self->refreshLoopActive;
3291  
3292 $nosave = 0 unless defined $nosave;
3293 if ($nosave) {
3294 $self->refreshView(undef, undef);
3295 } else {
3296 $self->refreshSaveView;
3297 }
3298  
3299 #clear from index
3300 my $last = $self->indexLast;
3301 for ($index .. $last) {
3302 my $entry = $self->getIndex($_);
3303 $entry->clear;
3304 }
3305 return if $index > $last;
3306  
3307 my $handler = $self->handler;
3308 my $entry = $self->getIndex($index);
3309 my ($x, $y) = $handler->startXY;
3310 my @params = ($x, $y, 0 , 0);
3311 my $prev = $self->infoPrevVisible($entry->name);
3312 if (defined $prev) {
3313 my $p = $self->get($prev);
3314 @params = ($p->rectX, $p->rectY, $p->column, $p->row);
3315 @params = $handler->nextPosition(@params);
3316 $params[0] = $x if $self->listMode;
3317 }
3318 push @params, $entry if $entry->selected;
3319 $self->refreshParams(@params);
3320 $self->refreshPos($index);
3321 unless ($self->refreshLoopActive) {
3322 $self->refreshLoopActive(1);
3323 $self->after($self->cget('-refreshinterval'), ['refreshLoop', $self])
3324 }
3325 }
3326  
3327 sub refreshRestoreView {
3328 my $self = shift;
3329 my $c = $self->Subwidget('Canvas');
3330 my ($xview, $yview) = $self->refreshView;
3331 $c->xview(moveto => $xview) if defined $xview;
3332 $c->yview(moveto => $yview) if defined $yview;
3333 }
3334  
3335 sub refreshSaveView {
3336 my $self = shift;
3337 my $c = $self->Subwidget('Canvas');
3338 my ($xview) = $c->xview;
3339 my ($yview) = $c->yview;
3340 $self->refreshView($xview, $yview);
3341 }
3342  
3343 =item B<refreshSingle>I<($entry)>
3344  
3345 Refreshes a single entry.
3346  
3347 =cut
3348  
3349 sub refreshSingle {
3350 my ($self, $entry) = @_;
3351 my $e = $self->get($entry);
3352 unless (defined $e) {
3353 croak "Entry '$entry' does not exist";
3354 return
3355 }
3356  
3357 my $x = $e->rectX;
3358 if ($self->cget('-arrange') eq 'tree') {
3359 $x = $x - $self->cget('-indent');
3360 }
3361 my $y = $e->rectY;
3362 my $c = $e->column;
3363 my $r = $e->row;
3364 $e->clear;
3365 $self->handler->draw($e, $x, $y, $c, $r);
3366 }
3367  
3368 sub refreshView {
3369 my $self = shift;
3370 $self->{REFRESHVIEW} = [@_] if @_;
3371 my $v = $self->{REFRESHVIEW};
3372 return @$v
3373 }
3374  
3375 =item B<see>I<($name)>
3376  
3377 Scrolls the canvas to make I<$name> visible if it is not, or not completely, visible.
3378  
3379 =cut
3380  
3381 sub see {
3382 my ($self, $name) = @_;
3383  
3384 my $scrollregion = $self->cget('-scrollregion');
3385 return unless @$scrollregion;
3386  
3387 my ($cx1, $cy1, $cx2, $cy2) = @$scrollregion; #the canvas
3388 my $i = $self->get($name);
3389 my ($cwidth, $cheight) = $self->canvasSize;
3390 my ($ix1, $iy1, $ix2, $iy2) = $i->region;
3391  
3392 my $h = $self->handler;
3393 #horizontal
3394 if ($h->scroll eq 'horizontal') {
3395 my ($vl, $vr) = $self->xview;
3396 my $div = $cx2 - $cx1;
3397 if (($div > 0) and ($ix1/$div < $vl)) { #going to the left
3398 $self->xview(moveto => $ix1/$div);
3399 } elsif (($div > 0) and ($ix2/$div > $vr)) { #going to the right.
3400 my $mr = ($ix2 - $cwidth + 2)/$div;
3401 $self->xview(moveto => $mr);
3402 }
3403 }
3404
3405 #vertical
3406 if ($h->scroll eq 'vertical') {
3407 my ($vt, $vb) = $self->yview;
3408 my $div = $cy2 - $cy1;
3409 if ($self->headerAvailable) {
3410 $iy1 = $iy1 - $self->cget('-headerheight')
3411 }
3412 if (($div > 0) and ($iy1/$div < $vt)) { #going up
3413 $self->yview(moveto => $iy1/$div);
3414 } elsif (($div > 0) and ($iy2/$div > $vb)){ #going down.
3415 my $mr = ($iy2 - $cheight + 2)/$div;
3416 $self->yview(moveto => $mr);
3417 }
3418 }
3419 }
3420  
3421 =item B<selectAll>
3422  
3423 Selects all entries.
3424  
3425 =cut
3426  
3427 sub selectAll {
3428 my $self = shift;
3429 return if $self->cget('-selectmode') eq 'single';
3430 my @pool = $self->getAll;
3431 grep { $_->select } @pool;
3432 }
3433  
3434 =item B<selectionClear>
3435  
3436 Clears the entire selection.
3437  
3438 =cut
3439  
3440 sub selectionClear {
3441 my $self = shift;
3442 my @pool = $self->getAll;
3443 grep { $_->select(0) } @pool;
3444 my $c = $self->Subwidget('Canvas');
3445 # $c->delete('sel'); #workaround
3446 }
3447  
3448 sub selectionClearChildren {
3449 my ($self, $entry) = @_;
3450 my @c = $self->getChildren($entry);
3451 for (@c) {
3452 $_->select(0);
3453 $self->selectionClearChildren($_->name);
3454 }
3455 }
3456  
3457 sub selectionFlip {
3458 my ($self, $begin, $end) = @_;
3459 return if $self->cget('-selectmode') eq 'exclusive';
3460 ($begin, $end) = $self->selectionIndex($begin, $end);
3461 for ($begin .. $end) {
3462 my $i = $self->getIndex($_);
3463 if ($i->selected) {
3464 $self->selectionClear if $self->cget('-selectmode') eq 'single';
3465 $i->select(0);
3466 } else {
3467 $self->selectionClear if $self->cget('-selectmode') eq 'single';
3468 $i->select;
3469 }
3470 }
3471 }
3472  
3473 =item B<selectionGet>
3474  
3475 Returns a list of entry names contained in the selection.
3476  
3477 =cut
3478  
3479 sub selectionGet {
3480 my $self = shift;
3481 my @list;
3482 my @pool = $self->getAll;
3483 for (@pool) { push @list, $_->name if $_->selected }
3484 return @list;
3485 }
3486  
3487 sub selectionIndex {
3488 my ($self, $begin, $end) = @_;
3489 $end = $begin unless defined $end;
3490 $begin = $self->index($begin);
3491 $end = $self->index($end);
3492 if ($begin > $end) {
3493 my $t = $begin;
3494 $begin = $end;
3495 $end = $t;
3496 }
3497 return ($begin, $end)
3498 }
3499  
3500 =item B<selectionSet>I<($begin, ?$end?)>
3501  
3502 Selects entry I<$begin>. If you specify I<$end> the
3503 range from I<$begin> to I<$end> will be selected.
3504  
3505 =cut
3506  
3507 sub selectionSet {
3508 my ($self, $begin, $end) = @_;
3509 if (($self->cget('-selectmode') eq 'single') or ($self->cget('-selectmode') eq 'exclusive')) {
3510 $self->selectionSingle($begin);
3511 } else {
3512 ($begin, $end) = $self->selectionIndex($begin, $end);
3513 my @pool = $self->getAll;
3514 for ($begin .. $end) {
3515 my $i = $pool[$_];
3516 $i->select(1) unless $i->noshow;
3517 }
3518 }
3519 }
3520  
3521 sub selectionSingle {
3522 my ($self, $name) = @_;
3523 my $index = $self->index($name);
3524 $self->selectionClear;
3525 $self->getIndex($index)->select(1);
3526 }
3527  
3528 =item B<selectionUnSet>I<($begin, $end)>
3529  
3530 Clears the selection of entry I<$begin>. If you specify I<$end> the
3531 range from I<$begin> to I<$end> will be cleared from the selection.
3532  
3533 =cut
3534  
3535 sub selectionUnSet {
3536 my ($self, $begin, $end) = @_;
3537 $end = $begin unless defined $end;
3538 ($begin, $end) = $self->selectionIndex($begin, $end);
3539 my @pool = $self->getAll;
3540 for ($begin .. $end) {
3541 my $i = $pool[$_];
3542 $i->select(0) unless $i->hidden;
3543 }
3544 }
3545  
3546 sub separator { return $_[0]->cget('-separator') }
3547  
3548 sub setScrollRegion {
3549 my $self = shift;
3550 my $canvas = $self->Subwidget('Canvas');
3551  
3552 #getting coordinates
3553 my ($d1, $d2, $x, $y) = $canvas->bbox("all");
3554 $x = 0 unless defined $x;
3555 $y = 0 unless defined $y;
3556 $x = $x + $self->cget('-marginright');
3557 $y = $y + $self->cget('-marginbottom');
3558 $self->lastScrollRegion($x, $y);
3559  
3560 #preventing the mouse wheel from scrolling the list when there are no scrollbars.
3561 my ($sx, $sy) = $self->canvasSize;
3562 $sy ++;
3563 # $x = 20 if $x < $sx;
3564 $y = $sy if $y < $sy;
3565  
3566 $self->configure(-scrollregion => [0, 0, $x, $y]);
3567 }
3568  
3569 =item B<show>I<($name)>
3570  
3571 Shows entry I<$name>. Call I<refresh> to see changes.
3572  
3573 =cut
3574  
3575 sub show {
3576 my ($self, $name) = @_;
3577 my $a = $self->get($name);
3578 return unless defined $a;
3579 $a->hidden(0);
3580 }
3581  
3582 sub sizesample {
3583 my $self = shift;
3584 if (@_) {
3585 $self->{SIZESAMPLE} = shift;
3586 $self->cellSizeKnown(0);
3587 }
3588 return $self->{SIZESAMPLE}
3589 }
3590  
3591  
3592 sub sortActive {
3593 my $self = shift;
3594 $self->{SORTACTIVE} = shift if @_;
3595 return $self->{SORTACTIVE}
3596 }
3597  
3598 sub sortArray {
3599 my $self = shift;
3600 my @pool = @_;
3601 $self->sortActive(1);
3602 my $on = $self->cget('-sorton');
3603 my $order = $self->cget('-sortorder');;
3604 my $col;
3605 if ($on eq '') {
3606 $col = $self
3607 } else {
3608 $col = $self->columnGet($on);
3609 }
3610 my ($numsort, $sortcase, $sortfield);
3611 $numsort = $col->cget('-sortnumerical');
3612 $sortcase = $col->cget('-sortcase');
3613 $sortfield = $col->cget('-sortfield');
3614
3615 my @sorted;
3616 if ($on eq '') {
3617 if ($numsort) {
3618 if ($order eq 'ascending') {
3619 @sorted = sort { $self->entryCget($a->name, $sortfield) <=> $self->entryCget($b->name, $sortfield) } @pool
3620 } else {
3621 @sorted = sort { $self->entryCget($b->name, $sortfield) <=> $self->entryCget($a->name, $sortfield) } @pool
3622 }
3623 } else {
3624 if ($sortcase) {
3625 if ($order eq 'ascending') {
3626 @sorted = sort { $self->entryCget($a->name, $sortfield) cmp $self->entryCget($b->name, $sortfield) } @pool
3627 } else {
3628 @sorted = sort { $self->entryCget($b->name, $sortfield) cmp $self->entryCget($a->name, $sortfield) } @pool
3629 }
3630 } else {
3631 if ($order eq 'ascending') {
3632 @sorted = sort { lc($self->entryCget($a->name, $sortfield)) cmp lc($self->entryCget($b->name, $sortfield)) } @pool
3633 } else {
3634 @sorted = sort { lc($self->entryCget($b->name, $sortfield)) cmp lc($self->entryCget($a->name, $sortfield)) } @pool
3635 }
3636 }
3637 }
3638 } else {
3639 if ($numsort) {
3640 if ($order eq 'ascending') {
3641 @sorted = sort { $self->itemCget($a->name, $on, $sortfield) <=> $self->itemCget($b->name, $on, $sortfield) } @pool
3642 } else {
3643 @sorted = sort { $self->itemCget($b->name, $on, $sortfield) <=> $self->itemCget($a->name, $on, $sortfield) } @pool
3644 }
3645 } else {
3646 if ($sortcase) {
3647 if ($order eq 'ascending') {
3648 @sorted = sort { $self->itemCget($a->name, $on, $sortfield) cmp $self->itemCget($b->name, $on, $sortfield) } @pool
3649 } else {
3650 @sorted = sort { $self->itemCget($b->name, $on, $sortfield) cmp $self->itemCget($a->name, $on, $sortfield) } @pool
3651 }
3652 } else {
3653 if ($order eq 'ascending') {
3654 @sorted = sort { lc($self->itemCget($a->name, $on, $sortfield)) cmp lc($self->itemCget($b->name, $on, $sortfield)) } @pool
3655 } else {
3656 @sorted = sort { lc($self->itemCget($b->name, $on, $sortfield)) cmp lc($self->itemCget($a->name, $on, $sortfield)) } @pool
3657 }
3658 }
3659 }
3660 }
3661 $self->sortActive('');
3662 return @sorted
3663 }
3664  
3665 =item B<sortList>
3666  
3667 Sorts the list and refreshes the display. Make a call to I<sortMode> first
3668 to specify how to sort or configure the options I<-sorton> and I<sortorder>.
3669  
3670 =cut
3671  
3672 sub sortList {
3673 my $self = shift;
3674 my $sorted = new Tk::ListBrowser::HashList;
3675 $self->clear;
3676 if ($self->hierarchy) {
3677 my @root = $self->getRoot;
3678 for (reverse 0 .. $self->priorityMax) {
3679 my $pr = $_;
3680 my @p = grep { $_->priority eq $pr} @root;
3681 @p = $self->sortArray(@p);
3682 for (@p) { $self->sortRecursive($_, $sorted) }
3683 }
3684 } else {
3685 my @all = $self->getAll;
3686 for (reverse 0 .. $self->priorityMax) {
3687 my $pr = $_;
3688 my @p = grep { $_->priority eq $pr} @all;
3689 @p = $self->sortArray(@p);
3690 for (@p) { $sorted->add($_) }
3691 }
3692 }
3693 $self->pool($sorted);
3694 $self->refresh;
3695 }
3696  
3697 =item B<sortMode>I<($column, $order)>
3698  
3699 Specify on which column to sort with I<$column>.
3700 I<$order> can be 'ascending' or 'descending'.
3701 This method changes the options I<-sorton> and I<-sortorder>.
3702 It is called after a mouse click on a sortable header.
3703  
3704 Specify $column as an empty string for the main list. Otherwise specify a column name.
3705  
3706 =cut
3707  
3708 sub sortMode {
3709 my ($self, $column, $order) = @_;
3710 $self->configure(-sorton => $column);
3711 $self->configure(-sortorder => $order);
3712 for ('', $self->columnList) {
3713 my $name = $_;
3714 my $widget = $self->headerGet($name);
3715 if ($name eq $column) {
3716 $widget->configure('-sortorder', $order);
3717 } else {
3718 $widget->configure('-sortorder', 'none');
3719 }
3720 }
3721 }
3722  
3723 sub sortRecursive {
3724 my ($self, $item, $sorted) = @_;
3725 $sorted->add($item);
3726 my @children = $self->getChildren($item->name);
3727 for (reverse 0 .. $self->priorityMax) {
3728 my $pr = $_;
3729 my @p = grep { $_->priority eq $pr} @children;
3730 @p = $self->sortArray(@p);
3731 for (@p) {
3732 $self->sortRecursive($_, $sorted)
3733 }
3734 }
3735 return $sorted
3736 }
3737  
3738 sub wraplength {
3739 my $self = shift;
3740 if (@_) {
3741 my $l = shift;
3742 if ($l > 0) {
3743 $l = 40 if $l < 40;
3744 }
3745 $self->{WRAPLENGTH} = $l;
3746 }
3747 return $self->{WRAPLENGTH}
3748 }
3749  
3750 sub xScrollCheck {
3751 my ($self, $fr1, $fr2) = @_;
3752 if ($self->listMode) {
3753 my @sel = $self->selectionGet;
3754 for (@sel) {
3755 $self->refreshSingle($_)
3756 }
3757 $self->anchorRefresh;
3758 }
3759 }
3760  
3761 =back
3762  
3763 =head1 CELL SIZE AND REFRESH
3764  
3765 Before we can meaningfully display the list we need to know the cell size
3766 of our entries. Below some considerations and strategies.
3767  
3768 =head3 All cells have equal size
3769  
3770 This is a basic principle. Only if cells have identical sizes the I<column> and I<row>
3771 arrange modes can work. In list modes the cell width is less relevant.
3772  
3773 If you have side columns configured, their cell height is determined by their owning entry. You may
3774 want to configure the columns cell width by calling B<cellSizeColumns> at some point. However, if you
3775 have configured headers, the cell width is governed by them and you do not need to bother.
3776  
3777 Below some ways to obtain your cell size.
3778  
3779 =head3 Configure manually
3780  
3781 We highly advise against doing it this way. However, if you must...
3782  
3783 You can manually calculate all the values and set the config variables
3784 I<-cellheight>, I<-cellimageheight>, I<-cellimagewidth>, I<-celltextheight>,
3785 I<-celltextwidth> and I<-cellwidth> yourself. After that you can safely call B<refreshPurge>.
3786  
3787 If you do it this way, do not forget to set B<cellSizeKnown> to 1.
3788  
3789 =head3 Do nothing
3790  
3791 Just call B<refresh>. It will iterate over the list and obtain a cell size the first time you call it.
3792 It will skip that step each time you call it afterward, untill you clear B<cellSizeKnown>.
3793 The first time you call B<refresh> is expensive, but it gives a cell size that is guaranteed to fit
3794 every entry.
3795  
3796 =head3 Set a sample
3797  
3798 Create an entry class object (Tk::ListBrowser::Entry unless you derieved your own). Make it have an image at
3799 least as large as the largest image in your list and a text at least as long as any text in your list.
3800 Assign it to the config variable I<-sizesample> or use it as a parameter to the B<refresh> method.
3801  
3802 my $e = new Tk::ListBrowser::Entry(
3803 -name => 'sample',
3804 -listbrowser => $lb, #reference to a Tk::ListBrowser object
3805 -text => 'A darn long string, possibly multiline',
3806 -image => $tkimage,
3807 );
3808 $lb->configure(-sizesample => $e);
3809 #or
3810 $lb->refresh($e);
3811  
3812 =head3 Adding and deleting entries.
3813  
3814 If you want the cell size recalculated every time you add or delete content, do the following.
3815  
3816 $lb->add($name, @options);
3817 $lb->cellSizeKnown(0);
3818 #or
3819 $lb->insert($entryobj, $index);
3820 $lb->cellSizeKnown(0);
3821 #or
3822 $lb->delete($name);
3823 $lb->cellSizeKnown(0);
3824  
3825 =head3 Using -autorefresh
3826  
3827 When -autorefresh is active a B<refreshPurge> is initiated after every addition or deletion.
3828 It totally assumes cell size is known. So you better take care of that before you add or
3829 remove anything.
3830  
3831 =head1 USING THE KEYBOARD
3832  
3833 Before you can manipulate the list using the keyboard, the anchor must be initialized first. You do
3834 that by pressing any of the navigation keys. After that you can start navigating and manipulate selections.
3835  
3836 The spacebar selects or deselects the entry that is currently held by the anchor. The I<-browsecmd>
3837 callback is called if the entry is selected.
3838  
3839 The return key selects the entry and invokes the I<-command> callback.
3840  
3841 You can navigate the list using the arrow keys and the the Home, Control-Home, End and Control-End keys.
3842 Holding shift while pressing these keys manipulates the selection.
3843  
3844 The escape key clears the selection and anchor or hides the filter entry if it is visible.
3845  
3846 CTRL+F pops a filter entry. Clicking CTRL+F again hides it. Filtering is done instantly upon entering
3847 text. This is influenced by the I<-filterforce> and I<-nofilter> options.
3848  
3849 =head1 USING THE MOUSE
3850  
3851 Clicking an entry with the left button selects it and assigns the anchor to it. Shift-click manipulates
3852 the selection of the range from the entry that holds the anchor to the one you click. Control-click
3853 selects or deselects the entry.
3854  
3855 You can drag-scroll the list by moving you mouse while holding the middle button pressed.
3856  
3857 =head1 LICENSE
3858  
3859 Same as Perl.
3860  
3861 =head1 AUTHOR
3862  
3863 Hans Jeuken (hanje at cpan dot org)
3864  
3865 =head1 TODO
3866  
3867 =head1 BUGS AND CAVEATS
3868  
3869 Setting a custom font greatly decreases the speed of refresh.
3870  
3871 This list module is suitable for small to medium size lists, like a couple of hundreds of entries.
3872 If you have a large list, adding and deleting entries will take longer. It has to rebuild it's
3873 index everytime for the remainder of the list. This affects adding and deleting at the beginning
3874 of the list more than near the end of the list. The plus size of this is when the index has been built,
3875 looking up entries is blazingly fast, also on large lists.
3876  
3877 If you find any bugs, please report them here: L<https://github.com/haje61/Tk-ListBrowser/issues>.
3878  
3879 =head1 SEE ALSO
3880  
3881 =over 4
3882  
3883 =item L<Tk::ListBrowser::Entry>
3884  
3885 =item L<Tk::ListBrowser::Item>
3886  
3887 =item L<Tk::ListBrowser::SideColumn>
3888  
3889 =back
3890  
3891 =cut
3892  
3893 1;