Debian Codegraph @

README

raw
1 NAME
2
3 Tickit::Widget::Scroller - a widget displaying a scrollable collection
4 of items
5
6 SYNOPSIS
7
8 use Tickit;
9 use Tickit::Widget::Scroller;
10 use Tickit::Widget::Scroller::Item::Text;
11
12 my $tickit = Tickit->new;
13
14 my $scroller = Tickit::Widget::Scroller->new;
15
16 $scroller->push(
17 Tickit::Widget::Scroller::Item::Text->new( "Hello world" ),
18 Tickit::Widget::Scroller::Item::Text->new( "Here are some lines" ),
19 map { Tickit::Widget::Scroller::Item::Text->new( "<Line $_>" ) } 1 .. 50,
20 );
21
22 $tickit->set_root_widget( $scroller );
23
24 $tickit->run
25
26 DESCRIPTION
27
28 This class provides a widget which displays a scrollable list of items.
29 The view of the items is scrollable, able to display only a part of the
30 list.
31
32 A Scroller widget stores a list of instances implementing the
33 Tickit::Widget::Scroller::Item interface.
34
35 STYLE
36
37 The default style pen is used as the widget pen.
38
39 The following style pen prefixes are used:
40
41 indicator => PEN
42
43 The pen used for the scroll position indicators at the top or bottom
44 of the display
45
46 KEYBINDINGS
47
48 The following keys are bound
49
50 * Down
51
52 Scroll one line down
53
54 * Up
55
56 Scroll one line up
57
58 * PageDown
59
60 Scroll half a window down
61
62 * PageUp
63
64 Scroll half a window up
65
66 * Ctrl-Home
67
68 Scroll to the top
69
70 * Ctrl-End
71
72 Scroll to the bottom
73
74 CONSTRUCTOR
75
76 new
77
78 $scroller = Tickit::Widget::Scroller->new( %args )
79
80 Constructs a new Tickit::Widget::Scroller object. The new object will
81 start with an empty list of items.
82
83 Takes the following named arguments:
84
85 gravity => STRING
86
87 Optional. If given the value bottom, resize events and the push
88 method will attempt to preserve the item at the bottom of the screen.
89 Otherwise, will preserve the top.
90
91 gen_top_indicator => CODE
92
93 gen_bottom_indicator => CODE
94
95 Optional. Generator functions for the top and bottom indicators. See
96 also set_gen_top_indicator and set_gen_bottom_indicator.
97
98 METHODS
99
100 on_scrolled
101
102 set_on_scrolled
103
104 $on_scrolled = $scroller->on_scrolled;
105
106 $scroller->set_on_scrolled( $on_scrolled );
107
108 Return or set the CODE reference to be called when the scroll position
109 is adjusted.
110
111 $on_scrolled->( $scroller, $delta );
112
113 This is invoked by the scroll method, including the scroll_to,
114 scroll_to_top and scroll_to_bottom. In normal cases it will be given
115 the delta offset that scroll itself was invoked with, though this may
116 be clipped if this would scroll past the beginning or end of the
117 display.
118
119 items
120
121 $count = $scroller->items;
122
123 Since version 0.31.
124
125 In scalar context, returns the number of items currently stored in the
126 Scroller. The behaviour of this method in non-scalar context is
127 currently unspecified.
128
129 push
130
131 $scroller->push( @items );
132
133 Append the given items to the end of the list.
134
135 If the Scroller is already at the tail (that is, the last line of the
136 last item is on display) and the gravity mode is bottom, the newly
137 added items will be displayed, possibly by scrolling downward if
138 required. While the scroller isn't adjusted by using any of the scroll
139 methods, it will remain following the tail of the items, scrolling
140 itself downwards as more are added.
141
142 unshift
143
144 $scroller->unshift( @items );
145
146 Prepend the given items to the beginning of the list.
147
148 If the Scroller is already at the head (that is, the first line of the
149 first item is on display) and the gravity mode is top, the newly added
150 items will be displayed, possibly by scrolling upward if required.
151 While the scroller isn't adjusted by using any of the scroll methods,
152 it will remain following the head of the items, scrolling itself
153 upwards as more are added.
154
155 shift
156
157 @items = $scroller->shift( $count );
158
159 Remove the given number of items from the start of the list and returns
160 them.
161
162 If any of the items are on display, the Scroller will be scrolled
163 upwards an amount sufficient to close the gap, ensuring the first
164 remaining item is now at the top of the display.
165
166 The returned items may be re-used by adding them back into the scroller
167 again either by push or unshift, or may be discarded.
168
169 pop
170
171 @items = $scroller->pop( $count );
172
173 Remove the given number of items from the end of the list and returns
174 them.
175
176 If any of the items are on display, the Scroller will be scrolled
177 downwards an amount sufficient to close the gap, ensuring the last
178 remaining item is now at the bottom of the display.
179
180 The returned items may be re-used by adding them back into the scroller
181 again either by push or unshift, or may be discarded.
182
183 scroll
184
185 $scroller->scroll( $delta );
186
187 Move the display up or down by the given $delta amount; with positive
188 moving down. This will be a physical count of displayed lines; if some
189 items occupy multiple lines, then fewer items may be scrolled than
190 lines.
191
192 scroll_to
193
194 $scroller->scroll_to( $line, $item_or_idx, $itemline );
195
196 Moves the display up or down so that display line $line contains line
197 $itemline of the item; which may be given by object reference or index
198 number. Any of these counts may be negative to count backwards from the
199 display lines, items, or lines within the item.
200
201 scroll_to_top
202
203 $scroller->scroll_to_top( $item_or_idx, $itemline );
204
205 Shortcut for scroll_to to set the top line of display; where $line is
206 0. If $itemline is undefined, it will be passed as 0. If $item_or_idx
207 is also undefined, it will be passed as 0. Calling this method with no
208 arguments, therefore scrolls to the very top of the display.
209
210 scroll_to_bottom
211
212 $scroller->scroll_to_bottom( $item_or_idx, $itemline );
213
214 Shortcut for scroll_to to set the bottom line of display; where $line
215 is -1. If $itemline is undefined, it will be passed as -1. If
216 $item_or_idx is also undefined, it will be passed as -1. Calling this
217 method with no arguments, therefore scrolls to the very bottom of the
218 display.
219
220 scroll_to_visible
221
222 $scroller->scroll_to_visible( $item_or_idx, $itemline, %opts );
223
224 Since version 0.33.
225
226 If the requested line of the requested item is already visible on the
227 display, this method does nothing. Otherwise, it scrolls up or down by
228 the smallest amount possible so that it becomes visible. If the line
229 was previously above then it scrolls just sufficient to bring that line
230 to the top-most of the display. If it was below, it scrolls to bring it
231 to the bottom-most.
232
233 If the optional margin named argument it set to a value larger than
234 zero, it causes that number of the top-most and bottom-most lines not
235 to count for purposes of visibility or scrolling.
236
237 line2item
238
239 $itemidx = $scroller->line2item( $line );
240
241 ( $itemidx, $itemline ) = $scroller->line2item( $line );
242
243 Returns the item index currently on display at the given line of the
244 window. In list context, also returns the line number within item. If
245 no window has been set, or there is no item on display at that line,
246 undef or an empty list are returned. $line may be negative to count
247 backward from the last line on display; the last line taking -1.
248
249 item2line
250
251 $line = $scroller->item2line( $item_or_idx, $itemline );
252
253 ( $line, $offscreen ) = $scroller->item2line( $item_or_idx, $itemline, $count_offscreen );
254
255 Returns the display line in the window of the given line of the item at
256 the given index. $item_or_idx may be an item directly, a non-negative
257 integer to give its index, or a negative to count backwards from the
258 last item. $itemline may be negative to count backward from the last
259 line of the item.
260
261 In list context, also returns a value describing the offscreen nature
262 of the item. For items fully on display, this value is undef. If the
263 given line of the given item is not on display because it is scrolled
264 off either the top or bottom of the window, this value will be either
265 "above" or "below" respectively. If $count_offscreen is true, then the
266 returned $line value will always be defined, even if the item line is
267 offscreen. This will be negative for items "above", and a value equal
268 or greater than the number of lines in the scroller's window for items
269 "below".
270
271 lines_above
272
273 $count = $scroller->lines_above;
274
275 Returns the number of lines of content above the scrolled display.
276
277 lines_below
278
279 $count = $scroller->lines_below;
280
281 Returns the number of lines of content below the scrolled display.
282
283 set_gen_top_indicator
284
285 set_gen_bottom_indicator
286
287 $scroller->set_gen_top_indicator( $method );
288
289 $scroller->set_gen_bottom_indicator( $method );
290
291 Accessors for the generators for the top and bottom indicator text. If
292 set, each should be a CODE reference or method name on the scroller
293 which will be invoked after any operation that changes the contents of
294 the window, such as scrolling or adding or removing items. It should
295 return a text string which, if defined and non-empty, will be displayed
296 in an indicator window. This will be a small one-line window displayed
297 at the top right or bottom right corner of the Scroller's window.
298
299 $text = $scroller->$method();
300
301 The ability to pass method names allows subclasses to easily implement
302 custom logic as methods without having to capture a closure.
303
304 update_indicators
305
306 $scroller->update_indicators;
307
308 Calls any defined generators for indicator text, and updates the
309 indicator windows with the returned text. This may be useful if the
310 functions would return different text now.
311
312 TODO
313
314 * Abstract away the "item storage model" out of the actual widget.
315 Implement more storage models, such as database-driven ones.. more
316 dynamic.
317
318 AUTHOR
319
320 Paul Evans <[email protected]>
321