src/lib/elm_diskselector.h

   1 /**
   2  * @defgroup Diskselector Diskselector
   3  * @ingroup Elementary
   4  *
   5  * @image html img/widget/diskselector/preview-00.png
   6  * @image latex img/widget/diskselector/preview-00.eps
   7  *
   8  * A diskselector is a kind of list widget. It scrolls horizontally,
   9  * and can contain label and icon objects. Three items are displayed
  10  * with the selected one in the middle.
  11  *
  12  * It can act like a circular list with round mode and labels can be
  13  * reduced for a defined length for side items.
  14  *
  15  * Smart callbacks one can listen to:
  16  * @li "selected" - when item is selected, i.e. scroller stops.
  17  * @li "scroll,anim,start" - scrolling animation has started
  18  * @li "scroll,anim,stop" - scrolling animation has stopped
  19  * @li "scroll,drag,start" - dragging the diskselector has started
  20  * @li "scroll,drag,stop" - dragging the diskselector has stopped
  21  * @note The "scroll,anim,*" and "scroll,drag,*" signals are only emitted by
  22  * user intervention.
  23  *
  24  * Available styles for it:
  25  * - @c "default"
  26  *
  27  * Default content parts of the diskselector items that you can use for are:
  28  * @li "icon" - An icon in the diskselector item
  29  *
  30  * Default text parts of the diskselector items that you can use for are:
  31  * @li "default" - Label of the diskselector item
  32  *
  33  * Supported elm_object_item common APIs.
  34  * @li elm_object_item_part_text_set
  35  * @li elm_object_item_part_text_get
  36  * @li elm_object_item_part_content_set
  37  * @li elm_object_item_part_content_get
  38  *
  39  * List of examples:
  40  * @li @ref diskselector_example_01
  41  * @li @ref diskselector_example_02
  42  */
  43
  44 /**
  45  * @addtogroup Diskselector
  46  * @{
  47  */
  48
  49 /**
  50  * Add a new diskselector widget to the given parent Elementary
  51  * (container) object.
  52  *
  53  * @param parent The parent object.
  54  * @return a new diskselector widget handle or @c NULL, on errors.
  55  *
  56  * This function inserts a new diskselector widget on the canvas.
  57  *
  58  * @ingroup Diskselector
  59  */
  60 EAPI Evas_Object           *elm_diskselector_add(Evas_Object *parent);
  61
  62 /**
  63  * Enable or disable round mode.
  64  *
  65  * @param obj The diskselector object.
  66  * @param enabled @c EINA_TRUE to enable round mode or @c EINA_FALSE to
  67  * disable it.
  68  *
  69  * Disabled by default. If round mode is enabled the items list will
  70  * work like a circular list, so when the user reaches the last item,
  71  * the first one will popup.
  72  *
  73  * @see elm_diskselector_round_enabled_get()
  74  *
  75  * @ingroup Diskselector
  76  */
  77 EAPI void                   elm_diskselector_round_enabled_set(Evas_Object *obj, Eina_Bool enabled);
  78
  79 /**
  80  * Get a value whether round mode is enabled or not.
  81  *
  82  * @see elm_diskselector_round_enabled_set() for details.
  83  *
  84  * @param obj The diskselector object.
  85  * @return @c EINA_TRUE means round mode is enabled. @c EINA_FALSE indicates
  86  * it's disabled. If @p obj is @c NULL, @c EINA_FALSE is returned.
  87  *
  88  * @ingroup Diskselector
  89  */
  90 EAPI Eina_Bool              elm_diskselector_round_enabled_get(const Evas_Object *obj);
  91
  92 /**
  93  * Get the side labels max length.
  94  *
  95  * @see elm_diskselector_side_text_max_length_set() for details.
  96  *
  97  * @param obj The diskselector object.
  98  * @return The max length defined for side labels, or 0 if not a valid
  99  * diskselector.
 100  *
 101  * @ingroup Diskselector
 102  */
 103 EAPI int                    elm_diskselector_side_text_max_length_get(const Evas_Object *obj);
 104
 105 /**
 106  * Set the side labels max length.
 107  *
 108  * @param obj The diskselector object.
 109  * @param len The max length defined for side labels.
 110  *
 111  * Length is the number of characters of items' label that will be
 112  * visible when it's set on side positions. It will just crop
 113  * the string after defined size. E.g.:
 114  *
 115  * An item with label "January" would be displayed on side position as
 116  * "Jan" if max length is set to 3, or "Janu", if this property
 117  * is set to 4.
 118  *
 119  * When it's selected, the entire label will be displayed, except for
 120  * width restrictions. In this case label will be cropped and "..."
 121  * will be concatenated.
 122  *
 123  * Default side label max length is 3.
 124  *
 125  * This property will be applied over all items, included before or
 126  * later this function call.
 127  *
 128  * @ingroup Diskselector
 129  */
 130 EAPI void                   elm_diskselector_side_text_max_length_set(Evas_Object *obj, int len);
 131
 132 /**
 133  * Set the number of items to be displayed.
 134  *
 135  * @param obj The diskselector object.
 136  * @param num The number of items the diskselector will display.
 137  *
 138  * Default value is 3, and also it's the minimum. If @p num is less
 139  * than 3, it will be set to 3.
 140  *
 141  * Also, it can be set on theme, using data item @c display_item_num
 142  * on group "elm/diskselector/item/X", where X is style set.
 143  * E.g.:
 144  *
 145  * group { name: "elm/diskselector/item/X";
 146  * data {
 147  *     item: "display_item_num" "5";
 148  *     }
 149  *
 150  * @ingroup Diskselector
 151  */
 152 EAPI void                   elm_diskselector_display_item_num_set(Evas_Object *obj, int num);
 153
 154 /**
 155  * Get the number of items in the diskselector object.
 156  *
 157  * @param obj The diskselector object.
 158  *
 159  * @ingroup Diskselector
 160  */
 161 EAPI int                   elm_diskselector_display_item_num_get(const Evas_Object *obj);
 162
 163 /**
 164  * Set bouncing behaviour when the scrolled content reaches an edge.
 165  *
 166  * Tell the internal scroller object whether it should bounce or not
 167  * when it reaches the respective edges for each axis.
 168  *
 169  * @param obj The diskselector object.
 170  * @param h_bounce Whether to bounce or not in the horizontal axis.
 171  * @param v_bounce Whether to bounce or not in the vertical axis.
 172  *
 173  * @see elm_scroller_bounce_set()
 174  *
 175  * @ingroup Diskselector
 176  */
 177 EAPI void                   elm_diskselector_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce);
 178
 179 /**
 180  * Get the bouncing behaviour of the internal scroller.
 181  *
 182  * Get whether the internal scroller should bounce when the edge of each
 183  * axis is reached scrolling.
 184  *
 185  * @param obj The diskselector object.
 186  * @param h_bounce Pointer to store the bounce state of the horizontal
 187  * axis.
 188  * @param v_bounce Pointer to store the bounce state of the vertical
 189  * axis.
 190  *
 191  * @see elm_scroller_bounce_get()
 192  * @see elm_diskselector_bounce_set()
 193  *
 194  * @ingroup Diskselector
 195  */
 196 EAPI void                   elm_diskselector_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce);
 197
 198 /**
 199  * Get the scrollbar policy.
 200  *
 201  * @see elm_diskselector_scroller_policy_get() for details.
 202  *
 203  * @param obj The diskselector object.
 204  * @param policy_h Pointer to store horizontal scrollbar policy.
 205  * @param policy_v Pointer to store vertical scrollbar policy.
 206  *
 207  * @ingroup Diskselector
 208  */
 209 EAPI void                   elm_diskselector_scroller_policy_get(const Evas_Object *obj, Elm_Scroller_Policy *policy_h, Elm_Scroller_Policy *policy_v);
 210
 211 /**
 212  * Set the scrollbar policy.
 213  *
 214  * @param obj The diskselector object.
 215  * @param policy_h Horizontal scrollbar policy.
 216  * @param policy_v Vertical scrollbar policy.
 217  *
 218  * This sets the scrollbar visibility policy for the given scroller.
 219  * #ELM_SCROLLER_POLICY_AUTO means the scrollbar is made visible if it
 220  * is needed, and otherwise kept hidden. #ELM_SCROLLER_POLICY_ON turns
 221  * it on all the time, and #ELM_SCROLLER_POLICY_OFF always keeps it off.
 222  * This applies respectively for the horizontal and vertical scrollbars.
 223  *
 224  * The both are disabled by default, i.e., are set to
 225  * #ELM_SCROLLER_POLICY_OFF.
 226  *
 227  * @ingroup Diskselector
 228  */
 229 EAPI void                   elm_diskselector_scroller_policy_set(Evas_Object *obj, Elm_Scroller_Policy policy_h, Elm_Scroller_Policy policy_v);
 230
 231 /**
 232  * Remove all diskselector's items.
 233  *
 234  * @param obj The diskselector object.
 235  *
 236  * @see elm_object_item_del()
 237  * @see elm_diskselector_item_append()
 238  *
 239  * @ingroup Diskselector
 240  */
 241 EAPI void                   elm_diskselector_clear(Evas_Object *obj);
 242
 243 /**
 244  * Get a list of all the diskselector items.
 245  *
 246  * @param obj The diskselector object.
 247  * @return An @c Eina_List of diskselector items, #Elm_Object_Item,
 248  * or @c NULL on failure.
 249  *
 250  * @see elm_diskselector_item_append()
 251  * @see elm_object_item_del()
 252  * @see elm_diskselector_clear()
 253  *
 254  * @ingroup Diskselector
 255  */
 256 EAPI const Eina_List       *elm_diskselector_items_get(const Evas_Object *obj);
 257
 258 /**
 259  * Appends a new item to the diskselector object.
 260  *
 261  * @param obj The diskselector object.
 262  * @param label The label of the diskselector item.
 263  * @param icon The icon object to use at left side of the item. An
 264  * icon can be any Evas object, but usually it is an icon created
 265  * with elm_icon_add().
 266  * @param func The function to call when the item is selected.
 267  * @param data The data to associate with the item for related callbacks.
 268  *
 269  * @return The created item or @c NULL upon failure.
 270  *
 271  * A new item will be created and appended to the diskselector, i.e., will
 272  * be set as last item. Also, if there is no selected item, it will
 273  * be selected. This will always happens for the first appended item.
 274  *
 275  * If no icon is set, label will be centered on item position, otherwise
 276  * the icon will be placed at left of the label, that will be shifted
 277  * to the right.
 278  *
 279  * Items created with this method can be deleted with
 280  * elm_object_item_del().
 281  *
 282  * Associated @p data can be properly freed when item is deleted if a
 283  * callback function is set with elm_object_item_del_cb_set().
 284  *
 285  * If a function is passed as argument, it will be called every time this item
 286  * is selected, i.e., the user stops the diskselector with this
 287  * item on center position. If such function isn't needed, just passing
 288  * @c NULL as @p func is enough. The same should be done for @p data.
 289  *
 290  * Simple example (with no function callback or data associated):
 291  * @code
 292  * disk = elm_diskselector_add(win);
 293  * ic = elm_icon_add(win);
 294  * elm_icon_file_set(ic, "path/to/image", NULL);
 295  * elm_icon_resizable_set(ic, EINA_TRUE, EINA_TRUE);
 296  * elm_diskselector_item_append(disk, "label", ic, NULL, NULL);
 297  * @endcode
 298  *
 299  * @see elm_object_item_del()
 300  * @see elm_diskselector_clear()
 301  * @see elm_icon_add()
 302  *
 303  * @ingroup Diskselector
 304  */
 305 EAPI Elm_Object_Item *elm_diskselector_item_append(Evas_Object *obj, const char *label, Evas_Object *icon, Evas_Smart_Cb func, const void *data);
 306
 307 /**
 308  * Get the selected item.
 309  *
 310  * @param obj The diskselector object.
 311  * @return The selected diskselector item.
 312  *
 313  * The selected item can be unselected with function
 314  * elm_diskselector_item_selected_set(), and the first item of
 315  * diskselector will be selected.
 316  *
 317  * The selected item always will be centered on diskselector, with
 318  * full label displayed, i.e., max length set to side labels won't
 319  * apply on the selected item. More details on
 320  * elm_diskselector_side_text_max_length_set().
 321  *
 322  * @ingroup Diskselector
 323  */
 324 EAPI Elm_Object_Item *elm_diskselector_selected_item_get(const Evas_Object *obj);
 325
 326 /**
 327  * Set the selected state of an item.
 328  *
 329  * @param it The diskselector item
 330  * @param selected The selected state
 331  *
 332  * This sets the selected state of the given item @p it.
 333  * @c EINA_TRUE for selected, @c EINA_FALSE for not selected.
 334  *
 335  * If a new item is selected the previously selected will be unselected.
 336  * Previously selected item can be get with function
 337  * elm_diskselector_selected_item_get().
 338  *
 339  * If the item @p it is unselected, the first item of diskselector will
 340  * be selected.
 341  *
 342  * Selected items will be visible on center position of diskselector.
 343  * So if it was on another position before selected, or was invisible,
 344  * diskselector will animate items until the selected item reaches center
 345  * position.
 346  *
 347  * @see elm_diskselector_item_selected_get()
 348  * @see elm_diskselector_selected_item_get()
 349  *
 350  * @ingroup Diskselector
 351  */
 352 EAPI void                   elm_diskselector_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
 353
 354 /*
 355  * Get whether the @p item is selected or not.
 356  *
 357  * @param it The diskselector item.
 358  * @return @c EINA_TRUE means item is selected. @c EINA_FALSE indicates
 359  * it's not. If @p obj is @c NULL, @c EINA_FALSE is returned.
 360  *
 361  * @see elm_diskselector_selected_item_set() for details.
 362  * @see elm_diskselector_item_selected_get()
 363  *
 364  * @ingroup Diskselector
 365  */
 366 EAPI Eina_Bool              elm_diskselector_item_selected_get(const Elm_Object_Item *it);
 367
 368 /**
 369  * Get the first item of the diskselector.
 370  *
 371  * @param obj The diskselector object.
 372  * @return The first item, or @c NULL if none.
 373  *
 374  * The list of items follows append order. So it will return the first
 375  * item appended to the widget that wasn't deleted.
 376  *
 377  * @see elm_diskselector_item_append()
 378  * @see elm_diskselector_items_get()
 379  *
 380  * @ingroup Diskselector
 381  */
 382 EAPI Elm_Object_Item *elm_diskselector_first_item_get(const Evas_Object *obj);
 383
 384 /**
 385  * Get the last item of the diskselector.
 386  *
 387  * @param obj The diskselector object.
 388  * @return The last item, or @c NULL if none.
 389  *
 390  * The list of items follows append order. So it will return last first
 391  * item appended to the widget that wasn't deleted.
 392  *
 393  * @see elm_diskselector_item_append()
 394  * @see elm_diskselector_items_get()
 395  *
 396  * @ingroup Diskselector
 397  */
 398 EAPI Elm_Object_Item *elm_diskselector_last_item_get(const Evas_Object *obj);
 399
 400 /**
 401  * Get the item before @p item in diskselector.
 402  *
 403  * @param it The diskselector item.
 404  * @return The item before @p item, or @c NULL if none or on failure.
 405  *
 406  * The list of items follows append order. So it will return item appended
 407  * just before @p item and that wasn't deleted.
 408  *
 409  * If it is the first item, @c NULL will be returned.
 410  * First item can be get by elm_diskselector_first_item_get().
 411  *
 412  * @see elm_diskselector_item_append()
 413  * @see elm_diskselector_items_get()
 414  *
 415  * @ingroup Diskselector
 416  */
 417 EAPI Elm_Object_Item *elm_diskselector_item_prev_get(const Elm_Object_Item *it);
 418
 419 /**
 420  * Get the item after @p item in diskselector.
 421  *
 422  * @param it The diskselector item.
 423  * @return The item after @p item, or @c NULL if none or on failure.
 424  *
 425  * The list of items follows append order. So it will return item appended
 426  * just after @p item and that wasn't deleted.
 427  *
 428  * If it is the last item, @c NULL will be returned.
 429  * Last item can be get by elm_diskselector_last_item_get().
 430  *
 431  * @see elm_diskselector_item_append()
 432  * @see elm_diskselector_items_get()
 433  *
 434  * @ingroup Diskselector
 435  */
 436 EAPI Elm_Object_Item *elm_diskselector_item_next_get(const Elm_Object_Item *it);
 437
 438 /**
 439  * @}
 440  */
 441