1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
NAME
Tickit::Widget::ScrollBox - allow a single child widget to be scrolled
SYNOPSIS
use Tickit;
use Tickit::Widget::ScrollBox;
use Tickit::Widget::Static;
my $scrollbox = Tickit::Widget::ScrollBox->new
->set_child( Tickit::Widget::Static->new(
text => join( "\n", map { "The content for line $_" } 1 .. 100 ),
) );
Tickit->new( root => $scrollbox )->run;
DESCRIPTION
This container widget draws a scrollbar beside a single child widget
and allows a portion of it to be displayed by scrolling.
STYLE
Th following style pen prefixes are used:
scrollbar => PEN
The pen used to render the background of the scroll bar
scrollmark => PEN
The pen used to render the active scroll position in the scroll bar
arrow => PEN
The pen used to render the scrolling arrow buttons
The following style keys are used:
arrow_up => STRING
arrow_down => STRING
arrow_left => STRING
arrow_right => STRING
Each should be a single character to use for the scroll arrow
buttons.
The following style actions are used:
up_1 (<Up>)
down_1 (<Down>)
left_1 (<Left>)
right_1 (<Right>)
Scroll by 1 line
up_half (<PageUp>)
down_half (<PageDown>)
left_half (<C-Left>)
right_half (<C-Right>)
Scroll by half of the viewport
to_top (<C-Home>)
to_bottom (<C-End>)
to_leftmost (<Home>)
to_rightmost (<End>)
Scroll to the edge of the area
CONSTRUCTOR
new
$scrollbox = Tickit::Widget::ScrollBox->new( %args )
Constructs a new Tickit::Widget::ScrollBox object.
Takes the following named arguments in addition to those taken by the
base Tickit::SingleChildWidget constructor:
vertical => BOOL or "on_demand"
horizontal => BOOL or "on_demand"
Whether to apply a scrollbar in the vertical or horizontal
directions. If not given, these default to vertical only.
If given as the string on_demand then the scrollbar will be
optionally be displayed only if needed; if the space given to the
widget is smaller than the child content necessary to display.
ACCESSORS
vextent
$vextent = $scrollbox->vextent
Returns the Tickit::Widget::ScrollBox::Extent object representing the
box's vertical scrolling extent.
hextent
$hextent = $scrollbox->hextent
Returns the Tickit::Widget::ScrollBox::Extent object representing the
box's horizontal scrolling extent.
METHODS
scroll
$scrollbox->scroll( $downward, $rightward )
Requests the content be scrolled downward a number of lines and
rightward a number of columns (either of which which may be negative).
scroll_to
$scrollbox->scroll_to( $top, $left )
Requests the content be scrolled such that the given line and column
number of the child's content is the topmost visible in the container.
SMART SCROLLING
If the child widget declares it supports smart scrolling, then the
ScrollBox will not implement content scrolling on its behalf. Extra
methods are used to co-ordinate the scroll position between the
scrolling-aware child widget and the containing ScrollBox. This is
handled by the following methods on the child widget.
If smart scrolling is enabled for the child, then its window will be
set to the viewport directly, and the child widget must offset its
content within the window as appropriate. The child must indicate the
range of its scrolling ability by using the set_total method on the
extent object it is given.
$smart = $child->CAN_SCROLL
If this method exists and returns a true value, the ScrollBox will use
smart scrolling. This method must return a true value for this to work,
allowing the method to itself be a proxy, for example, to proxy
scrolling information through a single child widget container.
$child->set_scrolling_extents( $vextent, $hextent )
Gives the child widget the vertical and horizontal scrolling extents.
The child widget should save thes values, and inspect the start value
of them any time it needs these to implement content offset position
when rendering.
$child->scrolled( $downward, $rightward, $h_or_v )
Informs the child widget that one of the scroll positions has changed.
It passes the delta (which may be negative) of each position, and a
string which will be either "h" or "v" to indicate whether it was an
adjustment of the horizontal or vertical scrollbar. The extent objects
will already have been updated by this point, so the child may also
inspect the start value of them to obtain the new absolute offsets.
TODO
* Choice of left/right and top/bottom bar positions.
* Click-and-hold on arrow buttons for auto-repeat
* Allow smarter cooperation with a scrolling-aware child widget;
likely by setting extent objects on the child if it declares to be
supported, and use that instead of an offset child window.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>
|
