GUI.CreateHorizontalScrollBar[Full]

GUI.CreateHorizontalScrollBarFull (x, y, size : int,
    min, max, start : int,
    actionProc : procedure x (value : int),
    arrowInc, pageInc, thumbSize : int) : int

A scroll bar is a widget that allows users to see a piece of a document that cannot be displayed on the screen in its entirety. The picture below shows a horizontal scroll bar. To control a scroll bar, there are a few choices: the user can click on the thumb (the box in the scroll bar) and slide it left or right, or the user can click in the scroll bar itself to the left or right of the thumb (in which case the thumb is moved up or down one "page"), or the user can click on the left or right arrows at the ends of the scroll bar (in which case the thumb is moved left or right one "arrow increment").

The programmer defines a page or an arrow increment. When the value of the scroll bar changes, the action procedure of the scroll bar is called with the new value as a parameter. The action procedure should then redraw the contents using the new value of the scroll bar.

The range of values that the scroll bar will give is determined by the min and max parameters in the Create call. The left side of the scroll bar represents the minimum value, while the right represents the maximum value. There is also the "thumb size". This represents the range of values that can be seen at once on the screen.

By default, the arrow increment (the amount the value is changed when the scrolling arrows are pressed) is set to one. The page increment (the amount the value is changed when the user clicks in the bar to the right or left of the thumb) is set to one quarter the difference between the minimum and the maximum. The "thumb size" is set to zero (see the description of scroll bars for an explanation of the thumb size).

The x and y parameters specify the lower-left corner of the scroll bar. The size parameter specifies the length of the scroll bar (including the arrows) in pixels. The min and max parameters are the minimum and maximum values returned by the scroll bar. The start parameter is the initial value of the scroll bar and should be between min and max inclusive. The actionProc parameter is the name of a procedure that is called when the value of the scroll bar is changed. The parameter to the action procedure is the current value of the scroll bar.

        import GUI 
        
        View.Set ("graphics:300;60,nobuttonbar") 
        var scrollBar : int
        
        procedure ScrollBarMoved (value : int)
            Text.Locate (2, 3)
            put "Horizontal Scroll Bar: ", value : 4
        end ScrollBarMoved
        
        scrollBar := GUI.CreateHorizontalScrollBar (10, 10, 250,
            50, 150, 50, ScrollBarMoved)
        loop
            exit when GUI.ProcessEvent
        end loop

For example, if you have a window that can display 20 lines of text at once and there are 100 lines of text, you would set min to 1, max to 100 and thumbSize to 20. The value returned by the scroll bar would then be the line number of the first line on the screen to be displayed. When the scroll bar was at its maximum value, it would return 81, since by doing so, lines 81-100 would be displayed.

        % The "ScrollPic" program.
        import GUI
        
        var h, v : int      % The scroll bars.
        var canvas : int        % The canvas.
        var pic : int       % The picture.
        const width : int := 220    % The width of the canvas.
        
        procedure ScrollPic (ignore : int)
            % Get the current value of the scroll bars.
            var x : int := GUI.GetSliderValue (h)
            var y : int := GUI.GetSliderValue (v)
            GUI.PicDraw (canvas, pic, -x, -y, picCopy)
        end ScrollPic
        
        pic := Pic.FileNew ("Forest.jpg")
        if pic <= 0 then
            put "Error loading picture: ", Error.LastMsg
            return
        end if
        
        View.Set ("graphics:265;265")
        
        canvas := GUI.CreateCanvas (15, 15 + GUI.GetScrollBarWidth, 
            width, width)
        % Note the frame of the canvas is:
        %   (14, 14 + ScrollbarWidth) - (235, 235 + ScrollbarWidth)
        h := GUI.CreateHorizontalScrollBarFull (14, 14,
            221, 0, Pic.Width (pic) , 0, ScrollPic, 3, 100, width)
        v := GUI.CreateVerticalScrollBarFull (235, 
            14 + GUI.GetScrollBarWidth, 221, 0, Pic.Height (pic), 
            Pic.Height (pic), ScrollPic, 3, 100, width)
        ScrollPic (0) % Draw the picture initially

        loop
            exit when GUI.ProcessEvent
        end loop

Scroll bars always have a fixed height (for horizontal scroll bars) or width (for vertical scroll bars). To get a scroll bar's width, use the GUI.GetScrollBarWidth function.

When GUI.CreateHorizontalScrollBar or GUI.CreateHorizontalScrollBarFull is called, the newly created scroll bar will be displayed immediately unless GUI.DisplayWhenCreated has been called with the display parameter set to false.

When a scroll bar is not enabled, the gray in the bar is set to white and the thumb is not displayed. The scroll bar no longer responds to any mouse clicks until the scroll bar is enabled again.

This means that you can only call the function by calling GUI.CreateHorizontalScrollBar, not by calling CreateHorizontalScrollBar.