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  * This program is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU General Public License
  14  * as published by the Free Software Foundation; either version 2
  15  * of the License, or (at your option) any later version.
  16  *
  17  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  18  * KIND, either express or implied.
  19  *
  20  ****************************************************************************/
  21
  22 #ifndef _GUI_LIST_H_
  23 #define _GUI_LIST_H_
  24
  25 #include "config.h"
  26 #include "icon.h"
  27 #include "screen_access.h"
  28 #include "skin_engine/skin_engine.h"
  29
  30 #define SCROLLBAR_WIDTH global_settings.scrollbar_width
  31
  32 enum list_wrap {
  33     LIST_WRAP_ON = 0,
  34     LIST_WRAP_OFF,
  35     LIST_WRAP_UNLESS_HELD,
  36 };
  37
  38 /*
  39  * The gui_list is based on callback functions, if you want the list
  40  * to display something you have to provide it a function that
  41  * tells it what to display.
  42  * There are three callback function :
  43  * one to get the text, one to get the icon and one to get the color
  44  */
  45
  46 /*
  47  * Icon callback
  48  *  - selected_item : an integer that tells the number of the item to display
  49  *  - data : a void pointer to the data you gave to the list when you
  50  *           initialized it
  51  *  Returns a pointer to the icon, the value inside it is used to display the
  52  *          icon after the function returns.
  53  * Note : we use the ICON type because the real type depends of the plateform
  54  */
  55 typedef enum themable_icons list_get_icon(int selected_item, void * data);
  56 /*
  57  * Text callback
  58  *  - selected_item : an integer that tells the number of the item to display
  59  *  - data : a void pointer to the data you gave to the list when you
  60  *           initialized it
  61  *  - buffer : a buffer to put the resulting text on it
  62  *             (The content of the buffer may not be used by the list, we use
  63  *             the return value of the function in all cases to avoid filling
  64  *             a buffer when it's not necessary)
  65  *  - buffer_len : length of the buffer
  66  * Returns a pointer to a string that contains the text to display
  67  */
  68 typedef const char * list_get_name(int selected_item, void * data,
  69                                    char * buffer, size_t buffer_len);
  70 /*
  71  * Voice callback
  72  *  - selected_item : an integer that tells the number of the item to speak
  73  *  - data : a void pointer to the data you gave to the list when you
  74  *           initialized it
  75  * Returns an integer, 0 means success, ignored really...
  76  */
  77 typedef int list_speak_item(int selected_item, void * data);
  78 #ifdef HAVE_LCD_COLOR
  79 /*
  80  * Color callback
  81  *  - selected_item : an integer that tells the number of the item to display
  82  *  - data : a void pointer to the data you gave to the list when you
  83  *           initialized it
  84  *  Returns an int with the lower 16 bits representing the color to display the
  85  *          selected item, negative value for default coloring.
  86  */
  87 typedef int list_get_color(int selected_item, void * data);
  88 #endif
  89
  90 struct gui_synclist
  91 {
  92     /* defines wether the list should stop when reaching the top/bottom
  93      * or should continue (by going to bottom/top) */
  94     bool limit_scroll;
  95     /* wether the text of the whole items of the list have to be
  96      * scrolled or only for the selected item */
  97     bool scroll_all;
  98     int nb_items;
  99     int selected_item;
 100     int start_item[NB_SCREENS]; /* the item that is displayed at the top of the screen */
 101     /* the number of lines that are selected at the same time */
 102     int selected_size;
 103 #ifdef HAVE_LCD_BITMAP
 104     int offset_position[NB_SCREENS]; /* the list's screen scroll placement in pixels */
 105 #endif
 106     long scheduled_talk_tick, last_talked_tick, dirty_tick;
 107
 108     list_get_icon *callback_get_item_icon;
 109     list_get_name *callback_get_item_name;
 110     list_speak_item *callback_speak_item;
 111
 112     /* The data that will be passed to the callback function YOU implement */
 113     void * data;
 114     /* The optional title, set to NULL for none */
 115     char * title;
 116     /* Optional title icon */
 117     enum themable_icons title_icon;
 118     bool show_selection_marker; /* set to true by default */
 119
 120 #ifdef HAVE_LCD_COLOR
 121     int title_color;
 122     list_get_color *callback_get_item_color;
 123 #endif
 124     struct viewport *parent[NB_SCREENS];
 125 };
 126
 127
 128 #ifdef HAVE_LCD_BITMAP
 129 extern void list_init(void);
 130 /* parse global setting to static int */
 131 extern void gui_list_screen_scroll_step(int ofs);
 132
 133 /* parse global setting to static bool */
 134 extern void gui_list_screen_scroll_out_of_view(bool enable);
 135 #endif /* HAVE_LCD_BITMAP */
 136
 137 extern void gui_synclist_init(
 138     struct gui_synclist * lists,
 139     list_get_name callback_get_item_name,
 140     void * data,
 141     bool scroll_all,
 142     int selected_size,
 143     struct viewport parent[NB_SCREENS] /* NOTE: new screens should NOT set this to NULL */
 144     );
 145 extern void gui_synclist_set_nb_items(struct gui_synclist * lists, int nb_items);
 146 extern void gui_synclist_set_icon_callback(struct gui_synclist * lists, list_get_icon icon_callback);
 147 extern void gui_synclist_set_voice_callback(struct gui_synclist * lists, list_speak_item voice_callback);
 148 extern void gui_synclist_set_viewport_defaults(struct viewport *vp, enum screen_type screen);
 149 #ifdef HAVE_LCD_COLOR
 150 extern void gui_synclist_set_color_callback(struct gui_synclist * lists, list_get_color color_callback);
 151 #endif
 152 extern void gui_synclist_speak_item(struct gui_synclist * lists);
 153 extern int gui_synclist_get_nb_items(struct gui_synclist * lists);
 154
 155 extern int  gui_synclist_get_sel_pos(struct gui_synclist * lists);
 156
 157 extern void gui_synclist_draw(struct gui_synclist * lists);
 158 extern void gui_synclist_scroll_stop(struct gui_synclist *lists);
 159 extern void gui_synclist_select_item(struct gui_synclist * lists,
 160                                      int item_number);
 161 extern void gui_synclist_add_item(struct gui_synclist * lists);
 162 extern void gui_synclist_del_item(struct gui_synclist * lists);
 163 extern void gui_synclist_limit_scroll(struct gui_synclist * lists, bool scroll);
 164 extern void gui_synclist_set_title(struct gui_synclist * lists, char * title,
 165                                    enum themable_icons icon);
 166 extern void gui_synclist_hide_selection_marker(struct gui_synclist *lists,
 167                                                 bool hide);
 168
 169 #if CONFIG_CODEC == SWCODEC
 170 extern bool gui_synclist_keyclick_callback(int action, void* data);
 171 #endif
 172 /*
 173  * Do the action implied by the given button,
 174  * returns true if the action was handled.
 175  * NOTE: *action may be changed regardless of return value
 176  */
 177 extern bool gui_synclist_do_button(struct gui_synclist * lists,
 178                                        int *action,
 179                                        enum list_wrap);
 180 #if defined(HAVE_LCD_BITMAP) && !defined(PLUGIN)
 181 struct listitem_viewport_cfg {
 182     struct wps_data *data;
 183     OFFSETTYPE(char *)   label;
 184     int     width;
 185     int     height;
 186     int     xmargin;
 187     int     ymargin;
 188     bool    tile;
 189     struct skin_viewport selected_item_vp;
 190 };
 191
 192 bool skinlist_get_item(struct screen *display, struct gui_synclist *list, int x, int y, int *item);
 193 bool skinlist_draw(struct screen *display, struct gui_synclist *list);
 194 bool skinlist_is_selected_item(void);
 195 void skinlist_set_cfg(enum screen_type screen,
 196                       struct listitem_viewport_cfg *cfg);
 197 const char* skinlist_get_item_text(int offset, bool wrap, char* buf, size_t buf_size);
 198 int skinlist_get_item_number(void);
 199 int skinlist_get_item_row(void);
 200 int skinlist_get_item_column(void);
 201 enum themable_icons skinlist_get_item_icon(int offset, bool wrap);
 202 bool skinlist_needs_scrollbar(enum screen_type screen);
 203 void skinlist_get_scrollbar(int* nb_item, int* first_shown, int* last_shown);
 204 int skinlist_get_line_count(enum screen_type screen, struct gui_synclist *list);
 205 #endif
 206
 207 #if  defined(HAVE_TOUCHSCREEN)
 208 /* this needs to be fixed if we ever get more than 1 touchscreen on a target */
 209 extern unsigned gui_synclist_do_touchscreen(struct gui_synclist * gui_list);
 210 /* only for private use in gui/list.c */
 211 extern void _gui_synclist_stop_kinetic_scrolling(void);
 212 #endif
 213
 214 /* If the list has a pending postponed scheduled announcement, that
 215    may become due before the next get_action tmieout. This function
 216    adjusts the get_action timeout appropriately. */
 217 extern int list_do_action_timeout(struct gui_synclist *lists, int timeout);
 218 /* This one combines a get_action call (with timeout overridden by
 219    list_do_action_timeout) with the gui_synclist_do_button call, for
 220    convenience. */
 221 extern bool list_do_action(int context, int timeout,
 222                            struct gui_synclist *lists, int *action,
 223                            enum list_wrap wrap);
 224
 225
 226 /** Simplelist implementation.
 227     USe this if you dont need to reimplement the list code,
 228     and just need to show a list
 229  **/
 230
 231 struct simplelist_info {
 232     char *title; /* title to show on the list */
 233     int  count; /* number of items in the list, each item is selection_size high */
 234     int selection_size; /* list selection size, usually 1 */
 235     bool hide_selection;
 236     bool scroll_all;
 237     int  timeout;
 238     int  selection; /* the item to select when the list is first displayed */
 239                     /* when the list is exited, this will be set to the
 240                        index of the last item selected, or -1 if the list
 241                        was exited with ACTION_STD_CANCEL                  */
 242     int (*action_callback)(int action, struct gui_synclist *lists); /* can be NULL */
 243         /* action_callback notes:
 244             action == the action pressed by the user
 245                 _after_ gui_synclist_do_button returns.
 246             lists == the lists struct so the callback can get selection and count etc. */
 247     enum themable_icons title_icon;
 248     list_get_icon *get_icon; /* can be NULL */
 249     list_get_name *get_name; /* NULL if you're using simplelist_addline() */
 250     list_speak_item *get_talk; /* can be NULL to not speak */
 251 #ifdef HAVE_LCD_COLOR
 252     list_get_color *get_color;
 253 #endif
 254     void *callback_data; /* data for callbacks */
 255 };
 256
 257 #define SIMPLELIST_MAX_LINES 32
 258 #define SIMPLELIST_MAX_LINELENGTH 32
 259
 260 /** The next three functions are used if the text is mostly static.
 261     These should be called in the action callback for the list.
 262  **/
 263 /* set the amount of lines shown in the list
 264    Only needed if simplelist_info.get_name == NULL */
 265 void simplelist_set_line_count(int lines);
 266 /* get the current amount of lines shown */
 267 int simplelist_get_line_count(void);
 268 /* add a line in the list. */
 269 void simplelist_addline(const char *fmt, ...);
 270
 271 /* setup the info struct. members not setup in this function need to be assigned manually
 272    members set in this function:
 273     info.selection_size = 1;
 274     info.hide_selection = false;
 275     info.scroll_all = false;
 276     info.action_callback = NULL;
 277     info.title_icon = Icon_NOICON;
 278     info.get_icon = NULL;
 279     info.get_name = NULL;
 280     info.get_voice = NULL;
 281     info.get_color = NULL;
 282     info.timeout = HZ/10;
 283     info.selection = 0;
 284 */
 285 void simplelist_info_init(struct simplelist_info *info, char* title,
 286                           int count, void* data);
 287
 288 /* show a list.
 289    if list->action_callback != NULL it is called with the action ACTION_REDRAW
 290     before the list is dislplayed for the first time */
 291 bool simplelist_show_list(struct simplelist_info *info);
 292
 293 #endif /* _GUI_LIST_H_ */