kimcinoo
/
efl
forked from enlightenment/efl
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Elementary: notify documentation. 

SVN revision: 61807
This commit is contained in:
Jonas M. Gastal 2011-07-27 13:40:30 +00:00
parent 4c2b1d1deb
commit e51dcb01b5
9 changed files with 314 additions and 140 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
legacy/elementary/doc/Makefile.am
View File

@ -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

54
legacy/elementary/doc/examples.dox
View File

@ -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

3
legacy/elementary/doc/index.doxy
View File

@ -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

4
legacy/elementary/doc/widgets/Makefile.am
View File

@ -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

15
legacy/elementary/doc/widgets/widget_preview_notify.c Normal file
View File

@ -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"

10
legacy/elementary/src/examples/Makefile.am
View File

@ -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

80
legacy/elementary/src/examples/notify_example_01.c Normal file
View File

@ -0,0 +1,80 @@
//Compile with:
//gcc -g `pkg-config --cflags --libs elementary` notify_example_01.c -o notify_example_01
#include <Elementary.h>
#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);
}

164
legacy/elementary/src/lib/Elementary.h.in
View File

@ -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
/**
* @}
*/
/**

121
legacy/elementary/src/lib/elm_notify.c
View File

@ -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 @@ _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)
{