1.141 class scroll_bar

A scroll_bar object allows the user to examine and modify the position of a view --provided by some window-- onto a larger object. Scrollbars are normally attached to windows, editors and list_browsers. Scrollbars probably are rarely used by normal PCE application programmers. They may be used in combination with class figure using figure->clip_area to create a mini-window (note that windows may also be displayed on other window objects).

A scroll_bar assumes there is an object of a certain size and a scroll_bar<-view on this object that allows the user to see part of it. This part is defined by a scroll_bar<-start position and a scroll_bar<-length. See scroll_bar->bubble’A scroll_bar is a normal graphical object. To connect it to some other object, two communications should be established:

Object --> scroll_bar

Each time the view or viewed object changes such that the scrollbar needs to be updated, the scroll_bar should be sent a graphical->request_compute message. When XPCE's redraw system is activated, scroll_bar->compute will be called to update the scrollbar. See scroll_bar->compute for the methods that need to be provided by the scrolled scroll_bar<-object to make this connection work.

Scroll_bar --> object

When the user activates the scroll_bar this information is passed to the scroll_bar<-object as follows:

If scroll_bar<-message equals @default, invoke scroll_bar->scroll_vertical on scroll_bar<-object if scroll_bar<-orientation equals vertical and scroll_bar->scroll_horizontal if scroll_bar<-orientation equals horizontal. This method is passed three arguments: direction, unit and amount.

If direction equals forwards, the view should move further down/right the object. Unit may be page, in which case amount is the permillage of page the view should be moved or line, in which case amount is the number of lines to move.

If direction equals backwards, the same parameters are passed, but the view should be moved up/left.

If direction equals goto, amount is a permillage indicating an absolute position in the file: 0 means goto the top/left, 1000 to the bottom/right.

See also

- class slider
- window->scroll_horizontal
- scroll_bar->bubble
- editor-scroll_bar

1.141.1 Class variables

scroll_bar.repeat_interval: real = 0.06

If the scroll_bar object has a UI for repeated scrolling, this class-variable determines the speed. See also scroll_bar.repeat_delay.

1.141.2 Instance variables

scroll_bar-direction: {forwards,backwards,goto}

Direction in which to scroll or jump.

scroll_bar-unit: {line,page,file}

Unit to scroll.

scroll_bar-amount: int

These slots represent the scroll-request. See also scroll_bar->event and scroll_bar<-message. The values are:

- unit

Scroll to a position in the file (document), per page or line. The interpretation of these units is left to the scrolled object.

- direction

Scroll forwards (towards the bottom/right) or backwards (towards the top/left) of the document. If the unit is file, -direction is goto.

- amount

For -unit is file or page, this is a promilage. Thus, {file, goto, 300} goes to 30% of the file, {page, forwards, 500} goes half a page down. For -unit is line, this is a line-count.

scroll_bar <- distance: int

Distance between the scrollbar and the object. The default is -1, so the lines of the scrollbar and object scrolled overlap. This variable is used by scroll_bar->place.

scroll_bar <- length: int

Inherits description from: scroll_bar->bubble

scroll_bar <- look: {win,gtk}

Look-and-feel. Currently only x, which implies compatible with the scrollbars from the Xaw library. Future version should offer Motif and OpenLook compatible versions of the scrollbar.

Inherits description from: dialog_item-look

scroll_bar <-> message: [code]*

Message executed when the user operates the scrollbar. See the description of class scroll_bar for the forwarded values.

scroll_bar <-> object: graphical*

Object scrolled. This object should understand the following messages

scroll_bar<-start	Start of the visible part
scroll_bar<-view	Length of the view part
scroll_bar<-length	Total length of the object

The returned values are integers. The unit is not important as a scroll_bar only considers the relative values.

See also

window->scroll_horizontal

scroll_bar <- orientation: {horizontal,vertical}

Determines the layout of the scroll_bar as well as the default messages sent (see description of class scroll_bar). If this value is changed by the send_method, the graphical<-width and graphical<-height are swapped.

scroll_bar <- placement: chain

Name consisting of left or right and top or bottom’, separated by spaces. It determines where the scroll_bar is placed using scroll_bar->place.

scroll_bar <- start: int

Inherits description from: scroll_bar->bubble

scroll_bar <- view: int

Inherits description from: scroll_bar->bubble

1.141.3 Send methods

scroll_bar ->length: int

Total length of object.

scroll_bar ->start: int

Start of visible part.

scroll_bar ->view: int

Length of visible part.

scroll_bar ->bubble: length=int, start=int, view=int

The three parameters scroll_bar<-length, scroll_bar<-start and scroll_bar<-view tell the scrollbar which part of the object scrolled is currently in the window:

scroll_bar->length	Total size of the object
scroll_bar->start	Start of the visible part
scroll_bar->view	Size of the visible part

The method scroll_bar->bubble allows the user to change all three parameters with one message. See also scroll_bar->compute.

See also

class scroll_bar

scroll_bar ->compute:

If graphical<-request_compute is not @nil, this method will:

1. test if the scroll_bar<-object has the send method scroll_bar->bubble_scroll_bar. If this is the case, this method is called with this scrollbar as argument. The receiving object is supposed to activate scroll_bar->bubble, passing the current viewport settings to the scrollbar.
2. If the scroll_bar<-object has all the methods scroll_bar<-start, scroll_bar<-view and scroll_bar<-length, the scrollbar will invoke them and update the viewport using the result. Backward compatibility only.

   If the scrolled object or the viewport is modified, the window or scroll_bar<-object should invoke graphical->request_compute on the scroll_bar to activate this mechanism.

scroll_bar ->event: event

Operate the scrollbar The exact definition depends on scroll_bar<-look. After user-interaction that should affect the scrolled scroll_bar<-object, the scroll_bar object determines -direction, -unit and -amount. Next:

• Invoke scroll_bar->scroll_vertical: -direction, -unit, -amount on the associated scroll_bar<-object if scroll_bar<-orientation is vertical and scroll_bar->scroll_horizontal otherwise. If this method is understood and succeeds the event is considered handled. See, for example, window->scroll_vertical
• Else, forward using the associated scroll_bar<-message.

scroll_bar ->initialise: object=object, orientation={horizontal,vertical}, message=[code]*

Create a scroll_bar to scroll object either horizontally or vertically. See also scroll_bar->message.

scroll_bar ->place: [graphical]

Position scrollbar relative to the given object. If no object is given, scroll_bar<-object is used. Exploits the variables

scroll_bar<-placement	to place left/right, top/bottom.
scroll_bar<-distance	to determine the distance to the object.

The scrollbar is displayed on the same graphical<-device as the given graphical.