CSPushLine Function

Description

This function pushes, or appends, the given text line on the console window output queue and then refreshes the window. When the console window auto redraw mode (see CSSetAutoRedraw) is True (default), the window is scrolled and repainted to ensure that this last pushed line is visible. When auto redraw is False, the line is still pushed, but nothing is painted.

Line number (ie position or index in the queue)

Each line that is pushed on the console has a line number. This number is returned by this API function. It is the position of the line in the console window circular output queue buffer. This number is important if you want to change the contents of the line later; it the line number you pass back to other API functions like CSSetLine or CSReplaceZone.

When the line queue becomes full (CSLineCount() = CSGetQueueCapacity()) and a line is pushed, the first pushed line in the queue, #1, is popped and the new line is pushed with a line index of 1. For the internal output buffer queue, when line #1 is popped because the queue is full, line #2 becomes the next line to pop (first in, first out); so, the second time a line is pushed (or output), the line that will be popped will be #2 and the line number of the pushed line will be #2, and so on for the infinity of time.

Performance enhancement when pushing multiple lines

When multiple lines are to be pushed on the console a significant performance enhancement can be achieved by first setting auto redraw to false, pushing the lines, then setting auto redraw to true (which automatically refreshes the window and scrolls the last output line into view if necessary).

Syntax

VB/A 32bits

Private Declare Function CSPushLine Lib "consoul_010205_32.dll" ( _
  ByVal hWnd As Long, _
  ByVal lpszString As Long, _
  ByVal wNoParsing As Integer _
) As Integer

VB/A 64bits

Private Declare PtrSafe Function CSPushLine Lib "consoul_010205_64.dll" ( _
  ByVal hWnd As LongPtr, _
  ByVal lpszString As LongPtr, _
  ByVal wNoParsing As Integer _
) As Integer

Return Value

The position of the line in the output buffer queue, or 0 (zero) if an error occurs.

Parameters

hWnd

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

lpszString

Address of the zero terminated unicode string to push.

NULL (or zero) can be passed to push a virtual line; Consoul will call back for the contents, when it's needed.

wNoParsing

0 (zero) or 1 (one). Text pushed to the console can contain Consoul compatible vt100 escape sequences, that will be parsed and applied. When wNoParsing is not zero, Consoul won't do any parsing, and push the text as it is.

Remarks

When in continuous render mode, Consoul will apply the attributes of the preceding line (color, bold, ...) at the bginning of the new line. When in "by line" mode, all attributes are reset before outputting the new line.