Class XbpScrollBar()

Class function of the XbpScrollBar class.

A scroll bar consists of four elements that allow interaction: two scroll buttons at each end, a movable scroll box and a scroll bar where the scroll box is moved. Depending on which part of the scroll bar is clicked, different actions are performed. The :scroll callback code block or the :scroll() callback method is used to react to user interaction with the scroll bar and processes the current position of the scroll box.

Scroll bars are passive dialog elements. If the scroll box is operated using the mouse, the scroll bar object does not receive the input focus. Instead, the input focus remains on the Xbase Part that was active before the scroll bar object was manipulated. To explicitly set the input focus to an XbpScrollbar object, the function SetAppFocus()must be used.

The xbeM_Wheel event is generated when the user rotates the mouse wheel, while the XbpScrollbar object has the input focus. The input focus is set to an XbpScrollbar object using the function SetAppFocus().

More information on the xbeM_Wheel event can be found in the documentation on XbpWindow:wheel.

Creates an instance of the XbpScrollBar class.

The instance variables in this group configure system resources. If changes are made to these values, they must either be made before the :create() method is executed or the :configure() method must be used to activate the changes.

Automatically updates the position of the scroll box.

Determines the value range of the scroll bar.

Sets the size of the scroll box.

Determines whether the scroll bar is horizontal or vertical.

Exclude the scrollbox from the range.

Requests system resources for the XbpScrollBar object.

Reconfigures the XbpScrollBar object after :create() has been executed.

Releases the system resources of the XbpScrollBar object.

Returns the current position of the scroll box.

Sets the current position of the scroll box.

Sets or returns the value range for the scroll bar.

Sets or returns the size of scroll box.

The second element (nDistance) indicates the distance the wheel is rotated, expressed in multiples or divisions of 120. The value is positive when the wheel is rotated up and negative when it is rotated down. Each multiple of 120 represents one "notch" on the mouse wheel, and typically corresponds to one line to be scrolled in the Xbase Part associated with the scroll bar. Note that higher resolution pointing devices and trackpads generate a larger number of xbeM_Wheel events with smaller values in the nDistance array element. These values directly correspond to the rotation distance reported by the hardware (driver), and are intended primarily for implementing custom scrolling behavior.

The third array element (nLines) specifies the number of lines to be scrolled. This is a computed value which takes into account previous mouse wheel operations, causing fractional rotations to be accumulated towards the next full line. The nLines element is non-zero only if one or more lines must be scrolled. For example, a mouse wheel being spun upwards so that approximately 1/3 of a line is reported with each xbeM_Wheel event might have the following sequence of values in the third array element: 0, 0, 1, 0, ... The nLines element is intended for implementing line-wise scrolling which may be required when displaying lines of text, for example.

The fourth array element (nOffset) contains the scroll offset in pixels. This is a computed value which takes into account previous mouse wheel operations, causing fractional rotations to be accumulated towards the next pixel. The scroll offset is based on the height of the default GUI font (XBPSYSFNT_GUIDEFAULT, see XbpFont:create()); one "notch" on the mouse wheel is roughly equivalent to two times the height of this font. The nOffset element is intended for implementing pixel-wise scrolling required when displaying images, for example.

The fifth array element (nLinesToScroll) specifies the system's "lines to scroll" setting, which is a setting configurable in Control Panel. This setting specifies a factor which applications should respect when performing scrolling operations. nLinesToScroll either contains a value greater than zero (number of lines to scroll per virtual line), or -1 if the user has configured page-wise scrolling.

Mouse wheel is activated.

Scroll bar has been moved.

Moving the record pointer using a scroll bar


// This example demonstrates how the actions of a vertical 
// scroll bar can be used to navigate within a database. 
// Three SLEs are created to display field data and the 
// record number. Database navigation is performed in the 
// scrollVertical() UDF, where the possible actions are 
// handled in a DO CASE structure. 

#include "Xbp.ch" 
#include "AppEvent.ch" 

PROCEDURE Main 
   LOCAL nEvent, mp1, mp2, oXbp 
   LOCAL oSle1, oSle2, oSle3 

   SetColor( "N/W" ) 
   CLS 
   USE Customer NEW 
   // Create 3 SLEs for displaying values from the database 
   oSle1 := XbpSLE():new( ,, {100,270}, {130,30} ) 
   oSle1:dataLink := {|| Customer->LastName } 
   oSle1:create():setData() 

   oSle2 := XbpSLE():new( ,, {100,200}, {130,30} ) 
   oSle2:dataLink := {|| Customer->FirstName } 
   oSle2:create():setData() 

   oSle3 := XbpSLE():new( ,, {100,130}, {130,30} ) 
   oSle3:dataLink := {|| Transform( Customer->(Recno()),"@N" ) } 
   oSle3:create():setData() 

   // Scroll bar for database navigation 
   oXbp := XbpScrollbar():new() 
   oXbp:type := XBPSCROLL_VERTICAL 
   oXbp:range:= { 1, LastRec() }         // Max. 32768 
   oXbp:create( ,, {250,130}, {15,170} ) 
   oXbp:scroll := {|mp1| scrollVertical( mp1[1], mp1[2] ), ; 
                         oSle1:setData(), ; 
                         oSle2:setData(), ; 
                         oSle3:setData()  } 
   nEvent := 0 
   // Event loop 
   DO WHILE nEvent <> xbeP_Close 
      nEvent := AppEvent( @mp1, @mp2, @oXbp ) 
      oXbp:handleEvent( nEvent, mp1, mp2 ) 
   ENDDO 
RETURN 

// Process scroll bar events 
PROCEDURE scrollVertical( nScrlPos, nCommand ) 
   DO CASE 
   CASE nCommand == XBPSB_PREVPOS 
        SKIP -1 
   CASE nCommand == XBPSB_NEXTPOS 
        SKIP  1 
   CASE nCommand == XBPSB_PREVPAGE 
        GOTO nScrlPos 
   CASE nCommand == XBPSB_NEXTPAGE 
        GOTO nScrlPos 
   CASE nCommand == XBPSB_SLIDERTRACK 
        // Nothing 
   CASE nCommand == XBPSB_ENDTRACK 
        GOTO nScrlPos 
   CASE nCommand == XBPSB_ENDSCROLL 
        GOTO nScrlPos 
   ENDCASE 
RETURN

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Class XbpScrollBar() Foundation