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 #ifdef HAVE_LCD_COLOR
  66 /*
  67  * Color callback
  68  *  - selected_item : an integer that tells the number of the item to display
  69  *  - data : a void pointer to the data you gave to the list when you
  70  *           initialized it
  71  *  Returns an int with the lower 16 bits representing the color to display the
  72  *          selected item, negative value for default coloring.
  73  */
  74 typedef int list_get_color(int selected_item, void * data);
  75 #endif
  76
  77 struct gui_list
  78 {
  79     /* defines wether the list should stop when reaching the top/bottom
  80      * or should continue (by going to bottom/top) */
  81     bool limit_scroll;
  82     /* wether the text of the whole items of the list have to be
  83      * scrolled or only for the selected item */
  84     bool scroll_all;
  85     bool cursor_flash_state;
  86
  87     int nb_items;
  88     int selected_item;
  89     int start_item; /* the item that is displayed at the top of the screen */
  90     /* the number of lines that are selected at the same time */
  91     int selected_size;
  92     /* These are used to calculate how much of the screen content we need
  93        to redraw. */
  94     int last_displayed_selected_item;
  95     int last_displayed_start_item;
  96 #ifdef HAVE_LCD_BITMAP
  97     int offset_position; /* the list's screen scroll placement in pixels */
  98 #endif
  99     /* Cache the width of the title string in pixels/characters */
 100     int title_width;
 101
 102     list_get_icon *callback_get_item_icon;
 103     list_get_name *callback_get_item_name;
 104
 105     struct screen * display;
 106     /* The data that will be passed to the callback function YOU implement */
 107     void * data;
 108     /* The optional title, set to NULL for none */
 109     char * title;
 110     /* Optional title icon */
 111     enum themable_icons title_icon;
 112     bool show_selection_marker; /* set to true by default */
 113
 114 #ifdef HAVE_LCD_COLOR
 115     int title_color;
 116     list_get_color *callback_get_item_color;
 117 #endif
 118 };
 119
 120 /*
 121  * Sets the numbers of items the list can currently display
 122  * note that the list's context like the currently pointed item is resetted
 123  *  - gui_list : the list structure
 124  *  - nb_items : the numbers of items you want
 125  */
 126 #define gui_list_set_nb_items(gui_list, nb) \
 127     (gui_list)->nb_items = nb
 128
 129 /*
 130  * Returns the numbers of items currently in the list
 131  *  - gui_list : the list structure
 132  */
 133 #define gui_list_get_nb_items(gui_list) \
 134     (gui_list)->nb_items
 135
 136 /*
 137  * Sets the icon callback function
 138  *  - gui_list : the list structure
 139  *  - _callback : the callback function
 140  */
 141 #define gui_list_set_icon_callback(gui_list, _callback) \
 142     (gui_list)->callback_get_item_icon=_callback
 143
 144 #ifdef HAVE_LCD_COLOR
 145 /*
 146  * Sets the color callback function
 147  *  - gui_list : the list structure
 148  *  - _callback : the callback function
 149  */
 150 #define gui_list_set_color_callback(gui_list, _callback) \
 151     (gui_list)->callback_get_item_color=_callback
 152 #endif
 153
 154 /*
 155  * Gives the position of the selected item
 156  *  - gui_list : the list structure
 157  * Returns the position
 158  */
 159 #define gui_list_get_sel_pos(gui_list) \
 160     (gui_list)->selected_item
 161
 162
 163 #ifdef HAVE_LCD_BITMAP
 164 /* parse global setting to static int */
 165 extern void gui_list_screen_scroll_step(int ofs);
 166
 167 /* parse global setting to static bool */
 168 extern void gui_list_screen_scroll_out_of_view(bool enable);
 169 #endif /* HAVE_LCD_BITMAP */
 170 /*
 171  * Tells the list wether it should stop when reaching the top/bottom
 172  * or should continue (by going to bottom/top)
 173  * - gui_list : the list structure
 174  * - scroll :
 175  *    - true : stops when reaching top/bottom
 176  *    - false : continues to go to bottom/top when reaching top/bottom
 177  */
 178 #define gui_list_limit_scroll(gui_list, scroll) \
 179     (gui_list)->limit_scroll=scroll
 180
 181 /*
 182  * This part handles as many lists as there are connected screens
 183  * (the api is similar to the ones above)
 184  * The lists on the screens are synchronized ;
 185  * theirs items and selected items are the same, but of course,
 186  * they can be displayed on screens with different sizes
 187  * The final aim is to let the programmer handle many lists in one
 188  * function call and make its code independant from the number of screens
 189  */
 190 struct gui_synclist
 191 {
 192     struct gui_list gui_list[NB_SCREENS];
 193 };
 194
 195 extern void gui_synclist_init(
 196     struct gui_synclist * lists,
 197     list_get_name callback_get_item_name,
 198     void * data,
 199     bool scroll_all,
 200     int selected_size
 201     );
 202 extern void gui_synclist_set_nb_items(struct gui_synclist * lists, int nb_items);
 203 extern void gui_synclist_set_icon_callback(struct gui_synclist * lists, list_get_icon icon_callback);
 204 extern int gui_synclist_get_nb_items(struct gui_synclist * lists);
 205
 206 extern int  gui_synclist_get_sel_pos(struct gui_synclist * lists);
 207
 208 extern void gui_synclist_draw(struct gui_synclist * lists);
 209 extern void gui_synclist_select_item(struct gui_synclist * lists,
 210                                      int item_number);
 211 extern void gui_synclist_add_item(struct gui_synclist * lists);
 212 extern void gui_synclist_del_item(struct gui_synclist * lists);
 213 extern void gui_synclist_limit_scroll(struct gui_synclist * lists, bool scroll);
 214 extern void gui_synclist_flash(struct gui_synclist * lists);
 215 extern void gui_synclist_set_title(struct gui_synclist * lists, char * title,
 216                                    int icon);
 217 extern void gui_synclist_hide_selection_marker(struct gui_synclist *lists,
 218                                                 bool hide);
 219 /*
 220  * Do the action implied by the given button,
 221  * returns the action taken if any, 0 else
 222  *  - lists : the synchronized lists
 223  *  - button : the keycode of a pressed button
 224  *  - specifies weather to allow the list to wrap or not, values at top of page
 225  * returned value :
 226  *  - ACTION_STD_NEXT when moving forward (next item or pgup)
 227  *  - ACTION_STD_PREV when moving backward (previous item or pgdown)
 228  */
 229 extern unsigned gui_synclist_do_button(struct gui_synclist * lists,
 230                                        unsigned button,
 231                                        enum list_wrap);
 232
 233 #endif /* _GUI_LIST_H_ */