apps/gui/list.h

   1 /***************************************************************************
   2  *             __________               __   ___.
   3  *   Open      \______   \ ____   ____ |  | _\_ |__   _______  ___
   4  *   Source     |       _//  _ \_/ ___\|  |/ /| __ \ /  _ \  \/  /
   5  *   Jukebox    |    |   (  <_> )  \___|    < | \_\ (  <_> > <  <
   6  *   Firmware   |____|_  /\____/ \___  >__|_ \|___  /\____/__/\_ \
   7  *                     \/            \/     \/    \/            \/
   8  * $Id$
   9  *
  10  * Copyright (C) 2005 by Kevin Ferrare
  11  *
  12  * All files in this archive are subject to the GNU General Public License.
  13  * See the file COPYING in the source tree root for full license agreement.
  14  *
  15  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  16  * KIND, either express or implied.
  17  *
  18  ****************************************************************************/
  19
  20 #ifndef _GUI_LIST_H_
  21 #define _GUI_LIST_H_
  22
  23 #include "config.h"
  24 #include "icon.h"
  25 #include "screen_access.h"
  26
  27 #define SCROLLBAR_WIDTH  6
  28
  29 enum list_wrap {
  30     LIST_WRAP_ON = 0,
  31     LIST_WRAP_OFF,
  32     LIST_WRAP_UNLESS_HELD,
  33 };
  34
  35 /*
  36  * The gui_list is based on callback functions, if you want the list
  37  * to display something you have to provide it a function that
  38  * tells it what to display.
  39  * There are three callback function :
  40  * one to get the text, one to get the icon and one to get the color
  41  */
  42
  43 /*
  44  * Icon callback
  45  *  - selected_item : an integer that tells the number of the item to display
  46  *  - data : a void pointer to the data you gave to the list when you
  47  *           initialized it
  48  *  Returns a pointer to the icon, the value inside it is used to display the
  49  *          icon after the function returns.
  50  * Note : we use the ICON type because the real type depends of the plateform
  51  */
  52 typedef enum themable_icons list_get_icon(int selected_item, void * data);
  53 /*
  54  * Text callback
  55  *  - selected_item : an integer that tells the number of the item to display
  56  *  - data : a void pointer to the data you gave to the list when you
  57  *           initialized it
  58  *  - buffer : a buffer to put the resulting text on it
  59  *             (The content of the buffer may not be used by the list, we use
  60  *             the return value of the function in all cases to avoid filling
  61  *             a buffer when it's not necessary)
  62  * Returns a pointer to a string that contains the text to display
  63  */
  64 typedef char * list_get_name(int selected_item, void * data, char * buffer);
  65 /*
  66  * Voice callback
  67  *  - selected_item : an integer that tells the number of the item to speak
  68  *  - data : a void pointer to the data you gave to the list when you
  69  *           initialized it
  70  * Returns an integer, 0 means success, ignored really...
  71  */
  72 typedef int list_speak_item(int selected_item, void * data);
  73 #ifdef HAVE_LCD_COLOR
  74 /*
  75  * Color callback
  76  *  - selected_item : an integer that tells the number of the item to display
  77  *  - data : a void pointer to the data you gave to the list when you
  78  *           initialized it
  79  *  Returns an int with the lower 16 bits representing the color to display the
  80  *          selected item, negative value for default coloring.
  81  */
  82 typedef int list_get_color(int selected_item, void * data);
  83 #endif
  84
  85 struct gui_synclist
  86 {
  87     /* defines wether the list should stop when reaching the top/bottom
  88      * or should continue (by going to bottom/top) */
  89     bool limit_scroll;
  90     /* wether the text of the whole items of the list have to be
  91      * scrolled or only for the selected item */
  92     bool scroll_all;
  93
  94     int nb_items;
  95     int selected_item;
  96     int start_item[NB_SCREENS]; /* the item that is displayed at the top of the screen */
  97     /* the number of lines that are selected at the same time */
  98     int selected_size;
  99     /* These are used to calculate how much of the screen content we need
 100        to redraw. */
 101     int last_displayed_selected_item;
 102     int last_displayed_start_item[NB_SCREENS];
 103 #ifdef HAVE_LCD_BITMAP
 104     int offset_position[NB_SCREENS]; /* the list's screen scroll placement in pixels */
 105 #endif
 106     /* Cache the width of the title string in pixels/characters */
 107     int title_width;
 108     long scheduled_talk_tick, last_talked_tick;
 109
 110     list_get_icon *callback_get_item_icon;
 111     list_get_name *callback_get_item_name;
 112     list_speak_item *callback_speak_item;
 113
 114     /* The data that will be passed to the callback function YOU implement */
 115     void * data;
 116     /* The optional title, set to NULL for none */
 117     char * title;
 118     /* Optional title icon */
 119     enum themable_icons title_icon;
 120     bool show_selection_marker; /* set to true by default */
 121
 122 #ifdef HAVE_LCD_COLOR
 123     int title_color;
 124     list_get_color *callback_get_item_color;
 125 #endif
 126 };
 127
 128 /*
 129  * Sets the numbers of items the list can currently display
 130  * note that the list's context like the currently pointed item is resetted
 131  *  - gui_list : the list structure
 132  *  - nb_items : the numbers of items you want
 133  */
 134 #define gui_list_set_nb_items(gui_list, nb) \
 135     (gui_list)->nb_items = nb
 136
 137 /*
 138  * Returns the numbers of items currently in the list
 139  *  - gui_list : the list structure
 140  */
 141 #define gui_list_get_nb_items(gui_list) \
 142     (gui_list)->nb_items
 143
 144 /*
 145  * Sets the icon callback function
 146  *  - gui_list : the list structure
 147  *  - _callback : the callback function
 148  */
 149 #define gui_list_set_icon_callback(gui_list, _callback) \
 150     (gui_list)->callback_get_item_icon=_callback
 151
 152 /*
 153  * Sets the voice callback function
 154  *  - gui_list : the list structure
 155  *  - _callback : the callback function
 156  */
 157 #define gui_list_set_voice_callback(gui_list, _callback) \
 158     (gui_list)->callback_speak_item=_callback
 159
 160 #ifdef HAVE_LCD_COLOR
 161 /*
 162  * Sets the color callback function
 163  *  - gui_list : the list structure
 164  *  - _callback : the callback function
 165  */
 166 #define gui_list_set_color_callback(gui_list, _callback) \
 167     (gui_list)->callback_get_item_color=_callback
 168 #endif
 169
 170 /*
 171  * Gives the position of the selected item
 172  *  - gui_list : the list structure
 173  * Returns the position
 174  */
 175 #define gui_list_get_sel_pos(gui_list) \
 176     (gui_list)->selected_item
 177
 178
 179 #ifdef HAVE_LCD_BITMAP
 180 /* parse global setting to static int */
 181 extern void gui_list_screen_scroll_step(int ofs);
 182
 183 /* parse global setting to static bool */
 184 extern void gui_list_screen_scroll_out_of_view(bool enable);
 185 #endif /* HAVE_LCD_BITMAP */
 186 /*
 187  * Tells the list wether it should stop when reaching the top/bottom
 188  * or should continue (by going to bottom/top)
 189  * - gui_list : the list structure
 190  * - scroll :
 191  *    - true : stops when reaching top/bottom
 192  *    - false : continues to go to bottom/top when reaching top/bottom
 193  */
 194 #define gui_list_limit_scroll(gui_list, scroll) \
 195     (gui_list)->limit_scroll=scroll
 196
 197
 198 extern void gui_synclist_init(
 199     struct gui_synclist * lists,
 200     list_get_name callback_get_item_name,
 201     void * data,
 202     bool scroll_all,
 203     int selected_size
 204     );
 205 extern void gui_synclist_set_nb_items(struct gui_synclist * lists, int nb_items);
 206 extern void gui_synclist_set_icon_callback(struct gui_synclist * lists, list_get_icon icon_callback);
 207 extern void gui_synclist_set_voice_callback(struct gui_synclist * lists, list_speak_item voice_callback);
 208 extern void gui_synclist_speak_item(struct gui_synclist * lists);
 209 extern int gui_synclist_get_nb_items(struct gui_synclist * lists);
 210
 211 extern int  gui_synclist_get_sel_pos(struct gui_synclist * lists);
 212
 213 extern void gui_synclist_draw(struct gui_synclist * lists);
 214 extern void gui_synclist_select_item(struct gui_synclist * lists,
 215                                      int item_number);
 216 extern void gui_synclist_add_item(struct gui_synclist * lists);
 217 extern void gui_synclist_del_item(struct gui_synclist * lists);
 218 extern void gui_synclist_limit_scroll(struct gui_synclist * lists, bool scroll);
 219 extern void gui_synclist_flash(struct gui_synclist * lists);
 220 extern void gui_synclist_set_title(struct gui_synclist * lists, char * title,
 221                                    int icon);
 222 extern void gui_synclist_hide_selection_marker(struct gui_synclist *lists,
 223                                                 bool hide);
 224 /*
 225  * Do the action implied by the given button,
 226  * returns true if the action was handled.
 227  * NOTE: *action may be changed regardless of return value
 228  */
 229 extern bool gui_synclist_do_button(struct gui_synclist * lists,
 230                                        unsigned *action,
 231                                        enum list_wrap);
 232
 233 /* If the list has a pending postponed scheduled announcement, that
 234    may become due before the next get_action tmieout. This function
 235    adjusts the get_action timeout appropriately. */
 236 extern int list_do_action_timeout(struct gui_synclist *lists, int timeout);
 237 /* This one combines a get_action call (with timeout overridden by
 238    list_do_action_timeout) with the gui_synclist_do_button call, for
 239    convenience. */
 240 extern bool list_do_action(int context, int timeout,
 241                            struct gui_synclist *lists, int *action,
 242                            enum list_wrap wrap);
 243
 244
 245 /** Simplelist implementation.
 246     USe this if you dont need to reimplement the list code,
 247     and just need to show a list
 248  **/
 249
 250 struct simplelist_info {
 251     char *title; /* title to show on the list */
 252     int  count; /* number of items in the list, each item is selection_size high */
 253     char selection_size; /* list selection size, usually 1 */
 254     bool hide_selection;
 255     bool scroll_all;
 256     int  timeout;
 257     int  start_selection; /* the item to select when the list is first displayed */
 258     int (*action_callback)(int action, struct gui_synclist *lists); /* can be NULL */
 259         /* action_callback notes:
 260             action == the action pressed by the user
 261                 _after_ gui_synclist_do_button returns.
 262             lists == the lists sturct so the callack can get selection and count etc. */
 263     list_get_icon *get_icon; /* can be NULL */
 264     list_get_name *get_name; /* NULL if you're using simplelist_addline() */
 265     list_speak_item *get_talk; /* can be NULL to not speak */
 266     void *callback_data; /* data for callbacks */
 267 };
 268
 269 #define SIMPLELIST_MAX_LINES 32
 270 #define SIMPLELIST_MAX_LINELENGTH 32
 271
 272 /** The next three functions are used if the text is mostly static.
 273     These should be called in the action callback for the list.
 274  **/
 275 /* set the amount of lines shown in the list
 276    Only needed if simplelist_info.get_name == NULL */
 277 void simplelist_set_line_count(int lines);
 278 /* get the current amount of lines shown */
 279 int simplelist_get_line_count(void);
 280 /* add/edit a line in the list.
 281    if line_number > number of lines shown it adds the line, else it edits the line */
 282 #define SIMPLELIST_ADD_LINE (SIMPLELIST_MAX_LINES+1)
 283 void simplelist_addline(int line_number, const char *fmt, ...);
 284
 285 /* setup the info struct. members not setup in this function need to be assigned manually
 286    members set in this function:
 287     info.selection_size = 1;
 288     info.hide_selection = false;
 289     info.scroll_all = false;
 290     info.action_callback = NULL;
 291     info.get_icon = NULL;
 292     info.get_name = NULL;
 293     info.get_voice = NULL;
 294     info.timeout = HZ/10;
 295     info.start_selection = 0;
 296 */
 297 void simplelist_info_init(struct simplelist_info *info, char* title,
 298                           int count, void* data);
 299
 300 /* show a list.
 301    if list->action_callback != NULL it is called with the action ACTION_REDRAW
 302     before the list is dislplayed for the first time */
 303 bool simplelist_show_list(struct simplelist_info *info);
 304
 305 #endif /* _GUI_LIST_H_ */