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