Zone painting

It is possible to draw on the surface of a zone, after its content has been rendered by the Consoul rendering engine.

If a callback fucntion is set to activate this feature (via the CSSetOnDrawZoneCallback API function), the Consoul rendering engine will callback the host application when it paints a line and lands on a ZONE_END escape sequence (see the vt100 page for details on these escape control sequences).

Limitations

The nofitication occurring when encountering a ZONE_END sequence, implies that opened zones (ZONE_BEGIN sequences) on the line that do not have a matching ZONE_END sequence, cannot be custom drawn, as no ZONE_END squence will be there to trigger the notification.

As a corollary, Consoul cannot assume that there's a matching ZONE_BEGIN sequence for a ZONE_END sequence on the line (and vice-versa).

Also, when calling back the host on a ZONE_END sequence, Consoul does nothing to match the zone id specified in that ZONE_END sequence to its ZONE_BEGIN sequence, which may not even exists.

These limitations have consequences on how the Consoul rendering engine computes the drawing rectangle occupied by the zone for which it sends the paint notification.

Zone drawing rectangle

The drawing rectangle which coordinates are passed to the host callback function begin with the line drawing rectangle from the last ZONE_BEGIN escape sequence encountered, even if that ZONE_BEGIN sequence was not for the same zone ID as the zone ID for the ZONE_END sequence triggering the callback. The zone drawing rectangle then extends to the position where the ZONE_END was encountered.

This means that to be able to distinguish for which zone Consoul calls back the host, the zones must be properly opened and closed, and they should not overlap.

Paint zone callback function

Example (VB/A)

Syntax

VB/A 32bits

Public Function OnConsoulZonePaint( _
  ByVal phWnd As Long, _
  ByVal phDC As Long, _
  ByVal piZoneID As Integer, _
  ByVal piLine As Long, _
  ByVal piLeft As Integer, _
  ByVal piTop As Integer, _
  ByVal piRight As Integer, _
  ByVal piBottom As Integer _
) As Integer

VB/A 64bits

Public Function OnConsoulZonePaint( _
  ByVal phWnd As LongPtr, _
  ByVal phDC As LongPtr, _
  ByVal piZoneID As Integer, _
  ByVal piLine As Long, _
  ByVal piLeft As Integer, _
  ByVal piTop As Integer, _
  ByVal piRight As Integer, _
  ByVal piBottom As Integer _
) As Integer

Return Value (host)

At this time, Consoul does nothing with the return value of this function, as a convention simply return 0 (zero).

Parameters

phWnd

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

phDC

A handle to the Win32 API display context, valid for the duration of the call. Do not store and reuse later, as this handle may change between calls.

piZoneID

The zone ID for which the event is triggered. As explained above, this is the zone ID taken from the ZONE_END escape sequence that triggers the callback.

piLine

The console line number (ie the line number of the Consoul window internal buffer queue, see CSPusLine) in which the zone is located.

piLeft, piTop, piRight, piBottom

The coordinates of the zone drawing rectangle, which defines the boundaries of the area inside which you can paint with any Win32 API functions that can operate on a display context (phDC).