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).
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
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
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).
The window handle (HWND) of the Consoul window for which the event is generated (as returned by CSCreateLogWindow).
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.
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.
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 (