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:
CSI
4m
This is underlined textCSI
24m
, 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
.