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