Class XbpCrt() Foundation

Class function of the XbpCrt class.


The XbpCrt class offers a straightforward way to transition existing text mode applications to GUI applications. An existing Clipper application can run in an XbpCrt window after being compiled with Xbase++. The program code can be changed to use Xbase Parts that provide graphic dialog elements step by step as time permits.

XbpCrt on Windows platforms

For the configuration of an XbpCrt window, the instance variable :taskList plays an important role when the window is displayed on the desktop. See the description of configuration instance variables for details.

When using MDI client windows in an application, there are some particular technical features where Windows differs from OS/2.

An MDI client window is created when an XbpCrt window receives as parent another XbpCrt window or the :drawingArea of an XbpDialog window:

If an XbpCrt window is to receive MDI client windows, it must have a menubar installed (see the method :menuBar()).
MDI client windows cannot have their own menubar.
It is not possible to create nested MDI client windows.

The xbeM_Wheel event is generated when the user rotates the mouse wheel and mouse events have been enabled via a call to SetMouse(.T.).

The xbeM_Wheel 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
Class name
XbpScrollbar *)
  1. Also see XbpScrollbar:wheel

The information in the <aWheel> array can be used for computing how far the content of the XbpCrt object needs to be scrolled to reflect the distance and direction in which the user has spun the mouse wheel.

The number of rows to scroll (line-wise scrolling) is reported in the nLines element of the <aWheel> array. Note that this element can be zero if the distance the mouse wheel was turned does not (yet) warrant scrolling a line. In this case, the corresponding xbeM_Wheel event can be ignored. The following code excerpt illustrates this procedure.

// 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 

The elements in <aWheel> can be also be used for implementing pixel-wise (or high-resolution) scrolling. This topic is covered in full detail in the documentation of XbpWindow:wheel().

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 

Class methods
Creates an instance of the XbpCrt class.

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

Determines whether the dialog can be covered by other windows.
Border type for the XbpCrt window.
Determines whether the Xbase Parts in the child list are clipped during graphic output.
Determines whether the "Close" menu item in the system menu is available.
Sets the height of the font for displaying characters in the text mode.
Sets the name of the font for displaying characters in the text mode.
Sets the width of the font used to display characters in the text mode.
Restricts the movement of the window to increments of :fontWidthwhen the mouse is used to move the window.
The resource ID of an icon.
Specifies the input mode.
Displays pushbuttons for minimizing and maximizing the window.
Determines whether to include the system menu in the title bar of the window.
Determines whether the XbpCrt window is included as an item in the task list.
Title of the XbpCrt window
Determines whether the title bar of the XbpCrt window is displayed.
Determines whether the XbpCrt object uses a Visual Style for display.
Determines whether the window is visible after :create() is executed.
Runtime data

The instance variables in this group can be changed after :create()is called without requiring a call to :configure(). The changes are automatically registered.

Determines the display behavior of text-mode output.
Determines whether automatic focus changes are allowed.
Turn the ability to select text on or off.
Allow the user to change the font by dragging & dropping from the font manager.
Determines whether the object is a drop zone.
Specifies whether the Crt window is currently the active window.
The XbpHelpLabel object for context sensitive help.
Position of the rightmost viewable text column in an XbpCrt window.
Position of the bottom viewable text row in an XbpCrt window.
Determines whether mouse coordinates are given as graphics or text coordinates.
Specifies the result of a modal dialog.
Specifies the tooltip text to be displayed.
Enables shortcut keys for the system menu.
The width of the display area of an XbpCrt window in pixels.
The height of the display area of an XbpCrt window in pixels.
Life cycle
Requests system resources for the object.
Reconfigures the Xbase Part after :create() has been executed.
Releases the system resources of the object.
Returns the current position of the window.
Returns the current size of the XbpCrt window.
Displays the XbpCrt object as a modal dialog.
Determines the current display state of the XbpCrt window.
Returns the modal state of the window.
Specifies whether the XbpCrt object has a menu bar.
Suppresses the display of the XbpCrt window on the screen.
Returns whether an XbpCrt window is visible.
Map a point from one coordinate space to another
Installs an XbpMenubar object in the XbpCrt window.
Returns the presentation space linked to the XbpCrt window.
Sets or returns a font object used by the XbpCrt window.
Sets or returns the font "compound name".
Sets the display state of the XbpCrt window.
Defines the XbpCrt window as "modal" or "non-modal".
Defines the shape of the mouse pointer.
Switches automatic mouse pointer tracking on or off.
Repositions the XbpCrt window.
Changes the size of the XbpCrt window.
Defines a new title for the XbpCrt window.
Redisplays the XbpCrt window after it has been hidden.
Shifts the XbpCrt window to the background.
Brings the XbpCrt window to the foreground.
Mouse events

An array <aPos> containing two elements that designate the position of the mouse pointer is passed as the first parameter to virtually all mouse messages. By default, the row and column position of the mouse pointer is given in text mode {nRow,nCol} coordinates. If the value XBPCRT_MOUSEMODE_PM is assigned to the instance variable :mouseMode, the <aPos> array contains graphic mouse coordinates {nX,nY}.

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 Crt object.
Mouse moved out of the Crt object.
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 pressed.
Right mouse button released.
Mouse wheel was operated.
Other events
Window is being closed.
A touch gesture was performed.
Help has been requested.
Keyboard input received.
XbpCrt window is losing display focus.
Xbase Part is losing input focus.
XbpCrt window has been moved.
Application will be terminated.
Size of the XbpCrt window has changed.
XbpCrt window receives the display focus.
XbpCrt window receives input focus.
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.
MDI application using XbpCrt windows
// In the example, two windows are created that are 
// visible only within the parent window. After the focus 
// changes due to a mouse click, the display focus is changed 
// and the output of the function QOut() occurs in the 
// window that currently has focus. 

#include "" 

   LOCAL nEvent, mp1, mp2, oXbp 
   LOCAL bSetFocus, bKillFocus 

   bSetFocus  := {|mp1,mp2,obj| ; 
                   QOut( obj:title, "received focus"), ; 
                   SetAppWindow( obj ) } 

   bKillFocus :=  {|mp1,mp2,obj| ; 
                   QOut( obj:title, "lost focus") } 

   oXbp := SetAppWindow()           // Parent window 
   oXbp:setTitle( "Parent" ) 
   oXbp:setInputFocus  := bSetFocus 
   oXbp:killInputFocus := bKillFocus 

   oXbp := XbpCrt():new( ,, {50, 100}, 10, 40, "Child A" ) 
   oXbp:autoFocus := .F.            // First child window 
   oXbp:setInputFocus  := bSetFocus 
   oXbp:killInputFocus := bKillFocus 

   oXbp := XbpCrt():new( ,, {300, 70}, 15, 35, "Child B" ) 
   oXbp:autoFocus := .F.            // Second child window 
   oXbp:setInputFocus  := bSetFocus 
   oXbp:killInputFocus := bKillFocus 

   nEvent := 0 
   DO WHILE nEvent <> xbeP_Close    // Event loop 
      nEvent := AppEvent( @mp1, @mp2, @oXbp, 0 ) 

      IF nEvent == xbeK_ESC         // Esc terminates 
      ELSEIF nEvent < xbeB_Event    // output in window with focus 
         ? "The key has the event code:", nEvent 
      ELSEIF oXbp <> NIL 
         oXbp:handleEvent( nEvent, mp1, mp2, oXbp ) 

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.