Elementary: hover documentation.

SVN revision: 61371

legacy/elementary/doc/examples.dox

@@ -1204,6 +1204,60 @@
  * @example flipselector_example.c
  */
 
+/**
+ * @page tutorial_hover Hover example
+ * @dontinclude hover_example_01.c
+ *
+ * On this example we are going to have a button that when clicked will show our
+ * hover widget, this hover will have content set on it's left, top, right and
+ * middle positions. In the middle position we are placing a button that when
+ * clicked will hide the hover. We are also going to use a non-default theme
+ * for our hover. We won't explain the functioning of button for that see @ref
+ * Button.
+ *
+ * We start our example with a couple of callbacks that show and hide the data
+ * they're given(which we'll see later on is the hover widget):
+ * @skip static
+ * @until }
+ * @until }
+ *
+ * In our main function we'll do some initialization and then create 3
+ * rectangles, one red, one green and one blue to use in our hover. We'll also
+ * create the 2 buttons that will show and hide the hover:
+ * @until show(bt2)
+ *
+ * With all of that squared away we can now get to the heart of the matter,
+ * creating our hover widget, which is easy as pie:
+ * @until hover
+ *
+ * Having created our hover we now need to set the parent and target. Which if
+ * you recall from the function documentations are going to tell the hover which
+ * area it should cover and where it should be centered:
+ * @until bt
+ *
+ * Now we set the theme for our hover. We're using the popout theme which gives
+ * our contents a white background and causes their appearance to be animated:
+ * @until popout
+ *
+ * And finally we set the content for our positions:
+ * @until bt2
+ *
+ * So far so good? Great 'cause that's all there is too it, what is left now is
+ * just connecting our buttons to the callbacks we defined at the beginning of
+ * the example and run the main loop:
+ * @until ELM_MAIN
+ *
+ * Our example will initially look like this:
+ * @image html screenshots/hover_example_01.png
+ * @image latex screenshots/hover_example_01.eps
+ *
+ * And after you click the "Show hover" button it will look like this:
+ * @image html screenshots/hover_example_01_a.png
+ * @image latex screenshots/hover_example_01_a.eps
+ *
+ * @example hover_example_01.c
+ */
+
 /**
   * @page tutorial_flip Flip example
   * @dontinclude flip_example_01.c

legacy/elementary/src/examples/Makefile.am

@@ -45,6 +45,7 @@ SRCS = \
 	box_example_02.c \
 	flip_example_01.c \
 	general_funcs_example.c \
+	hover_example_01.c \
 	label_example_01.c \
 	theme_example_01.c \
 	theme_example_02.c \
@@ -86,6 +87,7 @@ pkglib_PROGRAMS += \
 	box_example_02 \
 	flip_example_01 \
 	general_funcs_example \
+	hover_example_01 \
 	label_example_01 \
 	theme_example_01 \
 	theme_example_02 \
@@ -109,6 +111,7 @@ SCREENSHOTS = \
 	animator_example_01:animator_example_03.png:0.9 \
 	flip_example_01:flip_example_01.png:0.0 \
 	frame_example_01:frame_example_01.png:0.0 \
+	hover_example_01:hover_example_01.png:0.0 \
 	label_example_01:label_example_01.png:0.0 \
 	theme_example_01:theme_example_01.png:0.0 \
 	clock_example:clock_example.png:0.5 \

legacy/elementary/src/examples/hover_example_01.c

@@ -0,0 +1,81 @@
+//Compile with:
+//gcc -g `pkg-config --cflags --libs elementary` hover_example_01.c -o hover_example_01
+
+#include <Elementary.h>
+#ifdef HAVE_CONFIG_H
+# include "elementary_config.h"
+#endif
+
+static void
+_show_hover(void *data, Evas_Object *obj, void *event_info)
+{
+   evas_object_show(data);
+}
+
+static void
+_hide_hover(void *data, Evas_Object *obj, void *event_info)
+{
+   evas_object_hide(data);
+}
+
+EAPI int
+elm_main(int argc, char **argv)
+{
+   Evas_Object *win, *bg, *bt, *bt2, *rect, *rect2, *rect3, *hover;
+
+   win = elm_win_add(NULL, "hover", ELM_WIN_BASIC);
+   elm_win_title_set(win, "Hover");
+   elm_win_autodel_set(win, EINA_TRUE);
+   elm_policy_set(ELM_POLICY_QUIT, ELM_POLICY_QUIT_LAST_WINDOW_CLOSED);
+
+   bg = elm_bg_add(win);
+   elm_win_resize_object_add(win, bg);
+   evas_object_show(bg);
+
+   rect = evas_object_rectangle_add(evas_object_evas_get(win));
+   evas_object_size_hint_min_set(rect, 25, 25);
+   evas_object_color_set(rect, 255, 0, 0, 255);
+   evas_object_show(rect);
+
+   rect2 = evas_object_rectangle_add(evas_object_evas_get(win));
+   evas_object_size_hint_min_set(rect2, 25, 25);
+   evas_object_color_set(rect2, 0, 255, 0, 255);
+   evas_object_show(rect2);
+
+   rect3 = evas_object_rectangle_add(evas_object_evas_get(win));
+   evas_object_size_hint_min_set(rect3, 25, 25);
+   evas_object_color_set(rect3, 0, 0, 255, 255);
+   evas_object_show(rect3);
+
+   bt = elm_button_add(win);
+   elm_object_text_set(bt, "Show hover");
+   evas_object_move(bt, 60, 90);
+   evas_object_resize(bt, 80, 20);
+   evas_object_show(bt);
+
+   bt2 = elm_button_add(win);
+   elm_object_text_set(bt2, "Hide hover");
+   evas_object_show(bt2);
+
+   hover = elm_hover_add(win);
+   elm_hover_parent_set(hover, win);
+   elm_hover_target_set(hover, bt);
+
+   elm_object_style_set(hover, "popout");
+
+   elm_hover_content_set(hover, "left", rect);
+   elm_hover_content_set(hover, "top", rect2);
+   elm_hover_content_set(hover, "right", rect3);
+   elm_hover_content_set(hover, "middle", bt2);
+
+   evas_object_smart_callback_add(bt, "clicked", _show_hover, hover);
+   evas_object_smart_callback_add(bt2, "clicked", _hide_hover, hover);
+
+   evas_object_resize(win, 200, 200);
+   evas_object_show(win);
+
+   elm_run();
+
+   return 0;
+}
+ELM_MAIN()

legacy/elementary/src/lib/Elementary.h.in

@@ -3544,33 +3544,180 @@ extern "C" {
     * "block,clicked" - when it's hidden by a click outside of the notify's view
     */
 
-   /* hover */
+   /**
+    * @defgroup Hover Hover
+    *
+    * A Hover object will hover over its @p parent object at the @p target
+    * location. Anything in the background will be given a darker coloring to
+    * indicate that the hover object is on top (at the default theme). When the
+    * hover is clicked it is dismissed(hidden), if the contents of the hover are
+    * clicked that @b doesn't cause the hover to be dismissed.
+    *
+    * @note The hover object will take up the entire space of @p target
+    * object.
+    *
+    * Elementary has the following styles for the hover widget:
+    * @li default
+    * @li popout
+    * @li menu
+    * @li hoversel_vertical
+    *
+    * The following are the available position for content:
+    * @li left
+    * @li top-left
+    * @li top
+    * @li top-right
+    * @li right
+    * @li bottom-right
+    * @li bottom
+    * @li bottom-left
+    * @li middle
+    * @li smart
+    *
+    * Signals that you can add callbacks for are:
+    * @li "clicked" - the user clicked the empty space in the hover to dismiss
+    * @li "smart,changed" - a content object placed under the "smart"
+    *                   policy was replaced to a new slot direction.
+    *
+    * See @ref tutorial_hover for more information.
+    *
+    * @{
+    */
    typedef enum _Elm_Hover_Axis
      {
-        ELM_HOVER_AXIS_NONE,
-        ELM_HOVER_AXIS_HORIZONTAL,
-        ELM_HOVER_AXIS_VERTICAL,
-        ELM_HOVER_AXIS_BOTH
+        ELM_HOVER_AXIS_NONE, /**< ELM_HOVER_AXIS_NONE -- no prefered orientation */
+        ELM_HOVER_AXIS_HORIZONTAL, /**< ELM_HOVER_AXIS_HORIZONTAL -- horizontal */
+        ELM_HOVER_AXIS_VERTICAL, /**< ELM_HOVER_AXIS_VERTICAL -- vertical */
+        ELM_HOVER_AXIS_BOTH /**< ELM_HOVER_AXIS_BOTH -- both */
      } Elm_Hover_Axis;
-   EAPI Evas_Object *elm_hover_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
-   EAPI void         elm_hover_target_set(Evas_Object *obj, Evas_Object *target) EINA_ARG_NONNULL(1);
-   EAPI Evas_Object *elm_hover_target_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-   EAPI void         elm_hover_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
-   EAPI Evas_Object *elm_hover_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-   EAPI void         elm_hover_content_set(Evas_Object *obj, const char *swallow, Evas_Object *content) EINA_ARG_NONNULL(1);
-   EAPI Evas_Object *elm_hover_content_get(const Evas_Object *obj, const char *swallow) EINA_ARG_NONNULL(1);
-   EAPI Evas_Object *elm_hover_content_unset(Evas_Object *obj, const char *swallow) EINA_ARG_NONNULL(1);
-   EAPI const char  *elm_hover_best_content_location_get(const Evas_Object *obj, Elm_Hover_Axis pref_axis) EINA_ARG_NONNULL(1);
-   /* available styles:
-    * default
-    * popout
-    * menu
-    * hoversel_vertical
+   /**
+    * @brief Adds a hover object to @p parent
+    *
+    * @param parent The parent object
+    * @return The hover object or NULL if one could not be created
     */
-   /* smart callbacks called:
-    * "clicked" - the user clicked the empty space in the hover to dismiss
-    * "smart,changed" - a content object placed under the "smart"
-    *                   policy was replaced to a new slot direction.
+   EAPI Evas_Object *elm_hover_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Sets the target object for the hover.
+    *
+    * @param obj The hover object
+    * @param target The object to center the hover onto. The hover
+    *
+    * This function will cause the hover to be centered on the target object.
+    */
+   EAPI void         elm_hover_target_set(Evas_Object *obj, Evas_Object *target) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Gets the target object for the hover.
+    *
+    * @param obj The hover object
+    * @param parent The object to locate the hover over.
+    *
+    * @see elm_hover_target_set()
+    */
+   EAPI Evas_Object *elm_hover_target_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Sets the parent object for the hover.
+    *
+    * @param obj The hover object
+    * @param parent The object to locate the hover over.
+    *
+    * This function will cause the hover to take up the entire space that the
+    * parent object fills.
+    */
+   EAPI void         elm_hover_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Gets the parent object for the hover.
+    *
+    * @param obj The hover object
+    * @return The parent object to locate the hover over.
+    *
+    * @see elm_hover_parent_set()
+    */
+   EAPI Evas_Object *elm_hover_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Sets the content of the hover object and the direction in which it
+    * will pop out.
+    *
+    * @param obj The hover object
+    * @param swallow The direction that the object will be displayed
+    * at. Accepted values are "left", "top-left", "top", "top-right",
+    * "right", "bottom-right", "bottom", "bottom-left", "middle" and
+    * "smart".
+    * @param content The content to place at @p swallow
+    *
+    * Once the content object is set for a given direction, a previously
+    * set one (on the same direction) will be deleted. If you want to
+    * keep that old content object, use the elm_hover_content_unset()
+    * function.
+    *
+    * All directions may have contents at the same time, except for
+    * "smart". This is a special placement hint and its use case
+    * independs of the calculations coming from
+    * elm_hover_best_content_location_get(). Its use is for cases when
+    * one desires only one hover content, but with a dinamic special
+    * placement within the hover area. The content's geometry, whenever
+    * it changes, will be used to decide on a best location not
+    * extrapolating the hover's parent object view to show it in (still
+    * being the hover's target determinant of its medium part -- move and
+    * resize it to simulate finger sizes, for example). If one of the
+    * directions other than "smart" are used, a previously content set
+    * using it will be deleted, and vice-versa.
+    */
+   EAPI void         elm_hover_content_set(Evas_Object *obj, const char *swallow, Evas_Object *content) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Get the content of the hover object, in a given direction.
+    *
+    * Return the content object which was set for this widget in the
+    * @p swallow direction.
+    *
+    * @param obj The hover object
+    * @param swallow The direction that the object was display at.
+    * @return The content that was being used
+    *
+    * @see elm_hover_content_set()
+    */
+   EAPI Evas_Object *elm_hover_content_get(const Evas_Object *obj, const char *swallow) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Unset the content of the hover object, in a given direction.
+    *
+    * Unparent and return the content object set at @p swallow direction.
+    *
+    * @param obj The hover object
+    * @param swallow The direction that the object was display at.
+    * @return The content that was being used.
+    *
+    * @see elm_hover_content_set()
+    */
+   EAPI Evas_Object *elm_hover_content_unset(Evas_Object *obj, const char *swallow) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Returns the best swallow location for content in the hover.
+    *
+    * @param obj The hover object
+    * @param pref_axis The preferred orientation axis for the hover object to use
+    * @return The edje location to place content into the hover or @c
+    *         NULL, on errors.
+    *
+    * Best is defined here as the location at which there is the most available
+    * space.
+    *
+    * @p pref_axis may be one of
+    * - @c ELM_HOVER_AXIS_NONE -- no prefered orientation
+    * - @c ELM_HOVER_AXIS_HORIZONTAL -- horizontal
+    * - @c ELM_HOVER_AXIS_VERTICAL -- vertical
+    * - @c ELM_HOVER_AXIS_BOTH -- both
+    *
+    * If ELM_HOVER_AXIS_HORIZONTAL is choosen the returned position will
+    * nescessarily be along the horizontal axis("left" or "right"). If
+    * ELM_HOVER_AXIS_VERTICAL is choosen the returned position will nescessarily
+    * be along the vertical axis("top" or "bottom"). Chossing
+    * ELM_HOVER_AXIS_BOTH or ELM_HOVER_AXIS_NONE has the same effect and the
+    * returned position may be in either axis.
+    *
+    * @see elm_hover_content_set()
+    */
+   EAPI const char  *elm_hover_best_content_location_get(const Evas_Object *obj, Elm_Hover_Axis pref_axis) EINA_ARG_NONNULL(1);
+   /**
+    * @}
     */
 
    /* entry */

legacy/elementary/src/lib/elm_hover.c

@@ -1,24 +1,6 @@
 #include <Elementary.h>
 #include "elm_priv.h"
 
-/**
- * @defgroup Hover Hover
- *
- * A Hover object will over its @p parent object at the @p target
- * location. Anything in the background will be given a darker
- * coloring to indicate that the hover object is on top (at the
- * default theme).
- *
- * @note The hover object will take up the entire space of @p target
- * object.
- *
- * Signals that you can add callbacks for are:
- *
- * "clicked" - the user clicked the empty space in the hover to dismiss
- * "smart,changed" - a content object placed under the "smart"
- *                   policy was replaced to a new slot direction.
- */
-
 typedef struct _Widget_Data Widget_Data;
 typedef struct _Content_Info Content_Info;
 
@@ -484,14 +466,6 @@ _parent_del(void *data, Evas *e __UNUSED__, Evas_Object *obj __UNUSED__, void *e
    _sizing_eval(data);
 }
 
-/**
- * Adds a hover object to @p parent
- *
- * @param parent The parent object
- * @return The hover object or NULL if one could not be created
- *
- * @ingroup Hover
- */
 EAPI Evas_Object *
 elm_hover_add(Evas_Object *parent)
 {
@@ -555,15 +529,6 @@ elm_hover_add(Evas_Object *parent)
    return obj;
 }
 
-/**
- * Sets the target object for the hover.
- *
- * @param obj The hover object
- * @param target The object to center the hover onto. The hover
- * will take up the entire space that the target object fills.
- *
- * @ingroup Hover
- */
 EAPI void
 elm_hover_target_set(Evas_Object *obj, Evas_Object *target)
 {
@@ -590,14 +555,6 @@ elm_hover_target_set(Evas_Object *obj, Evas_Object *target)
 }
 
 
-/**
- * Sets the parent object for the hover.
- *
- * @param obj The hover object
- * @param parent The object to locate the hover over.
- *
- * @ingroup Hover
- */
 EAPI void
 elm_hover_parent_set(Evas_Object *obj, Evas_Object *parent)
 {
@@ -635,14 +592,6 @@ elm_hover_parent_set(Evas_Object *obj, Evas_Object *parent)
    _sizing_eval(obj);
 }
 
-/**
- * Gets the target object for the hover.
- *
- * @param obj The hover object
- * @return The target object of the hover.
- *
- * @ingroup Hover
- */
 EAPI Evas_Object *
 elm_hover_target_get(const Evas_Object *obj)
 {
@@ -653,14 +602,6 @@ elm_hover_target_get(const Evas_Object *obj)
    return wd->target;
 }
 
-/**
- * Gets the parent object for the hover.
- *
- * @param obj The hover object
- * @return The parent object to locate the hover over.
- *
- * @ingroup Hover
- */
 EAPI Evas_Object *
 elm_hover_parent_get(const Evas_Object *obj)
 {
@@ -730,37 +671,6 @@ _elm_hover_sub_obj_placement_eval_cb(void *data, Evas *e __UNUSED__, Evas_Object
    _elm_hover_sub_obj_placement_eval(data);
 }
 
-/**
- * Sets the content of the hover object and the direction in which
- * it will pop out.
- *
- * Once the content object is set for a given direction, a previously
- * set one (on the same direction) will be deleted. If you want to
- * keep that old content object, use the elm_hover_content_unset()
- * function.
- *
- * @param obj The hover object
- * @param swallow The direction that the object will be displayed
- * at. Accepted values are "left", "top-left", "top", "top-right",
- * "right", "bottom-right", "bottom", "bottom-left", "middle" and
- * "smart".
- * @param content The content to place at @p swallow
- *
- * All directions may have contents at the same time, except for
- * "smart". This is a special placement hint and its use case
- * independs of the calculations coming from
- * elm_hover_best_content_location_get(). Its use is for cases when
- * one desires only one hover content, but with a dinamic special
- * placement within the hover area. The content's geometry, whenever
- * it changes, will be used to decide on a best location not
- * extrapolating the hover's parent object view to show it in (still
- * being the hover's target determinant of its medium part -- move and
- * resize it to simulate finger sizes, for example). If one of the
- * directions other than "smart" are used, a previously content set
- * using it will be deleted, and vice-versa.
- *
- * @ingroup Hover
- */
 EAPI void
 elm_hover_content_set(Evas_Object *obj, const char *swallow, Evas_Object *content)
 {
@@ -826,20 +736,6 @@ end:
    _sizing_eval(obj);
 }
 
-/**
- * Get the content of the hover object, in a given direction.
- *
- * Return the content object which was set for this widget in the
- * given direction.
- *
- * @param obj The hover object
- * @param swallow The direction that the object was display at.
- * @return The content that was being used
- *
- * @note See elm_hover_content_set() for more information.
- *
- * @ingroup Hover
- */
 EAPI Evas_Object *
 elm_hover_content_get(const Evas_Object *obj, const char *swallow)
 {
@@ -877,19 +773,6 @@ _elm_hover_sub_obj_unparent(Evas_Object *obj)
    wd->smt_sub = NULL;
 }
 
-/**
- * Unset the content of the hover object, in a given direction.
- *
- * Unparent and return the content object set at that direction.
- *
- * @param obj The hover object
- * @param swallow The direction that the object was display at.
- * @return The content that was being used.
- *
- * @note See elm_hover_content_set() for more information.
- *
- * @ingroup Hover
- */
 EAPI Evas_Object *
 elm_hover_content_unset(Evas_Object *obj, const char *swallow)
 {
@@ -934,24 +817,6 @@ elm_hover_content_unset(Evas_Object *obj, const char *swallow)
    return NULL;
 }
 
-/**
- * Returns the best swallow location for content in the hover.
- *
- * @param obj The hover object
- * @param pref_axis The preferred orientation axis for the hover object to use
- * @return The edje location to place content into the hover or @c
- *         NULL, on errors.
- *
- * @p pref_axis may be one of
- * - @c ELM_HOVER_AXIS_NONE -- no prefered orientation
- * - @c ELM_HOVER_AXIS_HORIZONTAL -- horizontal
- * - @c ELM_HOVER_AXIS_VERTICAL -- vertical
- * - @c ELM_HOVER_AXIS_BOTH -- both
- *
- * See also elm_hover_content_set().
- *
- * @ingroup Hover
- */
 EAPI const char *
 elm_hover_best_content_location_get(const Evas_Object *obj, Elm_Hover_Axis pref_axis)
 {