µGFX  2.9
version 2.9
gwin_options.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.io/license.html
6  */
7 
8 /**
9  * @file src/gwin/gwin_options.h
10  * @brief GWIN sub-system options header file.
11  *
12  * @addtogroup GWIN
13  * @brief The GWIN module uses all the other modules (GDISP, GINPUT, GTIMER...) to
14  * form a complete GUI toolkit.
15  *
16  * @{
17  */
18 
19 #ifndef _GWIN_OPTIONS_H
20 #define _GWIN_OPTIONS_H
21 
22 /**
23  * @name GWIN Functionality to be included
24  * @{
25  */
26  /**
27  * @brief Should window manager support be included
28  * @details Defaults to GFXOFF
29  */
30  #ifndef GWIN_NEED_WINDOWMANAGER
31  #define GWIN_NEED_WINDOWMANAGER GFXOFF
32  #endif
33  /**
34  * @brief Should the widget hierarchy be included. This provides parent-child features.
35  * @details Defaults to GFXOFF
36  */
37  #ifndef GWIN_NEED_CONTAINERS
38  #define GWIN_NEED_CONTAINERS GFXOFF
39  #endif
40  /**
41  * @brief Should widget functions be included. Needed for any widget (eg Buttons, Sliders etc)
42  * @details Defaults to GFXOFF
43  */
44  #ifndef GWIN_NEED_WIDGET
45  #define GWIN_NEED_WIDGET GFXOFF
46  #endif
47  /**
48  * @brief The width of the rectangle that highlights a widget that is focused
49  * @details Defaults to 1
50  */
51  #ifndef GWIN_FOCUS_HIGHLIGHT_WIDTH
52  #define GWIN_FOCUS_HIGHLIGHT_WIDTH 1
53  #endif
54  /**
55  * @brief Should the simple container be included.
56  * @details Defaults to GFXOFF
57  */
58  #ifndef GWIN_NEED_CONTAINER
59  #define GWIN_NEED_CONTAINER GFXOFF
60  #endif
61  /**
62  * @brief Should the frame widget be included.
63  * @details Defaults to GFXOFF
64  */
65  #ifndef GWIN_NEED_FRAME
66  #define GWIN_NEED_FRAME GFXOFF
67  #endif
68  /**
69  * @brief Should console functions be included.
70  * @details Defaults to GFXOFF
71  */
72  #ifndef GWIN_NEED_CONSOLE
73  #define GWIN_NEED_CONSOLE GFXOFF
74  #endif
75  /**
76  * @brief Should graph functions be included.
77  * @details Defaults to GFXOFF
78  */
79  #ifndef GWIN_NEED_GRAPH
80  #define GWIN_NEED_GRAPH GFXOFF
81  #endif
82  /**
83  * @brief Should gl3d functions be included.
84  * @details Defaults to GFXOFF
85  */
86  #ifndef GWIN_NEED_GL3D
87  #define GWIN_NEED_GL3D GFXOFF
88  #endif
89  /**
90  * @brief Should button functions be included.
91  * @details Defaults to GFXOFF
92  */
93  #ifndef GWIN_NEED_BUTTON
94  #define GWIN_NEED_BUTTON GFXOFF
95  #endif
96  /**
97  * @brief Should progressbar functions be included.
98  * @details Defaults to GFXOFF
99  */
100  #ifndef GWIN_NEED_PROGRESSBAR
101  #define GWIN_NEED_PROGRESSBAR GFXOFF
102  #endif
103  /**
104  * @brief Should slider functions be included.
105  * @details Defaults to GFXOFF
106  */
107  #ifndef GWIN_NEED_SLIDER
108  #define GWIN_NEED_SLIDER GFXOFF
109  #endif
110  /**
111  * @brief Should checkbox functions be included.
112  * @details Defaults to GFXOFF
113  */
114  #ifndef GWIN_NEED_CHECKBOX
115  #define GWIN_NEED_CHECKBOX GFXOFF
116  #endif
117  /**
118  * @brief Should image functions be included.
119  * @details Defaults to GFXOFF
120  */
121  #ifndef GWIN_NEED_IMAGE
122  #define GWIN_NEED_IMAGE GFXOFF
123  #endif
124  /**
125  * @brief Should label functions be included.
126  * @details Defaults to GFXOFF
127  */
128  #ifndef GWIN_NEED_LABEL
129  #define GWIN_NEED_LABEL GFXOFF
130  #endif
131  /**
132  * @brief Should radio button functions be included.
133  * @details Defaults to GFXOFF
134  */
135  #ifndef GWIN_NEED_RADIO
136  #define GWIN_NEED_RADIO GFXOFF
137  #endif
138  /**
139  * @brief Should list widget functions be included.
140  * @details Defaults to GFXOFF
141  */
142  #ifndef GWIN_NEED_LIST
143  #define GWIN_NEED_LIST GFXOFF
144  #endif
145  /**
146  * @brief Should tabset functions be included.
147  * @details Defaults to GFXOFF
148  */
149  #ifndef GWIN_NEED_TABSET
150  #define GWIN_NEED_TABSET GFXOFF
151  #endif
152  /**
153  * @brief Should the virtual keyboard be included.
154  * @details Defaults to GFXOFF
155  */
156  #ifndef GWIN_NEED_KEYBOARD
157  #define GWIN_NEED_KEYBOARD GFXOFF
158  #endif
159  /**
160  * @brief Should the textedit widget be included.
161  * @details Defaults to GFXOFF
162  */
163  #ifndef GWIN_NEED_TEXTEDIT
164  #define GWIN_NEED_TEXTEDIT GFXOFF
165  #endif
166 /**
167  * @}
168  *
169  * @name GWIN Optional Parameters
170  * @{
171  */
172  /**
173  * @brief Add a tag to each widget
174  * @details Defaults to GFXOFF
175  * @note Adds a tag member to each widget. Any events created include this tag.
176  * The enables switch based application logic to detect the event source.
177  */
178  #ifndef GWIN_WIDGET_TAGS
179  #define GWIN_WIDGET_TAGS GFXOFF
180  #endif
181  /**
182  * @brief Use flat styling for controls rather than a 3D look
183  * @details Defaults to GFXOFF
184  * @note This may appear better on color-restricted displays
185  * @note Flat styling is less graphics and cpu intensive (marginally) than the default 3D look.
186  */
187  #ifndef GWIN_FLAT_STYLING
188  #define GWIN_FLAT_STYLING GFXOFF
189  #endif
190  /**
191  * @brief Don't use a timer for redrawing windows
192  * @details Defaults to GFXOFF
193  * @note Normally windows and widgets are redrawn on a timer. Setting this
194  * option causes them to be redrawn immediately. Note that this can
195  * cause extended blocking times on events and saves little code.
196  * @note If GWIN_NEED_WINDOWMANAGER is GFXOFF then this setting is ignored
197  * as redrawing always occurs immediately.
198  */
199  #ifndef GWIN_REDRAW_IMMEDIATE
200  #define GWIN_REDRAW_IMMEDIATE GFXOFF
201  #endif
202  /**
203  * @brief Redraw all windows in a single operation
204  * @details Defaults to GFXOFF
205  * @note Windows are normally redraw one per gtimer cycle.
206  * Setting this option causes all windows to be redrawn in
207  * a single gtimer cycle. Note that this can
208  * cause extended blocking times on the timer thread but may
209  * speed up redraw slightly.
210  * @note This is only relevant if GWIN_REDRAW_IMMEDIATE is GFXOFF.
211  * Everything always gets redrawn in a single operation if
212  * GWIN_REDRAW_IMMEDIATE is GFXON.
213  */
214  #ifndef GWIN_REDRAW_SINGLEOP
215  #define GWIN_REDRAW_SINGLEOP GFXOFF
216  #endif
217  /**
218  * @brief Buttons should not insist the mouse is over the button on mouse release
219  * @details Defaults to GFXOFF
220  */
221  #ifndef GWIN_BUTTON_LAZY_RELEASE
222  #define GWIN_BUTTON_LAZY_RELEASE GFXOFF
223  #endif
224  /**
225  * @brief Should the content of the console be saved for redrawing.
226  * @details Defaults to GFXOFF
227  * @details If this feature is enabled, the contents of the console will be saved
228  * as it is written. If a redraw is required it will be redrawn from the
229  * history. Scrolling will also use the history buffer if it is turned on.
230  * @note Using this option allocates the amount of memory to store the
231  * history based on the minimum character width in the current font
232  * at the time the history is turned on. Using a fixed width font is a good
233  * idea to minimize memory usage.
234  * @note If you change the size of the window or you change the font being displayed
235  * you should turn off the history and then turn it back on in order to get
236  * a new buffer of the correct size for the window/font combination. Strange
237  * redrawing and scrolling effects can occur if the buffer is too small to
238  * save a complete screen of data. Note the system tries to optimize storage
239  * so this may only be evident in very limited situations eg with a console
240  * with many characters in it.
241  * @note @p gwinConsoleSetBuffer() can be used to turn the history buffer off and on.
242  */
243  #ifndef GWIN_CONSOLE_USE_HISTORY
244  #define GWIN_CONSOLE_USE_HISTORY GFXOFF
245  #endif
246  /**
247  * @brief Use font width averaging for the history buffer allocation.
248  * @details Defaults to GFXOFF
249  * @details If this feature is enabled, the width one third of the way between
250  * the font's character width minimum and maximum will be used instead
251  * of the font's minimum width.
252  * @note This option reduces the memory allocation for a variable width font's
253  * history buffer. Note that strange
254  * redrawing and scrolling effects can occur if the buffer is too small to
255  * save a complete screen of data. The system tries to optimize storage
256  * so this may only be evident in very limited situations eg with a console
257  * with many characters in it.
258  */
259  #ifndef GWIN_CONSOLE_HISTORY_AVERAGING
260  #define GWIN_CONSOLE_HISTORY_AVERAGING GFXOFF
261  #endif
262  /**
263  * @brief Should the history be turned on for all console windows when they are first created.
264  * @details Defaults to GFXOFF
265  * @note @p gwinConsoleSetBuffer() can be used to turn the history buffer off and on at
266  * any time.
267  */
268  #ifndef GWIN_CONSOLE_HISTORY_ATCREATE
269  #define GWIN_CONSOLE_HISTORY_ATCREATE GFXOFF
270  #endif
271  /**
272  * @brief Console Windows need floating point support in @p gwinPrintf
273  * @details Defaults to GFXOFF
274  */
275  #ifndef GWIN_CONSOLE_USE_FLOAT
276  #define GWIN_CONSOLE_USE_FLOAT GFXOFF
277  #endif
278  /**
279  * @brief Console windows support escape sequences to control display
280  * @details Defaults to GFXOFF
281  *
282  * @note
283  * Currently supported:
284  * ESC color Change subsequent text color
285  * color: "0" = black, "1" = red, "2" = green, "3" = yellow, "4" = blue,
286  * "5" = magenta, "6" = cyan, "7" = white
287  * ESC C Revert subsequent text color to the window default
288  * ESC u Turn on underline
289  * ESC U Turn off underline
290  * ESC b Turn on bold
291  * ESC B Turn off bold
292  * ESC J Clear the window
293  */
294  #ifndef GWIN_CONSOLE_ESCSEQ
295  #define GWIN_CONSOLE_ESCSEQ GFXOFF
296  #endif
297  /**
298  * @brief Console Windows need BaseStreamSequential support (ChibiOS only)
299  * @details Defaults to GFXOFF
300  * @note To use the ChibiOS basestream functions such as chprintf()
301  * for printing in a console window you need to set this option to
302  * GFXON in your gfxconf.h and include in your application source file...
303  * \#include "chprintf.h"
304  * In your makefile, as part of your list of C source files, include
305  * ${CHIBIOS}/os/various/chprintf.c
306  */
307  #ifndef GWIN_CONSOLE_USE_BASESTREAM
308  #define GWIN_CONSOLE_USE_BASESTREAM GFXOFF
309  #endif
310  /**
311  * @brief Image windows can optionally support animated images
312  * @details Defaults to GFXOFF
313  */
314  #ifndef GWIN_NEED_IMAGE_ANIMATION
315  #define GWIN_NEED_IMAGE_ANIMATION GFXOFF
316  #endif
317  /**
318  * @brief Enable the API to use attributes in the label widget
319  * @details Defaults to GFXOFF
320  * @note Using this feature is discouraged. The proper (and faster as well
321  * as more efficient) way is to use two separate labels.
322  */
323  #ifndef GWIN_LABEL_ATTRIBUTE
324  #define GWIN_LABEL_ATTRIBUTE GFXOFF
325  #endif
326  /**
327  * @brief Enable the API to use images in items in the list widget
328  * @details Defaults to GFXOFF
329  */
330  #ifndef GWIN_NEED_LIST_IMAGES
331  #define GWIN_NEED_LIST_IMAGES GFXOFF
332  #endif
333  /**
334  * @brief Enable the API to automatically increment the progressbar over time
335  * @details Defaults to GFXOFF
336  */
337  #ifndef GWIN_PROGRESSBAR_AUTO
338  #define GWIN_PROGRESSBAR_AUTO GFXOFF
339  #endif
340  /**
341  * @brief Should the slider avoid snapping to a fixed position when the mouse is released
342  * @details Defaults to GFXOFF
343  * @note If GFXOFF the slider will snap to the closest set-able position when the
344  * mouse is released. If GFXON it will maintain the position the
345  * mouse was released at, except when at the minimum and maximum slider values.
346  */
347  #ifndef GWIN_SLIDER_NOSNAP
348  #define GWIN_SLIDER_NOSNAP GFXOFF
349  #endif
350  /**
351  * @brief The number of pixels of dead-band at each end of the slider
352  * @details Defaults to 5
353  * @note A dead-band is required because fingers can often cannot
354  * accurately control the slider peg at the edges of the slider
355  */
356  #ifndef GWIN_SLIDER_DEAD_BAND
357  #define GWIN_SLIDER_DEAD_BAND 5
358  #endif
359  /**
360  * @brief How many toggles it takes to go from minimum to maximum value on a slider
361  * @details Defaults to 20
362  * @note When the slider is being operated by a toggle device this setting describes
363  * how many toggles are required to go from end to end.
364  */
365  #ifndef GWIN_SLIDER_TOGGLE_INC
366  #define GWIN_SLIDER_TOGGLE_INC 20
367  #endif
368  /**
369  * @brief The height in pixels of a row of tabs in a tabset
370  * @details Defaults to 18
371  */
372  #ifndef GWIN_TABSET_TABHEIGHT
373  #define GWIN_TABSET_TABHEIGHT 18
374  #endif
375  /**
376  * @brief Should flashing of widgets be supported
377  * @details Defaults to GFXOFF
378  * @pre Requires GWIN_NEED_WINDOWMANAGER to be GFXON
379  */
380  #ifndef GWIN_NEED_FLASHING
381  #define GWIN_NEED_FLASHING GFXOFF
382  #endif
383  /**
384  * @brief What is the period for the flashing timer
385  * @details Defaults to 250 milliseconds
386  */
387  #ifndef GWIN_FLASHING_PERIOD
388  #define GWIN_FLASHING_PERIOD 250
389  #endif
390  /**
391  * @brief The default keyboard layout for the virtual gwin keyboard
392  * @details Defaults to VirtualKeyboardLayout_English1
393  */
394  #ifndef GWIN_KEYBOARD_DEFAULT_LAYOUT
395  #define GWIN_KEYBOARD_DEFAULT_LAYOUT VirtualKeyboard_English1
396  #endif
397 /**
398  * @}
399  *
400  * @name GWIN Virtual Keyboard Layouts
401  * @brief One or more of these may be defined. They will only be created if GWIN_NEED_KEYBOARD is GFXON.
402  * @{
403  */
404  /**
405  * @brief The default keyboard layout for the virtual gwin keyboard
406  * @details Defaults to VirtualKeyboardLayout_English1
407  */
408  #ifndef GWIN_NEED_KEYBOARD_ENGLISH1
409  #define GWIN_NEED_KEYBOARD_ENGLISH1 GFXON
410  #endif
411 /** @} */
412 
413 #endif /* _GWIN_OPTIONS_H */
414 /** @} */