?lang_form? ?lang_select? ?lang_submit? ?lang_endform?
{HEADER END}
{BLAME START}

library

?curdirlinks? -

Blame information for rev 32

Line No. Rev Author Line
1 32 kaklik /*****************************************************************************
2 * Module for Microchip Graphics Library
3 * GOL Layer
4 * TextEntry
5 *****************************************************************************
6 * FileName: TextEntry.h
7 * Dependencies: None
8 * Processor: PIC24F, PIC24H, dsPIC, PIC32
9 * Compiler: MPLAB C30 V3.00, MPLAB C32
10 * Linker: MPLAB LINK30, MPLAB LINK32
11 * Company: Microchip Technology Incorporated
12 *
13 * Software License Agreement
14 *
15 * Copyright © 2008 Microchip Technology Inc. All rights reserved.
16 * Microchip licenses to you the right to use, modify, copy and distribute
17 * Software only when embedded on a Microchip microcontroller or digital
18 * signal controller, which is integrated into your product or third party
19 * product (pursuant to the sublicense terms in the accompanying license
20 * agreement).
21 *
22 * You should refer to the license agreement accompanying this Software
23 * for additional information regarding your rights and obligations.
24 *
25 * SOFTWARE AND DOCUMENTATION ARE PROVIDED “AS IS” WITHOUT WARRANTY OF ANY
26 * KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY
27 * OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR
28 * PURPOSE. IN NO EVENT SHALL MICROCHIP OR ITS LICENSORS BE LIABLE OR
29 * OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION,
30 * BREACH OF WARRANTY, OR OTHER LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT
31 * DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL,
32 * INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA,
33 * COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY
34 * CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF),
35 * OR OTHER SIMILAR COSTS.
36 *
37 * Author Date Comment
38 *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
39 * Harold Serrano 10/24/08 ...
40 *****************************************************************************/
41 #ifndef _TEXTENTRY_H
42 #define _TEXTENTRY_H
43  
44 #include <Graphics\GOL.h>
45  
46 /*********************************************************************
47 * Object States Definition:
48 *********************************************************************/
49 #define TE_KEY_PRESSED 0x0004 // Bit for press state of one of the keys.
50 #define TE_DISABLED 0x0002 // Bit for disabled state.
51 #define TE_ECHO_HIDE 0x0008 // Bit to hide the entered characters and instead echo "*" characters to the display.
52 #define TE_DRAW 0x4000 // Bit to indicate object must be redrawn.
53 #define TE_HIDE 0x8000 // Bit to indicate object must be removed from screen.
54 #define TE_UPDATE_KEY 0x2000 // Bit to indicate redraw of a key is needed.
55 #define TE_UPDATE_TEXT 0x1000 // Bit to indicate redraw of the text displayed is needed.
56  
57 /*********************************************************************
58 * Optional COMMANDS assigned to keys
59 *********************************************************************/
60 #define TE_DELETE_COM 0x01 // This macro is used to assign a "delete" command on a key.
61 #define TE_SPACE_COM 0x02 // This macro is used to assign an insert "space" command on a key.
62 #define TE_ENTER_COM 0x03 // This macro is used to assign an "enter" (carriage return) command on a key.
63  
64 // User can use this command to customize application code in the message
65  
66 // callback function. Use the returned translated TE_MSG_ENTER to detect the key
67  
68 // pressed was assigned the enter command. Refer to TeTranslateMsg() for details.
69  
70 /*********************************************************************
71 * Overview: Defines the parameters and the strings assigned for each key.
72 *********************************************************************/
73 typedef struct
74 {
75 SHORT left; // Left position of the key
76 SHORT top; // Top position of the key
77 SHORT right; // Right position of the key
78 SHORT bottom; // Bottom position of the key
79 SHORT index; // Index of the key in the list
80 WORD state; // State of the key. Either Pressed (TE_KEY_PRESSED) or Released (0)
81 BOOL update; // flag to indicate key is to be redrawn with the current state
82 WORD command; // Command of the key. Either TE_DELETE_COM, TE_SPACE_COM or TE_ENTER_COM.
83 XCHAR *pKeyName; // Pointer to the custom text assigned to the key. This is displayed over the face of the key.
84 SHORT textWidth; // Computed text width, done at creation. Used to predict size and position of text on the key face.
85 SHORT textHeight; // Computed text height, done at creation. Used to predict size and position of text on the key face.
86 void *pNextKey; // Pointer to the next key parameters.
87 } KEYMEMBER;
88  
89 /*********************************************************************
90 * Overview: Defines the parameters required for a TextEntry Object.
91 *********************************************************************/
92 typedef struct
93 {
94 OBJ_HEADER hdr; // Generic header for all objects (see OBJ_HEADER).
95 SHORT horizontalKeys; // Number of horizontal keys
96 SHORT verticalKeys; // Number of vertical keys
97 XCHAR *pTeOutput; // Pointer to the buffer assigned by the user which holds the text shown in the editbox.
98  
99 // User creates and manages the buffer. Buffer can also be managed using the APIs provided
100 // to add a character, delete the last character or clear the buffer.
101 WORD CurrentLength; // Current length of the string in the buffer. The maximum value of this is equal to outputLenMax.
102  
103 // TextEntry object will update this parameter when adding, removing characters or clearing the buffer
104 // and switching buffers.
105 WORD outputLenMax; // Maximum expected length of output buffer pTeOutput
106 KEYMEMBER *pActiveKey; // Pointer to the active key KEYMEMBER. This is only used by the Widget. User must not change
107  
108 // the value of this parameter directly.
109 KEYMEMBER *pHeadOfList; // Pointer to head of the list
110 void *pDisplayFont; // Pointer to the font used in displaying the text.
111 } TEXTENTRY;
112  
113 /*********************************************************************
114 * Function: TEXTENTRY *TeCreate(WORD ID, SHORT left, SHORT top,
115 * SHORT right, SHORT bottom, WORD state,
116 * SHORT horizontalKeys, SHORT verticalKeys, XCHAR *pText[],
117 * void *pBuffer, WORD bufferLength,void *pDisplayFont,
118 * GOL_SCHEME *pScheme)
119 *
120 * Overview: This function creates a TEXTENTRY object with the parameters given.
121 * It automatically attaches the new object into a global linked list of
122 * objects and returns the address of the object.
123 *
124 *
125 * PreCondition: If the object will use customized keys, the structure CUSTOMEKEYS must be
126 * populated before calling this function.
127 *
128 * Input: ID - Unique user defined ID for the object instance
129 * left- Left most position of the object.
130 * top - Top most position of the object.
131 * right - Right most position of the object.
132 * bottom - Bottom most position of the object.
133 * state - state of the widget.
134 * horizontalKeys - Number of horizontal keys
135 * verticalKeys - Number of vertical keys
136 * pText - array of pointer to the custom "text" assigned by the user.
137 * bufferLength - length of the buffer assigned by the user.
138 * pDisplayFont - pointer to the font image to be used on the editbox
139 * pScheme- Pointer to the style scheme used.
140 *
141 * Output Returns the pointer to the object created.
142 *
143 * Side Effects: none.
144 *
145 ********************************************************************/
146 TEXTENTRY *TeCreate
147 (
148 WORD ID,
149 SHORT left,
150 SHORT top,
151 SHORT right,
152 SHORT bottom,
153 WORD state,
154 SHORT horizontalKeys,
155 SHORT verticalKeys,
156 XCHAR *pText[],
157 void *pBuffer,
158 WORD bufferLength,
159 void *pDisplayFont,
160 GOL_SCHEME *pScheme
161 );
162  
163 /*********************************************************************
164 * Function: WORD TeDraw(TEXTENTRY *pTe)
165 *
166 * Overview: This function renders the object on the screen using
167 * the current parameter settings. Location of the object is
168 * determined by the left, top, right and bottom parameters.
169 * The colors used are dependent on the state of the object.
170 *
171 * This widget will draw the keys using the function
172 * GOLPanelDraw(). The number of keys will depend on the horizontal
173 * and vertical parameters given (horizontalKeys*verticakKeys).
174 *
175 * PreCondition: Object must be created before this function is called.
176 *
177 * Input: pTe- Pointer to the object to be rendered.
178 *
179 * Output: Returns the status of the drawing
180 * - 1 - If the rendering was completed and
181 * - 0 - If the rendering is not yet finished.
182 * Next call to the function will resume the
183 * rendering on the pending drawing state.
184 *
185 * Side Effects: none.
186 *
187 ********************************************************************/
188 WORD TeDraw(TEXTENTRY *pTe);
189  
190 /*********************************************************************
191 * Function: WORD TeTranslateMsg(TEXTENTRY *pTe, GOL_MSG *pMsg)
192 *
193 * Overview: This function evaluates the message from a user if the
194 * message will affect the object or not. If the message
195 * is valid, the keys in the Text Entry object will be
196 * scanned to detect which key was pressed. If True, the
197 * corresponding text will be displayed, the ‘text’ will
198 * also be stored in the TeOutput parameter of the object.
199 *
200 * <TABLE>
201 * Translated Message Input Source Events Description
202 * ################## ############ ###### ###########
203 * TE_MSG_PRESS Touch Screen EVENT_PRESS, EVENT_MOVE If the event occurs and the x,y position falls in the face of one of the keys of the object while the key is unpressed.
204 * TE_MSG_RELEASED Touch Screen EVENT_MOVE If the event occurs and the x,y position falls outside the face of one of the keys of the object while the key is pressed.
205 * TE_MSG_RELEASED Touch Screen EVENT_RELEASE If the event occurs and the x,y position falls does not falls inside any of the faces of the keys of the object.
206 * TE_MSG_ADD_CHAR Touch Screen EVENT_RELEASE, EVENT_MOVE If the event occurs and the x,y position falls in the face of one of the keys of the object while the key is unpressed and the key is associated with no commands.
207 * TE_MSG_DELETE Touch Screen EVENT_RELEASE, EVENT_MOVE If the event occurs and the x,y position falls in the face of one of the keys of the object while the key is unpressed and the key is associated with delete command.
208 * TE_MSG_SPACE Touch Screen EVENT_RELEASE, EVENT_MOVE If the event occurs and the x,y position falls in the face of one of the keys of the object while the key is unpressed and the key is associated with space command.
209 * TE_MSG_ENTER Touch Screen EVENT_RELEASE, EVENT_MOVE If the event occurs and the x,y position falls in the face of one of the keys of the object while the key is unpressed and the key is associated with enter command.
210 * OBJ_MSG_INVALID Any Any If the message did not affect the object.
211 * </TABLE>
212 *
213 * PreCondition: none
214 *
215 * Input: pTe- The pointer to the object where the message will be
216 * evaluated to check if the message will affect the object.
217 * pMsg- Pointer to the message struct containing the message from
218 * the user interface.
219 *
220 * Output: Returns the translated message depending on the received GOL message:
221 * - TE_MSG_PRESS – A key is pressed
222 * - TE_MSG_RELEASED - A key was released (generic for keys with no commands or characters assigned)
223 * - TE_MSG_ADD_CHAR – A key was released with character assigned
224 * - TE_MSG_DELETE – A key was released with delete command assigned
225 * - TE_MSG_SPACE - A key was released with space command assigned
226 * - TE_MSG_ENTER - A key was released with enter command assigned
227 * - OBJ_MSG_INVALID – Text Entry is not affected
228 *
229 * Side Effects: none.
230 *
231 ********************************************************************/
232 WORD TeTranslateMsg(TEXTENTRY *pTe, GOL_MSG *pMsg);
233  
234 /*********************************************************************
235 * Function: TeMsgDefault(WORD translatedMsg, TEXTENTRY *pTe, GOL_MSG* pMsg)
236 *
237 * Overview: This function performs the actual state change
238 * based on the translated message given. The following state changes
239 * are supported:
240 * <TABLE>
241 * Translated Message Input Source Set/Clear State Bit Description
242 * ################## ############ ###### ###########
243 * TE_MSG_ADD_CHAR Touch Screen, Set TE_UPDATE_TEXT, Add a character in the buffer and update the text displayed.
244 * TE_UPDATE_KEY,
245 * Clear TE_KEY_PRESSED
246 * TE_MSG_SPACE Touch Screen, Set TE_UPDATE_TEXT, Insert a space character in the buffer and update the text displayed.
247 * TE_UPDATE_KEY,
248 * Clear TE_KEY_PRESSED
249 * TE_MSG_DELETE Touch Screen, Set TE_UPDATE_TEXT, Delete the most recent character in the buffer and update the text displayed.
250 * TE_UPDATE_KEY,
251 * Clear TE_KEY_PRESSED
252 * TE_MSG_ENTER Touch Screen, Set TE_UPDATE_TEXT, User can define the use of this event in the message callback. Object will just update the key.
253 * TE_UPDATE_KEY,
254 * Clear TE_KEY_PRESSED
255 * TE_MSG_RELEASED Touch Screen, Clear TE_KEY_PRESSED A Key in the object will be redrawn in the unpressed state.
256 * Set Te_UPDATE_KEY
257 * TE_MSG_PRESSED Touch Screen, Set TE_KEY_PRESSED A Key in the object will be redrawn in the pressed state.
258 * TE_UPDATE_KEY
259 *
260 * </TABLE>
261 *
262 * PreCondition: none
263 *
264 * Input: translatedMsg - The translated message.
265 * pTe - The pointer to the object whose state will be modified.
266 * pMsg - The pointer to the GOL message.
267 *
268 * Output: none
269 *
270 * Example:
271 * See BtnTranslateMsg() example.
272 *
273 * Side Effects: none
274 *
275 ********************************************************************/
276 void TeMsgDefault(WORD translatedMsg, TEXTENTRY *pTe, GOL_MSG *pMsg);
277  
278 /*********************************************************************
279 * Function: void TeSetBuffer(TEXTENTRY *pTe, XCHAR *pText, WORD MaxSize)
280 *
281 * Overview: This function sets the buffer used to display text. If the
282 * buffer is initialized with a string, the string must be
283 * a null terminated string. If the string length is greater
284 * than MaxSize, string will be truncated to MaxSize.
285 * pText must point to a valid memory location with size equal
286 * to MaxSize+1. The +1 is used for the string terminator.
287 *
288 *
289 * PreCondition: none
290 *
291 * Input: pTe- pointer to the object
292 * pText- pointer to the new text buffer to be displayed
293 * maxSize - maximum length of the new buffer to be used.
294 * Output: none.
295 *
296 * Side Effects: none.
297 *
298 ********************************************************************/
299 void TeSetBuffer(TEXTENTRY *pTe, XCHAR *pText, WORD MaxSize);
300  
301 /*********************************************************************
302 * Macro: TeGetBuffer(pTe)
303 *
304 * Overview: This macro will return the currently used buffer in the
305 * TextEntry object.
306 *
307 * PreCondition: none
308 *
309 * Input: pTe- pointer to the object
310 *
311 * Output: It will return a pointer to the buffer used.
312 *
313 * Side Effects: none.
314 *
315 ********************************************************************/
316 #define TeGetBuffer(pTe) (((TEXTENTRY *)pTe)->pTeOutput)
317  
318 /*********************************************************************
319 * Function: void TeClearBuffer (TEXTENTRY *pTe)
320 *
321 * Overview: This function will clear the data in the display. You must
322 * set the drawing state bit TE_UPDATE_TEXT
323 * to update the TEXTENTRY on the screen.
324 *
325 * PreCondition: none
326 *
327 * Input: pTe- pointer to the object
328 *
329 * Output: none
330 *
331 * Side Effects: none.
332 *
333 ********************************************************************/
334 void TeClearBuffer(TEXTENTRY *pTe);
335  
336 /*********************************************************************
337 * Function: BOOL TeIsKeyPressed(TEXTENTRY *pTe, WORD index)
338 *
339 * Overview: This function will test if a key given by its index
340 * in the TextEntry object has been pressed.
341 *
342 * PreCondition: none
343 *
344 * Input: pTe- pointer to the object
345 * index- index to the key in the link list
346 * Output: Returns a TRUE if the key is pressed. FALSE if key
347 * is not pressed or the given index does not exist in
348 * the list.
349 *
350 * Side Effects: none.
351 *
352 ********************************************************************/
353 BOOL TeIsKeyPressed(TEXTENTRY *pTe, WORD index);
354  
355 /*********************************************************************
356 * Function: void TeSetKeyCommand(TEXTENTRY *pTe,WORD index,WORD command)
357 *
358 * Overview: This function will assign a command (TE_DELETE_COM, TE_SPACE_COM
359 * or TE_ENTER_COM) to a key with the given index.
360 *
361 * PreCondition: none
362 *
363 * Input: pTe - pointer to the object
364 * index - index to the key in the link list
365 * command- command assigned for the key
366 *
367 * Output: Returns TRUE if successful and FALSE if not.
368 *
369 * Side Effects: none.
370 *
371 ********************************************************************/
372 BOOL TeSetKeyCommand(TEXTENTRY *pTe, WORD index, WORD command);
373  
374 /*********************************************************************
375 * Function: TeGetKeyCommand(pTe, index)
376 *
377 * Overview: This function will return the currently used command by a key
378 * with the given index.
379 *
380 * PreCondition: none
381 *
382 * Input: pTe- pointer to the object
383 * index- index to the key in the link list
384 *
385 * Output: It will return the command ID currently set for the key. If the
386 * given index is not in the list the function returns zero.
387 * 0x00 - no command is assigned or the index given does not exist.
388 * 0x01 - TE_DELETE_COM
389 * 0x02 - TE_SPACE_COM
390 * 0x03 - TE_ENTER_COM
391 *
392 * Side Effects: none.
393 *
394 ********************************************************************/
395 WORD TeGetKeyCommand(TEXTENTRY *pTe, WORD index);
396  
397 /*********************************************************************
398 * Function: TeSetKeyText(TEXTENTRY *pTe, WORD index, XCHAR *pText)
399 *
400 * Overview: This function will set the test assigned to a key with
401 * the given index.
402 *
403 * PreCondition: none
404 *
405 * Input: pTe - pointer to the object
406 * index - index to the key in the link list
407 * pText - pointer to the new string to be used
408 *
409 * Output: Returns TRUE if successful and FALSE if not.
410 *
411 * Side Effects: none.
412 *
413 ********************************************************************/
414 BOOL TeSetKeyText(TEXTENTRY *pTe, WORD index, XCHAR *pText);
415  
416 /*********************************************************************
417 * Function: KEYMEMBER *TeCreateKeyMembers(TEXTENTRY *pTe,XCHAR *pText[])
418 *
419 * Overview: This function will create the list of KEYMEMBERS that holds the
420 * information on each key. The number of keys is determined by the
421 * equation (verticalKeys*horizontalKeys). The object creates the information
422 * holder for each key automatically and assigns each entry in the *pText[]
423 * array with the first entry automatically assigned to the key with an
424 * index of 1. The number of entries to *pText[] must be equal or greater
425 * than (verticalKeys*horizontalKeys). The last key is assigned with an index
426 * of (verticalKeys*horizontalKeys)-1. No checking is performed on the
427 * length of *pText[] entries to match (verticalKeys*horizontalKeys).
428 *
429 * PreCondition: none
430 *
431 * Input: pTe - pointer to the object
432 * pText - pointer to the text defined by the user
433 *
434 * Output: Returns the pointer to the newly created KEYMEMBER list. A NULL is returned
435 * if the list is not created succesfully.
436 *
437 * Side Effects: none.
438 *
439 ********************************************************************/
440 KEYMEMBER *TeCreateKeyMembers(TEXTENTRY *pTe, XCHAR *pText[]);
441  
442 /*********************************************************************
443 * Function: void TeDelKeyMembers(TEXTENTRY *pTe)
444 *
445 * Overview: This function will delete the KEYMEMBER list assigned to
446 * the object from memory. Pointer to the KEYMEMBER list is
447 * then initialized to NULL.
448 *
449 * PreCondition: none
450 *
451 * Input: pTe - pointer to the object
452 *
453 * Output: none.
454 *
455 * Side Effects: none.
456 *
457 ********************************************************************/
458 void TeDelKeyMembers(TEXTENTRY *pTe);
459  
460 /*********************************************************************
461 * Function: void TeSpaceChar(TEXTENTRY *pTe)
462 *
463 * Overview: This function will insert a space character to the end of
464 * the buffer. Drawing states TE_UPDATE_TEXT or TE_DRAW must
465 * be set to see the effect of this insertion.
466 *
467 * PreCondition: none
468 *
469 * Input: pTe - pointer to the object
470 *
471 * Output: none.
472 *
473 * Side Effects: none.
474 *
475 ********************************************************************/
476 void TeSpaceChar(TEXTENTRY *pTe);
477  
478 /*********************************************************************
479 * Function: void TeAddChar(TEXTENTRY *pTe)
480 *
481 * Overview: This function will insert a character to the end of
482 * the buffer. The character inserted is dependent on the
483 * currently pressed key. Drawing states TE_UPDATE_TEXT or
484 * TE_DRAW must be set to see the effect of this insertion.
485 *
486 * PreCondition: none
487 *
488 * Input: pTe - pointer to the object
489 *
490 * Output:
491 *
492 * Side Effects: none.
493 *
494 ********************************************************************/
495 void TeAddChar(TEXTENTRY *pTe);
496 #endif // _TEXTENTRY_H
{BLAME END}
{FOOTER START}

Powered by WebSVN v2.8.3