Difference between revisions of "Console"

Revision as of 19:17, 1 July 2014

The console widget is a rectangular window with a fore- and background color. The widget does currently not accept any input and can only output text using gwinPrintf(). The widget is capable of handling line breaks when the text reaches the end of the window and it can also handle text scrolling when you insert new lines at the bottom when the window is already filled.

Scrolling

The console widget can scroll text upwards if a new line is inserted at the bottom when the window is already filled. This feature can be enabled by setting the GDISP_NEED_SCROLL macro to TRUE in your gfxconf.h. If this feature is not enabled, the console will simply clear itself and begin to write at the top again once the window is full.

Float

The console is capable of printing float values through gwinPrintf() when GWIN_CONSOLE_USE_FLOAT is set to TRUE in your gfxconf.h. Note that this feature requires a lot of memory and CPU time.

History

In its bare state, the console does not keep track of its content. This means that making the console invisible using gwinSetVisible() will lose all the content that has previously written to it - it will simply be empty once it becomes visible again. Everything that gets written to the console during the invisible state is also lost. To enable the history feature which prevents this behaviour, set GWIN_CONSOLE_USE_HISTORY to TRUE in your gfxconf.h. The API call gwinConsoleSetBuffer() is now available to enable or disable the history at any time. The console will automatically allocate the required buffer depending on it's window size. Once the history is disabled again, the buffer will be deallocated.

Alternatively, you can also set GWIN_CONSOLE_HISTORY_ATCREATE to TRUE. Every console widget will then automatically turn on the history feature when it's being created.

Buffer size

The buffer size will be automatically allocated by the console widget once gwinConsoleSetBuffer() is being called to enable the history. It's crucial to get the correct buffer size (enough to hold the correct content but not too much in order to save memory) to prevent false behaviour. Therefore, it's not possible to submit a customs sized buffer.

Escape sequences

One major problem that comes with the history buffer is that the font color does not get stored. As we have to use as little RAM as possible, we cannot add a color attribute to each character. Setting a color per line would also be a very limiting feature. To workaround the problem, escape sequences have been introduced to the console widget. These capabilities can be enabled by setting GWIN_CONSOLE_ESCSEQ to TRUE. There are escape sequences to control the color and the format of the text:

Escape Description ESC color Change subsequent text color color: 0 = black, 1 = red, 2 = green, 3 = yellow, 4 = blue, 5 = magenta, 6 = cyan, 7 = white

ESC C Revert subsequent text color to the window default ESC u Turn on underline ESC U Turn off underline ESC b Turn on bold ESC B Turn off bold ESC J Clear the window

An escape sequence is introduced by \033. Please refer to the example below to see how to use the escape sequences properly.

API reference

The API reference of the console window can be found here.

Example

The following example creates three individual console windows and outputs text to them. It also takes usage of the escape sequences.

#include "gfx.h"
 
/* The handles for three consoles */
GHandle GW1, GW2, GW3;
 
int main(void) {
	uint8_t i;
	font_t	font1, font2;
 
	/* initialize and clear the display */
	gfxInit();
 
	/* Set some fonts */
	font1 = gdispOpenFont("UI2");
	font2 = gdispOpenFont("DejaVu Sans 12");
	gwinSetDefaultFont(font1);
 
	/* create the three console windows */
	{
		GWindowInit		wi;
 
		wi.show = TRUE;
		wi.x = 0; wi.y = 0; wi.width = gdispGetWidth(); wi.height = gdispGetHeight()/2;
		GW1 = gwinConsoleCreate(0, &wi);
		wi.y = gdispGetHeight()/2; wi.width = gdispGetWidth()/2; wi.height = gdispGetHeight();
		GW2 = gwinConsoleCreate(0, &wi);
		wi.x = gdispGetWidth()/2; wi.height = gdispGetHeight();
		GW3 = gwinConsoleCreate(0, &wi);
	}
 
	/* Use a special font for GW1 */
	gwinSetFont(GW1, font2);
 
	/* Set the fore- and background colors for each console */
	gwinSetColor(GW1, Green);
	gwinSetBgColor(GW1, Black);
	gwinSetColor(GW2, White);
	gwinSetBgColor(GW2, Blue);
	gwinSetColor(GW3, Black);
	gwinSetBgColor(GW3, Red);
 
	/* clear all console windows - to set background */
	gwinClear(GW1);
	gwinClear(GW2);
	gwinClear(GW3);
 
	/* Output some data on the first console */
	for(i = 0; i < 10; i++) {
		gwinPrintf(GW1, "Hello \033buGFX\033B!\r\n");
	}
 
	/* Output some data on the second console */
	for(i = 0; i < 16; i++) {
		gwinPrintf(GW2, "Message Nr.: \0331\033b%d\033B\033C\r\n", i+1);
	}
 
	/* Output some data on the third console */
	for(i = 0; i < 18; i++) {
		gwinPrintf(GW3, "Message Nr.: \033u%d\033U\r\n", i+1);
	}
 
	while(TRUE) {
		gfxSleepMilliseconds(500);
	}
}

The result of the program looks like this: