/ 
Prima-1.00
River stage two • 17 direct dependents • 19 total dependents
/ Prima::ScrollBar

NAME

ScrollBar - Prima scroll bars class

SYNOPSIS

use ScrollBar;

my $sb = Prima::ScrollBar-> create( owner => $group, %rest_of_profile);
my $sb = $group-> insert( 'ScrollBar', %rest_of_profile);

my $isAutoTrack = $sb-> autoTrack;
$sb-> autoTrack( $yesNo);

my $val = $sb-> value;
$sb-> value( $value);
$sb-> set_value( $value);

my $min = $sb-> min;
my $max = $sb-> max;
$sb-> min( $min);
$sb-> max( $max);
$sb-> set_bounds( $min, $max);

my $step = $sb-> step;
my $pageStep = $sb-> pageStep;
$sb-> step( $step);
$sb-> pageStep( $pageStep);
$sb-> set_steps( $step, $pageStep);

my $partial = $sb-> partial;
my $whole = $sb-> whole;
$sb-> partial( $partial);
$sb-> whole( $whole);
$sb-> set_proportion( $partial, $whole);

my $size = $sb-> minThumbSize;
$sb-> minThumbSize( $size);
$sb-> set_min_thumb_size( $size);

my $isVertical = $sb-> vertical;
$sb-> vertical( $yesNo);
$sb-> set_vertical( $yesNo);

my ($width,$height) = $sb-> get_default_size;

DESCRIPTION

The class ScrollBar implements both vertical and horizontal scrollbars in Prima. This is a purely Perl class without any C-implemented parts except those inherited from Widget.

For the basic organization of Prima classes see Prima.

Options

Methods init() and set() understand the following options (I describe here only those new to ScrollBar or with default values different of those set in Widget).

First, there are options which found new defaults in ScrollBar class:

selectable

Default value is 0 (logical false). Set this to 1 if you ever want ScrollBar to receive keyboard focus.

height

Default value is $Prima::ScrollBar::stdMetrics[1], which is an operating system dependent value determined with a call to Application-> get_default_scrollbar_metrics. The height is affected because by default the horizontal ScrollBar will be created.

widgetClass

This is to provide default color scheme. Default value is wc::ScrollBar, where cc is a package located in Const library.

tabStop

Default value is 0 (logical false). Indeed, there is no need for a non-selectable widget to be tab-stoppable. :-)

growMode

Default value is gm::GrowHiX, i.e. the scrollbar will try to maintain the constant distance from its right edge to its owner's right edge as the owner changes its size. This is useful for horizontal scrollbars.

Next, ScrollBar introduces the following new options:

autoTrack

This boolean option says the ScrollBar whether it should send Change notification during mouse tracking events. Generally it should only be set to 0 on slow computers.

Default value is 1 (logical true).

vertical

This logical option determines the main scrollbar style. Set this to 1 if you wish to create a vertical scrollbar, 0 - to create a horizontal one. This option is a run-time property, so you can in fact morph scrollbars from horizontal to vertical and vice versa. Looks funny.

Default value is 0 (logical false).

value

The most important characteristic of the scrollbar. Corresponds directly to the position of a thumb.

Default value is 0.

min

This options sets the lower limit for value.

Default value is 0.

max

This options sets the upper limit for value.

Default value is 100.

minThumbSize

The thumb cannot have main dimension lesser than this.

Default value is 21 pixels.

step

This determines the minimal increment/decrement to value during mouse/keyboard interaction.

Default value is 1.

pageStep

This determines the increment/decrement to value during "page"-related operations, like clicking the mouse somewhere on the strip outside the thumb, or pressing PgDn or PgUp.

Default value is 10.

partial

This tells the scrollbar how many of imaginary units the thumb should occupy. See whole below.

Default value is 10.

whole

This tells the scrollbar how many of imaginary units correspond to the whole length of the scrollbar. This value has nothing in common with min and max. You may think of the combination of partial and whole as of the proportion between the visible size of something (document, for example) and the whole size of that "something". Useful to struggle against infamous "bird" size of Windows scrollbar thumbs.

Default value is 100.

Properties. Set/get methods.

autoTrack

Retrieves the current value/sets the new value of auto tracking. See option autoTrack above. There are no corresponding set/get methods.

value

Retrieves the current thumb position/sets the thumb position. This property has no corresponding get() method.

min

Retrieves and sets the lower limit for value. There is a method set_bounds() which sets both min and max in a single swoop. There is no corresponding get() method.

max

Retrieves and sets the upper limit for value. There is a method set_bounds() which sets both min and max in a single swoop. There is no corresponding get() method.

step

Retrieves and sets the "single" stepping value of the thumb. There is also a method set_steps() which sets both step and pageStep. There is no corresponding get() method.

pageStep

Retrieves and sets the "page" stepping value of the thumb. There is also a method set_steps() which sets both step and pageStep. There is no corresponding get() method.

partial

Retrieves and sets the length of a thumb in logical units. There is also a method set_proportion() which sets both partial and whole. There is no corresponding get() method.

whole

Retrieves and sets the length of a whole scrollbar in logical units. There is also a method set_proportion() which sets both partial and whole. There is no corresponding get() method.

minThumbSize

Retrieves and sets the minimal size of main dimension of a thumb. There is no corresponding get() method, though set_min_thumb_size() is here.

vertical

Retrieves and sets the horizontal/vertical style of a scrollbar. There is no corresponding get() method, though set_vertical() is defined.

Public methods

get_default_size()

Returns as ($x,$y) the default (platform dependant) width for a vertical scrollbar and height for a horizontal scrollbar. There are no corresponding set() method and corresponding property.

Important callbacks

There is only one callback designed to be generally useful: Change. The Change notification is sent whenever the thumb position of scrollbar is changed, subject to a certain limitations when autoTrack is false. The notification conforms the general Prima rule: it is sent when appropriate, regardless to whether this was a result of user interaction, or a side effect of some method programmer has called.

Other methods (Methods the user should not call)

Those methods and event handlers (callbacks) are purely for internal use. Don't call them directly!

profile_default();
profile_check_in();
init();
on_size();
on_paint();
translate_point();
draw_part();
ScrollTimer_Tick();
on_keydown();
on_mousedown();
on_mouseclick();
on_mouseup();
on_mousemove();
reset();

EXAMPLE

  #! /usr/local/bin/prima

  use Prima;
  use Prima::Classes;
  use Prima::Const;
  use Prima::Application name => 'ScrollBar test';
  use Prima::ScrollBar;
  use Prima::Label;

  my $w = Prima::Window-> create(
			  text => 'ScrollBar test',
			  size => [300,200]);
  my $lbl = $w-> insert( Label =>
			 text => 'Nothing interesting',
			 autoWidth => 0,
			 width => 280,
			 left => 10,
			 bottom => 100,
			 alignment => ta::Center);
  my $sb = $w-> insert( ScrollBar =>
			width => 280,
			left => 10,
			bottom => 50,
			onChange => sub {
			  $lbl-> text( $_[0]-> value);
			});
  run Prima;

BUGS

Numerous, to say the least.

SEE ALSO

Prima, Widget, MouseScroller, Classes, Const, IntUtils

COPYRIGHT

Copyright 1997, 1998 The Protein Laboratory, University of Copenhagen. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Dmitry Karasik <dk@plab.ku.dk>, Anton Berezin <tobez@plab.ku.dk> - documentation