/ 
TUI-Vision-2.000_001
/ TUI::Views::ScrollBar

NAME

TUI::Views::ScrollBar - scroll bar view for Turbo Vision components

HIERARCHY

TObject
  TView
    TScrollBar

SYNOPSIS

use TUI::Objects;
use TUI::Views;

my $bounds = TRect->new( ax => 0, ay => 0, bx => 30, by => 10 );
my $vbar   = TScrollBar->new(
  bounds => TRect->new( ax => 29, ay => 0, bx => 30, by => 10 )
);

my $viewer = TListViewer->new(
  bounds     => $bounds,
  numCols    => 1,
  hScrollBar => undef,
  vScrollBar => $vbar,
);

# Typical setup for list-style scrolling.
$vbar->setRange(0, 99);
$vbar->setStep(10, 1);
$vbar->setValue(0);

DESCRIPTION

TScrollBar implements a visual scroll bar used to control and display a numeric position within a bounded range. Scroll bars are typically attached to other views such as list viewers, text editors, or scrollers and remain synchronized with the associated view.

When linked to a compatible view, the scroll bar automatically reflects changes in position and range. Conversely, user interaction with the scroll bar generates events that notify the owning view of position changes.

TScrollBar supports both vertical and horizontal orientations. A vertical scroll bar is created when its width is one column; otherwise, a horizontal scroll bar is created.

Commonly Used Features

In everyday code, scroll bars are usually created once and then configured with either setParams (single-call setup) or the setRange/setStep/ setValue trio (incremental setup). After that, application logic mainly reacts to scroll events rather than manipulating internal fields directly.

VARIABLES

The following global variables define the characters used to render TScrollBar elements.

$vChars

Defines the character set used for vertical scroll bars. The default value uses CP437 characters (up, down, track, thumb).

$hChars

Defines the character set used for horizontal scroll bars. The default value uses CP437 characters (left, right, track, thumb).

ATTRIBUTES

The following attributes describe the state and behavior of the scroll bar.

value

Current position of the scroll bar (Int).

minVal

Lower bound of the scroll bar range (Int).

maxVal

Upper bound of the scroll bar range (Int).

pgStep

Page step size used for page-up and page-down operations (Int).

arStep

Arrow step size used for single-step movements (Int).

CONSTRUCTOR

new

my $scrollBar = TScrollBar->new(bounds => $bounds);

Creates a new scroll bar with the specified bounds.

bounds

Bounding rectangle of the scroll bar (TRect).

new_TScrollBar

my $scrollBar = new_TScrollBar($bounds);

Factory-style constructor using positional arguments.

This constructor is equivalent to calling new with the bounds parameter and is provided for compatibility with traditional Turbo Vision construction patterns.

METHODS

draw

$scrollBar->draw();

Draws the scroll bar.

drawPos

$scrollBar->drawPos($pos);

Draws the scroll bar thumb at the specified position.

getPalette

my $palette = $scrollBar->getPalette();

Returns the color palette used to draw the scroll bar.

getPos

my $pos = $scrollBar->getPos();

Returns the current scroll bar position.

getSize

my $size = $scrollBar->getSize();

Returns the usable size of the scroll bar track.

handleEvent

$scrollBar->handleEvent($event);

Handles mouse and keyboard events directed at the scroll bar.

scrollDraw

$scrollBar->scrollDraw();

Redraws the scroll bar after a value change and notifies the owner.

scrollStep

my $delta = $scrollBar->scrollStep($part);

Determines the step size associated with a specific scroll bar part, such as an arrow or page region.

setParams

$scrollBar->setParams($value, $min, $max, $pgStep, $arStep);

Initializes all scroll bar parameters in a single call.

setRange

$scrollBar->setRange($min, $max);

Sets the minimum and maximum range of the scroll bar.

setStep

$scrollBar->setStep($pgStep, $arStep);

Sets the page and arrow step sizes.

setValue

$scrollBar->setValue($value);

Sets the current scroll bar value and updates the display.

EXAMPLE

The following example demonstrates how to create a scroll bar and link it to a list viewer:

# Define scroll bar bounds relative to the list viewer
my $barBounds = $bounds->clone;
$barBounds->{b}->{x} += 1;
$barBounds->{a}->{x}  = $bounds->{b}->{x};

# Create the scroll bar
my $listScroller = TScrollBar->new(bounds => $barBounds);

# Create a list viewer and link it to the scroll bar
my $listObject = TListViewer->new(
    bounds     => $bounds,
    numCols    => 1,
    scrollBar  => $listScroller,
);

# Insert both views into the owning group
$group->insert($listScroller);
$group->insert($listObject);

AUTHORS

Borland International (original Turbo Vision design)
J. Schneider <brickpool@cpan.org> (Perl implementation and maintenance)

COPYRIGHT AND LICENSE

Copyright (c) 1990-1994, 1997 by Borland International

Copyright (c) 2025-2026 the "AUTHORS" as listed above.

This software is licensed under the MIT license (see the LICENSE file, which is part of the distribution).