Class XbpWindow() Foundation

Class function of the XbpWindow class.


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 

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

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.

When new user defined dialog elements are derived to use the functionality of the XbpWindow class, an existing XBP class that clearly defines the type of dialog element must be used as the superclass. For example, the XbpDialog class or the XbpPushbutton class can be used as the superclass. A class declaration inheriting directly from the XbpWindow class (such as CLASS xyz FROM XbpWindow) is not allowed.

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:

Classes with default behavior for xbeM_Wheel
XbpScrollbar *)
  1. Also see XbpScrollbar:wheel

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. 
   lScrollPage := .F. 
   nLines *= aWheel[5] 

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

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] 
   nUnits := Min( nOffset, SCROLL_UNIT ) 
   nOffset *= aWheel[5] 

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

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 

The event xbeM_Wheel is not supported for ActiveX controls. If an ActiveX control supports similar functionality, the corresponding COM/ActiveX methods or interfaces must be used instead.


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.

Indicates whether animation is activated when the window is opened.
Determines whether Xbase Parts in the child list are clipped during graphic output.
Determines whether the parent is clipped during graphic output.
Determines whether siblings are clipped during graphic output.
Groups Xbase Parts for navigation using the Tab key.
Contains alignment and layout information.
Specifies an object which controls child arrangement.
Controls how the object is redrawn during resize operations.
Specifies the visual style class that defines object appearance.
Specifies the id of the part within the visual style class assigned.
Allows the Xbase Part to be accessed during navigation with the Tab key.
Determines whether the object uses a Visual Style for display.
Determines whether the dialog element is visible after :create() is executed.
Specifies the visual style to use for displaying the object.
Runtime data
Determines the current state of the object.
Determines whether the object is a drop zone.
The XbpHelpLabel object for context sensitive help.
Specifies the input mode.
Specifies the tooltip text to be displayed.
Life cycle
Initializes instance variables.
Requests system resources for the object.
Reconfigures the Xbase Part after :create() has been executed.
Releases the system resources of the object.
Sends all mouse messages to the Xbase Part.
Disables the Xbase Part.
Enables the Xbase Part.
Get current invalid rectangle of the Xbase Part.
Suppresses the display of the Xbase Part on the screen.
Mark a window area as invalid (for redraw).
Requests a presentation space and locks it.
Suppresses automatic screen updates.
Map a point from one coordinate space to another
Defines the window as modal or non-modal.
Defines the shape of the mouse pointer.
Switches automatic mouse pointer tracking on or off.
Repositions the Xbase Part.
Changes position and size of the Xbase Part.
Changes the size of the Xbase Part.
Redisplays a hidden Xbase Part.
Shifts the Xbase Part to the background.
Brings the Xbase Part to the foreground.
Unlocks a presentation space that was locked using :lockPS().
Determines the device context for the window.
Sets or returns the background color
Sets or returns the foreground color.
Sets or returns a font object used by Xbase Parts displaying characters.
Sets or returns the font "compound name".
Sets or returns the presentation parameter array.
Returns the current position of the window.
Returns the current size of the window.
Retrieves the handle of a window
Returns the modal state of the window.
Returns whether the Xbase Part has input focus.
Returns whether an Xbase Part is enabled.
Returns whether the Xbase Part is visible.
Tests whether certain visual cues are active.
Mouse events

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 window. 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 moved into display rectangle.
Mouse moved out of the display rectangle.
Left mouse button clicked.
Left mouse button double clicked.
Left mouse button pressed.
Left mouse button released.
Middle mouse button click.
Middle mouse button double clicked.
Middle mouse button pressed.
Middle mouse button released.
Mouse has been moved.
Right mouse button clicked.
Right mouse button double clicked.
Right mouse button was pressed.
Right mouse button released.
Mouse wheel is activated.
Other events
A touch gesture was performed.
Help has been requested.
Keyboard input received.
Xbase Part is losing input focus.
Xbase Part has been moved.
Xbase Part has been redrawn.
Application will be terminated.
Size of the Xbase Part has changed.
Input focus set.
Item has been dragged over a drop zone.
Item is being dragged inside a drop zone.
Item has been moved outside a drop zone.
Item has been dropped over a drop zone.

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.