version 2.8
gwin_textedit.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_textedit.h
10  * @brief GWIN textedit widget header file
11  *
12  * @defgroup TextEdit TextEdit
13  * @ingroup Widgets
14  *
15  * @brief Widget that accepts text input.
16  *
17  * @note Due to the modularity of the @p GINPUT module, the text input can either come from a real physical
18  * keyboard or from a vritual on-screen keyboard such as the @p KeyboardWidget.
19  *
20  * @pre GFX_USE_GDISP must be set to TRUE in your gfxconf.h
21  * @pre GFX_USE_GWIN must be set to TRUE in your gfxconf.h
22  * @pre GDISP_NEED_TEXT must be set to TRUE in your gfxconf.h
23  * @pre GWIN_NEED_TEXTEDIT must be set to TRUE in your gfxconf.h
24  * @pre The fonts you want to use must be enabled in your gfxconf.h
25  *
26  * @{
27  */
28 
29 #ifndef _GWIN_TEXTEDIT_H
30 #define _GWIN_TEXTEDIT_H
31 
32 // This file is included within "src/gwin/gwin_widget.h"
33 
34 // A TextEdit widget
35 typedef struct GTexteditObject {
36  GWidgetObject w;
37 
38  char* textBuffer;
39  size_t maxSize;
40  uint16_t cursorPos;
41 } GTexteditObject;
42 
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
46 
47 /**
48  * @brief Create a TextEdit widget
49  * @details A TextEdit widget is a rectangular box which allows the user to input data through a keyboard.
50  * The keyboard can either be a physical one or a virtual on-screen keyboard as the keyboard driver
51  * is abstracted through the GINPUT module.
52  *
53  * @param[in] g The GDisplay on which the textedit should be displayed
54  * @param[in] wt The TextEdit structure to initialise. If this is NULL, the structure is dynamically allocated.
55  * @param[in] pInit The initialisation parameters to use.
56  * @param[in] maxSize The maximum number of characters the TextEdit widget can hold. (0 means unlimited).
57  *
58  * @return NULL if there is no resultant drawing area, otherwise the widget handle.
59  *
60  * @note If the initial text set is larger than maxSize then the text is truncated at maxSize characters.
61  * @api
62  */
63 GHandle gwinGTexteditCreate(GDisplay* g, GTexteditObject* wt, GWidgetInit* pInit, size_t maxSize);
64 #define gwinTexteditCreate(wt, pInit, maxSize) gwinGTexteditCreate(GDISP, wt, pInit, maxSize)
65 
66 /**
67  * @brief Send a special key to the textedit such as GKEY_LEFT, GKEY_RIGHT, GKEY_HOME, GKEY_END
68  *
69  * @param[in] gh The window handle (must be a textedit window)
70  * @param[in] key The special key to send.
71  * @pre Requires GINPUT_NEED_KEYBOARD or GWIN_NEED_KEYBOARD to be on
72  * @api
73  */
74 void gwinTextEditSendSpecialKey(GHandle gh, uint8_t key);
75 
76 /**
77  * @brief Send a normal utf8 character to the textedit
78  *
79  * @param[in] gh The window handle (must be a textedit window)
80  * @param[in] pkey The pointer to the utf8 character to send.
81  * @param[in] len The length of the utf8 character in bytes.
82  * @note This must ONLY be called with a single utf8 character at a time. Don't attempt to
83  * send a string of characters in the one call.
84  * @note Characters are interpreted as if they came directly from a keyboard ie a backspace
85  * character will perform the backspace operation, a tab will send the focus to the next
86  * control etc.
87  * @pre Requires GINPUT_NEED_KEYBOARD or GWIN_NEED_KEYBOARD to be on
88  * @api
89  */
90 void gwinTextEditSendKey(GHandle gh, char *pkey, unsigned len);
91 
92 /**
93  * @defgroup Renderings_Textedit Renderings
94  *
95  * @brief Built-in rendering functions for the textedit widget.
96  *
97  * @details These function may be passed to @p gwinSetCustomDraw() to get different textedit drawing styles.
98  *
99  * @note In your custom textedit drawing function you may optionally call these
100  * standard functions and then draw your extra details on top.
101  * @note These custom drawing routines don't have to worry about setting clipping as the framework
102  * sets clipping to the object window prior to calling these routines.
103  *
104  * @{
105  */
106 
107 /**
108  * @brief The default rendering function for the textedit widget.
109  *
110  * @param[in] gw The widget object (must be a button textedit).
111  * @param[in] param A parameter passed in from the user. Ignored by this function.
112  *
113  * @api
114  */
115 void gwinTexteditDefaultDraw(GWidgetObject* gw, void* param);
116 
117 /** @} */
118 
119 #ifdef __cplusplus
120 }
121 #endif
122 
123 #endif // _GWIN_TEXTEDIT_H
124 /** @} */
void gwinTextEditSendSpecialKey(GHandle gh, uint8_t key)
Send a special key to the textedit such as GKEY_LEFT, GKEY_RIGHT, GKEY_HOME, GKEY_END.
The structure to initialise a widget.
Definition: gwin_widget.h:97
void gwinTexteditDefaultDraw(GWidgetObject *gw, void *param)
The default rendering function for the textedit widget.
GHandle gwinGTexteditCreate(GDisplay *g, GTexteditObject *wt, GWidgetInit *pInit, size_t maxSize)
Create a TextEdit widget.
void gwinTextEditSendKey(GHandle gh, char *pkey, unsigned len)
Send a normal utf8 character to the textedit.
The GWIN Widget structure.
Definition: gwin_widget.h:118
A window object structure.
Definition: gwin.h:40