Menu
▾
▴
E SVN: gastal IN trunk/elementary: doc doc/widgets src/examples src/lib
|
From: Enlightenment S. <no-...@en...> - 2011-07-27 13:40:37
|
Log: Elementary: notify documentation. Author: gastal Date: 2011-07-27 06:40:30 -0700 (Wed, 27 Jul 2011) New Revision: 61807 Trac: http://trac.enlightenment.org/e/changeset/61807 Added: trunk/elementary/doc/widgets/widget_preview_notify.c trunk/elementary/src/examples/notify_example_01.c Modified: trunk/elementary/doc/Makefile.am trunk/elementary/doc/examples.dox trunk/elementary/doc/index.doxy trunk/elementary/doc/widgets/Makefile.am trunk/elementary/src/examples/Makefile.am trunk/elementary/src/lib/Elementary.h.in trunk/elementary/src/lib/elm_notify.c Modified: trunk/elementary/doc/Makefile.am =================================================================== --- trunk/elementary/doc/Makefile.am 2011-07-27 13:32:51 UTC (rev 61806) +++ trunk/elementary/doc/Makefile.am 2011-07-27 13:40:30 UTC (rev 61807) @@ -58,7 +58,8 @@ 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 Modified: trunk/elementary/doc/examples.dox =================================================================== --- trunk/elementary/doc/examples.dox 2011-07-27 13:32:51 UTC (rev 61806) +++ trunk/elementary/doc/examples.dox 2011-07-27 13:40:30 UTC (rev 61807) @@ -4194,6 +4194,60 @@ */ /** + * @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 * @example bg_example_01.c Modified: trunk/elementary/doc/index.doxy =================================================================== --- trunk/elementary/doc/index.doxy 2011-07-27 13:32:51 UTC (rev 61806) +++ trunk/elementary/doc/index.doxy 2011-07-27 13:40:30 UTC (rev 61807) @@ -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 Modified: trunk/elementary/doc/widgets/Makefile.am =================================================================== --- trunk/elementary/doc/widgets/Makefile.am 2011-07-27 13:32:51 UTC (rev 61806) +++ trunk/elementary/doc/widgets/Makefile.am 2011-07-27 13:40:30 UTC (rev 61807) @@ -74,7 +74,8 @@ 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 @@ 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 Modified: trunk/elementary/src/examples/Makefile.am =================================================================== --- trunk/elementary/src/examples/Makefile.am 2011-07-27 13:32:51 UTC (rev 61806) +++ trunk/elementary/src/examples/Makefile.am 2011-07-27 13:40:30 UTC (rev 61807) @@ -92,7 +92,8 @@ 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 @@ 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 @@ 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 Modified: trunk/elementary/src/lib/Elementary.h.in =================================================================== --- trunk/elementary/src/lib/Elementary.h.in 2011-07-27 13:32:51 UTC (rev 61806) +++ trunk/elementary/src/lib/Elementary.h.in 2011-07-27 13:40:30 UTC (rev 61807) @@ -6668,35 +6668,171 @@ * "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 + /** + * @} */ /** Modified: trunk/elementary/src/lib/elm_notify.c =================================================================== --- trunk/elementary/src/lib/elm_notify.c 2011-07-27 13:32:51 UTC (rev 61806) +++ trunk/elementary/src/lib/elm_notify.c 2011-07-27 13:40:30 UTC (rev 61807) @@ -1,21 +1,6 @@ #include <Elementary.h> #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 <b>automatically</b> - * 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 @@ 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 @@ 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 @@ _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 @@ 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 @@ 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 @@ _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 @@ 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 @@ _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 @@ 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 @@ _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 @@ 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 @@ 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) { |