201 lines
7.7 KiB
Plaintext
201 lines
7.7 KiB
Plaintext
~~Title: Scroller Container PG~~
|
|
{{page>index}}
|
|
----
|
|
===== Scroller Container =====
|
|
|
|
{{ :container_scroller_tree.png }}{{ :container_scroller.png }}
|
|
|
|
A scroller holds (and clips) a single object and allows you to scroll across
|
|
it. This means that the user can use a scroll bar or their finger to drag the
|
|
viewable region across the object, moving through a much larger area than is
|
|
contained in the viewport. The scroller will always have a default minimum
|
|
size that is not limited by its contents.
|
|
|
|
The scroller widget inherits all the functions of the
|
|
[[/program_guide/container/layout|Layout Container]].
|
|
|
|
=== Table of Contents ===
|
|
|
|
* [[/program_guide/containers/scroller#Creating_a_Scroller|Creating a Scroller]]
|
|
* [[/program_guide/containers/scroller#Adding_Objects_to_the_Scroller|Adding Objects to the Scroller]]
|
|
* [[/program_guide/containers/scroller#Managing_the_Properties_of_the_Scroller|Managing the Properties of the Scroller]]
|
|
* [[/program_guide/containers/scroller#Signals|Signals]]
|
|
* [[/program_guide/containers/scroller#Example|Example]]
|
|
|
|
=== Related Info ===
|
|
|
|
* [[https://build.enlightenment.org/job/nightly_elm_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Scroller.html|Scroller Container API]]
|
|
* [[https://build.enlightenment.org/job/nightly_elm_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/tutorial_scroller.html|A Scroller Example]]
|
|
|
|
===== Creating a Scroller =====
|
|
|
|
To create a scroller, use the ''elm_scroller_add()'' function:
|
|
|
|
<code c>
|
|
Evas_Object *scroller = elm_scroller_add(parent);
|
|
</code>
|
|
|
|
==== Adding Objects to the Scoller ====
|
|
|
|
To add an object to the scroller, use the ''elm_object_content_set()'' function:
|
|
|
|
<code c>
|
|
Evas_Object *image;
|
|
|
|
image = elm_image_add(parent);
|
|
elm_image_file_set(image, "image.png", NULL);
|
|
evas_object_show(image);
|
|
evas_object_size_hint_min_set(image, 2560, 1600);
|
|
elm_object_content_set(scroller, image);
|
|
</code>
|
|
|
|
In the above code, we set a minimum size of 2560 x 1600 pixels for the image.
|
|
The scroller is smaller than the image, so you can scroll across the image.
|
|
|
|
If you want to be informed when the user begins scrolling the image, use the
|
|
following code:
|
|
|
|
<code c>
|
|
evas_object_smart_callback_add(scroller, "scroll,drag,start",
|
|
_scroll_start_cb, NULL);
|
|
|
|
// Callback function for the "animate,begin" signal.
|
|
// This callback is called when the user begins scrolling the image.
|
|
void _scroll_start_cb(void *data, Evas_Object *obj, void *event_info)
|
|
{
|
|
printf("Scroll starts\n");
|
|
}
|
|
</code>
|
|
|
|
==== Managing the Properties of the Scroll ====
|
|
|
|
When scrolling content, the scroller may "bounce" when reaching the edge of
|
|
the content. This is a visual way of indicating that there is no more content
|
|
to scroll in that direction. Bounce is enabled by default for both axes. To
|
|
enable or disable the bounce for either or both axes, use the
|
|
elm_scroller_bounce_set() function. The following code disables the bounce for
|
|
the horizontal axis and enables it for the vertical axis:
|
|
|
|
<code c>
|
|
elm_scroller_bounce_set(scroller, EINA_FALSE, EINA_TRUE);
|
|
</code>
|
|
|
|
The scroller can limit the scrolling to "pages". In this case, the scrolling
|
|
occurs in page-sized chunks of content rather than in a purely continuous
|
|
fashion, with the scroller displaying a single "page" at a time. This feature
|
|
sets the size of the page relative to the viewport of the scroller. A size of
|
|
1.0 equals 1 viewport (horizontally or vertically). A size of 0.0 disables
|
|
paging for that axis. These settings are mutually exclusive with page size
|
|
(see the ''elm_scroller_page_size_set()'' function). A size of 0.5 equals half a
|
|
viewport. Usable size values are normally between 0.0 and 1.0, including 1.0.
|
|
If you only want a single axis to scroll in pages, use 0.0 for the other axis.
|
|
|
|
==== Signals ====
|
|
|
|
The scroller emits the following signals, which you can catch in your
|
|
application:
|
|
|
|
* ''"edge,left"'' - the left edge of the content has been reached
|
|
* ''"edge,right"'' - the right edge of the content has been reached
|
|
* ''"edge,top"'' - the top edge of the content has been reached
|
|
* ''"edge,bottom"'' - the bottom edge of the content has been reached
|
|
* ''"scroll"'' - the content has been scrolled (moved)
|
|
* ''"scroll,left"'' - the content has been scrolled (moved) leftwards
|
|
* ''"scroll,right"'' - the content has been scrolled (moved) rightwards
|
|
* ''"scroll,up"'' - the content has been scrolled (moved) upwards
|
|
* ''"scroll,down"'' - the content has been scrolled (moved) downwards
|
|
* ''"scroll,anim,start"'' - scrolling animation has started
|
|
* ''"scroll,anim,stop"'' - scrolling animation has stopped
|
|
* ''"scroll,drag,start"'' - dragging the contents around has started
|
|
* ''"scroll,drag,stop"'' - dragging the contents around has stopped
|
|
* ''"vbar,drag"'' - the vertical scroll bar has been dragged
|
|
* ''"vbar,press"'' - the vertical scroll bar has been pressed
|
|
* ''"vbar,unpress"'' - the vertical scroll bar has been unpressed
|
|
* ''"hbar,drag"'' - the horizontal scroll bar has been dragged
|
|
* ''"hbar,press"'' - the horizontal scroll bar has been pressed
|
|
* ''"hbar,unpress"'' - the horizontal scroll bar has been unpressed
|
|
* ''"scroll,page,changed"'' - the visible page has changed
|
|
* ''"focused"'' - When the scroller has received focus. (since 1.8)
|
|
* ''"unfocused"'' - When the scroller has lost focus. (since 1.8)
|
|
|
|
|
|
==== Example ====
|
|
|
|
A good example of the scroller is a picture slideshow: we add images to the
|
|
scroller and limit the scrolling to pages (one picture at a time). In the
|
|
following code, we disable the scroll bars for both axes, limit the scrolling
|
|
to pages by using the ''elm_scroller_page_scroll_limit_set()'' function, and lock
|
|
the scrolling on the Y axis by using the ''elm_object_scroll_lock_y_set()''
|
|
function:
|
|
|
|
<code c>
|
|
elm_scroller_policy_set(scroller, ELM_SCROLLER_POLICY_OFF, ELM_SCROLLER_POLICY_OFF);
|
|
elm_scroller_page_scroll_limit_set(scroller, 1, 0);
|
|
elm_object_scroll_lock_y_set(scroller, EINA_TRUE);
|
|
</code>
|
|
|
|
We create a horizontal box, which will contain all the images, and which
|
|
itself will be contained by the scroller:
|
|
|
|
<code c>
|
|
box = elm_box_add(scroller);
|
|
elm_box_horizontal_set(box, EINA_TRUE);
|
|
elm_object_content_set(scroller, box);
|
|
evas_object_show(box);
|
|
</code>
|
|
|
|
We then create all the images and add them to the horizontal box:
|
|
|
|
<code c>
|
|
img = elm_image_add(scroller);
|
|
snprintf(buf, sizeof(buf), IMAGE_DIR"/%d.jpg", i);
|
|
elm_image_file_set(img, buf, NULL);
|
|
evas_object_show(img);
|
|
pages = eina_list_append(pages, img);
|
|
elm_box_pack_end(box, img);
|
|
</code>
|
|
|
|
We store references to the images in an ''eina_list'' for easy retrieval later.
|
|
|
|
Finally, we display the first page of the scroller:
|
|
|
|
<code c>
|
|
elm_scroller_page_show(scroller, 0, 0);
|
|
</code>
|
|
|
|
The size of the scroller depends on the size of the parent. When the parent
|
|
changes, for example when the window is resized or rotated, the scroller is
|
|
also resized. Since we need to be informed when the scroller is resized, we
|
|
add a callback on the ''EVAS_CALLBACK_RESIZE'' event for the scroller:
|
|
|
|
<code c>
|
|
evas_object_event_callback_add(scroller, EVAS_CALLBACK_RESIZE, _scroller_resize_cb, NULL);
|
|
</code>
|
|
|
|
The callback retrieves the new size of the scroller by using the
|
|
''evas_object_geometry_get()'' function on the object pointer. The pointer is
|
|
relative to the object that has been resized, which in our case is the
|
|
scroller itself. We can then iterate through the images of the scroller and
|
|
set the minimum size to fit the scroller size:
|
|
|
|
<code c>
|
|
EINA_LIST_FOREACH(images, l, page)
|
|
{
|
|
evas_object_size_hint_min_set(page, w, h);
|
|
}
|
|
</code>
|
|
|
|
Finally, we set the page size of the scroller to match the scroller size and
|
|
display the first page:
|
|
|
|
<code c>
|
|
elm_scroller_page_size_set(obj, w, h);
|
|
elm_scroller_page_show(obj, 0, 0);
|
|
</code>
|
|
|
|
\\
|
|
[[https://build.enlightenment.org/job/nightly_elm_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/tutorial_scroller.html|A Scroller Example]]
|
|
\\
|
|
----
|
|
{{page>index}}
|