CSCreateLogWindow Function

Consoul window creation

Each consoul console window is created with a line queue. The line queue is a memory buffer that stores the vt100 content of each console line that is output, ie pushed, in the console. The size of the queue defines the rotation buffer, or the number of lines that consoul keeps in memory, before rotating the buffer in FIFO mode (First-In First-Out) at the next CSPushLine() call.

The principle of the rotation queue used internally by Consoul is illustrated in this blog post.

The default size of the queue is 500 and can only be changed at window creation time with the CSCreateLogWindow() function. The number of lines in the queue can be queried with CSLineCount. Each line in the queue has an index from 1 to CSLineCount.

Virtual mode

When the console window is in virtual mode, NULL string pointers can be pushed into the queue (a NULL string pointer is different than an empty line). Consoul will call back for the line content if it has to show a line for which a NULL string pointer was pushed. Once the content for the line is provided by the callback, Consoul will keep it and will not call back again, unless the line is again set to a NULL string pointer (CSSetLine). Please note that the persistence of graphic properties feature from one line to the next (also called continuous mode) is not fully supported in virtual mode at this time.

Syntax

VB/A 32bits

Private Declare Function CSCreateLogWindow Lib "consoul_010205_32.dll" ( _
  ByVal hwndParent As Long, _
  ByVal x As Long, ByVal y As Long, ByVal Width As Long, ByVal Height As Long, _
  ByVal lBackColor As Long, ByVal lForeColor As Long, _
  ByVal sFontName As Long, ByVal iFontSize As Integer, _
  ByVal iQueueSize As Integer, ByVal wCreateAttribs As Integer _
) As Long

VB/A 64bits

Private Declare PtrSafe Function CSCreateLogWindow Lib "consoul_010205_64.dll" ( _
  ByVal hwndParent As LongPtr, _
  ByVal x As Long, ByVal y As Long, ByVal Width As Long, ByVal Height As Long, _
  ByVal lBackColor As Long, ByVal lForeColor As Long, _
  ByVal sFontName As LongPtr, ByVal iFontSize As Integer, _
  ByVal iQueueSize As Integer, ByVal wCreateAttribs As Integer _
) As LongPtr

Return Value

The return value is a Win32 API handle to the console Window (HWND). This is the unique identifier of the Consoul window, that is passed to all other Consoul API functions.

Parameters

hwndParent

Handle of the parent window for the new Consoul window. If hwndParent is NULL (zero), the window will be created as a child of the desktop window.

Applied window styles

If hwndParent is NULL:

Style = WS_CAPTION | WS_SIZEBOX | WS_VSCROLL | WS_CHILDWINDOW

ExStyle = WS_EX_CLIENTEDGE | WS_EX_TOOLWINDOW

WndClass = "ConsoulFrameWindowClass"

If hwndParent is NOT NULL:

Style = WS_VSCROLL | WS_CHILDWINDOW | WS_TABSTOP | CS_DBLCLKS

ExStyle = 0

WndClass = "ConsoulControlWindowClass"

x, y, width, height

The position and size, in pixels, of the child window that Consoul creates in its host.

lBackcolor, lForecolor

The Backcolor and Forecolor for the Consoul window.

sFontname

Name of the font to use. Should be a non proportional font (or monospaced, fixed character width), but any name will be accepted.

In case the specified font is not installed on the running system, the nearest font is selected by Windows. If a proportional font is used, functions drawing and positioning the caret, as those computing rows, columns or anything else based on a fixed character width will produce inadequate results as the font average char width property is be used internally by the Consoul rendering engine.

iFontsize

Size of the font in logical units, of the font's character cell or character. This is passed to the CreateFont() win32 API function to create the font.

iQSize

The maximum capacity of the internal queue buffer, or the maximum number of lines that can be pushed in the console before the buffer begins to cycle.

wCreateAttribs

A combination of the following bit values (ORed):

Attribute name Value
LW_CREATE_FILLEDVEMPTY 1
LW_AUTOADJUST_ON_MAXCHARWIDTH 2
LW_NO_AUTOREDRAW 4
LW_RENDERMODEBYLINE 8
LW_TRACK_ZONES 32
LW_SENDMESSAGE_NOCALLBACKS 64
LW_MULTIZONECLICK 128
LW_SEND_MOUSEMOVE 16
LW_BKCOLSPILL 256

LW_CREATE_FILLEDVEMPTY

Fills the queue by pushing NULL string pointers. Consoul will call back for each line content when the line becomes visible.

LW_AUTOADJUST_ON_MAXCHARWIDTH

Each time a block of text is output on a console line, the right position is aligned with the next multiple of the font average char width. Vt100 text is composed of either control sequences (CSI or Control Sequence Introducer (Chr$(27) + command + EOM or End Of Marker ("m")), and text. A block of text is what stands between control sequences, example:

CSI4mThis is underlined textCSI24m, but this is not

Contains 2 text blocks: "This is underlined text" and ", but this is not".

After outputting the first block of text, Consoul will advance the next graphical output position on the next next multiple of the font average char width.

This adjustement can happen only when using a non-proportional font.

LW_NO_AUTOREDRAW

Consoul will not output anything until CSSetAutoRedraw is set to 1. Turning off the AutoRedraw feature speeds up CSPushLine bulk operations by not immediately repainting the console window, until AutoRedraw is set to 1.

LW_RENDERMODEBYLINE

Recomended.

Activates the non persistent graphical output mode. At the end of each console line, all graphical attributes (bold, underline, etc...) are automatically reset.

LW_TRACK_ZONES

Activates the tracking of the mouse cursor. Consoul will callback when the mouse enters or exits a zone.

LW_SENDMESSAGE_NOCALLBACKS

Consoul uses a function callback mechanism to notify its DLL host of various events. If this flag is set at creation time, it will instead send messages (via the windows SendMessage() API) to the parent window.

LW_MULTIZONECLICK

Deprecated

Consoul zones can overlap. When Consoul notifies its host, it does it so only once, for the innermost zone of the event. When this flag is set, Consoul will callback its host as many times as there are open zones, up to the innermost one.

LW_SEND_MOUSEMOVE

Deprecated

Consoul will callback for each mouse move event, which may generate a significant load of callbacks. Too much callbacks can potentially make the host irresponsive, use with care.

LW_BKCOLSPILL

Activates the "Backcolor spill" mode at window creation time. Backcolor Spill mode can be also be activated and deactivated with VT100X (Consoul's vt100 eXtensions escape sequences).

BackColor Spill mode can be useful when we add spacing on top or bottom of each console line (CSSetLineSpacing). It let's the text backcolor spill out of the "character" cell and fill the line spacing until the end of the console line.

Remarks

Consoul console windows are NOT visible after creation. To make the console window visible, use the Win32 ShowWindow API with the windows handle returned by CSCreateLogWindow.

Last updated: May 13 2022.