E SVN: sachiel IN trunk/elementary: doc src/examples src/lib

[Enlightenment S. <no-...@en...>]

Log:
Inwin basic example
  
  

Author:       sachiel
Date:         2011-07-28 05:11:26 -0700 (Thu, 28 Jul 2011)
New Revision: 61853
Trac:         http://trac.enlightenment.org/e/changeset/61853

Added:
  trunk/elementary/src/examples/inwin_example.c 
Modified:
  trunk/elementary/doc/examples.dox trunk/elementary/src/examples/Makefile.am trunk/elementary/src/lib/Elementary.h.in 

Modified: trunk/elementary/doc/examples.dox
===================================================================
--- trunk/elementary/doc/examples.dox	2011-07-28 12:11:14 UTC (rev 61852)
+++ trunk/elementary/doc/examples.dox	2011-07-28 12:11:26 UTC (rev 61853)
@@ -4764,6 +4764,82 @@
  */
 
 /**
+ * @page inwin_example_01 Inwin - General overview
+ *
+ * Inwin is a very simple widget to show, so this example will be a very simple
+ * one, just using all of the available API.
+ *
+ * The program is nothing but a window with a lonely button, as shown here.
+ *
+ * @image html screenshots/inwin_example.png
+ * @image latex screenshots/inwin_example.eps width=\textwidth
+ *
+ * And pressing the button makes an inwin appear.
+ *
+ * @image html screenshots/inwin_example_a.png
+ * @image latex screenshots/inwin_example_a.eps width=\textwidth
+ *
+ * And the code is just as simple. We being with some global variables to keep
+ * track of our Inwin.
+ * @dontinclude inwin_example.c
+ * @skip static
+ * @until current_style
+ *
+ * And two callbacks used by the buttons the above screenshot showed. In these,
+ * we check if @c inwin exists and execute the proper action on it. If it's not
+ * there anymore, then we were abandoned to our luck, so we disabled ourselves.
+ * @until _inwin_destroy
+ * @until }
+ * @until }
+ *
+ * The lonely button from the beginning, when clicked, will call the following
+ * function, which begins by checking if an inwin exists, and if it's there,
+ * we bring it back to the front and exit from our function without any further
+ * ado.
+ * @until }
+ *
+ * But if no inwin is there to show, we need to create one. First we need the
+ * top-most window for the program, as no inwin can be created using other
+ * objects as parents. Then we create our popup, set the next style in the list
+ * and show it.
+ * @until current_style =
+ *
+ * As for the content of our inwin, it's just a box with a label and some
+ * buttons inside.
+ * @until _inwin_destroy
+ * @until }
+ *
+ * Now, all the code above shows how every object must always be set as content
+ * for some other object, be it by setting the full content, packing it in a
+ * box or table or working as icon for some other widget. But we didn't do
+ * anything like that for the inwin, this one is just created and shown and
+ * everything works. Other widgets can be used this way, but they would need
+ * to be placed and resized manually or nothing would be shown correctly. The
+ * inwin, however, sets itself as a children of the top-level window and will
+ * be resized as the parent window changes too.
+ *
+ * Another characteristic of Inwin is that when it's shown above everyone else,
+ * it will work kind of like a modal window, blocking any other widget from
+ * receiving events until the window is manually dismissed by pressing some
+ * button to close it or having blocking task signalling its completion so
+ * normal operations can be resumed. This is unlike the @ref Hover widget,
+ * that would show its content on top of the designated target, but clicking
+ * anywhere else would dismiss it automatically.
+ *
+ * To illustrate that last point, when we close the main window and an inwin
+ * is still there, we'll take out the content from the inwin and place it in
+ * a hover.
+ * @until }
+ * @until }
+ *
+ * And the rest of the program doesn't have anything else related to inwin,
+ * so it won't be shown here, but you can find it in
+ * @ref inwin_example.c "inwin_example.c".
+ *
+ * @example inwin_example.c
+ */
+
+/**
  * @page bg_example_01_c bg_example_01.c
  * @include bg_example_01.c
  * @example bg_example_01.c

Modified: trunk/elementary/src/examples/Makefile.am
===================================================================
--- trunk/elementary/src/examples/Makefile.am	2011-07-28 12:11:14 UTC (rev 61852)
+++ trunk/elementary/src/examples/Makefile.am	2011-07-28 12:11:26 UTC (rev 61853)
@@ -96,7 +96,8 @@
 	slideshow_example.c \
 	progressbar_example.c \
 	notify_example_01.c \
-	photocam_example_01.c
+	photocam_example_01.c \
+	inwin_example.c
 
 pkglib_PROGRAMS =
 
@@ -182,7 +183,8 @@
 	slideshow_example \
 	progressbar_example \
 	notify_example_01 \
-	photocam_example_01
+	photocam_example_01 \
+	inwin_example
 
 # This variable will hold the list of screenshots that will be made
 # by "make screenshots". Each item in the list is of the form:
@@ -242,6 +244,8 @@
 	notify_example_01:notify_example_01_a.png:6.0 \
 	slideshow_example:slideshow_example.png:1.0 \
 	photocam_example_01:photocam_example_01.png:3
+	inwin_example:inwin_example.png:0.0 \
+	inwin_example:inwin_example_a.png:0.2
 
 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-28 12:11:14 UTC (rev 61852)
+++ trunk/elementary/src/lib/Elementary.h.in	2011-07-28 12:11:26 UTC (rev 61853)
@@ -1743,6 +1743,9 @@
     * possible, but it's sized vertically the most it needs to fit its\
     * contents.
     *
+    * Some examples of Inwin can be found in the following:
+    * @li @ref inwin_example_01
+    *
     * @{
     */
    /**