YukonEVM.dll - an overview

YukonEVM.dll is part #6 of The YUKON Project. It combines Xbase++'s event handling system in the GUI thread with native Windows message handling in the current thread. This is accomplished with one function and one class.
 

AppEventEx()

This function is an extended AppEvent() function. AppEventEx() accepts the same parameters as AppEvent() and is used in the very same way. AppEventEx() extracts xbeP_* events from Xbase++'s event queue, WM_* messages from Windows' message queue, and ensures correct event and message dispatching.

There is no learning curve when an Xbase++ application is extended with native WM_* Windows message handling.
 

XbpStaticEx()

This is an extended XbpStatic() class, providing an additional window handle. The extra window handle belongs to the current thread, while the XbpStatic window handle belongs to Xbase++'s GUI thread. The extra window is a child of XbpStatic, i.e. it has the same position and size.

Being "at home" in two threads (GUI thread and current thread), the very same XbpStaticEx object is capable of receiving events from Xbase++'s event queue, as well as receiving messages from the current thread's message queue. Provided the AppEventEx() function is called within the Xbase++ event loop, a programmer can associate a WM_* message with a callback code block. This code block is evaluated each time an XbpStaticEx object receives the associated WM_* message.

This way, message handling becomes similar to the callback slot concept of Xbase Parts. The only difference is that an XbpStaticEx object does not provide instance variables for each WM_* message it could possibly receive. Instead, WM_* message/code block associations are maintained via the :setCallback() and :getCallBack() methods. Both methods access an internal hash table holding message/code block associations.

There are two more possibilities for implementing WM_* message handling. Both are described in depth in the YUKON documentation.
 

Common Controls

The major purpose of XbpStaticEx is to serve as super class for Common Control classes, and to include Common Controls in XbpDialog windows. There are 25 Common Control classes prepared for correct message handling and dispatching. A complete sample program is available in the directory \source\samples\Yukon\EVM showing how a Common Control class can be implemented using the Month Calendar Control as an example:

The image shows a Month Calendar Control displaying three calendar sheets (it uses the locale of my computer, which is German). When the user clicks a day, the control receives the MCN_SELECT notification message from the operating system. This message can be reacted to using a code block, as shown in the follwing lines of PRG code creating a MonthCalControl object:

   oCtrl := MonthCalControl():new( oDlg:drawingArea,, {30,30}, { 600,200 } )

   // Set control styles
   oCtrl:windowStyle  += MCS_WEEKNUMBERS + MCS_DAYSTATE

   // Set initialization values
   oCtrl:initVars := { ;
      { MCM_SETFIRSTDAYOFWEEK , 1                   }, ; // start with Sunday
      { MCM_SETCURSEL         , Stod( "20080113" )  }, ; // current selection
      { MCM_SETCOLOR          , aColors             }, ; // colors
      { MCM_SETTODAY          , Date()              }  ; // today's date
   }

   // Notification callback code blocks
   oCtrl:setCallback( MCN_GETDAYSTATE , {|obj,dDate,aState| GetDayState( dDate, aState ) } )
   oCtrl:setCallback( MCN_SELECT      , {|obj,dDate| QOut(dDate) } )
   oCtrl:setCallback( MCN_SELCHANGE   , {|obj,dFirst,dLast| QOut(dFirst,dLast) } )

   oCtrl:create()

   DO WHILE nEvent <> xbeP_Close
      nEvent := AppEventEx( @mp1, @mp2, @oXbp )
      IF oXbp <> NIL
         IF nEvent == xbeP_Keyboard
            EXIT
         ENDIF
         oXbp:handleEvent( nEvent, mp1, mp2 )
      ENDIF
   ENDDO   

This code snippet is intended to give you a quick idea about creation of a Common Control, as well as handling of messages and notifications. The complete source code is included as sample implementation in The YUKON Project (also in the Demo version)

Note: #define constants for Common Control styles, messages and notifications are documented in the Windows platform SDK, not in The YUKON Project. YukonEVM.dll ensures that they can be used in Xbase++ as documented in the Windows platform SDK.

Read more...