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