# Directives

V_SCROLLBAR | Create/Control Vertical Scrollbar

## Formats

1. Define/Create: | V_SCROLLBAR ctl_id, @(col,ln,wth,ht) [,ctrlopt]
2. Define at Edge of Window: | V_SCROLLBAR ctl_id WINDOW [,ctrlopt]
3. Delete: | V_SCROLLBAR REMOVE ctl_id [,ERR=stmtref]
4. Disable/Enable: | V_SCROLLBAR { ENABLE | DISABLE } ctl_id [,ERR=stmtref]
5. Set Focus: | V_SCROLLBAR GOTO ctl_id [,ERR=stmtref]
6. Read Setting: | V_SCROLLBAR READ ctl_id, setting, max [,rgn_chg] [,arrow_chg] [,ERR=stmtref]
7. Update: | V_SCROLLBAR WRITE ctl_id, marker, max [,ERR=stmtref]
8. Hide/Show: | V_SCROLLBAR { HIDE | SHOW } ctl_id [,ERR=stmtref]

Where

@(col,ln,wth,ht) | Position and size of the vertical scrollbar region. Numeric expressions. Column and line coordinates for top left corner, width in number of columns and height in number of lines.
arrow_chg | Amount to increase/decrease the V_SCROLLBAR setting when the user selects the arrow at the top/bottom edge of the vertical scrollbar. Numeric expression. (Default: 1)
ctl_id | Unique logical identifier for a vertical scrollbar (any integer -32000 to +32000). Avoid integers that conflict with keyboard definitions (e.g. 4 cancels CTL=4 for the F4 key) or Negative CTL Definitions.
ctrlopt | Control options. The only supported option for V_SCROLLBAR is:
OPT=char$ | Single character parameter/option:
"D" | Disabled. User cannot access the scrollbar.
"d" | Scrollbar is permanently disabled (cannot be enabled).
"H" | Hide. Do not display the scrollbar.
"A" | Auto. Generate CTL signal for each movement.
"s" | Scroll. Allow scroll within resizable/scrollable dialogue box.
marker | Relative position to set as the V_SCROLLBAR marker. Numeric expression between 1 and the maximum.
max | Logical maximum value of the V_SCROLLBAR. Numeric expression.
rgn_chg | Amount to increase/decrease the V_SCROLLBAR setting when the user selects the region left/right of the marker. Numeric expression. (Default: max/width)
setting | Numeric variable to receive the current scrollbar setting.
stmtref | Program line number or statement label to which to transfer control.

## Description

Use the V_SCROLLBAR directive to create a vertical scrollbar control object on the screen. Your program logic can read and adjust a value by increments to control logical record position within a file every time the user moves the vertical scrollbar.

Use either V_SCROLLBAR Format 1 or Format 2 to define or create a vertical scrollbar. The value in ctl_id gives the vertical scrollbar a unique identifier. This is generated as a CTL value whenever the vertical scrollbar is selected and changed.

Vertical Scrollbar Properties

The Apostrophe Operator can be used with the unique logical identifier (ctl_id) to dynamically read and alter a wide variety of control attributes (properties) directly from the programming language.

See V_SCROLLBAR Properties for the list of properties available for manipulating a vertical scrollbar.

## Format 1

Create

V_SCROLLBAR ctl_id,@(col,ln,wth,ht)[,ctrlopt]

Use this format to create a vertical scrollbar inside the current window.

Example:

> v_scrollbar 100,@(70,2,2,20)

This example defines a vertical scrollbar that is 2 columns wide, 20 lines high, starting at column 70 on line 2. Whenever the scrollbar is selected, a CTL=100 is generated.

## Format 2

Define at Edge of Window

V_SCROLLBAR ctl_id WINDOW[,ctrlopt]

Use the V_SCROLLBAR format with WINDOW to create a vertical scrollbar at the edge of the window.

## Format 3

Delete

V_SCROLLBAR REMOVE ctl_id[,ERR=stmtref]

Use the V_SCROLLBAR REMOVE format to delete the vertical scrollbar.

## Format 4

Disable/Enable

V_SCROLLBAR {DISABLE | ENABLE} ctl_id [,ERR=stmtref]

Use the V_SCROLLBAR DISABLE format to gray out a vertical scrollbar so that it will be visible but inaccessible to users. To reactivate it, use V_SCROLLBAR ENABLE.

## Format 5

Set Focus

V_SCROLLBAR GOTO ctl_id[,ERR=stmtref]

Use the V_SCROLLBAR GOTO format to set the focus on the vertical scrollbar, ready for the user's next action.

## Format 6

Read Setting

V_SCROLLBAR READ ctl_id, setting, max,[rgn_chg][,arrow_chg][,ERR=stmtref]

Use this format to read the current setting of the vertical scrollbar. Once a new position is selected, you must read it before your application can use the value to update the actual V_SCROLLBAR position.

Example:

> 0120 v_scrollbar read 100,X,1000
> 0130 v_scrollbar write 100,X,1000

Line 0120 reads the scrollbar position relative to 1000 and line 0130 updates the settings.

## Format 7

Update

V_SCROLLBAR WRITE ctl_id,marker,max[,ERR=stmtref]

Use the V_SCROLLBAR WRITE format to update or write the V_SCROLLBAR settings.

## Format 8

Hide/Show

V_SCROLLBAR {HIDE | SHOW} ctl_id[,ERR=stmtref]

With the V_SCROLLBAR HIDE format, the scrollbar remains active but is not displayed. It is still accessible programmatically. Use the SHOW format to restore the display and user access.

## See Also

V_SCROLLBAR Properties
H_SCROLLBAR Create/Control Horizontal Scroll Bar
H_SCROLLBAR Properties

## Example

0100 ! 100 - Vertical Scrollbar Example
0110 let VAL=1,MX=400,BJMP=25,SJMP=1
0120 v_scrollbar 101,@(6,14,1,10)
0130 v_scrollbar 102,@(15,14,2,10)
0140 v_scrollbar 103,@(25,14,3,10)
0150 v_scrollbar 104 window
0160 input (0,hlp="V_SCROLLBAR")@(40,18),"Select...: ",'CL',X$
0170 if ctl<101 or ctl>104 then goto 0210
0180 v_scrollbar read ctl,VAL,MX,BJMP,SJMP
0190 v_scrollbar write ctl,VAL,MX
0200 print @(40,19),"Selection:",ctl,":",str(VAL),'CL',; goto 0160
0210 if ctl=0 or ctl>=3 then stop else goto 0160