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 /*
  30  * The gui_list is based on callback functions, if you want the list
  31  * to display something you have to provide it a function that
  32  * tells it what to display.
  33  * There are two callback function :
  34  * one to get the text and one to get the icon
  35  */
  36
  37 /*
  38  * Icon callback
  39  *  - selected_item : an integer that tells the number of the item to display
  40  *  - data : a void pointer to the data you gave to the list when
  41  *           you initialized it
  42  *  - icon : a pointer to the icon, the value inside it is used to display
  43  *           the icon after the function returns.
  44  * Note : we use the ICON type because the real type depends of the plateform
  45  */
  46 typedef void list_get_icon(int selected_item,
  47                            void * data,
  48                            ICON * icon);
  49 /*
  50  * Text callback
  51  *  - selected_item : an integer that tells the number of the item to display
  52  *  - data : a void pointer to the data you gave to the list when
  53  *           you initialized it
  54  *  - buffer : a buffer to put the resulting text on it
  55  *             (The content of the buffer may not be used by the list, we use
  56  *             the return value of the function in all cases to avoid filling
  57  *             a buffer when it's not necessary)
  58  * Returns a pointer to a string that contains the text to display
  59  */
  60 typedef char * list_get_name(int selected_item,
  61                              void * data,
  62                              char *buffer);
  63
  64 struct gui_list
  65 {
  66     int nb_items;
  67     int selected_item;
  68     bool cursor_flash_state;
  69     int start_item; /* the item that is displayed at the top of the screen */
  70
  71 #ifdef HAVE_LCD_BITMAP
  72     int offset_position; /* the list's screen scroll placement in pixels */
  73 #endif
  74     list_get_icon *callback_get_item_icon;
  75     list_get_name *callback_get_item_name;
  76
  77     struct screen * display;
  78     /* defines wether the list should stop when reaching the top/bottom
  79      * or should continue (by going to bottom/top) */
  80     bool limit_scroll;
  81     /* wether the text of the whole items of the list have to be
  82      * scrolled or only for the selected item */
  83     bool scroll_all;
  84     /* the number of lines that are selected at the same time */
  85     int selected_size;
  86     /* The data that will be passed to the callback function YOU implement */
  87     void * data;
  88     /* The optional title, set to NULL for none */
  89     char *title;
  90     /* Cache the width of the title string in pixels/characters */
  91     int title_width;
  92     /* Optional title icon */
  93     ICON title_icon;
  94 };
  95
  96 /*
  97  * Initializes a scrolling list
  98  *  - gui_list : the list structure to initialize
  99  *  - callback_get_item_icon : pointer to a function that associates an icon
 100  *    to a given item number
 101  *  - callback_get_item_name : pointer to a function that associates a label
 102  *    to a given item number
 103  *  - data : extra data passed to the list callback
 104  */
 105 extern void gui_list_init(struct gui_list * gui_list,
 106     list_get_name callback_get_item_name,
 107     void * data,
 108     bool scroll_all,
 109     int selected_size
 110     );
 111
 112 /*
 113  * Sets the numbers of items the list can currently display
 114  * note that the list's context like the currently pointed item is resetted
 115  *  - gui_list : the list structure
 116  *  - nb_items : the numbers of items you want
 117  */
 118 #define gui_list_set_nb_items(gui_list, nb) \
 119     (gui_list)->nb_items = nb
 120
 121 /*
 122  * Returns the numbers of items currently in the list
 123  *  - gui_list : the list structure
 124  */
 125 #define gui_list_get_nb_items(gui_list) \
 126     (gui_list)->nb_items
 127
 128 /*
 129  * Puts the selection in the screen
 130  *  - gui_list : the list structure
 131  *  - put_from_end : if true, selection will be put as close from
 132  *                   the end of the list as possible, else, it's
 133  *                   from the beginning
 134  */
 135 extern void gui_list_put_selection_in_screen(struct gui_list * gui_list,
 136                                              bool put_from_end);
 137
 138 /*
 139  * Sets the icon callback function
 140  *  - gui_list : the list structure
 141  *  - _callback : the callback function
 142  */
 143 #define gui_list_set_icon_callback(gui_list, _callback) \
 144     (gui_list)->callback_get_item_icon=_callback
 145
 146 /*
 147  * Attach the scrolling list to a screen
 148  * (The previous screen attachement is lost)
 149  *  - gui_list : the list structure
 150  *  - display : the screen to attach
 151  */
 152 extern void gui_list_set_display(struct gui_list * gui_list,
 153                                  struct screen * display);
 154
 155 /*
 156  * Gives the position of the selected item
 157  *  - gui_list : the list structure
 158  * Returns the position
 159  */
 160 #define gui_list_get_sel_pos(gui_list) \
 161     (gui_list)->selected_item
 162
 163
 164 /*
 165  * Selects an item in the list
 166  *  - gui_list : the list structure
 167  *  - item_number : the number of the item which will be selected
 168  */
 169 extern void gui_list_select_item(struct gui_list * gui_list, int item_number);
 170
 171 /*
 172  * Draws the list on the attached screen
 173  * - gui_list : the list structure
 174  */
 175 extern void gui_list_draw(struct gui_list * gui_list);
 176
 177 /*
 178  * Selects the next item in the list
 179  * (Item 0 gets selected if the end of the list is reached)
 180  * - gui_list : the list structure
 181  */
 182 extern void gui_list_select_next(struct gui_list * gui_list);
 183
 184 /*
 185  * Selects the previous item in the list
 186  * (Last item in the list gets selected if the list beginning is reached)
 187  * - gui_list : the list structure
 188  */
 189 extern void gui_list_select_previous(struct gui_list * gui_list);
 190
 191 #ifdef HAVE_LCD_BITMAP
 192 /*
 193  * Makes all the item in the list scroll by one step to the right.
 194  * Should stop increasing the value when reaching the widest item value
 195  * in the list.
 196  */
 197 void gui_list_scroll_right(struct gui_list * gui_list);
 198
 199 /*
 200  * Makes all the item in the list scroll by one step to the left.
 201  * stops at starting position.
 202  */
 203 void gui_list_scroll_left(struct gui_list * gui_list);
 204
 205 /* parse global setting to static int */
 206 extern void gui_list_screen_scroll_step(int ofs);
 207
 208 /* parse global setting to static bool */
 209 extern void gui_list_screen_scroll_out_of_view(bool enable);
 210 #endif /* HAVE_LCD_BITMAP */
 211
 212 /*
 213  * Go to next page if any, else selects the last item in the list
 214  * - gui_list : the list structure
 215  * - nb_lines : the number of lines to try to move the cursor
 216  */
 217 extern void gui_list_select_next_page(struct gui_list * gui_list,
 218                                       int nb_lines);
 219
 220 /*
 221  * Go to previous page if any, else selects the first item in the list
 222  * - gui_list : the list structure
 223  * - nb_lines : the number of lines to try to move the cursor
 224  */
 225 extern void gui_list_select_previous_page(struct gui_list * gui_list,
 226                                           int nb_lines);
 227
 228 /*
 229  * Adds an item to the list (the callback will be asked for one more item)
 230  * - gui_list : the list structure
 231  */
 232 extern void gui_list_add_item(struct gui_list * gui_list);
 233
 234 /*
 235  * Removes an item to the list (the callback will be asked for one less item)
 236  * - gui_list : the list structure
 237  */
 238 extern void gui_list_del_item(struct gui_list * gui_list);
 239
 240 /*
 241  * Tells the list wether it should stop when reaching the top/bottom
 242  * or should continue (by going to bottom/top)
 243  * - gui_list : the list structure
 244  * - scroll :
 245  *    - true : stops when reaching top/bottom
 246  *    - false : continues to go to bottom/top when reaching top/bottom
 247  */
 248 #define gui_list_limit_scroll(gui_list, scroll) \
 249     (gui_list)->limit_scroll=scroll
 250
 251 /*
 252  * One call on 2, the selected lune will either blink the cursor or
 253  * invert/display normal the selected line
 254  * - gui_list : the list structure
 255  */
 256 extern void gui_list_flash(struct gui_list * gui_list);
 257
 258 /*
 259  * Set the title and title icon of the list. Setting title to NULL disables
 260  * both the title and icon. Use NOICON if there is no icon.
 261  */
 262 extern void gui_list_set_title(struct gui_list *gui_list, char* title,
 263                                ICON icon);
 264
 265 /*
 266  * This part handles as many lists as there are connected screens
 267  * (the api is similar to the ones above)
 268  * The lists on the screens are synchronized ;
 269  * theirs items and selected items are the same, but of course,
 270  * they can be displayed on screens with different sizes
 271  * The final aim is to let the programmer handle many lists in one
 272  * function call and make its code independant from the number of screens
 273  */
 274 struct gui_synclist
 275 {
 276     struct gui_list gui_list[NB_SCREENS];
 277 };
 278
 279 extern void gui_synclist_init(
 280     struct gui_synclist * lists,
 281     list_get_name callback_get_item_name,
 282     void * data,
 283     bool scroll_all,
 284     int selected_size
 285     );
 286 extern void gui_synclist_set_nb_items(struct gui_synclist * lists, int nb_items);
 287 extern void gui_synclist_set_icon_callback(struct gui_synclist * lists, list_get_icon icon_callback);
 288 extern int gui_synclist_get_nb_items(struct gui_synclist * lists);
 289
 290 extern int  gui_synclist_get_sel_pos(struct gui_synclist * lists);
 291
 292 extern void gui_synclist_draw(struct gui_synclist * lists);
 293 extern void gui_synclist_select_item(struct gui_synclist * lists,
 294                                      int item_number);
 295 extern void gui_synclist_select_next(struct gui_synclist * lists);
 296 extern void gui_synclist_select_previous(struct gui_synclist * lists);
 297 extern void gui_synclist_select_next_page(struct gui_synclist * lists,
 298                                           enum screen_type screen);
 299 extern void gui_synclist_select_previous_page(struct gui_synclist * lists,
 300                                               enum screen_type screen);
 301 extern void gui_synclist_add_item(struct gui_synclist * lists);
 302 extern void gui_synclist_del_item(struct gui_synclist * lists);
 303 extern void gui_synclist_limit_scroll(struct gui_synclist * lists, bool scroll);
 304 extern void gui_synclist_flash(struct gui_synclist * lists);
 305 extern void gui_synclist_set_title(struct gui_synclist * lists, char * title,
 306                                    ICON icon);
 307 void gui_synclist_scroll_right(struct gui_synclist * lists);
 308 void gui_synclist_scroll_left(struct gui_synclist * lists);
 309
 310 /*
 311  * Do the action implied by the given button,
 312  * returns the action taken if any, 0 else
 313  *  - lists : the synchronized lists
 314  *  - button : the keycode of a pressed button
 315  * returned value :
 316  *  - ACTION_STD_NEXT when moving forward (next item or pgup)
 317  *  - ACTION_STD_PREV when moving backward (previous item or pgdown)
 318  */
 319 extern unsigned gui_synclist_do_button(struct gui_synclist * lists, unsigned button);
 320
 321 #endif /* _GUI_LIST_H_ */