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
  29 #define SCROLLBAR_WIDTH  6
  30
  31 enum list_wrap {
  32     LIST_WRAP_ON = 0,
  33     LIST_WRAP_OFF,
  34     LIST_WRAP_UNLESS_HELD,
  35 };
  36
  37 /*
  38  * The gui_list is based on callback functions, if you want the list
  39  * to display something you have to provide it a function that
  40  * tells it what to display.
  41  * There are three callback function :
  42  * one to get the text, one to get the icon and one to get the color
  43  */
  44
  45 /*
  46  * Icon callback
  47  *  - selected_item : an integer that tells the number of the item to display
  48  *  - data : a void pointer to the data you gave to the list when you
  49  *           initialized it
  50  *  Returns a pointer to the icon, the value inside it is used to display the
  51  *          icon after the function returns.
  52  * Note : we use the ICON type because the real type depends of the plateform
  53  */
  54 typedef enum themable_icons list_get_icon(int selected_item, void * data);
  55 /*
  56  * Text callback
  57  *  - selected_item : an integer that tells the number of the item to display
  58  *  - data : a void pointer to the data you gave to the list when you
  59  *           initialized it
  60  *  - buffer : a buffer to put the resulting text on it
  61  *             (The content of the buffer may not be used by the list, we use
  62  *             the return value of the function in all cases to avoid filling
  63  *             a buffer when it's not necessary)
  64  *  - buffer_len : length of the buffer
  65  * Returns a pointer to a string that contains the text to display
  66  */
  67 typedef char * list_get_name(int selected_item, void * data,
  68                              char * buffer, size_t buffer_len);
  69 /*
  70  * Voice callback
  71  *  - selected_item : an integer that tells the number of the item to speak
  72  *  - data : a void pointer to the data you gave to the list when you
  73  *           initialized it
  74  * Returns an integer, 0 means success, ignored really...
  75  */
  76 typedef int list_speak_item(int selected_item, void * data);
  77 #ifdef HAVE_LCD_COLOR
  78 /*
  79  * Color callback
  80  *  - selected_item : an integer that tells the number of the item to display
  81  *  - data : a void pointer to the data you gave to the list when you
  82  *           initialized it
  83  *  Returns an int with the lower 16 bits representing the color to display the
  84  *          selected item, negative value for default coloring.
  85  */
  86 typedef int list_get_color(int selected_item, void * data);
  87 #endif
  88
  89 struct gui_synclist
  90 {
  91     /* defines wether the list should stop when reaching the top/bottom
  92      * or should continue (by going to bottom/top) */
  93     bool limit_scroll;
  94     /* wether the text of the whole items of the list have to be
  95      * scrolled or only for the selected item */
  96     bool scroll_all;
  97
  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     /* These are used to calculate how much of the screen content we need
 104        to redraw. */
 105     int last_displayed_selected_item;
 106     int last_displayed_start_item[NB_SCREENS];
 107 #ifdef HAVE_LCD_BITMAP
 108     int offset_position[NB_SCREENS]; /* the list's screen scroll placement in pixels */
 109 #endif
 110     /* Cache the width of the title string in pixels/characters */
 111     int title_width;
 112     long scheduled_talk_tick, last_talked_tick;
 113
 114     list_get_icon *callback_get_item_icon;
 115     list_get_name *callback_get_item_name;
 116     list_speak_item *callback_speak_item;
 117
 118     /* The data that will be passed to the callback function YOU implement */
 119     void * data;
 120     /* The optional title, set to NULL for none */
 121     char * title;
 122     /* Optional title icon */
 123     enum themable_icons title_icon;
 124     bool show_selection_marker; /* set to true by default */
 125
 126 #ifdef HAVE_LCD_COLOR
 127     int title_color;
 128     list_get_color *callback_get_item_color;
 129 #endif
 130     struct viewport *parent[NB_SCREENS];
 131 };
 132
 133
 134 #ifdef HAVE_LCD_BITMAP
 135 /* parse global setting to static int */
 136 extern void gui_list_screen_scroll_step(int ofs);
 137
 138 /* parse global setting to static bool */
 139 extern void gui_list_screen_scroll_out_of_view(bool enable);
 140 #endif /* HAVE_LCD_BITMAP */
 141
 142 void list_init_viewports(struct gui_synclist * lists);
 143
 144 extern void gui_synclist_init(
 145     struct gui_synclist * lists,
 146     list_get_name callback_get_item_name,
 147     void * data,
 148     bool scroll_all,
 149     int selected_size,
 150     struct viewport parent[NB_SCREENS] /* NOTE: new screens should NOT set this to NULL */
 151     );
 152 extern void gui_synclist_set_nb_items(struct gui_synclist * lists, int nb_items);
 153 extern void gui_synclist_set_icon_callback(struct gui_synclist * lists, list_get_icon icon_callback);
 154 extern void gui_synclist_set_voice_callback(struct gui_synclist * lists, list_speak_item voice_callback);
 155 #ifdef HAVE_LCD_COLOR
 156 extern void gui_synclist_set_color_callback(struct gui_synclist * lists, list_get_color color_callback);
 157 #endif
 158 extern void gui_synclist_speak_item(struct gui_synclist * lists);
 159 extern int gui_synclist_get_nb_items(struct gui_synclist * lists);
 160
 161 extern int  gui_synclist_get_sel_pos(struct gui_synclist * lists);
 162
 163 extern void gui_synclist_draw(struct gui_synclist * lists);
 164 extern void gui_synclist_select_item(struct gui_synclist * lists,
 165                                      int item_number);
 166 extern void gui_synclist_add_item(struct gui_synclist * lists);
 167 extern void gui_synclist_del_item(struct gui_synclist * lists);
 168 extern void gui_synclist_limit_scroll(struct gui_synclist * lists, bool scroll);
 169 extern void gui_synclist_flash(struct gui_synclist * lists);
 170 extern void gui_synclist_set_title(struct gui_synclist * lists, char * title,
 171                                    int icon);
 172 extern void gui_synclist_hide_selection_marker(struct gui_synclist *lists,
 173                                                 bool hide);
 174 /*
 175  * Do the action implied by the given button,
 176  * returns true if the action was handled.
 177  * NOTE: *action may be changed regardless of return value
 178  */
 179 extern bool gui_synclist_do_button(struct gui_synclist * lists,
 180                                        unsigned *action,
 181                                        enum list_wrap);
 182
 183 /* If the list has a pending postponed scheduled announcement, that
 184    may become due before the next get_action tmieout. This function
 185    adjusts the get_action timeout appropriately. */
 186 extern int list_do_action_timeout(struct gui_synclist *lists, int timeout);
 187 /* This one combines a get_action call (with timeout overridden by
 188    list_do_action_timeout) with the gui_synclist_do_button call, for
 189    convenience. */
 190 extern bool list_do_action(int context, int timeout,
 191                            struct gui_synclist *lists, int *action,
 192                            enum list_wrap wrap);
 193
 194
 195 /** Simplelist implementation.
 196     USe this if you dont need to reimplement the list code,
 197     and just need to show a list
 198  **/
 199
 200 struct simplelist_info {
 201     char *title; /* title to show on the list */
 202     int  count; /* number of items in the list, each item is selection_size high */
 203     char selection_size; /* list selection size, usually 1 */
 204     bool hide_selection;
 205     bool scroll_all;
 206     int  timeout;
 207     int  start_selection; /* the item to select when the list is first displayed */
 208     int (*action_callback)(int action, struct gui_synclist *lists); /* can be NULL */
 209         /* action_callback notes:
 210             action == the action pressed by the user
 211                 _after_ gui_synclist_do_button returns.
 212             lists == the lists sturct so the callack can get selection and count etc. */
 213     list_get_icon *get_icon; /* can be NULL */
 214     list_get_name *get_name; /* NULL if you're using simplelist_addline() */
 215     list_speak_item *get_talk; /* can be NULL to not speak */
 216     void *callback_data; /* data for callbacks */
 217 };
 218
 219 #define SIMPLELIST_MAX_LINES 32
 220 #define SIMPLELIST_MAX_LINELENGTH 32
 221
 222 /** The next three functions are used if the text is mostly static.
 223     These should be called in the action callback for the list.
 224  **/
 225 /* set the amount of lines shown in the list
 226    Only needed if simplelist_info.get_name == NULL */
 227 void simplelist_set_line_count(int lines);
 228 /* get the current amount of lines shown */
 229 int simplelist_get_line_count(void);
 230 /* add/edit a line in the list.
 231    if line_number > number of lines shown it adds the line, else it edits the line */
 232 #define SIMPLELIST_ADD_LINE (SIMPLELIST_MAX_LINES+1)
 233 void simplelist_addline(int line_number, const char *fmt, ...);
 234
 235 /* setup the info struct. members not setup in this function need to be assigned manually
 236    members set in this function:
 237     info.selection_size = 1;
 238     info.hide_selection = false;
 239     info.scroll_all = false;
 240     info.action_callback = NULL;
 241     info.get_icon = NULL;
 242     info.get_name = NULL;
 243     info.get_voice = NULL;
 244     info.timeout = HZ/10;
 245     info.start_selection = 0;
 246 */
 247 void simplelist_info_init(struct simplelist_info *info, char* title,
 248                           int count, void* data);
 249
 250 /* show a list.
 251    if list->action_callback != NULL it is called with the action ACTION_REDRAW
 252     before the list is dislplayed for the first time */
 253 bool simplelist_show_list(struct simplelist_info *info);
 254
 255 #endif /* _GUI_LIST_H_ */