version 2.8
gwin_console.h
Go to the documentation of this file.
1 /*
2  * This file is subject to the terms of the GFX License. If a copy of
3  * the license was not distributed with this file, you can obtain one at:
4  *
5  * http://ugfx.org/license.html
6  */
7 
8 /**
9  * @file src/gwin/gwin_console.h
10  * @brief GWIN Graphic window subsystem header file.
11  *
12  * @defgroup Console Console
13  * @ingroup Windows
14  *
15  * @brief Console widget that can be used similar a terminal on a computer.
16  *
17  * @details GWIN allows it to create a console/terminal like window.
18  * You can simply use chprintf() to print to the terminal.
19  *
20  * @pre GFX_USE_GWIN must be set to TRUE in your gfxconf.h
21  * @pre GWIN_NEED_CONSOLE must be set to TRUE in your gfxconf.h
22  *
23  * @{
24  */
25 
26 #ifndef _GWIN_CONSOLE_H
27 #define _GWIN_CONSOLE_H
28 
29 /* This file is included within "src/gwin/gwin.h" */
30 
31 // A console window. Supports wrapped text writing and a cursor.
32 typedef struct GConsoleObject {
33  GWindowObject g;
34  coord_t cx, cy; // Cursor position
35 
36  #if GWIN_CONSOLE_ESCSEQ
37  uint8_t startattr; // ANSI-like escape sequences
38  uint8_t currattr;
39  uint16_t escstate;
40  #endif
41 
42  #if GWIN_CONSOLE_USE_HISTORY
43  char * buffer; // buffer to store console content
44  size_t bufsize; // size of buffer
45  size_t bufpos; // the position of the next char
46  #endif
47 
48  #if GFX_USE_OS_CHIBIOS && GWIN_CONSOLE_USE_BASESTREAM
49  struct GConsoleWindowStream_t {
50  const struct GConsoleWindowVMT_t *vmt;
51  _base_asynchronous_channel_data
52  } stream;
53  #endif
54 
55 } GConsoleObject;
56 
57 #ifdef __cplusplus
58 extern "C" {
59 #endif
60 
61 /**
62  * @brief Create a console window.
63  * @details A console window allows text to be written.
64  * @note Text in a console window supports newlines and will wrap text as required.
65  * @return NULL if there is no resultant drawing area, otherwise a window handle.
66  *
67  * @param[in] g The GDisplay to display this window on
68  * @param[in] gc The GConsoleObject structure to initialise. If this is NULL the structure is dynamically allocated.
69  * @param[in] pInit The initialization parameters to use
70  *
71  * @note The drawing color and the background color get set to the current defaults. If you haven't called
72  * @p gwinSetDefaultColor() or @p gwinSetDefaultBgColor() then these are White and Black respectively.
73  * @note The font gets set to the current default font. If you haven't called @p gwinSetDefaultFont() then there
74  * is no default font and text drawing operations will no nothing.
75  * @note On creation even if the window is visible it is not automatically cleared.
76  * You may do that by calling @p gwinClear() (possibly after changing your background color)
77  * @note A console does not save the drawing state. It is not automatically redrawn if the window is moved or
78  * its visibility state is changed.
79  *
80  * @api
81  */
82 GHandle gwinGConsoleCreate(GDisplay *g, GConsoleObject *gc, const GWindowInit *pInit);
83 #define gwinConsoleCreate(gc, pInit) gwinGConsoleCreate(GDISP, gc, pInit)
84 
85 #if GFX_USE_OS_CHIBIOS && GWIN_CONSOLE_USE_BASESTREAM
86  /**
87  * @brief Get a stream from a console window suitable for use with chprintf().
88  * @return The stream handle or NULL if this is not a console window.
89  *
90  * @param[in] gh The window handle (must be a console window)
91  *
92  * @note Only useful in ChibiOS
93  *
94  * @api
95  */
96  BaseSequentialStream *gwinConsoleGetStream(GHandle gh);
97 #endif
98 
99 #if GWIN_CONSOLE_USE_HISTORY
100  /**
101  * @brief Assign a buffer to keep track of the content while the widget is invisible.
102  * @pre GWIN_CONSOLE_USE_HISTORY must be set to TRUE in your gfxconf.h
103  *
104  * @param[in] gh The window handle (must be a console window)
105  * @param[in] onoff If TRUE a buffer is allocated to maintain console text
106  * when the console is obscured or invisible. If FALSE, then
107  * any existing buffer is deallocated.
108  * @note When the history buffer is turned on, scrolling is implemented using the
109  * history buffer.
110  *
111  * @return TRUE if the history buffer is now turned on.
112  */
113  bool_t gwinConsoleSetBuffer(GHandle gh, bool_t onoff);
114 #endif
115 
116 /**
117  * @brief Put a character at the cursor position in the window.
118  * @note Uses the current foreground color to draw the character and fills the background using the background drawing color
119  *
120  * @param[in] gh The window handle (must be a console window)
121  * @param[in] c The character to draw
122  *
123  * @api
124  */
125 void gwinPutChar(GHandle gh, char c);
126 
127 /**
128  * @brief Put a string at the cursor position in the window. It will wrap lines as required.
129  * @note Uses the current foreground color to draw the string and fills the background using the background drawing color
130  *
131  * @param[in] gh The window handle (must be a console window)
132  * @param[in] str The string to draw
133  *
134  * @api
135  */
136 void gwinPutString(GHandle gh, const char *str);
137 
138 /**
139  * @brief Put the character array at the cursor position in the window. It will wrap lines as required.
140  * @note Uses the current foreground color to draw the string and fills the background using the background drawing color
141  *
142  * @param[in] gh The window handle (must be a console window)
143  * @param[in] str The string to draw
144  * @param[in] n The number of characters to draw
145  *
146  * @api
147  */
148 void gwinPutCharArray(GHandle gh, const char *str, size_t n);
149 
150 /**
151  * @brief Print a formatted string at the cursor position in the window. It will wrap lines as required.
152  * @details This function implements a minimal printf() like functionality
153  * The general parameters format is: %[-][width|*][.precision|*][l|L]p.
154  * The following parameter types (p) are supported:
155  * - <b>x</b> hexadecimal integer.
156  * - <b>X</b> hexadecimal long.
157  * - <b>o</b> octal integer.
158  * - <b>O</b> octal long.
159  * - <b>d</b> decimal signed integer.
160  * - <b>D</b> decimal signed long.
161  * - <b>u</b> decimal unsigned integer.
162  * - <b>U</b> decimal unsigned long.
163  * - <b>c</b> character.
164  * - <b>s</b> string.
165  * @note Uses the current foreground color to draw the string and fills the background using the background drawing color
166  *
167  * @param[in] gh The window handle (must be a console window)
168  * @param[in] fmt The format string (as per printf)
169  * @param[in] ... The format string arguments.
170  *
171  * @api
172  */
173 void gwinPrintf(GHandle gh, const char *fmt, ...);
174 
175 #ifdef __cplusplus
176 }
177 #endif
178 
179 #endif /* _GWIN_CONSOLE_H */
180 /** @} */
The structure to initialise a GWIN.
Definition: gwin.h:75
GHandle gwinGConsoleCreate(GDisplay *g, GConsoleObject *gc, const GWindowInit *pInit)
Create a console window.
int16_t coord_t
The type for a coordinate or length on the screen.
Definition: gdisp.h:39
void gwinPutString(GHandle gh, const char *str)
Put a string at the cursor position in the window. It will wrap lines as required.
void gwinPrintf(GHandle gh, const char *fmt,...)
Print a formatted string at the cursor position in the window. It will wrap lines as required...
void gwinPutChar(GHandle gh, char c)
Put a character at the cursor position in the window.
A window object structure.
Definition: gwin.h:40
void gwinPutCharArray(GHandle gh, const char *str, size_t n)
Put the character array at the cursor position in the window. It will wrap lines as required...