src/lib/elm_diskselector.h

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