From e51dcb01b5fbc30ebf775861afa24246d2037dd6 Mon Sep 17 00:00:00 2001 From: "Jonas M. Gastal" Date: Wed, 27 Jul 2011 13:40:30 +0000 Subject: [PATCH] Elementary: notify documentation. SVN revision: 61807 --- legacy/elementary/doc/Makefile.am | 3 +- legacy/elementary/doc/examples.dox | 54 ++++++ legacy/elementary/doc/index.doxy | 3 + legacy/elementary/doc/widgets/Makefile.am | 4 +- .../doc/widgets/widget_preview_notify.c | 15 ++ legacy/elementary/src/examples/Makefile.am | 10 +- .../src/examples/notify_example_01.c | 80 +++++++++ legacy/elementary/src/lib/Elementary.h.in | 164 ++++++++++++++++-- legacy/elementary/src/lib/elm_notify.c | 121 ------------- 9 files changed, 314 insertions(+), 140 deletions(-) create mode 100644 legacy/elementary/doc/widgets/widget_preview_notify.c create mode 100644 legacy/elementary/src/examples/notify_example_01.c diff --git a/legacy/elementary/doc/Makefile.am b/legacy/elementary/doc/Makefile.am index 95cc847d65..25711807dd 100644 --- a/legacy/elementary/doc/Makefile.am +++ b/legacy/elementary/doc/Makefile.am @@ -58,7 +58,8 @@ WGT_PREVIEW = \ panel:preview-00.png:widget_preview_panel:150:50 \ gengrid:preview-00.png:widget_preview_gengrid:200:160 \ progressbar:preview-00.png:widget_preview_progressbar:150:50 \ - box:preview-00.png:widget_preview_box:200:160 + box:preview-00.png:widget_preview_box:200:160 \ + notify:preview-00.png:widget_preview_notify:60:30 widget-build: @$(MAKE) -C widgets diff --git a/legacy/elementary/doc/examples.dox b/legacy/elementary/doc/examples.dox index 923e48b1e5..285b5156e8 100644 --- a/legacy/elementary/doc/examples.dox +++ b/legacy/elementary/doc/examples.dox @@ -4193,6 +4193,60 @@ * @example progressbar_example.c */ +/** + * @page tutorial_notify Notify example + * @dontinclude notify_example_01.c + * + * In this example we will have 3 notifys in 3 different positions. The first of + * which will dissapear after 5 seconds or when a click outside it occurs, the + * second and third will not dissapear and differ from each other only in + * position. + * + * We start our example with the usual stuff you've seen in other examples: + * @until show(bx) + * + * We now create a label to use as the content of our first notify: + * @until show + * + * Having the label we move to creating our notify, telling it to block events, + * setting its timeout(to autohide it): + * @until pack_end + * + * To have the notify dissapear when a click outside its area occur we have to + * listen to its "block,clicked" signal: + * @until smart_callback + * + * Our callback will look like this: + * @skip static + * @until } + * @dontinclude notify_example_01.c + * + * Next we create another label and another notify. Note, however, that this + * time we don't set a timeout and don't have it block events. What we do is set + * the orient so that this notify will appear in the bottom of its parent: + * @skip smart_callback + * @skip content + * @until pack_end + * + * For our third notify the only change is the orient which is now center: + * @until pack_end + * + * Now we tell the main loop to run: + * @until ELM_MAIN + * + * Our example will initially look like this: + * + * @image html screenshots/notify_example_01.png + * @image latex screenshots/notify_example_01.eps width=\textwidth + * + * Once the first notify is hidden: + * + * @image html screenshots/notify_example_01_a.png + * @image latex screenshots/notify_example_01_a.eps width=\textwidth + * + * @example notify_example_01.c + */ + /** * @page bg_example_01_c bg_example_01.c * @include bg_example_01.c diff --git a/legacy/elementary/doc/index.doxy b/legacy/elementary/doc/index.doxy index 283f8c2da3..41789a1d53 100644 --- a/legacy/elementary/doc/index.doxy +++ b/legacy/elementary/doc/index.doxy @@ -136,6 +136,9 @@ * @li @ref Mapbuf * @li @ref Menu * @li @ref Notify + * + * @image html img/widget/notify/preview-00.png + * @image latex img/widget/notify/preview-00.eps * @li @ref Pager * * @image html img/widget/pager/preview-00.png diff --git a/legacy/elementary/doc/widgets/Makefile.am b/legacy/elementary/doc/widgets/Makefile.am index 079829733d..329fe5f830 100644 --- a/legacy/elementary/doc/widgets/Makefile.am +++ b/legacy/elementary/doc/widgets/Makefile.am @@ -74,7 +74,8 @@ widget_preview_toggle \ widget_preview_panel \ widget_preview_gengrid \ widget_preview_progressbar \ -widget_preview_box +widget_preview_box \ +widget_preview_notify LDADD = $(top_builddir)/src/lib/libelementary.la @ELEMENTARY_EWEATHER_LIBS@ @ELEMENTARY_EDBUS_LIBS@ @ELEMENTARY_EFREET_LIBS@ @ELEMENTARY_EMAP_LIBS@ @ELEMENTARY_LIBS@ @EIO_LIBS@ @my_libs@ @@ -130,5 +131,6 @@ EXTRA_DIST = \ widget_preview_gengrid.c \ widget_preview_progressbar.c \ widget_preview_box.c \ + widget_preview_notify.c \ widget_preview_tmpl_foot.c \ widget_preview_tmpl_head.c diff --git a/legacy/elementary/doc/widgets/widget_preview_notify.c b/legacy/elementary/doc/widgets/widget_preview_notify.c new file mode 100644 index 0000000000..ae0d4c2eef --- /dev/null +++ b/legacy/elementary/doc/widgets/widget_preview_notify.c @@ -0,0 +1,15 @@ +#include "widget_preview_tmpl_head.c" + +Evas_Object *o = elm_notify_add(win); +evas_object_size_hint_weight_set(o, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); +elm_win_resize_object_add(win, o); +evas_object_show(o); + +Evas_Object *o2 = elm_label_add(win); +elm_object_text_set(o2, "content"); +evas_object_show(o2); + +elm_notify_content_set(o, o2); + + +#include "widget_preview_tmpl_foot.c" diff --git a/legacy/elementary/src/examples/Makefile.am b/legacy/elementary/src/examples/Makefile.am index d0267c6495..265604d425 100644 --- a/legacy/elementary/src/examples/Makefile.am +++ b/legacy/elementary/src/examples/Makefile.am @@ -92,7 +92,8 @@ SRCS = \ panel_example_01.c \ gengrid_example.c \ entry_example.c \ - progressbar_example.c + progressbar_example.c \ + notify_example_01.c pkglib_PROGRAMS = @@ -174,7 +175,8 @@ pkglib_PROGRAMS += \ genlist_example_02 \ genlist_example_03 \ entry_example \ - progressbar_example + progressbar_example \ + notify_example_01 # This variable will hold the list of screenshots that will be made # by "make screenshots". Each item in the list is of the form: @@ -228,7 +230,9 @@ SCREENSHOTS = \ panel_example_01:panel_example_01.png:0.0 \ gengrid_example:gengrid_example.png:0.0 \ entry_example:entry_example.png:0.0 \ - progressbar_example:progressbar_example.png:0.0 + progressbar_example:progressbar_example.png:0.0 \ + notify_example_01:notify_example_01.png:0.0 \ + notify_example_01:notify_example_01_a.png:6.0 HTML_SS_DIR=$(top_builddir)/doc/html/screenshots LATEX_SS_DIR=$(top_builddir)/doc/latex/screenshots diff --git a/legacy/elementary/src/examples/notify_example_01.c b/legacy/elementary/src/examples/notify_example_01.c new file mode 100644 index 0000000000..16cf3a5790 --- /dev/null +++ b/legacy/elementary/src/examples/notify_example_01.c @@ -0,0 +1,80 @@ +//Compile with: +//gcc -g `pkg-config --cflags --libs elementary` notify_example_01.c -o notify_example_01 + +#include +#ifdef HAVE_CONFIG_H +# include "elementary_config.h" +#endif + +static void _hide(void *data, Evas_Object *obj, void *event_info); + +EAPI int +elm_main(int argc, char **argv) +{ + Evas_Object *win, *bg, *bx, *notify, *content; + + win = elm_win_add(NULL, "notify", ELM_WIN_BASIC); + elm_win_title_set(win, "Notify"); + 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); + + bx = elm_box_add(win); + elm_box_horizontal_set(bx, EINA_FALSE); + evas_object_size_hint_weight_set(bx, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_size_hint_align_set(bx, EVAS_HINT_FILL, EVAS_HINT_FILL); + elm_win_resize_object_add(win, bx); + evas_object_show(bx); + + content = elm_label_add(win); + elm_object_text_set(content, "default"); + evas_object_show(content); + + notify = elm_notify_add(win); + elm_notify_repeat_events_set(notify, EINA_FALSE); + elm_notify_timeout_set(notify, 5); + elm_notify_content_set(notify, content); + evas_object_size_hint_weight_set(notify, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_show(notify); + elm_box_pack_end(bx, notify); + evas_object_smart_callback_add(notify, "block,clicked", _hide, NULL); + + content = elm_label_add(win); + elm_object_text_set(content, "bottom"); + evas_object_show(content); + + notify = elm_notify_add(win); + elm_notify_orient_set(notify, ELM_NOTIFY_ORIENT_BOTTOM); + elm_notify_content_set(notify, content); + evas_object_size_hint_weight_set(notify, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_show(notify); + elm_box_pack_end(bx, notify); + + content = elm_label_add(win); + elm_object_text_set(content, "center"); + evas_object_show(content); + + notify = elm_notify_add(win); + elm_notify_orient_set(notify, ELM_NOTIFY_ORIENT_CENTER); + elm_notify_content_set(notify, content); + evas_object_size_hint_weight_set(notify, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_show(notify); + elm_box_pack_end(bx, notify); + + evas_object_resize(win, 100, 200); + evas_object_show(win); + + elm_run(); + + return 0; +} +ELM_MAIN() + +static void +_hide(void *data, Evas_Object *obj, void *event_info) +{ + evas_object_hide(obj); +} \ No newline at end of file diff --git a/legacy/elementary/src/lib/Elementary.h.in b/legacy/elementary/src/lib/Elementary.h.in index 80b1dfdab9..3c6185c148 100644 --- a/legacy/elementary/src/lib/Elementary.h.in +++ b/legacy/elementary/src/lib/Elementary.h.in @@ -6668,35 +6668,171 @@ extern "C" { * "theme,changed" - when elm theme is changed. */ - /* notify */ + /** + * @defgroup Notify Notify + * + * @image html img/widget/notify/preview-00.png + * @image latex img/widget/notify/preview-00.eps + * + * Display a container in a particular region of the parent(top, bottom, + * etc. A timeout can be set to automatically hide the notify. This is so + * that, after an evas_object_show() on a notify object, if a timeout was set + * on it, it will @b automatically get hidden after that time. + * + * Signals that you can add callbacks for are: + * @li "timeout" - when timeout happens on notify and it's hidden + * @li "block,clicked" - when a click outside of the notify happens + * + * @ref tutorial_notify show usage of the API. + * + * @{ + */ + /** + * @brief Possible orient values for notify. + * + * This values should be used in conjunction to elm_notify_orient_set() to + * set the position in which the notify should appear(relative to its parent) + * and in conjunction with elm_notify_orient_get() to know where the notify + * is appearing. + */ typedef enum _Elm_Notify_Orient { - ELM_NOTIFY_ORIENT_TOP, - ELM_NOTIFY_ORIENT_CENTER, - ELM_NOTIFY_ORIENT_BOTTOM, - ELM_NOTIFY_ORIENT_LEFT, - ELM_NOTIFY_ORIENT_RIGHT, - ELM_NOTIFY_ORIENT_TOP_LEFT, - ELM_NOTIFY_ORIENT_TOP_RIGHT, - ELM_NOTIFY_ORIENT_BOTTOM_LEFT, - ELM_NOTIFY_ORIENT_BOTTOM_RIGHT, - ELM_NOTIFY_ORIENT_LAST + ELM_NOTIFY_ORIENT_TOP, /**< Notify should appear in the top of parent, default */ + ELM_NOTIFY_ORIENT_CENTER, /**< Notify should appear in the center of parent */ + ELM_NOTIFY_ORIENT_BOTTOM, /**< Notify should appear in the bottom of parent */ + ELM_NOTIFY_ORIENT_LEFT, /**< Notify should appear in the left of parent */ + ELM_NOTIFY_ORIENT_RIGHT, /**< Notify should appear in the right of parent */ + ELM_NOTIFY_ORIENT_TOP_LEFT, /**< Notify should appear in the top left of parent */ + ELM_NOTIFY_ORIENT_TOP_RIGHT, /**< Notify should appear in the top right of parent */ + ELM_NOTIFY_ORIENT_BOTTOM_LEFT, /**< Notify should appear in the bottom left of parent */ + ELM_NOTIFY_ORIENT_BOTTOM_RIGHT, /**< Notify should appear in the bottom right of parent */ + ELM_NOTIFY_ORIENT_LAST /**< Sentinel value, @b don't use */ } Elm_Notify_Orient; + /** + * @brief Add a new notify to the parent + * + * @param parent The parent object + * @return The new object or NULL if it cannot be created + */ EAPI Evas_Object *elm_notify_add(Evas_Object *parent) EINA_ARG_NONNULL(1); + /** + * @brief Set the content of the notify widget + * + * @param obj The notify object + * @param content The content will be filled in this notify object + * + * Once the content object is set, a previously set one will be deleted. If + * you want to keep that old content object, use the + * elm_notify_content_unset() function. + */ EAPI void elm_notify_content_set(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1); + /** + * @brief Unset the content of the notify widget + * + * @param obj The notify object + * @return The content that was being used + * + * Unparent and return the content object which was set for this widget + * + * @see elm_notify_content_set() + */ EAPI Evas_Object *elm_notify_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * @brief Return the content of the notify widget + * + * @param obj The notify object + * @return The content that is being used + * + * @see elm_notify_content_set() + */ EAPI Evas_Object *elm_notify_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * @brief Set the notify parent + * + * @param obj The notify object + * @param content The new parent + * + * Once the parent object is set, a previously set one will be disconnected + * and replaced. + */ EAPI void elm_notify_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1); + /** + * @brief Get the notify parent + * + * @param obj The notify object + * @return The parent + * + * @see elm_notify_parent_set() + */ EAPI Evas_Object *elm_notify_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * @brief Set the orientation + * + * @param obj The notify object + * @param orient The new orientation + * + * Sets the position in which the notify will appear in its parent. + * + * @see @ref Elm_Notify_Orient for possible values. + */ EAPI void elm_notify_orient_set(Evas_Object *obj, Elm_Notify_Orient orient) EINA_ARG_NONNULL(1); + /** + * @brief Return the orientation + * @param obj The notify object + * @return The orientation of the notification + * + * @see elm_notify_orient_set() + * @see Elm_Notify_Orient + */ EAPI Elm_Notify_Orient elm_notify_orient_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * @brief Set the time interval after which the notify window is going to be + * hidden. + * + * @param obj The notify object + * @param time The timeout in seconds + * + * This function sets a timeout and starts the timer controlling when the + * notify is hidden. Since calling evas_object_show() on a notify restarts + * the timer controlling when the notify is hidden, setting this before the + * notify is shown will in effect mean starting the timer when the notify is + * shown. + * + * @note Set a value <= 0.0 to disable a running timer. + * + * @note If the value > 0.0 and the notify is previously visible, the + * timer will be started with this value, canceling any running timer. + */ EAPI void elm_notify_timeout_set(Evas_Object *obj, double timeout) EINA_ARG_NONNULL(1); + /** + * @brief Return the timeout value (in seconds) + * @param obj the notify object + * + * @see elm_notify_timeout_set() + */ EAPI double elm_notify_timeout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * @brief Sets whether events should be passed to by a click outside + * its area. + * + * @param obj The notify object + * @param repeats EINA_TRUE Events are repeats, else no + * + * When true if the user clicks outside the window the events will be caught + * by the others widgets, else the events are blocked. + * + * @note The default value is EINA_TRUE. + */ EAPI void elm_notify_repeat_events_set(Evas_Object *obj, Eina_Bool repeat) EINA_ARG_NONNULL(1); + /** + * @brief Return true if events are repeat below the notify object + * @param obj the notify object + * + * @see elm_notify_repeat_events_set() + */ EAPI Eina_Bool elm_notify_repeat_events_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); - /* smart callbacks called: - * "timeout" - when timeout happens on notify and it's hidden - * "block,clicked" - when it's hidden by a click outside of the notify's view + /** + * @} */ /** diff --git a/legacy/elementary/src/lib/elm_notify.c b/legacy/elementary/src/lib/elm_notify.c index a0241c16b6..5ddf0a676c 100644 --- a/legacy/elementary/src/lib/elm_notify.c +++ b/legacy/elementary/src/lib/elm_notify.c @@ -1,21 +1,6 @@ #include #include "elm_priv.h" -/** - * @defgroup Notify Notify - * - * Display a window in a particular region of the application (top, - * bottom, etc. A timeout can be set to automatically close the - * window. This is so that, after an evas_object_show() on a notify - * object, if a timeout was set on it, it will automatically - * get hidden after that time. - * - * Signals that you can add callbacks for are: - * - * "timeout" - when timeout happens on notify and it's hidden - * "block,clicked" - when it's hidden by a click outside of the notify's view - */ - typedef struct _Widget_Data Widget_Data; struct _Widget_Data @@ -428,14 +413,6 @@ _elm_notify_focus_next_hook(const Evas_Object *obj, Elm_Focus_Direction dir, Eva return elm_widget_focus_next_get(cur, dir, next); } -/** - * Add a new notify to the parent - * - * @param parent The parent object - * @return The new object or NULL if it cannot be created - * - * @ingroup Notify - */ EAPI Evas_Object * elm_notify_add(Evas_Object *parent) { @@ -476,18 +453,6 @@ elm_notify_add(Evas_Object *parent) return obj; } -/** - * Set the content of the notify widget - * - * Once the content object is set, a previously set one will be deleted. - * If you want to keep that old content object, use the - * elm_notify_content_unset() function. - * - * @param obj The notify object - * @param content The content will be filled in this notify object - * - * @ingroup Notify - */ EAPI void elm_notify_content_set(Evas_Object *obj, Evas_Object *content) { @@ -511,16 +476,6 @@ elm_notify_content_set(Evas_Object *obj, Evas_Object *content) _calc(obj); } -/** - * Unset the content of the notify widget - * - * Unparent and return the content object which was set for this widget - * - * @param obj The notify object - * @return The content that was being used - * - * @ingroup Notify - */ EAPI Evas_Object * elm_notify_content_unset(Evas_Object *obj) { @@ -536,14 +491,6 @@ elm_notify_content_unset(Evas_Object *obj) return content; } -/** - * Return the content of the notify widget - * - * @param obj The notify object - * @return The content that is being used - * - * @ingroup Notify - */ EAPI Evas_Object * elm_notify_content_get(const Evas_Object *obj) { @@ -554,17 +501,6 @@ elm_notify_content_get(const Evas_Object *obj) return wd->content; } -/** - * Set the notify parent - * - * Once the parent object is set, a previously set one will be disconnected - * and replaced. - * - * @param obj The notify object - * @param content The new parent - * - * @ingroup Notify - */ EAPI void elm_notify_parent_set(Evas_Object *obj, Evas_Object *parent) { @@ -607,14 +543,6 @@ elm_notify_parent_set(Evas_Object *obj, Evas_Object *parent) _calc(obj); } -/** - * Get the notify parent - * - * @param obj The notify object - * @return The parent - * - * @ingroup Notify - */ EAPI Evas_Object * elm_notify_parent_get(const Evas_Object *obj) { @@ -624,14 +552,6 @@ elm_notify_parent_get(const Evas_Object *obj) return wd->parent; } -/** - * Set the orientation - * - * @param obj The notify object - * @param orient The new orientation - * - * @ingroup Notify - */ EAPI void elm_notify_orient_set(Evas_Object *obj, Elm_Notify_Orient orient) { @@ -644,10 +564,6 @@ elm_notify_orient_set(Evas_Object *obj, Elm_Notify_Orient orient) _resize(obj, NULL, obj, NULL); } -/** - * Return the orientation - * @param obj the notify objects - */ EAPI Elm_Notify_Orient elm_notify_orient_get(const Evas_Object *obj) { @@ -657,25 +573,6 @@ elm_notify_orient_get(const Evas_Object *obj) return wd->orient; } -/** - * Set the time interval after which the notify window is going to be - * hidden. - * - * @param obj The notify object - * @param time The new timeout - * - * As said previously, an evas_object_show() on a notify object which - * had a timeout set by this function will trigger a timer to - * automatically hide it again. So, any order one calls - * elm_notify_timeout_set() and evas_object_show() on the same object - * (at hidden state) will behave the same. - * - * @note Set a value <= 0.0 to disable a running timer. - * - * @note If the value > 0.0 and the notify is previously visible, the - * timer will be started with this value, canceling any running timer. - * - */ EAPI void elm_notify_timeout_set(Evas_Object *obj, double timeout) { @@ -686,10 +583,6 @@ elm_notify_timeout_set(Evas_Object *obj, double timeout) _timer_init(obj, wd); } -/** - * Return the timeout value (in seconds) - * @param obj the notify object - */ EAPI double elm_notify_timeout_get(const Evas_Object *obj) { @@ -699,16 +592,6 @@ elm_notify_timeout_get(const Evas_Object *obj) return wd->timeout; } -/** - * When true if the user clicks outside the window the events will be - * catch by the others widgets, else the events are block and the signal - * dismiss will be sent when the user click outside the window. - * - * @note The default value is EINA_TRUE. - * - * @param obj The notify object - * @param repeats EINA_TRUE Events are repeats, else no - */ EAPI void elm_notify_repeat_events_set(Evas_Object *obj, Eina_Bool repeat) { @@ -729,10 +612,6 @@ elm_notify_repeat_events_set(Evas_Object *obj, Eina_Bool repeat) evas_object_del(wd->block_events); } -/** - * Return true if events are repeat below the notify object - * @param obj the notify object - */ EAPI Eina_Bool elm_notify_repeat_events_get(const Evas_Object *obj) {