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