Tizen Native API  5.0
Diskselector

diskselector_inheritance_tree.png

A diskselector is a kind of list widget. It scrolls horizontally, and can contain label and icon objects. Three items are displayed with the selected one in the middle.

It can act like a circular list with round mode and labels can be reduced for a defined length for side items.

This widget implements the elm-scrollable-interface interface, so that all (non-deprecated) functions for the base Scroller widget also work for diskselectors.

Some calls on the diskselector's API are marked as deprecated, as they just wrap the scrollable widgets counterpart functions. Use the ones we point you to, for each case of deprecation here, instead -- eventually the deprecated ones will be discarded (next major release).

This widget emits the following signals, besides the ones sent from Layout:

  • "selected" - when item is selected, i.e. scroller stops.
  • "clicked" - This is called when a user clicks an item (since 1.8)
  • "scroll,anim,start" - scrolling animation has started
  • "scroll,anim,stop" - scrolling animation has stopped
  • "scroll,drag,start" - dragging the diskselector has started
  • "scroll,drag,stop" - dragging the diskselector has stopped
  • "focused" - When the diskselector has received focus. (since 1.8)
  • "unfocused" - When the diskselector has lost focus. (since 1.8)
  • "language,changed" - the program's language changed (since 1.9)
Note:
The "scroll,anim,*" and "scroll,drag,*" signals are only emitted by user intervention.

Available styles for it:

  • "default"

Default content parts of the diskselector items that you can use for are:

  • "icon" - An icon in the diskselector item

Default text parts of the diskselector items that you can use for are:

  • "default" - A label of the diskselector item

Supported elm_object_item common APIs.

List of examples:

Functions

EINA_DEPRECATED void elm_diskselector_bounce_set (Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce)
EINA_DEPRECATED void elm_diskselector_bounce_get (const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce)
EINA_DEPRECATED void elm_diskselector_scroller_policy_get (const Evas_Object *obj, Elm_Scroller_Policy *policy_h, Elm_Scroller_Policy *policy_v)
EINA_DEPRECATED void elm_diskselector_scroller_policy_set (Evas_Object *obj, Elm_Scroller_Policy policy_h, Elm_Scroller_Policy policy_v)
void elm_diskselector_side_text_max_length_set (Elm_Diskselector *obj, int len)
 Set the side labels max length.
int elm_diskselector_side_text_max_length_get (const Elm_Diskselector *obj)
 Get the side labels max length.
void elm_diskselector_round_enabled_set (Elm_Diskselector *obj, Eina_Bool enabled)
 Enable or disable round mode.
Eina_Bool elm_diskselector_round_enabled_get (const Elm_Diskselector *obj)
 Get a value whether round mode is enabled or not.
void elm_diskselector_display_item_num_set (Elm_Diskselector *obj, int num)
 Set the number of items to be displayed.
int elm_diskselector_display_item_num_get (const Elm_Diskselector *obj)
 Get the number of items in the diskselector object.
Elm_Widget_Itemelm_diskselector_first_item_get (const Elm_Diskselector *obj)
 Get the first item of the diskselector.
const Eina_Listelm_diskselector_items_get (const Elm_Diskselector *obj)
 Get a list of all the diskselector items.
Elm_Widget_Itemelm_diskselector_last_item_get (const Elm_Diskselector *obj)
 Get the last item of the diskselector.
Elm_Widget_Itemelm_diskselector_selected_item_get (const Elm_Diskselector *obj)
 Get the selected item.
Elm_Widget_Itemelm_diskselector_item_append (Elm_Diskselector *obj, const char *label, Efl_Canvas_Object *icon, Evas_Smart_Cb func, const void *data)
 Appends a new item to the diskselector object.
void elm_diskselector_clear (Elm_Diskselector *obj)
 Remove all diskselector's items.
Evas_Objectelm_diskselector_add (Evas_Object *parent)

Function Documentation

Add a new diskselector widget to the given parent Elementary (container) object.

Parameters:
parentThe parent object.
Returns:
a new diskselector widget handle or NULL, on errors.

This function inserts a new diskselector widget on the canvas.

Examples:
diskselector_example_01.c, and diskselector_example_02.c.
EINA_DEPRECATED void elm_diskselector_bounce_get ( const Evas_Object obj,
Eina_Bool h_bounce,
Eina_Bool v_bounce 
)

Get the bouncing behaviour of the internal scroller.

Get whether the internal scroller should bounce when the edge of each axis is reached scrolling.

Parameters:
objThe diskselector object.
h_bouncePointer to store the bounce state of the horizontal axis.
v_bouncePointer to store the bounce state of the vertical axis.
Deprecated:
Use elm_scroller_bounce_get() instead.
See also:
elm_scroller_bounce_get()
elm_diskselector_bounce_set()
EINA_DEPRECATED void elm_diskselector_bounce_set ( Evas_Object obj,
Eina_Bool  h_bounce,
Eina_Bool  v_bounce 
)

Set bouncing behaviour when the scrolled content reaches an edge.

Tell the internal scroller object whether it should bounce or not when it reaches the respective edges for each axis.

Parameters:
objThe diskselector object.
h_bounceWhether to bounce or not in the horizontal axis.
v_bounceWhether to bounce or not in the vertical axis.
Deprecated:
Use elm_scroller_bounce_set() instead.
See also:
elm_scroller_bounce_set()
void elm_diskselector_clear ( Elm_Diskselector *  obj)

Remove all diskselector's items.

See also elm_object_item_del, elm_diskselector_item_append.

Parameters:
[in]objThe object.
Examples:
diskselector_example_02.c.
int elm_diskselector_display_item_num_get ( const Elm_Diskselector *  obj)

Get the number of items in the diskselector object.

Parameters:
[in]objThe object.
Returns:
The number of items the diskselector will display.
Examples:
diskselector_example_01.c.
void elm_diskselector_display_item_num_set ( Elm_Diskselector *  obj,
int  num 
)

Set the number of items to be displayed.

Default value is 3, and also it's the minimum. If num is less than 3, it will be set to 3.

Also, it can be set on theme, using data item display_item_num on group "elm/diskselector/item/X", where X is style set.

Parameters:
[in]objThe object.
[in]numThe number of items the diskselector will display.
Examples:
diskselector_example_01.c.
Elm_Widget_Item* elm_diskselector_first_item_get ( const Elm_Diskselector *  obj)

Get the first item of the diskselector.

The list of items follows append order. So it will return the first item appended to the widget that wasn't deleted.

See also elm_diskselector_item_append, elm_diskselector_items_get.

Parameters:
[in]objThe object.
Returns:
The first item, or null if none.
Examples:
diskselector_example_02.c.
Elm_Widget_Item* elm_diskselector_item_append ( Elm_Diskselector *  obj,
const char *  label,
Efl_Canvas_Object icon,
Evas_Smart_Cb  func,
const void *  data 
)

Appends a new item to the diskselector object.

A new item will be created and appended to the diskselector, i.e., will be set as last item. Also, if there is no selected item, it will be selected. This will always happens for the first appended item.

If no icon is set, label will be centered on item position, otherwise the icon will be placed at left of the label, that will be shifted to the right.

Items created with this method can be deleted with elm_object_item_del.

Associated data can be properly freed when item is deleted if a callback function is set with elm_object_item_del_cb_set.

If a function is passed as argument, it will be called every time this item is selected, i.e., the user stops the diskselector with this item on center position. If such function isn't needed, just passing null as func is enough. The same should be done for data.

See also elm_object_item_del, elm_diskselector_clear, elm_icon_add.

Parameters:
[in]objThe object.
[in]labelThe label of the diskselector item.
[in]iconThe icon object to use at left side of the item. An icon can be any Evas object, but usually it is an icon created with elm_icon_add().
[in]funcThe function to call when the item is selected.
[in]dataThe data to associate with the item for related callbacks.
Returns:
New item
Examples:
diskselector_example_01.c, and diskselector_example_02.c.
const Eina_List* elm_diskselector_items_get ( const Elm_Diskselector *  obj)

Get a list of all the diskselector items.

See also elm_diskselector_item_append, elm_object_item_del, elm_diskselector_clear.

Parameters:
[in]objThe object.
Returns:
A list of diskselector items, or ull on failure.
Examples:
diskselector_example_02.c.
Elm_Widget_Item* elm_diskselector_last_item_get ( const Elm_Diskselector *  obj)

Get the last item of the diskselector.

The list of items follows append order. So it will return last first item appended to the widget that wasn't deleted.

See also elm_diskselector_item_append, elm_diskselector_items_get.

Parameters:
[in]objThe object.
Returns:
The last item, or null if none.
Examples:
diskselector_example_02.c.
Eina_Bool elm_diskselector_round_enabled_get ( const Elm_Diskselector *  obj)

Get a value whether round mode is enabled or not.

See also elm_diskselector_round_enabled_set for details.

Parameters:
[in]objThe object.
Returns:
true to enable round mode or false to disable it.
void elm_diskselector_round_enabled_set ( Elm_Diskselector *  obj,
Eina_Bool  enabled 
)

Enable or disable round mode.

Disabled by default. If round mode is enabled the items list will work like a circular list, so when the user reaches the last item, the first one will popup.

See also elm_diskselector_round_enabled_get.

Parameters:
[in]objThe object.
[in]enabledtrue to enable round mode or false to disable it.
Examples:
diskselector_example_01.c.

Get the scrollbar policy.

See also:
elm_diskselector_scroller_policy_get() for details.
Parameters:
objThe diskselector object.
policy_hPointer to store horizontal scrollbar policy.
policy_vPointer to store vertical scrollbar policy.
Deprecated:
Use elm_scroller_policy_get() instead.
See also:
elm_scroller_policy_get()

Set the scrollbar policy.

Parameters:
objThe diskselector object.
policy_hHorizontal scrollbar policy.
policy_vVertical scrollbar policy.

This sets the scrollbar visibility policy for the given scroller. ELM_SCROLLER_POLICY_AUTO means the scrollbar is made visible if it is needed, and otherwise kept hidden. ELM_SCROLLER_POLICY_ON turns it on all the time, and ELM_SCROLLER_POLICY_OFF always keeps it off. This applies respectively for the horizontal and vertical scrollbars.

The both are disabled by default, i.e., are set to ELM_SCROLLER_POLICY_OFF.

Deprecated:
Use elm_scroller_policy_set() instead.
See also:
elm_scroller_policy_set()
Elm_Widget_Item* elm_diskselector_selected_item_get ( const Elm_Diskselector *  obj)

Get the selected item.

The selected item can be unselected with elm_diskselector_item_selected_set, and the first item of diskselector will be selected.

The selected item always will be centered on diskselector, with full label displayed, i.e., max length set to side labels won't apply on the selected item. More details on elm_diskselector_side_text_max_length_set.

Parameters:
[in]objThe object.
Returns:
The selected diskselector item.
Examples:
diskselector_example_02.c.
int elm_diskselector_side_text_max_length_get ( const Elm_Diskselector *  obj)

Get the side labels max length.

See also elm_diskselector_side_text_max_length_set for details.

Parameters:
[in]objThe object.
Returns:
The max length defined for side labels.
void elm_diskselector_side_text_max_length_set ( Elm_Diskselector *  obj,
int  len 
)

Set the side labels max length.

Length is the number of characters of items' label that will be visible when it's set on side positions. It will just crop the string after defined size. E.g.:

An item with label "January" would be displayed on side position as "Jan" if max length is set to 3, or "Janu", if this property is set to 4.

When it's selected, the entire label will be displayed, except for width restrictions. In this case label will be cropped and "..." will be concatenated.

Default side label max length is 3.

This property will be applied over all items, included before or later this function call.

Parameters:
[in]objThe object.
[in]lenThe max length defined for side labels.
Examples:
diskselector_example_01.c.