?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 * List box
5 *****************************************************************************
6 * FileName: ListBox.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 * Anton Alkhimenok 11/12/07 Version 1.0 release
40 *****************************************************************************/
41 #ifndef _LISTBOX_H
42 #define _LISTBOX_H
43  
44 #include <Graphics\GOL.h>
45  
46 /*********************************************************************
47 * Object States Definition:
48 *********************************************************************/
49 #define LB_FOCUSED 0x0001 // Bit for focused state
50 #define LB_DISABLED 0x0002 // Bit for disabled state
51 #define LB_RIGHT_ALIGN 0x0004 // Bit to indicate text is left aligned
52 #define LB_CENTER_ALIGN 0x0008 // Bit to indicate text is center aligned
53 #define LB_SINGLE_SEL 0x0010 // Bit to indicate the only item can be selected
54 #define LB_DRAW_ITEMS 0x1000 // Bit to indicate whole edit box must be redrawn
55 #define LB_DRAW_FOCUS 0x2000 // Bit to indicate whole edit box must be redrawn
56 #define LB_DRAW 0x4000 // Bit to indicate whole edit box must be redrawn
57 #define LB_HIDE 0x8000 // Bit to remove object from screen
58 #define LB_INDENT 0x02 // Indentation constant for the text from the frame
59  
60 /*********************************************************************
61 * Overview: Defines the parameters required for a list item used in
62 * list box.
63 *
64 *********************************************************************/
65 typedef struct
66 {
67 void *pPrevItem; // Pointer to the next item
68 void *pNextItem; // Pointer to the next item
69 WORD status; // Specifies the status of the item.
70  
71 // The following values are defined for
72 // the status: LB_STS_SELECTED, LB_STS_REDRAW.
73 XCHAR *pText; // Pointer to the text for the item
74 void *pBitmap; // Pointer to the bitmap
75 WORD data; // Some data associated with the item
76 } LISTITEM;
77  
78 /*********************************************************************
79 * Bit definitions for the status of an item
80 *********************************************************************/
81 #define LB_STS_SELECTED 0x0001 // Item is selected.
82 #define LB_STS_REDRAW 0x0002 // Item is to be redrawn.
83  
84 /*********************************************************************
85 * Overview: Defines the parameters required for a list box Object.
86 *
87 *********************************************************************/
88 typedef struct
89 {
90 OBJ_HEADER hdr; // Generic header for all Objects (see OBJ_HEADER).
91 LISTITEM *pItemList; // Pointer to the list of items.
92 LISTITEM *pFocusItem; // Pointer to the focused item.
93 WORD itemsNumber; // Number of items in the list box.
94 SHORT scrollY; // Scroll displacement for the list.
95 SHORT textHeight; // Pre-computed text height.
96 } LISTBOX;
97  
98 /*********************************************************************
99 * Macros: LbSetBitmap(pItem, pBtmap)
100 *
101 * Overview: This macro sets the bitmap used in the item.
102 *
103 * PreCondition: none
104 *
105 * Input: pItem - Pointer to the item.
106 * pBtmap - Pointer to the bitmap to be used.
107 *
108 * Output: none
109 *
110 * Example:
111 * See LbAddItem() example.
112 *
113 * Side Effects: none
114 *
115 ********************************************************************/
116 #define LbSetBitmap(pItem, pBtmap) ((LISTITEM *)pItem)->pBitmap = pBtmap
117  
118 /*********************************************************************
119 * Macros: LbGetBitmap(pItem)
120 *
121 * Overview: This macro returns the location of the currently
122 * used bitmap for the item.
123 *
124 * PreCondition: none
125 *
126 * Input: pItem - Pointer to the list item.
127 *
128 * Output: Returns the pointer to the current bitmap used.
129 *
130 * Example:
131 * <CODE>
132 * // Assume pLb is initialized to an existing list box
133 * LISTITEM *pItem;
134 * void *pBitmap;
135 *
136 * pItem = LbGetItemList(pLb);
137 * pBitmap = LbGetBitmap(pItem);
138 * </CODE>
139 *
140 * Side Effects: none
141 *
142 ********************************************************************/
143 #define LbGetBitmap(pItem) ((LISTITEM *)pItem)->pBitmap
144  
145 /*********************************************************************
146 * Function: LISTBOX *LbCreate(WORD ID, SHORT left, SHORT top, SHORT right,
147 * SHORT bottom, WORD state, XCHAR* pText,
148 * GOL_SCHEME *pScheme)
149 *
150 * Overview: This function creates a LISTBOX object with the parameters given.
151 * It automatically attaches the new object into a global linked list of
152 * objects and returns the address of the object.
153 *
154 * PreCondition: none
155 *
156 * Input: ID - Unique user defined ID for the object instance.
157 * left - Left most position of the Object.
158 * top - Top most position of the Object.
159 * right - Right most position of the Object.
160 * bottom - Bottom most position of the Object.
161 * pText - Pointer to the initialization text for the items.
162 * pScheme - Pointer to the style scheme.
163 *
164 * Output: Returns the pointer to the object created.
165 *
166 * Example:
167 * <CODE>
168 * #define LISTBOX_ID 10
169 *
170 * const XCHAR ItemList[] = "Line1\n" "Line2\n";
171 *
172 * GOL_SCHEME *pScheme;
173 * LISTBOX *pLb;
174 * XCHAR *pTemp;
175 * WORD state, counter;
176 *
177 * pScheme = GOLCreateScheme();
178 * state = LB_DRAW;
179 *
180 * // create an empty listbox with default style scheme
181 * pLb = LbCreate( LISTBOX_ID, // ID number
182 * 10,10,150,200, // dimension
183 * state, // initial state
184 * NULL, // set items to be empty
185 * NULL); // use default style scheme
186 * // check if Listbox was created
187 * if (pLb == NULL)
188 * return 0;
189 *
190 * // create the list of items to be placed in the listbox
191 * // Add items (each line will become one item,
192 * // lines must be separated by '\n' character)
193 * pTemp = ItemList;
194 * counter = 0;
195 * while(*pTemp){
196 * // since each item is appended NULL is assigned to
197 * // LISTITEM pointer.
198 * if(NULL == LbAddItem(pLb, NULL, pTemp, NULL, 0, counter))
199 * break;
200 * while((unsigned XCHAR)*pTemp++ > (unsigned XCHAR)31);
201 * if(*(pTemp-1) == 0)
202 * break;
203 * counter++;
204 * }
205 * </CODE>
206 *
207 * Side Effects: none
208 *
209 ********************************************************************/
210 LISTBOX * LbCreate
211 (WORD ID, SHORT left, SHORT top, SHORT right, SHORT bottom, WORD state, XCHAR * pText, GOL_SCHEME * pScheme);
212  
213 /*********************************************************************
214 * Function: LISTITEM* LbAddItem(LISTBOX *pLb, LISTITEM *pPrevItem,
215 * XCHAR *pText, void* pBitmap, WORD status, WORD data)
216 *
217 * Overview: This function allocates memory for the LISTITEM and adds
218 * it to the list box. The newly created LISTITEM will store
219 * the location of pText, pBitmap and other parameters describing
220 * the added item.
221 *
222 * PreCondition: none
223 *
224 * Input: pLb - The pointer to the list box object.
225 * pPrevItem - Pointer to the item after which a new item must
226 * be inserted, if this pointer is NULL, the item
227 * will be appended at the end of the items list.
228 * pText - Pointer to the text that will be inserted. Text must
229 * persist in memory for as long as it is referenced
230 * by an item in the list box.
231 * pBitmap - Pointer to the bitmap for the item. Bitmap must
232 * persist in memory for as long as it is referenced
233 * by the an item in the list box.
234 * status - This parameter specifies if the item being added
235 * will be selected or redrawn
236 * (LB_STS_SELECTED or LB_STS_REDRAW). Refer to
237 * LISTITEM structure for details.
238 * data - User assigned data associated with the item.
239 *
240 * Output: Return a pointer to the item created,
241 * NULL if the operation was not successful.
242 *
243 * Example:
244 * <CODE>
245 * const XCHAR ItemList[] = "Line1\n" "Line2\n" "Line3\n";
246 *
247 * extern BITMAP_FLASH myIcon;
248 * LISTBOX *pLb;
249 * LISTITEM *pItem, *pItemList;
250 * XCHAR *pTemp;
251 *
252 * // Assume that pLb is pointing to an existing list box in memory
253 * // that is empty (no list).
254 *
255 * // Create the list of the list box
256 *
257 * // Initialize this to NULL to indicate that items will be added
258 * // at the end of the list if the list exist on the list box or
259 * // start a new list if the list box is empty.
260 * pItem = NULL;
261 * pTemp = ItemList;
262 * pItem = LbAddItem(pLb, pItem, pTemp, NULL, LB_STS_SELECTED, 1)
263 * if(pItem == NULL)
264 * return 0;
265 * LbSetBitmap(pItem, &myIcon);
266 *
267 * // Adjust pTemp to point to the next line
268 * while((unsigned XCHAR)*pTemp++ > (unsigned XCHAR)31);
269 *
270 * // add the next item
271 * pItem = LbAddItem(pLb, pItem, pTemp, NULL, 0, 2)
272 * if(pItem == NULL)
273 * return 0;
274 * LbSetBitmap(pItem, &myIcon);
275 *
276 * // Adjust pTemp to point to the next line
277 * while((unsigned XCHAR)*pTemp++ > (unsigned XCHAR)31);
278 *
279 * // this time insert the next item after the first item on the list
280 * pItem = LbGetItemList(pLb);
281 * pItem = LbAddItem(pLb, pItem, pTemp, NULL, 0, 3)
282 * if(pItem == NULL)
283 * return 0;
284 * LbSetBitmap(pItem, &myIcon);
285 *
286 * </CODE>
287 *
288 * Side Effects: none
289 *
290 ********************************************************************/
291 LISTITEM *LbAddItem(LISTBOX *pLb, LISTITEM *pPrevItem, XCHAR *pText, void *pBitmap, WORD status, WORD data);
292  
293 /*********************************************************************
294 * Function: void LbDelItem(LISTBOX *pLb, LISTITEM *pItem)
295 *
296 * Overview: This function removes an item from the list box
297 * and frees the memory used.
298 *
299 * PreCondition: none
300 *
301 * Input: pLb - The pointer to the list box object.
302 * pItem - The pointer to the item that will be removed.
303 *
304 * Output: none
305 *
306 * Side Effects: none
307 *
308 ********************************************************************/
309 void LbDelItem(LISTBOX *pLb, LISTITEM *pItem);
310  
311 /*********************************************************************
312 * Function: void LbDelItemsList(LISTBOX *pLb)
313 *
314 * Overview: This function removes all items from the list box
315 * and frees the memory used.
316 *
317 * PreCondition: none
318 *
319 * Input: pLb - The pointer to the list box object.
320 *
321 * Output: none
322 *
323 * Side Effects: none
324 *
325 ********************************************************************/
326 void LbDelItemsList(LISTBOX *pLb);
327  
328 /*********************************************************************
329 * Function: LISTITEM* LbGetSel(LISTBOX *pLb, LISTITEM *pFromItem)
330 *
331 * Overview: This function searches for selected items from the list box.
332 * A starting position can optionally be given. If starting
333 * position is set to NULL, search will begin from the first
334 * item list. It returns the pointer to the first selected item
335 * found or NULL if there are no items selected.
336 *
337 * PreCondition: none
338 *
339 * Input: pLb - The pointer to the list box object.
340 * pFromItem - The pointer to the item the search must start from,
341 * if the pointer is NULL the search begins from the
342 * start of the items list.
343 *
344 * Output: pointer to the selected item, NULL if there are no items selected
345 *
346 *
347 * Side Effects: none
348 *
349 ********************************************************************/
350 LISTITEM *LbGetSel(LISTBOX *pLb, LISTITEM *pFromItem);
351  
352 /*********************************************************************
353 * Function: void LbChangeSel(LISTBOX *pLb, LISTITEM *pItem)
354 *
355 * Overview: This function changes the selection status of an item
356 * in the list box. If the item is currently selected, it
357 * resets the selection. If the item is currently not
358 * selected it is set to be selected.
359 *
360 * PreCondition: none
361 *
362 * Input: pLb - The pointer to the list box object.
363 * pItem - The pointer to the item the selection status
364 * will be changed.
365 *
366 * Output: none
367 *
368 * Side Effects: none
369 *
370 ********************************************************************/
371 void LbChangeSel(LISTBOX *pLb, LISTITEM *pItem);
372  
373 /*********************************************************************
374 * Macro: LbSetSel(pLb, pItem)
375 *
376 * Overview: This macro sets the selection status of an item to
377 * selected.
378 *
379 * PreCondition: none
380 *
381 * Input: pLb - The pointer to the list box object.
382 * pItem - The pointer to the item the selection status
383 * will be set.
384 *
385 * Output: none
386 *
387 * Side Effects: none
388 *
389 ********************************************************************/
390 #define LbSetSel(pLb, pItem) \
391 if(!(pItem->status & LB_STS_SELECTED)) \
392 LbChangeSel((LISTBOX *)pLb, pItem);
393  
394 /*********************************************************************
395 * Macro: LbClrSel(pLb, pItem)
396 *
397 * Overview: This macro clears the selection of an item.
398 *
399 * PreCondition: none
400 *
401 * Input: pLb - The pointer to the list box.
402 * pItem - The pointer to the item the selection status should be cleared.
403 *
404 * Output: none
405 *
406 * Side Effects: none
407 *
408 ********************************************************************/
409 #define LbClrtSel(pLb, pItem) \
410 if(pItem->status & LB_STS_SELECTED) \
411 LbChangeSel((LISTBOX *)pLb, pItem);
412  
413 /*********************************************************************
414 * Macro: LbGetCount(pLb)
415 *
416 * Overview: This macro returns the number of items in the list box.
417 *
418 * PreCondition: none
419 *
420 * Input: pLb - The pointer to the list box object.
421 *
422 * Output: The number of items the list box contains.
423 *
424 * Side Effects: none
425 *
426 ********************************************************************/
427 #define LbGetCount(pLb) ((LISTBOX *)pLb)->itemsNumber
428  
429 /*********************************************************************
430 * Macro: LbGetVisibleCount(pLb)
431 *
432 * Overview: This macro returns the number of items visible in the
433 * list box window.
434 *
435 * PreCondition: none
436 *
437 * Input: pLb - The pointer to the list box object.
438 *
439 * Output: The number of items visible in the list box window.
440 *
441 * Side Effects: none
442 *
443 ********************************************************************/
444 #define LbGetVisibleCount(pLb) \
445 ( \
446 (((LISTBOX *)pLb)->hdr.bottom - ((LISTBOX *)pLb)->hdr.top - 2 * (GOL_EMBOSS_SIZE + LB_INDENT)) / \
447 ((LISTBOX *)pLb)->textHeight \
448 )
449  
450 /*********************************************************************
451 * Function: void LbSetFocusedItem(LISTBOX* pLb, SHORT index)
452 *
453 * Overview: This function sets the focus for the item with the
454 * given index.
455 *
456 * PreCondition: none
457 *
458 * Input: pLb - The pointer to the list box object.
459 * index - The index number of the item to be focused.
460 * First item on the list is always indexed 0.
461 *
462 * Output: none.
463 *
464 * Side Effects: none
465 *
466 ********************************************************************/
467 void LbSetFocusedItem(LISTBOX *pLb, SHORT index);
468  
469 /*********************************************************************
470 * Function: SHORT LbGetFocusedItem(LISTBOX* pLb)
471 *
472 * Overview: This function returns the index of the focused item
473 * in the list box.
474 *
475 * PreCondition: none
476 *
477 * Input: pLb - The pointer to the list box object.
478 *
479 * Output: Returns the index of the focused item in the list box.
480 *
481 * Side Effects: none
482 *
483 ********************************************************************/
484 SHORT LbGetFocusedItem(LISTBOX *pLb);
485  
486 /*********************************************************************
487 * Macro: LISTITEM LbGetItemList(LISTBOX* pLb)
488 *
489 * Overview: This function returns the pointer to the current
490 * item list used in the list box.
491 *
492 * PreCondition: none
493 *
494 * Input: pLb - The pointer to the list box object.
495 *
496 * Output: Returns the pointer to the LISTITEM used in the list box.
497 *
498 * Example:
499 * See LbAddItem() example.
500 *
501 * Side Effects: none
502 *
503 ********************************************************************/
504 #define LbGetItemList(pLb) ((LISTITEM *)pLb->pItemList)
505  
506 /*********************************************************************
507 * Function: WORD LbTranslateMsg(LISTBOX *pLb, GOL_MSG *pMsg)
508 *
509 * Overview: This function evaluates the message from a user if the
510 * message will affect the object or not. The table below enumerates the translated
511 * messages for each event of the touch screen and keyboard inputs.
512 *
513 * <TABLE>
514 * Translated Message Input Source Events Description
515 * ################## ############ ###### ###########
516 * LB_MSG_TOUCHSCREEN Touch Screen Any Item is selected using touch screen.
517 * LB_MSG_MOVE Keyboard EVENT_KEYSCAN Focus is moved to the next item depending on the key pressed (UP or DOWN key).
518 * LB_MSG_SEL Keyboard EVENT_KEYSCAN LB_MSG_SEL – Selection is set to the currently focused item.
519 * OBJ_MSG_INVALID Any Any If the message did not affect the object.
520 * </TABLE>
521 *
522 * PreCondition: none
523 *
524 * Input: pLB - The pointer to the object where the message will be
525 * evaluated to check if the message will affect the object.
526 * pMsg - Pointer to the message struct containing the message from
527 * the user interface.
528 *
529 * Output: Returns the translated message depending on the received GOL message:
530 * - LB_MSG_TOUCHSCREEN – Item is selected using touch screen.
531 * - LB_MSG_MOVE – Focus is moved to the next item depending on the key pressed (UP or DOWN key).
532 * - LB_MSG_SEL – Selection is set to the currently focused item.
533 *
534 * Side Effects: none
535 *
536 ********************************************************************/
537 WORD LbTranslateMsg(LISTBOX *pLb, GOL_MSG *pMsg);
538  
539 /*********************************************************************
540 * Function: void LbMsgDefault(WORD translatedMsg, LISTBOX *pLb, GOL_MSG *pMsg)
541 *
542 * Overview: This function performs the actual state change
543 * based on the translated message given. The following state changes
544 * are supported:
545 * <TABLE>
546 * Translated Message Input Source Set/Clear State Bit Description
547 * ################## ############ ###### ###########
548 * LB_MSG_TOUCHSCREEN Touch Screen Set LB_FOCUSED, If focus is enabled, the focus state bit LB_FOCUSED will be set. LB_DRAW_FOCUS draw state bit will force
549 * Set LB_DRAW_FOCUS the List Box to be redrawn with focus.
550 * Set LB_DRAW_ITEMS List Box will redrawn with selected item(s).
551 * LB_MSG_MOVE KeyBoard Set LB_DRAW_ITEMS List Box will redrawn with focus on one item.
552 * LB_MSG_SEL KeyBoard Set LB_DRAW_ITEMS List Box will redrawn with selection on the current item focused.
553 * </TABLE>
554 *
555 * PreCondition: none
556 *
557 * Input: translatedMsg - The translated message
558 * pB - The pointer to the object whose state will be modified.
559 * pMsg - The pointer to the GOL message.
560 *
561 * Output: none
562 *
563 * Side Effects: none
564 *
565 ********************************************************************/
566 void LbMsgDefault(WORD translatedMsg, LISTBOX *pLb, GOL_MSG *pMsg);
567  
568 /*********************************************************************
569 * Function: WORD LbDraw(LISTBOX *pLb)
570 *
571 * Overview: This function renders the object on the screen using
572 * the current parameter settings. Location of the object is
573 * determined by the left, top, right and bottom parameters.
574 * The colors used are dependent on the state of the object.
575 * The font used is determined by the style scheme set.
576 *
577 * The text or items drawn in the visible window of the
578 * list box is dependent on the alignment set.
579 *
580 * When rendering objects of the same type, each object
581 * must be rendered completely before the rendering of the
582 * next object is started. This is to avoid incomplete
583 * object rendering.
584 *
585 * PreCondition: Object must be created before this function is called.
586 *
587 * Input: pLb - Pointer to the object to be rendered.
588 *
589 * Output: Returns the status of the drawing
590 * - 1 - If the rendering was completed and
591 * - 0 - If the rendering is not yet finished.
592 * Next call to the function will resume the
593 * rendering on the pending drawing state.
594 *
595 * Side Effects: none
596 *
597 ********************************************************************/
598 WORD LbDraw(LISTBOX *pLb);
599 #endif // _LISTBOX_H
{BLAME END}
{FOOTER START}

Powered by WebSVN v2.8.3