# Directives

H_SCROLLBAR | Create/Control Horizontal Scrollbar

## Formats

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

Where:

@(col,ln,wth,ht) | Position and size of the horizontal 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 H_SCROLLBAR setting when the user selects the arrow at the left/right edge of the horizontal scrollbar. Numeric expression. (Default: 1)
ctl_id | Unique logical identifier for a horizontal 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. Use this value with the Apostrophe Operator to access various H_SCROLLBAR Properties.
ctrlopt | Control options. Supported options for H_SCROLLBAR include:
ERR=stmtref | Error transfer.
OPT=char$ | Single character parameters:
"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 | H_SCROLLBAR setting. Numeric expression between 1 and the maximum, max.
max | Logical maximum value of the H_SCROLLBAR. Numeric expression.
rgn_chg | Amount to increase/decrease the H_SCROLLBAR setting when the user selects the region left/right of the marker. Numeric expression. (Default: maximum 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 H_SCROLLBAR directive to create a horizontal scrollbar control object on the screen. Your program logic can read and adjust a value by increments to control logical column position within a record every time the user moves the horizontal scrollbar control object.

Horizontal 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 H_SCROLLBAR Properties for the list of properties available for manipulating a horizontal scrollbar.

## Format 1

Define/Create
H_SCROLLBAR ctl_id,@(col,ln,wth,ht)[,ctrlopt]
When you create the H_SCROLLBAR, the value in ctl_id is the unique identifier for it. This value is used to generate a CTL value whenever a user selects and moves the horizontal scrollbar.

Example:

This example defines a scrollbar 70 columns wide and 1 line high, starting at column 5 on line 20. Whenever the horizontal scrollbar is selected, a CTL value 10000 will be generated:

> h_scrollbar 10000,@(5,20,70,1)

#### Note:
Once a new position is selected, you must read it before your application can use the value to update the actual horizontal scrollbar position.

## Format 2

Define at Edge of Window
H_SCROLLBAR ctl_id WINDOW[,ctrlopt]
Scrollbars can appear either within the current window or at the edge of the window. Use the WINDOW keyword to have your horizontal scrollbar appear at the edge of the window.

## Format 3

Delete
H_SCROLLBAR REMOVE ctl_id[,ERR=stmtref]
Use the H_SCROLLBAR REMOVE format to delete the horizontal scrollbar.

## Format 4

Disable/Enable
H_SCROLLBAR {DISABLE | ENABLE} ctl_id [,ERR=stmtref]
Use the H_SCROLLBAR DISABLE format to gray out a horizontal scrollbar so that it will be visible but inaccessible to users. To reactivate it, use H_SCROLLBAR ENABLE.

## Format 5

Set Focus
H_SCROLLBAR GOTO ctl_id[,ERR=stmtref]
Use the H_SCROLLBAR GOTO format to set the focus on your horizontal scrollbar, ready for the user's next action.

## Format 6

Read Setting
H_SCROLLBAR READ ctl_id,setting,max,[rgn_chg][,arrow_chg][,ERR=stmtref]
Use the H_SCROLLBAR READ format to read the H_SCROLLBAR settings.

Example:

To read the horizontal scrollbar position relative to 1000:

> h_scrollbar read 100,X,1000

## Format 7

Update
H_SCROLLBAR WRITE ctl_id,marker,max[,ERR=stmtref]
Use the H_SCROLLBAR WRITE format to update or write the H_SCROLLBAR settings.

## Format 8

Hide/Show
H_SCROLLBAR {HIDE | SHOW} ctl_id[,ERR=stmtref]
With the H_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

H_SCROLLBAR Properties
V_SCROLLBAR Create/Control Vertical Scrollbar
V_SCROLLBAR Properties

## Example

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