Difference between revisions of "Console"

From uGFX Wiki
Jump to: navigation, search
(Created page with "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 <code>gwinPrintf()<...")
 
(→‎API reference)
 
(9 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
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 <code>gwinPrintf()</code>. 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.
+
The console widget is a rectangular window with a fore- and background color. The console widget currently doesn't accept any input and can only output text using <code>gwinPrintf()</code>. 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.
 +
 
 +
== API reference ==
 +
The API reference of the console window can be found [http://api.ugfx.org/group___console.html here].
  
 
== Scrolling ==
 
== 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 <code>GDISP_NEED_SCROLL</code> 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.
 
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 <code>GDISP_NEED_SCROLL</code> 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.
 +
Note that some display controllers are not capable of scrolling (they don't natively support scrolling and there is no pixel read-back capability). For these display's setting <code>GDISP_NEED_SCROLL</code> will result in a compile error.
  
 
== Float ==
 
== Float ==
−
The console is capable of printing float values through <code>gwinPrintf()</code> when <code>GWIN_CONSOLE_USE_FLOAT</code> is set to ''TRUE'' in your [[gfxconf.h]]. Note that this feature requires a lot of memory and CPU time.
+
The console is capable of printing float values through <code>gwinPrintf()</code> when <code>GWIN_CONSOLE_USE_FLOAT</code> is set to ''TRUE'' in your [[gfxconf.h]]. Note float operations may be slow if your CPU does not support floating arithmetic.
  
 
== History ==
 
== History ==
 
In its bare state, the console does not keep track of its content. This means that making the console invisible using <code>gwinSetVisible()</code> 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.
 
In its bare state, the console does not keep track of its content. This means that making the console invisible using <code>gwinSetVisible()</code> 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 <code>GWIN_CONSOLE_USE_HISTORY</code> to ''TRUE'' in your [[gfxconf.h]]. The API call <code>gwinConsoleSetBuffer()</code> 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.
+
To enable the history feature which prevents this behavior, set <code>GWIN_CONSOLE_USE_HISTORY</code> to ''TRUE'' in your [[gfxconf.h]]. The API call <code>gwinConsoleSetBuffer()</code> 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 <code>GWIN_CONSOLE_HISTORY_ATCREATE</code> to ''TRUE''. Every console widget will then automatically turn on the history feature when it's being created.
 
Alternatively, you can also set <code>GWIN_CONSOLE_HISTORY_ATCREATE</code> to ''TRUE''. Every console widget will then automatically turn on the history feature when it's being created.
  
 
== Buffer size ==
 
== Buffer size ==
−
The buffer size will be automatically allocated by the console widget once <code>gwinConsoleSetBuffer()</code> 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.
+
The buffer size will be automatically allocated by the console widget once <code>gwinConsoleSetBuffer()</code> 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 behavior. Therefore, it's not possible to submit a customs sized buffer.
−
 
+
  
 
== Escape sequences ==
 
== 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 <code>GWIN_CONSOLE_ESCSEQ</code> to ''TRUE''. There are escape sequences to control the color and the format of the text:
 
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 <code>GWIN_CONSOLE_ESCSEQ</code> to ''TRUE''. There are escape sequences to control the color and the format of the text:
  
−
Escape Description
+
{| class="wikitable"
−
ESC color
+
! scope="col"|Escape
−
Change subsequent text color
+
! scope="col"|Description"
−
color: 0 = black, 1 = red, 2 = green, 3 = yellow, 4 = blue, 5 = magenta, 6 = cyan, 7 = white
+
|-
−
 
+
|ESC color
−
ESC C Revert subsequent text color to the window default
+
|Change subsequent text color <br/>color: 0 = black, 1 = red, 2 = green, 3 = yellow, 4 = blue, 5 = magenta, 6 = cyan, 7 = white
−
ESC u Turn on underline
+
|-
−
ESC U Turn off underline
+
|ESC C
−
ESC b Turn on bold
+
|Revert subsequent text color to the window default
−
ESC B Turn off bold
+
|-
−
ESC J Clear the window
+
|ESC u
−
  An escape sequence is introduced by \033. Please refer to the example below to see how to use the escape sequences properly.
+
|Turn on underline
−
 
+
|-
−
== API reference ==
+
|ESC U
−
The API reference of the console window can be found [http://ugfx.org/images/resources/doxygen/master/group___console.html here].
+
|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.
  
 
== Example ==
 
== Example ==

Latest revision as of 15:46, 4 February 2016

The console widget is a rectangular window with a fore- and background color. The console widget currently doesn't 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.

API reference

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

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. Note that some display controllers are not capable of scrolling (they don't natively support scrolling and there is no pixel read-back capability). For these display's setting GDISP_NEED_SCROLL will result in a compile error.

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 float operations may be slow if your CPU does not support floating arithmetic.

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 behavior, 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 behavior. 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.

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:

Retrieved from "https://wiki.ugfx.io/index.php?title=Console&oldid=1437"