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).
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.
Public Function OnConsoulVirtualLine( _ ByVal phWnd As Long, _ ByVal piLine As Long _ ) As Integer
Public Function OnConsoulVirtualLine( _ ByVal phWnd As LongPtr, _ ByVal piLine As Long _ ) As Integer
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.
The window handle (HWND) of the Consoul window, as returned by CSCreateLogWindow.
The line number (of the Consoul window internal queue buffer) for which the content is requested.
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.