Virtual mode

Consoul is designed to stream data you want to continuously output to the console, keeping a fixed number of lines in a buffer queue that automatically rotates once full. If the data you want to output in the console can be provided dynamically, the Consoul window can be used in virtual mode.

In virtual mode, the Consoul rendering engine still tries to fetch the data to display in its (line) buffer queue, but the engine will first attempt to dynamically callback the host to obtain the (vt100) content when the line is marked as virtual.

Consoul will call the callback function when the line or part of it enters the visible portion of the Consoul window. For instance, if the windows queue has a capacity (CSGetQueueCapacity) of 500 lines and the number of visible rows (CSGetVisibleRows) is 10, Consoul will callback the host 10 times, starting at the first visible line (CSGetTopLine).

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.

Once the line content has been provided by the host in its callback function, Consoul will not callback the host anymore for this line, unless the callback indicates that the line stays virtual or that the line content is set back to a NULL string pointer, by the host, using the CSSetLine API function.

To facilitate virtual mode operation, Consoul allows to immediately mark all its lines as virtual, at window creation time, by setting the LW_CREATE_FILLEDVEMPTY flags in the pwCreateAttribs parameter of CSCreateLogWindow.

It is also possible to turn all the lines to virtual lines later at once by calling the CSResetAllLines API function.

Virtual line callback

To provide the content for a line, the host has to implement a function respecting the following signature, and has to pass the address of this function to the Consoul rendering engine by calling the CSSetOnVirtuaLineCallback API function.

Syntax (host)

VB/A 32bits

Public Function OnConsoulVirtualLine( _
  ByVal phWnd As Long, _
  ByVal piLine As Long _
) As Integer

VB/A 64bits

Public Function OnConsoulVirtualLine( _
  ByVal phWnd As LongPtr, _
  ByVal piLine As Long _
) As Integer

Return Value

The return value should be 0 (zero) if the host provides content for the line, using the CSSetLine method to set the virtual line contents, so that Consoul will parse the vt100 content and display it while finishing to handle the current paint process. If the return value is non zero, Consoul will keep the line marked as virtual, display an empty line, and call back again when another Windows paint event for this line occurs.

Parameters

hWnd

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

piLine

The line number (of the Consoul window internal queue buffer) for which the content is requested.

Remarks

Virtual mode is designed to work with Consoul windows using the by line rendering mode. The persistence of graphical properties from one line to another, or continuous mode is not supported in virtual mode.