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  * - "selected" - when item is selected, i.e. scroller stops.
  17  *
  18  * Available styles for it:
  19  * - @c "default"
  20  *
  21  * Default contents parts of the diskseletor items that you can use for are:
  22  * @li "icon" - An icon in the diskselector item
  23  *
  24  * Default text parts of the diskselector items that you can use for are:
  25  * @li "default" - Label of the diskselector item
  26  *
  27  * List of examples:
  28  * @li @ref diskselector_example_01
  29  * @li @ref diskselector_example_02
  30  */
  31
  32 /**
  33  * @addtogroup Diskselector
  34  * @{
  35  */
  36
  37 /**
  38  * Add a new diskselector widget to the given parent Elementary
  39  * (container) object.
  40  *
  41  * @param parent The parent object.
  42  * @return a new diskselector widget handle or @c NULL, on errors.
  43  *
  44  * This function inserts a new diskselector widget on the canvas.
  45  *
  46  * @ingroup Diskselector
  47  */
  48 EAPI Evas_Object           *elm_diskselector_add(Evas_Object *parent);
  49
  50 /**
  51  * Enable or disable round mode.
  52  *
  53  * @param obj The diskselector object.
  54  * @param round @c EINA_TRUE to enable round mode or @c EINA_FALSE to
  55  * disable it.
  56  *
  57  * Disabled by default. If round mode is enabled the items list will
  58  * work like a circle list, so when the user reaches the last item,
  59  * the first one will popup.
  60  *
  61  * @see elm_diskselector_round_get()
  62  *
  63  * @ingroup Diskselector
  64  */
  65 EAPI void                   elm_diskselector_round_set(Evas_Object *obj, Eina_Bool round);
  66
  67 /**
  68  * Get a value whether round mode is enabled or not.
  69  *
  70  * @see elm_diskselector_round_set() for details.
  71  *
  72  * @param obj The diskselector object.
  73  * @return @c EINA_TRUE means round mode is enabled. @c EINA_FALSE indicates
  74  * it's disabled. If @p obj is @c NULL, @c EINA_FALSE is returned.
  75  *
  76  * @ingroup Diskselector
  77  */
  78 EAPI Eina_Bool              elm_diskselector_round_get(const Evas_Object *obj);
  79
  80 /**
  81  * Get the side labels max length.
  82  *
  83  * @see elm_diskselector_side_label_length_set() for details.
  84  *
  85  * @param obj The diskselector object.
  86  * @return The max length defined for side labels, or 0 if not a valid
  87  * diskselector.
  88  *
  89  * @ingroup Diskselector
  90  */
  91 EAPI int                    elm_diskselector_side_label_length_get(const Evas_Object *obj);
  92
  93 /**
  94  * Set the side labels max length.
  95  *
  96  * @param obj The diskselector object.
  97  * @param len The max length defined for side labels.
  98  *
  99  * Length is the number of characters of items' label that will be
 100  * visible when it's set on side positions. It will just crop
 101  * the string after defined size. E.g.:
 102  *
 103  * An item with label "January" would be displayed on side position as
 104  * "Jan" if max length is set to 3, or "Janu", if this property
 105  * is set to 4.
 106  *
 107  * When it's selected, the entire label will be displayed, except for
 108  * width restrictions. In this case label will be cropped and "..."
 109  * will be concatenated.
 110  *
 111  * Default side label max length is 3.
 112  *
 113  * This property will be applyed over all items, included before or
 114  * later this function call.
 115  *
 116  * @ingroup Diskselector
 117  */
 118 EAPI void                   elm_diskselector_side_label_length_set(Evas_Object *obj, int len);
 119
 120 /**
 121  * Set the number of items to be displayed.
 122  *
 123  * @param obj The diskselector object.
 124  * @param num The number of items the diskselector will display.
 125  *
 126  * Default value is 3, and also it's the minimun. If @p num is less
 127  * than 3, it will be set to 3.
 128  *
 129  * Also, it can be set on theme, using data item @c display_item_num
 130  * on group "elm/diskselector/item/X", where X is style set.
 131  * E.g.:
 132  *
 133  * group { name: "elm/diskselector/item/X";
 134  * data {
 135  *     item: "display_item_num" "5";
 136  *     }
 137  *
 138  * @ingroup Diskselector
 139  */
 140 EAPI void                   elm_diskselector_display_item_num_set(Evas_Object *obj, int num);
 141
 142 /**
 143  * Get the number of items in the diskselector object.
 144  *
 145  * @param obj The diskselector object.
 146  *
 147  * @ingroup Diskselector
 148  */
 149 EAPI int                   elm_diskselector_display_item_num_get(const Evas_Object *obj);
 150
 151 /**
 152  * Set bouncing behaviour when the scrolled content reaches an edge.
 153  *
 154  * Tell the internal scroller object whether it should bounce or not
 155  * when it reaches the respective edges for each axis.
 156  *
 157  * @param obj The diskselector object.
 158  * @param h_bounce Whether to bounce or not in the horizontal axis.
 159  * @param v_bounce Whether to bounce or not in the vertical axis.
 160  *
 161  * @see elm_scroller_bounce_set()
 162  *
 163  * @ingroup Diskselector
 164  */
 165 EAPI void                   elm_diskselector_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce);
 166
 167 /**
 168  * Get the bouncing behaviour of the internal scroller.
 169  *
 170  * Get whether the internal scroller should bounce when the edge of each
 171  * axis is reached scrolling.
 172  *
 173  * @param obj The diskselector object.
 174  * @param h_bounce Pointer where to store the bounce state of the horizontal
 175  * axis.
 176  * @param v_bounce Pointer where to store the bounce state of the vertical
 177  * axis.
 178  *
 179  * @see elm_scroller_bounce_get()
 180  * @see elm_diskselector_bounce_set()
 181  *
 182  * @ingroup Diskselector
 183  */
 184 EAPI void                   elm_diskselector_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce);
 185
 186 /**
 187  * Get the scrollbar policy.
 188  *
 189  * @see elm_diskselector_scroller_policy_get() for details.
 190  *
 191  * @param obj The diskselector object.
 192  * @param policy_h Pointer where to store horizontal scrollbar policy.
 193  * @param policy_v Pointer where to store vertical scrollbar policy.
 194  *
 195  * @ingroup Diskselector
 196  */
 197 EAPI void                   elm_diskselector_scroller_policy_get(const Evas_Object *obj, Elm_Scroller_Policy *policy_h, Elm_Scroller_Policy *policy_v);
 198
 199 /**
 200  * Set the scrollbar policy.
 201  *
 202  * @param obj The diskselector object.
 203  * @param policy_h Horizontal scrollbar policy.
 204  * @param policy_v Vertical scrollbar policy.
 205  *
 206  * This sets the scrollbar visibility policy for the given scroller.
 207  * #ELM_SCROLLER_POLICY_AUTO means the scrollbar is made visible if it
 208  * is needed, and otherwise kept hidden. #ELM_SCROLLER_POLICY_ON turns
 209  * it on all the time, and #ELM_SCROLLER_POLICY_OFF always keeps it off.
 210  * This applies respectively for the horizontal and vertical scrollbars.
 211  *
 212  * The both are disabled by default, i.e., are set to
 213  * #ELM_SCROLLER_POLICY_OFF.
 214  *
 215  * @ingroup Diskselector
 216  */
 217 EAPI void                   elm_diskselector_scroller_policy_set(Evas_Object *obj, Elm_Scroller_Policy policy_h, Elm_Scroller_Policy policy_v);
 218
 219 /**
 220  * Remove all diskselector's items.
 221  *
 222  * @param obj The diskselector object.
 223  *
 224  * @see elm_diskselector_item_del()
 225  * @see elm_diskselector_item_append()
 226  *
 227  * @ingroup Diskselector
 228  */
 229 EAPI void                   elm_diskselector_clear(Evas_Object *obj);
 230
 231 /**
 232  * Get a list of all the diskselector items.
 233  *
 234  * @param obj The diskselector object.
 235  * @return An @c Eina_List of diskselector items, #Elm_Object_Item,
 236  * or @c NULL on failure.
 237  *
 238  * @see elm_diskselector_item_append()
 239  * @see elm_diskselector_item_del()
 240  * @see elm_diskselector_clear()
 241  *
 242  * @ingroup Diskselector
 243  */
 244 EAPI const Eina_List       *elm_diskselector_items_get(const Evas_Object *obj);
 245
 246 /**
 247  * Appends a new item to the diskselector object.
 248  *
 249  * @param obj The diskselector object.
 250  * @param label The label of the diskselector item.
 251  * @param icon The icon object to use at left side of the item. An
 252  * icon can be any Evas object, but usually it is an icon created
 253  * with elm_icon_add().
 254  * @param func The function to call when the item is selected.
 255  * @param data The data to associate with the item for related callbacks.
 256  *
 257  * @return The created item or @c NULL upon failure.
 258  *
 259  * A new item will be created and appended to the diskselector, i.e., will
 260  * be set as last item. Also, if there is no selected item, it will
 261  * be selected. This will always happens for the first appended item.
 262  *
 263  * If no icon is set, label will be centered on item position, otherwise
 264  * the icon will be placed at left of the label, that will be shifted
 265  * to the right.
 266  *
 267  * Items created with this method can be deleted with
 268  * elm_diskselector_item_del().
 269  *
 270  * Associated @p data can be properly freed when item is deleted if a
 271  * callback function is set with elm_diskselector_item_del_cb_set().
 272  *
 273  * If a function is passed as argument, it will be called everytime this item
 274  * is selected, i.e., the user stops the diskselector with this
 275  * item on center position. If such function isn't needed, just passing
 276  * @c NULL as @p func is enough. The same should be done for @p data.
 277  *
 278  * Simple example (with no function callback or data associated):
 279  * @code
 280  * disk = elm_diskselector_add(win);
 281  * ic = elm_icon_add(win);
 282  * elm_icon_file_set(ic, "path/to/image", NULL);
 283  * elm_icon_scale_set(ic, EINA_TRUE, EINA_TRUE);
 284  * elm_diskselector_item_append(disk, "label", ic, NULL, NULL);
 285  * @endcode
 286  *
 287  * @see elm_diskselector_item_del()
 288  * @see elm_diskselector_item_del_cb_set()
 289  * @see elm_diskselector_clear()
 290  * @see elm_icon_add()
 291  *
 292  * @ingroup Diskselector
 293  */
 294 EAPI Elm_Object_Item *elm_diskselector_item_append(Evas_Object *obj, const char *label, Evas_Object *icon, Evas_Smart_Cb func, const void *data);
 295
 296
 297 /**
 298  * Delete them item from the diskselector.
 299  *
 300  * @param it The item of diskselector to be deleted.
 301  *
 302  * If deleting all diskselector items is required, elm_diskselector_clear()
 303  * should be used instead of getting items list and deleting each one.
 304  *
 305  * @see elm_diskselector_clear()
 306  * @see elm_diskselector_item_append()
 307  * @see elm_diskselector_item_del_cb_set()
 308  *
 309  * @ingroup Diskselector
 310  */
 311 EAPI void                   elm_diskselector_item_del(Elm_Object_Item *it);
 312
 313 /**
 314  * Set the function called when a diskselector item is freed.
 315  *
 316  * @param it The item to set the callback on
 317  * @param func The function called
 318  *
 319  * If there is a @p func, then it will be called prior item's memory release.
 320  * That will be called with the following arguments:
 321  * @li item's data;
 322  * @li item's Evas object;
 323  * @li item itself;
 324  *
 325  * This way, a data associated to a diskselector item could be properly
 326  * freed.
 327  *
 328  * @ingroup Diskselector
 329  */
 330 EAPI void                   elm_diskselector_item_del_cb_set(Elm_Object_Item *it, Evas_Smart_Cb func);
 331
 332 /**
 333  * Get the selected item.
 334  *
 335  * @param obj The diskselector object.
 336  * @return The selected diskselector item.
 337  *
 338  * The selected item can be unselected with function
 339  * elm_diskselector_item_selected_set(), and the first item of
 340  * diskselector will be selected.
 341  *
 342  * The selected item always will be centered on diskselector, with
 343  * full label displayed, i.e., max lenght set to side labels won't
 344  * apply on the selected item. More details on
 345  * elm_diskselector_side_label_length_set().
 346  *
 347  * @ingroup Diskselector
 348  */
 349 EAPI Elm_Object_Item *elm_diskselector_selected_item_get(const Evas_Object *obj);
 350
 351 /**
 352  * Set the selected state of an item.
 353  *
 354  * @param it The diskselector item
 355  * @param selected The selected state
 356  *
 357  * This sets the selected state of the given item @p it.
 358  * @c EINA_TRUE for selected, @c EINA_FALSE for not selected.
 359  *
 360  * If a new item is selected the previosly selected will be unselected.
 361  * Previoulsy selected item can be get with function
 362  * elm_diskselector_selected_item_get().
 363  *
 364  * If the item @p it is unselected, the first item of diskselector will
 365  * be selected.
 366  *
 367  * Selected items will be visible on center position of diskselector.
 368  * So if it was on another position before selected, or was invisible,
 369  * diskselector will animate items until the selected item reaches center
 370  * position.
 371  *
 372  * @see elm_diskselector_item_selected_get()
 373  * @see elm_diskselector_selected_item_get()
 374  *
 375  * @ingroup Diskselector
 376  */
 377 EAPI void                   elm_diskselector_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
 378
 379 /*
 380  * Get whether the @p item is selected or not.
 381  *
 382  * @param it The diskselector item.
 383  * @return @c EINA_TRUE means item is selected. @c EINA_FALSE indicates
 384  * it's not. If @p obj is @c NULL, @c EINA_FALSE is returned.
 385  *
 386  * @see elm_diskselector_selected_item_set() for details.
 387  * @see elm_diskselector_item_selected_get()
 388  *
 389  * @ingroup Diskselector
 390  */
 391 EAPI Eina_Bool              elm_diskselector_item_selected_get(const Elm_Object_Item *it);
 392
 393 /**
 394  * Get the first item of the diskselector.
 395  *
 396  * @param obj The diskselector object.
 397  * @return The first item, or @c NULL if none.
 398  *
 399  * The list of items follows append order. So it will return the first
 400  * item appended to the widget that wasn't deleted.
 401  *
 402  * @see elm_diskselector_item_append()
 403  * @see elm_diskselector_items_get()
 404  *
 405  * @ingroup Diskselector
 406  */
 407 EAPI Elm_Object_Item *elm_diskselector_first_item_get(const Evas_Object *obj);
 408
 409 /**
 410  * Get the last item of the diskselector.
 411  *
 412  * @param obj The diskselector object.
 413  * @return The last item, or @c NULL if none.
 414  *
 415  * The list of items follows append order. So it will return last first
 416  * item appended to the widget that wasn't deleted.
 417  *
 418  * @see elm_diskselector_item_append()
 419  * @see elm_diskselector_items_get()
 420  *
 421  * @ingroup Diskselector
 422  */
 423 EAPI Elm_Object_Item *elm_diskselector_last_item_get(const Evas_Object *obj);
 424
 425 /**
 426  * Get the item before @p item in diskselector.
 427  *
 428  * @param it The diskselector item.
 429  * @return The item before @p item, or @c NULL if none or on failure.
 430  *
 431  * The list of items follows append order. So it will return item appended
 432  * just before @p item and that wasn't deleted.
 433  *
 434  * If it is the first item, @c NULL will be returned.
 435  * First item can be get by elm_diskselector_first_item_get().
 436  *
 437  * @see elm_diskselector_item_append()
 438  * @see elm_diskselector_items_get()
 439  *
 440  * @ingroup Diskselector
 441  */
 442 EAPI Elm_Object_Item *elm_diskselector_item_prev_get(const Elm_Object_Item *it);
 443
 444 /**
 445  * Get the item after @p item in diskselector.
 446  *
 447  * @param it The diskselector item.
 448  * @return The item after @p item, or @c NULL if none or on failure.
 449  *
 450  * The list of items follows append order. So it will return item appended
 451  * just after @p item and that wasn't deleted.
 452  *
 453  * If it is the last item, @c NULL will be returned.
 454  * Last item can be get by elm_diskselector_last_item_get().
 455  *
 456  * @see elm_diskselector_item_append()
 457  * @see elm_diskselector_items_get()
 458  *
 459  * @ingroup Diskselector
 460  */
 461 EAPI Elm_Object_Item *elm_diskselector_item_next_get(const Elm_Object_Item *it);
 462
 463 /**
 464  * Set the text to be shown in the diskselector item.
 465  *
 466  * @param it Target item
 467  * @param text The text to set in the content
 468  *
 469  * Setup the text as tooltip to object. The item can have only one tooltip,
 470  * so any previous tooltip data is removed.
 471  *
 472  * @see elm_object_tooltip_text_set() for more details.
 473  *
 474  * @ingroup Diskselector
 475  */
 476 EAPI void                   elm_diskselector_item_tooltip_text_set(Elm_Object_Item *it, const char *text);
 477
 478 /**
 479  * Set the content to be shown in the tooltip item.
 480  *
 481  * Setup the tooltip to item. The item can have only one tooltip,
 482  * so any previous tooltip data is removed. @p func(with @p data) will
 483  * be called every time that need show the tooltip and it should
 484  * return a valid Evas_Object. This object is then managed fully by
 485  * tooltip system and is deleted when the tooltip is gone.
 486  *
 487  * @param it the diskselector item being attached a tooltip.
 488  * @param func the function used to create the tooltip contents.
 489  * @param data what to provide to @a func as callback data/context.
 490  * @param del_cb called when data is not needed anymore, either when
 491  *        another callback replaces @p func, the tooltip is unset with
 492  *        elm_diskselector_item_tooltip_unset() or the owner @a item
 493  *        dies. This callback receives as the first parameter the
 494  *        given @a data, and @c event_info is the item.
 495  *
 496  * @see elm_object_tooltip_content_cb_set() for more details.
 497  *
 498  * @ingroup Diskselector
 499  */
 500 EAPI void                   elm_diskselector_item_tooltip_content_cb_set(Elm_Object_Item *it, Elm_Tooltip_Item_Content_Cb func, const void *data, Evas_Smart_Cb del_cb);
 501
 502 /**
 503  * Unset tooltip from item.
 504  *
 505  * @param it diskselector item to remove previously set tooltip.
 506  *
 507  * Remove tooltip from item. The callback provided as del_cb to
 508  * elm_diskselector_item_tooltip_content_cb_set() will be called to notify
 509  * it is not used anymore.
 510  *
 511  * @see elm_object_tooltip_unset() for more details.
 512  * @see elm_diskselector_item_tooltip_content_cb_set()
 513  *
 514  * @ingroup Diskselector
 515  */
 516 EAPI void                   elm_diskselector_item_tooltip_unset(Elm_Object_Item *it);
 517
 518 /**
 519  * Sets a different style for this item tooltip.
 520  *
 521  * @note before you set a style you should define a tooltip with
 522  *       elm_diskselector_item_tooltip_content_cb_set() or
 523  *       elm_diskselector_item_tooltip_text_set()
 524  *
 525  * @param it diskselector item with tooltip already set.
 526  * @param style the theme style to use (default, transparent, ...)
 527  *
 528  * @see elm_object_tooltip_style_set() for more details.
 529  *
 530  * @ingroup Diskselector
 531  */
 532 EAPI void                   elm_diskselector_item_tooltip_style_set(Elm_Object_Item *it, const char *style);
 533
 534 /**
 535  * Get the style for this item tooltip.
 536  *
 537  * @param it diskselector item with tooltip already set.
 538  * @return style the theme style in use, defaults to "default". If the
 539  *         object does not have a tooltip set, then NULL is returned.
 540  *
 541  * @see elm_object_tooltip_style_get() for more details.
 542  * @see elm_diskselector_item_tooltip_style_set()
 543  *
 544  * @ingroup Diskselector
 545  */
 546 EAPI const char            *elm_diskselector_item_tooltip_style_get(const Elm_Object_Item *it);
 547
 548 /**
 549  * Set the cursor to be shown when mouse is over the diskselector item
 550  *
 551  * @param it Target item
 552  * @param cursor the cursor name to be used.
 553  *
 554  * @see elm_object_cursor_set() for more details.
 555  *
 556  * @ingroup Diskselector
 557  */
 558 EAPI void                   elm_diskselector_item_cursor_set(Elm_Object_Item *it, const char *cursor);
 559
 560 /**
 561  * Get the cursor to be shown when mouse is over the diskselector item
 562  *
 563  * @param it diskselector item with cursor already set.
 564  * @return the cursor name.
 565  *
 566  * @see elm_object_cursor_get() for more details.
 567  * @see elm_diskselector_cursor_set()
 568  *
 569  * @ingroup Diskselector
 570  */
 571 EAPI const char            *elm_diskselector_item_cursor_get(const Elm_Object_Item *it);
 572
 573 /**
 574  * Unset the cursor to be shown when mouse is over the diskselector item
 575  *
 576  * @param it Target item
 577  *
 578  * @see elm_object_cursor_unset() for more details.
 579  * @see elm_diskselector_cursor_set()
 580  *
 581  * @ingroup Diskselector
 582  */
 583 EAPI void                   elm_diskselector_item_cursor_unset(Elm_Object_Item *it);
 584
 585 /**
 586  * Sets a different style for this item cursor.
 587  *
 588  * @note before you set a style you should define a cursor with
 589  *       elm_diskselector_item_cursor_set()
 590  *
 591  * @param it diskselector item with cursor already set.
 592  * @param style the theme style to use (default, transparent, ...)
 593  *
 594  * @see elm_object_cursor_style_set() for more details.
 595  *
 596  * @ingroup Diskselector
 597  */
 598 EAPI void                   elm_diskselector_item_cursor_style_set(Elm_Object_Item *it, const char *style);
 599
 600 /**
 601  * Get the style for this item cursor.
 602  *
 603  * @param it diskselector item with cursor already set.
 604  * @return style the theme style in use, defaults to "default". If the
 605  *         object does not have a cursor set, then @c NULL is returned.
 606  *
 607  * @see elm_object_cursor_style_get() for more details.
 608  * @see elm_diskselector_item_cursor_style_set()
 609  *
 610  * @ingroup Diskselector
 611  */
 612 EAPI const char            *elm_diskselector_item_cursor_style_get(const Elm_Object_Item *it);
 613
 614
 615 /**
 616  * Set if the cursor set should be searched on the theme or should use
 617  * the provided by the engine, only.
 618  *
 619  * @note before you set if should look on theme you should define a cursor
 620  * with elm_diskselector_item_cursor_set().
 621  * By default it will only look for cursors provided by the engine.
 622  *
 623  * @param it widget item with cursor already set.
 624  * @param engine_only boolean to define if cursors set with
 625  * elm_diskselector_item_cursor_set() should be searched only
 626  * between cursors provided by the engine or searched on widget's
 627  * theme as well.
 628  *
 629  * @see elm_object_cursor_engine_only_set() for more details.
 630  *
 631  * @ingroup Diskselector
 632  */
 633 EAPI void                   elm_diskselector_item_cursor_engine_only_set(Elm_Object_Item *it, Eina_Bool engine_only);
 634
 635 /**
 636  * Get the cursor engine only usage for this item cursor.
 637  *
 638  * @param it widget item with cursor already set.
 639  * @return engine_only boolean to define it cursors should be looked only
 640  * between the provided by the engine or searched on widget's theme as well.
 641  * If the item does not have a cursor set, then @c EINA_FALSE is returned.
 642  *
 643  * @see elm_object_cursor_engine_only_get() for more details.
 644  * @see elm_diskselector_item_cursor_engine_only_set()
 645  *
 646  * @ingroup Diskselector
 647  */
 648 EAPI Eina_Bool              elm_diskselector_item_cursor_engine_only_get(const Elm_Object_Item *it);
 649
 650 /**
 651  * @}
 652  */
 653