Class XbpWindow() Foundation

The XbpWindow class is derived from the XbpPartHandler class and inherits the ability to understand and react to events. Another important characteristic of an XbpWindow object is its capability for interaction. It can react to events that occur within the screen area managed by the object. Within the XbpWindow class, a number of default events are handled and reactions to these events occur when the :handleEvent() method is called. For each default event, a method exists that is executed after the event occurs. As an example, clicking the left mouse button generates the event xbeM_LbClick. When this event occurs, the :LbClick() method is executed. This is done automatically within the method :handleEvent(). The following lines illustrate this:

DO WHILE .T.                                // event loop 
   nEvent := AppEvent( @mp1, @mp2, @oXbp )  // read event 
   oXbp:handleEvent( nEvent, mp1, mp2 )     // react 
ENDDO 

/*      Internal in the method :handleEvent() 
DO CASE 
... 
CASE nEvent == xbeM_LbClick 
   self:LbClick( mp1, mp2 ) 
ENDCASE 
*/ 

The event is retrieved using AppEvent() and passed to the method :handleEvent() where the reaction occurs. After the event is received, the corresponding method is executed. For this reason, these methods are referred to as "callback methods".

Callback methods can be redefined by programmers when they create new classes that inherit from Xbase Parts. Alternatively, the reaction to an event can be defined using a code block stored in specific instance variables of the XbpWindow object. These instance variables are called "callback slots". Callback slots are instance variables that have the same name as the corresponding callback methods. When a code block is assigned to one of these instance variables, the code block is executed after the execution of the callback method.

Since the XbpWindow class is an abstract class, no instances of it can be created. Its purpose is to provide functionality to other classes that are derived from it. The functionality provided by this class includes screen management and reactions to events. The latter can be defined using code blocks that are assigned to callback slots or by overloading the callback methods. For each callback slot, a method with the same name exists and can be overloaded (redefined) in subclasses. When a callback method is defined in a subclass, it is executed when the corresponding event occurs.

The xbeM_Wheel event is generated when the user rotates the mouse wheel. This event is always sent to the Xbase Part that has input focus, no matter whether or not the mouse pointer is located within or outside the area of the Xbase Part. All classes derived from XbpWindow that display data which can be vertically scrolled have a default behavior to process this event. This applies to the following classes:

The information in the <aWheel> array can be used for computing how far the content of the window needs to be scrolled to reflect the distance and direction in which the user has spun the mouse wheel. The elements in <aWheel> can be used for implementing both line-wise and pixel-wise (or high-resolution) scrolling.

Implementing line-wise scrolling

If the Xbase Part uses line-wise scrolling, for example, because it displays lines of text, a scrolling operation must be performed for as many lines as reported in the nLines element of the <aWheel> array. The xbeM_Wheel events where this element is zero can be ignored.

... 
// Line-wise scrolling: perform scrolling for full lines, 
// ignore wheel events for partial lines 
aWheel := mp2 

nLines := aWheel[3] 

// Determine whether page-wise scrolling is configured and 
// apply user's "lines to scroll" setting (factor) 
IF aWheel[5] == -1 
   lScrollPage := .T. 
ELSE 
   lScrollPage := .F. 
   nLines *= aWheel[5] 
ENDIF 

DO WHILE nLines > 0 
   IF aWheel[3] > 0 
      IF lScrollPage 
         ::pageDown()   // Move view downwards by one page 
      ELSE 
         ::down()       // Move view downwards by one line 
      ENDIF 
   ELSE 
      IF lScrollPage 
         ::pageUp()     // Move view upwards by one page 
      ELSE 
         ::up()         // Move view upwards by one line 
      ENDIF 
   ENDIF 
   nLines-- 
ENDDO 
... 

If the Xbase Part supports pixel-wise scrolling, however, the view must be scrolled by as many pixels as specified in the nOffset element of the <aWheel> array. The xbeM_Wheel events where this element is zero can be ignored. Note that fast rotations of the mouse wheel can cause "jumps" in a scrolled view when applying the scroll offsets in one go. For a smooth scrolling experience, it is instead recommended to scroll using a limited/fixed increment. This is outlined in the following code snippet.

... 
#define SCROLL_UNIT 2 

// Pixel-wise scrolling: scroll view for a number of pixels, 
// ignore wheel events for partial rotation 
aWheel := mp2 

nOffset:= Abs( aWheel[4] ) 

// Determine whether page-wise scrolling is configured and 
// apply user's "lines to scroll" setting (factor). If 
// page-wise scrolling is configured, use the window height 
// as the scroll unit. 
IF aWheel[5] == -1 
   nUnits := ::currentSize()[2] 
ELSE 
   nUnits := Min( nOffset, SCROLL_UNIT ) 
   nOffset *= aWheel[5] 
ENDIF 

DO WHILE nOffset > 0 
   IF aWheel[3] > 0 
      ::scrollDown( nUnits ) 
   ELSE 
      ::scrollUp( nUnits ) 
   ENDIF 
   nOffset -= nUnits 
ENDDO 
... 

When the first element of <aWheel> is not equal to zero, the $ operator can be used to check which additional keys are pressed while the mouse wheel is rotated. For example:

nEvent := AppEvent( @mp1, @mp2, @oXbp ) 

IF nEvent == xbeM_Wheel 
   IF XBP_MK_SHIFT $ mp2[1] 
      // code for Shift key processing 
   ENDIF 
ENDIF