Classes Class XbpCrt()

Class XbpCrt() Foundation

Class function of the XbpCrt class.

Superclass
XbpPartHandler()
Description

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
XbpBrowse
XbpCombobox (XBPCOMBO_DROPDOWNLIST)
XbpListbox
XbpMLE
XbpQuickBrowse
XbpSpinbutton
XbpTreeview
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. 
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 
...

A working example showing how the wheel event can be used for supporting scrolling items in a MEMOEDIT() is located in the chapter "Touch input in character mode applications".

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

Class methods
:new()
Creates an instance of the XbpCrt class.
Configuration

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.

:alwaysOnTop
Determines whether the dialog can be covered by other windows.
:border
Border type for the XbpCrt window.
:clipChildren
Determines whether the Xbase Parts in the child list are clipped during graphic output.
:closeable
Determines whether the "Close" menu item in the system menu is available.
:fontHeight
Sets the height of the font for displaying characters in the text mode.
:fontName
Sets the name of the font for displaying characters in the text mode.
:fontWidth
Sets the width of the font used to display characters in the text mode.
:gridMove
Restricts the movement of the window to increments of :fontWidthwhen the mouse is used to move the window.
:icon
The resource ID of an icon.
:inputMode
Specifies the input mode.
:minMax
Displays pushbuttons for minimizing and maximizing the window.
:sysMenu
Determines whether to include the system menu in the title bar of the window.
:taskList
Determines whether the XbpCrt window is included as an item in the task list.
:title
Title of the XbpCrt window
:titleBar
Determines whether the title bar of the XbpCrt window is displayed.
:useVisualStyle
Determines whether the XbpCrt object uses a Visual Style for display.
:visible
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.

:asyncFlush
Determines the display behavior of text-mode output.
:autoFocus
Determines whether automatic focus changes are allowed.
:autoMark
Turn the ability to select text on or off.
:dropFont
Allow the user to change the font by dragging & dropping from the font manager.
:dropZone
Determines whether the object is a drop zone.
:hasDisplayFocus
Specifies whether the Crt window is currently the active window.
:helpLink
The XbpHelpLabel object for context sensitive help.
:maxCol
Position of the rightmost viewable text column in an XbpCrt window.
:maxRow
Position of the bottom viewable text row in an XbpCrt window.
:mouseMode
Determines whether mouse coordinates are given as graphics or text coordinates.
:modalResult
Specifies the result of a modal dialog.
:toolTipText
Specifies the tooltip text to be displayed.
:useShortCuts
Enables shortcut keys for the system menu.
:xSize
The width of the display area of an XbpCrt window in pixels.
:ySize
The height of the display area of an XbpCrt window in pixels.
Life cycle
:create()
Requests system resources for the object.
:configure()
Reconfigures the Xbase Part after :create() has been executed.
:destroy()
Releases the system resources of the object.
Methods
:currentPos()
Returns the current position of the window.
:currentSize()
Returns the current size of the XbpCrt window.
:showModal()
Displays the XbpCrt object as a modal dialog.
:getFrameState()
Determines the current display state of the XbpCrt window.
:getModalState()
Returns the modal state of the window.
:hasMenuBar()
Specifies whether the XbpCrt object has a menu bar.
:hide()
Suppresses the display of the XbpCrt window on the screen.
:isVisible()
Returns whether an XbpCrt window is visible.
:mapPoint()
Map a point from one coordinate space to another
:menuBar()
Installs an XbpMenubar object in the XbpCrt window.
:presSpace()
Returns the presentation space linked to the XbpCrt window.
:setFont()
Sets or returns a font object used by the XbpCrt window.
:setFontCompoundName()
Sets or returns the font "compound name".
:setFrameState()
Sets the display state of the XbpCrt window.
:setModalState()
Defines the XbpCrt window as "modal" or "non-modal".
:setPointer()
Defines the shape of the mouse pointer.
:setTrackPointer()
Switches automatic mouse pointer tracking on or off.
:setPos()
Repositions the XbpCrt window.
:setSize()
Changes the size of the XbpCrt window.
:setTitle()
Defines a new title for the XbpCrt window.
:show()
Redisplays the XbpCrt window after it has been hidden.
:toBack()
Shifts the XbpCrt window to the background.
:toFront()
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.

:enter
Mouse moved into Crt object.
:leave
Mouse moved out of the Crt object.
:lbClick
Left mouse button clicked.
:lbDblClick
Left mouse button double clicked.
:lbDown
Left mouse button pressed
:lbUp
Left mouse button released.
:mbClick
Middle mouse button click.
:mbDblClick
Middle mouse button double clicked.
:mbDown
Middle mouse button pressed.
:mbUp
Middle mouse button released.
:motion
Mouse has been moved.
:rbClick
Right mouse button clicked.
:rbDblClick
Right mouse button double clicked.
:rbDown
Right mouse button pressed.
:rbUp
Right mouse button released.
:wheel
Mouse wheel was operated.
Other events
:close
Window is being closed.
:gesture
A touch gesture was performed.
:helpRequest
Help has been requested.
:keyboard
Keyboard input received.
:killDisplayFocus
XbpCrt window is losing display focus.
:killInputFocus
Xbase Part is losing input focus.
:move
XbpCrt window has been moved.
:quit
Application will be terminated.
:resize
Size of the XbpCrt window has changed.
:setDisplayFocus
XbpCrt window receives the display focus.
:setInputFocus
XbpCrt window receives input focus.
:dragEnter
Item has been dragged over a drop zone.
:dragMotion
Item is being dragged inside a drop zone.
:dragLeave
Item has been moved outside a drop zone.
:dragDrop
Item has been dropped over a drop zone.
Examples
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 "Appevent.ch" 

PROCEDURE Main 
   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:create() 
   oXbp:setInputFocus  := bSetFocus 
   oXbp:killInputFocus := bKillFocus 

   oXbp := XbpCrt():new( ,, {300, 70}, 15, 35, "Child B" ) 
   oXbp:autoFocus := .F.            // Second child window 
   oXbp:create() 
   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 
         EXIT 
      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 ) 
      ENDIF 
   ENDDO 
RETURN
Feedback

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.