Messages and callbacks

Description

To notify the host of occurring events, Consoul supports two notifications mechanisms:

1. Callback functions

   Callbacks are functions that Consoul blindly calls in the host process. Although any name can be given to the callback function implemented in the host, the callback function names in the signatures presented here just use an arbitrary and hopefully descriptive enough function name.

2. Windows messages

   Consoul will send messages, using the SendMessage Win32 API function, to the parent window handle provided at creation time via the CSCreateLogWindow API function.

By default, Consoul uses the callback function mechanism. To query or change this behaviour Consoul provides the CSGetUseCallbacks and CSSetUseCallbacks API functions.

When this documentation states that the Consoul window sends a message (to its host), it means it either executes the callback function with the appropriate parameters (CSGetUseCallbacks()=1), or it sends a message to the parent window with the Windows SendMessage Win32 API function (CSGetUseCallbacks()=0).

Using callback functions

Setting callbacks

The following Consoul API functions are used to setup the callback mechanism:

VB/A 32bits

Private Declare PtrSafe Function CSSetOnMouseButtonCallback Lib "consoul_010205_32.dll" ( _
    ByVal hWnd As Long, _
    ByVal pEvtProc As Long _
) As Integer
Private Declare PtrSafe Function CSSetOnVirtuaLineCallback Lib "consoul_010205_32.dll" ( _
    ByVal hWnd As Long, _
    ByVal pEvtProc As Long _
) As Integer
Private Declare PtrSafe Function CSSetOnDrawZoneCallback Lib "consoul_010205_32.dll" ( _
    ByVal hWnd As Long, _
    ByVal pEvtProc As Long _
) As Integer
Private Declare PtrSafe Function CSSetOnWmPaintCallback Lib "consoul_010205_32.dll" ( _
    ByVal hWnd As LongPtr, _
    ByVal pwCbkMode As Integer, _
    ByVal pEvtProc As LongPtr _
) As Integer

VB/A 64bits

Private Declare PtrSafe Function CSSetOnMouseButtonCallback Lib "consoul_010205_64.dll" ( _
    ByVal hWnd As LongPtr, _
    ByVal pEvtProc As LongPtr _
) As Integer
Private Declare PtrSafe Function CSSetOnVirtuaLineCallback Lib "consoul_010205_64.dll" ( _
    ByVal hWnd As LongPtr, _
    ByVal pEvtProc As LongPtr _
) As Integer
Private Declare PtrSafe Function CSSetOnDrawZoneCallback Lib "consoul_010205_64.dll" ( _
    ByVal hWnd As LongPtr, _
    ByVal pEvtProc As LongPtr _
) As Integer
Private Declare PtrSafe Function CSSetOnWmPaintCallback Lib "consoul_010205_32.dll" ( _
    ByVal hWnd As LongPtr, _
    ByVal pwCbkMode As Integer, _
    ByVal pEvtProc As LongPtr _
) As Integer

Parameters

hWnd

The window handle (HWND) of the Consoul window, as returned by CSCreateLogWindow.

pwCbkMode

This parameter is specific to the CSSetOnWmPaintCallback function. It can be either WMPAINTCBK_BEFORE (=1 (one)) or WMPAINTCBK_AFTER (=2 (two)). This is actually a bit field and both values can be Ored to let Consoul call back at both moments of the painting process (see Surface Painting).

pEvtProc

The address of the function that Consoul will call back. Each of the callback function requires a specific signature.

Host implementation

The host application can implement any number of the callback function(s) and dynamically set them as the function instance that is invoked by Consoul using the CSSet...Callback API functions. Consoul will pass the Consoul window handle (hWnd) to the callback, of the console window initiating the callback, so that the host can manage multiple Consoul windows.

Receiving mouse events

Mouse callback function

To receive mouse events callbacks from Consoul, the memory address of a mouse callback function implementing a specific signature must be set with the CSSetOnMouseButtonCallback Consoul API function.

Function signatures (VB/A)

Syntax

VB/A 32bits

Public Function OnConsoulMouseButton( _
    ByVal phWnd As Long, _
    ByVal piEvtCode As Integer, _
    ByVal pwParam As Integer, _
    ByVal piZoneID As Integer, _
    ByVal piRow As Integer, _
    ByVal piCol As Integer, _
    ByVal piPosX As Integer, _
    ByVal piPosY As Integer _
) As Integer

VB/A 64bits

Public Function OnConsoulMouseButton( _
    ByVal phWnd As LongPtr, _
    ByVal piEvtCode As Integer, _
    ByVal pwParam As Integer, _
    ByVal piZoneID As Integer, _
    ByVal piRow As Integer, _
    ByVal piCol As Integer, _
    ByVal piPosX As Integer, _
    ByVal piPosY As Integer _
) As Integer

Return Value (host)

In the host implementation, returning 1 from this callback tells Consoul that the message was processed and Consoul should not call back again for this message. Consoul calls back multiple times for a mouse message only if the multi zone click mode (CSGetMultiZoneClick) is ON.

Parameters

phWnd

The window handle (HWND) of the Consoul window for which the event is generated (as returned by CSCreateLogWindow).

piEvtCode

Consoul calls back the host callback function for mouse messages with this parameter set to one of the the following own message codes, each generating a distinct callback to the host:

WM_USER message	Value
WM_USER_ROWCOLCHANGE	WM_USER+500
WM_USER_ZONEENTER	WM_USER+501
WM_USER_ZONELEAVE	WM_USER+502

or, one of the following standard Win32 message codes:

• #WM_MOUSEMOVE
• #WM_LBUTTONDOWN, #WM_LBUTTONUP, #WM_RBUTTONDOWN
• #WM_RBUTTONUP, #WM_MBUTTONDOWN, #WM_MBUTTONUP
• #WM_XBUTTONDOWN, #WM_XBUTTONUP, #WM_LBUTTONDBLCLK,
• #WM_RBUTTONDBLCLK, #WM_MBUTTONDBLCLK

Note: Full reference of the Consoul message codes are follow below.

pwParam

pwParam echoes the Win32 wParam parameter of Consoul's window Window procedure. The state of the keyboard control keys (Shift, Control, Alt) are contained in this parameter with the same bit flags values as the Win32 API:

MK_CONTROL, MK_LBUTTON, MK_MBUTTON, MK_RBUTTON, MK_SHIFT, MK_XBUTTON1, MK_XBUTTON2

More about these flags and message codes on Microsoft's Win32 API docs typically from this starting point.

piZoneID

For an event touching a zone, the concerned zone ID is set in piZoneID.

piRow, piCol

The row and the column of the console that are the event target. The column (piCol) may be inaccurate if the Consoul window font is not monospaced, as it is a computed value based on the font average char width.

piPosX, piPosY

The position in pixels of the mouse cursor ([0,0] being the top left corner of the Consoul window) at the moment of the event.

Remarks

Following the mouse movement (mirroring the WM_MOUSEMOVE Win32 message) is possible with Consoul, but as this can cause a large flow of events, the feature is walled behind the CSSetMouseMoveEvents API function. By default the feature is OFF. When the feature is OFF, Consoul doesn't callback the host (or send the message to the parent window).

A single event like a mouse button down can generate multiple callbacks when multi zone click mode is ON (CSGetMultiZoneClick) and more than one zone area is hit by the mouse cursor position (zones can overlap). However, multi zone click is OFF by default and has to be specifically turned ON (CSSetMultiZoneClikc).

Virtual Mode callback

See the virtual line callback page for an explanation of Consoul virtual mode and its callback function.

Zone painting callback

Using the Win32 API, it is possible to draw over the contents of a zone with a callback function. See the zone painting page for more details about this feature and how to implement it in the host.

Surface painting callback

Using the Win32 API, it is possible to draw over the contents of the full client area of the Consoul window with a callback function. See the surface painting page for more details about this feature and how to implement it in the host.

Consoul message codes reference

Consoul Windows classes

Consoul registers two Win32 windows classes to create its windows:

• "ConsoulControlWindowClass" (for child windows (ie when a parent hWnd is given at window creation))
• "ConsoulFrameWindowClass" (Consoul windows with no parent are created with a frame (window title and borders))

See CSCreateLogWindow

Consoul windows classes message codes

Note: WM_USER = &H400 ' Hex 400 = Dec 1024

WM_USER message	Value
WM_USER_ROWCOLCHANGE	WM_USER+500
WM_USER_ZONEENTER	WM_USER+501
WM_USER_ZONELEAVE	WM_USER+502
WM_USER_ODZONEDRAW	WM_USER+503
WM_USER_SETVIRTUALLINE	WM_USER+505

WM_USER_ROWCOLCHANGE

This message is sent when the mouse cursor movement causes a row or column change, keeping in consideration that the column is computed using the font average char width.

WM_USER_ZONEENTER, WM_USER_ZONELEAVE

These messages are sent when the mouse cursor enters, respectively leaves, a zone.

Consoul generates these events only when the mouse tracking mode in ON. Mouse tracking mode can be switched ON or OFF with the CSSetTrackZones API function.

WM_USER_ODZONEDRAW

See zone painting

WM_USER_SETVIRTUALLINE

Note: This is the only message that checks for a return value.

Consoul fires this message when it needs the content for a virtual console line. A vitual console line is a line that has been pushed (CSPushLine) or set (CSSetLine) with an NULL string. A NULL string is basically a 0 (zero) string pointer.

To respond to this message, a distinct callback function must be defined in the host. The mechanism is explained in the virtual mode page.

Using windows messages

Please see the SimpleConsole sample in C.