.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Tickit::Widget::ScrollBox 3pm" .TH Tickit::Widget::ScrollBox 3pm "2022-12-17" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" "Tickit::Widget::ScrollBox" \- allow a single child widget to be scrolled .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& use Tickit; \& use Tickit::Widget::ScrollBox; \& use Tickit::Widget::Static; \& \& my $scrollbox = Tickit::Widget::ScrollBox\->new \& \->set_child( Tickit::Widget::Static\->new( \& text => join( "\en", map { "The content for line $_" } 1 .. 100 ), \& ) ); \& \& Tickit\->new( root => $scrollbox )\->run; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This container widget draws a scrollbar beside a single child widget and allows a portion of it to be displayed by scrolling. .SH "STYLE" .IX Header "STYLE" Th following style pen prefixes are used: .IP "scrollbar => \s-1PEN\s0" 4 .IX Item "scrollbar => PEN" The pen used to render the background of the scroll bar .IP "scrollmark => \s-1PEN\s0" 4 .IX Item "scrollmark => PEN" The pen used to render the active scroll position in the scroll bar .IP "arrow => \s-1PEN\s0" 4 .IX Item "arrow => PEN" The pen used to render the scrolling arrow buttons .PP The following style keys are used: .IP "arrow_up => \s-1STRING\s0" 4 .IX Item "arrow_up => STRING" .PD 0 .IP "arrow_down => \s-1STRING\s0" 4 .IX Item "arrow_down => STRING" .IP "arrow_left => \s-1STRING\s0" 4 .IX Item "arrow_left => STRING" .IP "arrow_right => \s-1STRING\s0" 4 .IX Item "arrow_right => STRING" .PD Each should be a single character to use for the scroll arrow buttons. .PP The following style actions are used: .IP "up_1 ()" 4 .IX Item "up_1 ()" .PD 0 .IP "down_1 ()" 4 .IX Item "down_1 ()" .IP "left_1 ()" 4 .IX Item "left_1 ()" .IP "right_1 ()" 4 .IX Item "right_1 ()" .PD Scroll by 1 line .IP "up_half ()" 4 .IX Item "up_half ()" .PD 0 .IP "down_half ()" 4 .IX Item "down_half ()" .IP "left_half ()" 4 .IX Item "left_half ()" .IP "right_half ()" 4 .IX Item "right_half ()" .PD Scroll by half of the viewport .IP "to_top ()" 4 .IX Item "to_top ()" .PD 0 .IP "to_bottom ()" 4 .IX Item "to_bottom ()" .IP "to_leftmost ()" 4 .IX Item "to_leftmost ()" .IP "to_rightmost ()" 4 .IX Item "to_rightmost ()" .PD Scroll to the edge of the area .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" .SS "new" .IX Subsection "new" .Vb 1 \& $scrollbox = Tickit::Widget::ScrollBox\->new( %args ) .Ve .PP Constructs a new \f(CW\*(C`Tickit::Widget::ScrollBox\*(C'\fR object. .PP Takes the following named arguments in addition to those taken by the base Tickit::SingleChildWidget constructor: .ie n .IP "vertical => \s-1BOOL\s0 or ""on_demand""" 8 .el .IP "vertical => \s-1BOOL\s0 or ``on_demand''" 8 .IX Item "vertical => BOOL or on_demand" .PD 0 .ie n .IP "horizontal => \s-1BOOL\s0 or ""on_demand""" 8 .el .IP "horizontal => \s-1BOOL\s0 or ``on_demand''" 8 .IX Item "horizontal => BOOL or on_demand" .PD Whether to apply a scrollbar in the vertical or horizontal directions. If not given, these default to vertical only. .Sp If given as the string \f(CW\*(C`on_demand\*(C'\fR 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. .SH "ACCESSORS" .IX Header "ACCESSORS" .SS "vextent" .IX Subsection "vextent" .Vb 1 \& $vextent = $scrollbox\->vextent .Ve .PP Returns the Tickit::Widget::ScrollBox::Extent object representing the box's vertical scrolling extent. .SS "hextent" .IX Subsection "hextent" .Vb 1 \& $hextent = $scrollbox\->hextent .Ve .PP Returns the Tickit::Widget::ScrollBox::Extent object representing the box's horizontal scrolling extent. .SH "METHODS" .IX Header "METHODS" .SS "scroll" .IX Subsection "scroll" .Vb 1 \& $scrollbox\->scroll( $downward, $rightward ) .Ve .PP Requests the content be scrolled downward a number of lines and rightward a number of columns (either of which which may be negative). .SS "scroll_to" .IX Subsection "scroll_to" .Vb 1 \& $scrollbox\->scroll_to( $top, $left ) .Ve .PP 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. .SH "SMART SCROLLING" .IX Header "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. .PP 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 \f(CW\*(C`set_total\*(C'\fR method on the extent object it is given. .ie n .SS "$smart = $child\->\s-1CAN_SCROLL\s0" .el .SS "\f(CW$smart\fP = \f(CW$child\fP\->\s-1CAN_SCROLL\s0" .IX Subsection "$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. .ie n .SS "$child\->set_scrolling_extents( $vextent, $hextent )" .el .SS "\f(CW$child\fP\->set_scrolling_extents( \f(CW$vextent\fP, \f(CW$hextent\fP )" .IX Subsection "$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 \f(CW\*(C`start\*(C'\fR value of them any time it needs these to implement content offset position when rendering. .ie n .SS "$child\->scrolled( $downward, $rightward, $h_or_v )" .el .SS "\f(CW$child\fP\->scrolled( \f(CW$downward\fP, \f(CW$rightward\fP, \f(CW$h_or_v\fP )" .IX Subsection "$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 \f(CW"h"\fR or \f(CW"v"\fR 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 \f(CW\*(C`start\*(C'\fR value of them to obtain the new absolute offsets. .SH "TODO" .IX Header "TODO" .IP "\(bu" 4 Choice of left/right and top/bottom bar positions. .IP "\(bu" 4 Click-and-hold on arrow buttons for auto-repeat .IP "\(bu" 4 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. .SH "AUTHOR" .IX Header "AUTHOR" Paul Evans