raster pushed a commit to branch master.
http://git.enlightenment.org/core/elementary.git/commit/?id=35277789216c73115f53f26fb611ab903d6c9837
commit 35277789216c73115f53f26fb611ab903d6c9837
Author: Bora Hwang <bora1.hw...@samsung.com>
Date: Thu Mar 20 20:12:02 2014 +0900
clear up the documentation of tooltip
Summary: Since explanations of tooltip's APIs are scattered in header or
source code, these needs to be cleared up.
Reviewers: seoz, Hermet, woohyun, raster
Reviewed By: raster
Differential Revision: https://phab.enlightenment.org/D644
---
src/lib/elm_tooltip.h | 65 +++++++++++++++++++++++++++++--
src/lib/els_tooltip.c | 103 --------------------------------------------------
2 files changed, 62 insertions(+), 106 deletions(-)
diff --git a/src/lib/elm_tooltip.h b/src/lib/elm_tooltip.h
index ea9da6a..7e1edbd 100644
--- a/src/lib/elm_tooltip.h
+++ b/src/lib/elm_tooltip.h
@@ -117,11 +117,33 @@ typedef Evas_Object *(*Elm_Tooltip_Content_Cb)(void
*data, Evas_Object *obj, Eva
*/
typedef Evas_Object *(*Elm_Tooltip_Item_Content_Cb)(void *data, Evas_Object
*obj, Evas_Object *tooltip, void *item);
+/**
+ * @brief Force show tooltip of object
+ *
+ * @param obj Target object
+ *
+ * Force show the tooltip and disable hide on mouse_out.
+ * If another content is set as tooltip, the visible tooltip will hididen and
+ * showed again with new content.
+ * This can force show more than one tooltip at a time.
+ *
+ * @ingroup Tooltips
+ */
EAPI void elm_object_tooltip_show(Evas_Object *obj);
+
+/**
+ * @brief Force hide tooltip of object
+ *
+ * @param obj Target object
+ *
+ * Force hide the tooltip and (re)enable future mouse interations.
+ *
+ * @ingroup Tooltips
+ */
EAPI void elm_object_tooltip_hide(Evas_Object *obj);
/**
- * Set the text to be displayed inside the tooltip.
+ * @brief Set the text to be displayed inside the tooltip.
*
* @param obj The tooltip object.
* @param text The text to be displayed.
@@ -131,11 +153,46 @@ EAPI void elm_object_tooltip_hide(Evas_Object
*obj);
EAPI void elm_object_tooltip_text_set(Evas_Object *obj, const char
*text);
EAPI void elm_object_tooltip_domain_translatable_text_set(Evas_Object
*obj, const char *domain, const char *text);
#define elm_object_tooltip_translatable_text_set(obj, text)
elm_object_tooltip_domain_translatable_text_set((obj), NULL, (text))
+
+/**
+ * @brief Set the content to be shown in the tooltip object
+ *
+ * @param obj The object being attached a tooltip.
+ * @param func The function used to create the tooltip contents.
+ * @param data What to provide to @a func as callback data/context.
+ * @param del_cb Function called when data is not needed anymore, either when
+ * another callback replaces @p func, the tooltip is unset with
+ * elm_object_tooltip_unset() or the owner object @a obj
+ * dies. This callback receives as the first parameter the
+ * given @a data, and @c event_info is NULL.
+ *
+ * Setup the tooltip to object. The object can have only one tooltip,
+ * so any previous tooltip data is removed. @p func(with @p data) will
+ * be called every time that need show the tooltip and it should
+ * return a valid Evas_Object. This object is then managed fully by
+ * tooltip system and is deleted when the tooltip is gone.
+ *
+ * @ingroup Tooltips
+ */
EAPI void elm_object_tooltip_content_cb_set(Evas_Object *obj,
Elm_Tooltip_Content_Cb func, const void *data, Evas_Smart_Cb del_cb);
+
+/**
+ * @brief Unset tooltip from object
+ *
+ * @param obj Target object
+ *
+ * Remove tooltip from object. The callback provided as del_cb to
+ * elm_object_tooltip_content_cb_set() will be called to notify it is
+ * not used anymore.
+ *
+ * @see elm_object_tooltip_content_cb_set()
+ *
+ * @ingroup Tooltips
+ */
EAPI void elm_object_tooltip_unset(Evas_Object *obj);
/**
- * Sets a different style for this object tooltip.
+ * @brief Set a different style for this object tooltip.
*
* @note before you set a style you should define a tooltip with
* elm_object_tooltip_content_cb_set() or
@@ -149,7 +206,7 @@ EAPI void elm_object_tooltip_unset(Evas_Object *obj);
EAPI void elm_object_tooltip_style_set(Evas_Object *obj, const char
*style);
/**
- * Get the style for this object tooltip.
+ * @brief Get the style for this object tooltip.
*
* @param obj an object with tooltip already set.
* @return style the theme style in use, defaults to "default". If the
@@ -161,6 +218,7 @@ EAPI const char *elm_object_tooltip_style_get(const
Evas_Object *obj);
/**
* @brief Disable size restrictions on an object's tooltip
+ *
* @param obj The tooltip's anchor object
* @param disable If EINA_TRUE, size restrictions are disabled
* @return EINA_FALSE on failure, EINA_TRUE on success
@@ -174,6 +232,7 @@ EAPI Eina_Bool
elm_object_tooltip_window_mode_set(Evas_Object *obj, Eina_Bool
/**
* @brief Retrieve size restriction state of an object's tooltip
+ *
* @param obj The tooltip's anchor object
* @return If EINA_TRUE, size restrictions are disabled
*
diff --git a/src/lib/els_tooltip.c b/src/lib/els_tooltip.c
index 4ea4a48..bfbb40c 100644
--- a/src/lib/els_tooltip.c
+++ b/src/lib/els_tooltip.c
@@ -894,18 +894,6 @@ elm_object_sub_tooltip_content_cb_set(Evas_Object
*eventarea, Evas_Object *owner
if (del_cb) del_cb((void *)data, owner, NULL);
}
-/**
- * Force show tooltip of object
- *
- * @param obj Target object
- *
- * Force show the tooltip and disable hide on mouse_out.
- * If another content is set as tooltip, the visible tooltip will hididen and
- * showed again with new content.
- * This can force show more than one tooltip at a time.
- *
- * @ingroup Tooltips
- */
EAPI void
elm_object_tooltip_show(Evas_Object *obj)
{
@@ -914,15 +902,6 @@ elm_object_tooltip_show(Evas_Object *obj)
_elm_tooltip_show(tt);
}
-/**
- * Force hide tooltip of object
- *
- * @param obj Target object
- *
- * Force hide the tooltip and (re)enable future mouse interations.
- *
- * @ingroup Tooltips
- */
EAPI void
elm_object_tooltip_hide(Evas_Object *obj)
{
@@ -931,18 +910,6 @@ elm_object_tooltip_hide(Evas_Object *obj)
_elm_tooltip_hide_anim_start(tt);
}
-/**
- * Set the text to be shown in the tooltip object
- *
- * @param obj Target object
- * @param text The text to set in the content
- *
- * Setup the text as tooltip to object. The object can have only one tooltip,
- * so any previous tooltip data is removed.
- * This method call internaly the elm_tooltip_content_cb_set().
- *
- * @ingroup Tooltips
- */
EAPI void
elm_object_tooltip_text_set(Evas_Object *obj, const char *text)
{
@@ -954,8 +921,6 @@ elm_object_tooltip_text_set(Evas_Object *obj, const char
*text)
(obj, _elm_tooltip_label_create, text, _elm_tooltip_label_del_cb);
}
-/**
- */
EAPI void
elm_object_tooltip_domain_translatable_text_set(Evas_Object *obj, const char
*domain, const char *text)
{
@@ -972,45 +937,12 @@
elm_object_tooltip_domain_translatable_text_set(Evas_Object *obj, const char *do
_elm_tooltip_trans_label_del_cb);
}
-/**
- * Set the content to be shown in the tooltip object
- *
- * Setup the tooltip to object. The object can have only one tooltip,
- * so any previous tooltip data is removed. @p func(with @p data) will
- * be called every time that need show the tooltip and it should
- * return a valid Evas_Object. This object is then managed fully by
- * tooltip system and is deleted when the tooltip is gone.
- *
- * @param obj the object being attached a tooltip.
- * @param func the function used to create the tooltip contents.
- * @param data what to provide to @a func as callback data/context.
- * @param del_cb called when data is not needed anymore, either when
- * another callback replaces @p func, the tooltip is unset with
- * elm_object_tooltip_unset() or the owner object @a obj
- * dies. This callback receives as the first parameter the
- * given @a data, and @c event_info is NULL.
- *
- * @ingroup Tooltips
- */
EAPI void
elm_object_tooltip_content_cb_set(Evas_Object *obj, Elm_Tooltip_Content_Cb
func, const void *data, Evas_Smart_Cb del_cb)
{
elm_object_sub_tooltip_content_cb_set(obj, obj, func, data, del_cb);
}
-/**
- * Unset tooltip from object
- *
- * @param obj Target object
- *
- * Remove tooltip from object. The callback provided as del_cb to
- * elm_object_tooltip_content_cb_set() will be called to notify it is
- * not used anymore.
- *
- * @see elm_object_tooltip_content_cb_set()
- *
- * @ingroup Tooltips
- */
EAPI void
elm_object_tooltip_unset(Evas_Object *obj)
{
@@ -1018,16 +950,6 @@ elm_object_tooltip_unset(Evas_Object *obj)
_elm_tooltip_unset(tt);
}
-/**
- * Sets a different style for this object tooltip.
- *
- * @note before you set a style you should define a tooltip with
- * elm_object_tooltip_content_cb_set() or
- * elm_object_tooltip_text_set().
- *
- * @param obj an object with tooltip already set.
- * @param style the theme style to use (default, transparent, ...)
- */
EAPI void
elm_object_tooltip_style_set(Evas_Object *obj, const char *style)
{
@@ -1036,13 +958,6 @@ elm_object_tooltip_style_set(Evas_Object *obj, const char
*style)
elm_tooltip_theme(tt);
}
-/**
- * Get the style for this object tooltip.
- *
- * @param obj an object with tooltip already set.
- * @return style the theme style in use, defaults to "default". If the
- * object does not have a tooltip set, then NULL is returned.
- */
EAPI const char *
elm_object_tooltip_style_get(const Evas_Object *obj)
{
@@ -1050,15 +965,6 @@ elm_object_tooltip_style_get(const Evas_Object *obj)
return tt->style ? tt->style : "default";
}
-/**
- * @brief Disable size restrictions on an object's tooltip
- * @param obj The tooltip's anchor object
- * @param disable If EINA_TRUE, size restrictions are disabled
- * @return EINA_FALSE on failure, EINA_TRUE on success
- *
- * This function allows a tooltip to expand beyond its parent window's canvas.
- * It will instead be limited only by the size of the display.
- */
EAPI Eina_Bool
elm_object_tooltip_window_mode_set(Evas_Object *obj, Eina_Bool disable)
{
@@ -1066,15 +972,6 @@ elm_object_tooltip_window_mode_set(Evas_Object *obj,
Eina_Bool disable)
return tt->free_size = disable;
}
-/**
- * @brief Retrieve size restriction state of an object's tooltip
- * @param obj The tooltip's anchor object
- * @return If EINA_TRUE, size restrictions are disabled
- *
- * This function returns whether a tooltip is allowed to expand beyond
- * its parent window's canvas.
- * It will instead be limited only by the size of the display.
- */
EAPI Eina_Bool
elm_object_tooltip_window_mode_get(const Evas_Object *obj)
{
--
