Enlightenment CVS committal
Author : dj2
Project : e17
Module : docs
Dir : e17/docs/ewlbook/xml
Modified Files:
bookinfo.xml config.xml getting_started.xml
object_hierarchy.xml widget_packing.xml widgets.xml
Added Files:
appendix-ewl_media_example.xml themes.xml
Log Message:
- updates to the widget section
- add some content to the object hierarchy section
- add a themes section
- add an appendix which will be an app example
===================================================================
RCS file: /cvsroot/enlightenment/e17/docs/ewlbook/xml/bookinfo.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -3 -r1.2 -r1.3
--- bookinfo.xml 11 Jul 2004 04:33:45 -0000 1.2
+++ bookinfo.xml 16 Jul 2004 04:11:17 -0000 1.3
@@ -22,11 +22,19 @@
<date>July 10, 2004</date>
<revremark>Flush out some of the widget information</revremark>
</revision>
+
+ <revision>
+ <authorinitials>dj2</authorinitials>
+ <revnumber>0.3</revnumber>
+ <date>July 15, 2004</date>
+ <revremark>Add more widgets, add some hierarchy stuff</revremark>
+ </revision>
</revhistory>
<abstract>
- <para>This book is an tutorial on the use of the EWL
-(Enlightened Widget Library).</para>
+ <para>
+ This book is a tutorial on the use of the EWL (Enlightened Widget Library).
+ </para>
</abstract>
</bookinfo>
===================================================================
RCS file: /cvsroot/enlightenment/e17/docs/ewlbook/xml/config.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -3 -r1.1 -r1.2
--- config.xml 9 Jul 2004 03:21:44 -0000 1.1
+++ config.xml 16 Jul 2004 04:11:17 -0000 1.2
@@ -1,5 +1,9 @@
<chapter id="ch-Config">
-<title>Config</title>
+<title>Configuration</title>
+
+<para>
+Configuration type stuff.
+</para>
</chapter>
===================================================================
RCS file: /cvsroot/enlightenment/e17/docs/ewlbook/xml/getting_started.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -3 -r1.1 -r1.2
--- getting_started.xml 9 Jul 2004 03:21:44 -0000 1.1
+++ getting_started.xml 16 Jul 2004 04:11:17 -0000 1.2
@@ -502,7 +502,7 @@
<para>
Some of the possible callbacks include:
</para>
-<variablelist termlength="45">
+<variablelist termlength="35" spacing="compact">
<title>Possible EWL Callbacks</title>
<varlistentry>
<term>EWL_CALLBACK_DESTROY</term>
===================================================================
RCS file: /cvsroot/enlightenment/e17/docs/ewlbook/xml/object_hierarchy.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -3 -r1.1 -r1.2
--- object_hierarchy.xml 9 Jul 2004 03:21:44 -0000 1.1
+++ object_hierarchy.xml 16 Jul 2004 04:11:17 -0000 1.2
@@ -1,5 +1,71 @@
<chapter id="ch-OjbectHierarchy">
<title>Object Hierarchy</title>
+<para>
+The EWL widgets are setup in a hierarcy. The base widget that everything
+extends from is the <literal>Ewl_Object</literal>. The
+<literal>Ewl_Object</literal> provides all of the base functionality for
+each widget including the sizing, alignment, fill policies, padding and
+others. This is the main building block of the EWL. An application using EWL
+will never need to allocate an <literal>Ewl_Object</literal>
+</para>
+
+<para>
+Sitting just above the <literal>Ewl_Object</literal> is the
+<literal>Ewl_Widget</literal>. Again, all widgets inheret from this object,
+which in turn inherits from the <literal>Ewl_Object</literal>. This object
+provides the base functinality for a widget to interact with users. Like
+the <literal>Ewl_Object</literal> an application will never need to allocate
+an <literal>Ewl_Widget</literal> itself.
+</para>
+
+<para>
+With the <literal>Ewl_Widget</literal> in place we can start to build up the
+hierarchy of widgets that form the EWL. The hierarchy looks something similar to
+that in the <link linkend="fig-obj_hierarchy">EWL Object Hierarcy</link> figure below.
+</para>
+
+<para>
+ <figure id="fig-obj_hierarchy">
+ <title>The EWL Object Hierarchy</title>
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="img/obj_hierarchy.png" format="png" />
+ </imageobject>
+ <textobject>
+ <phrase>The EWL Object Hierarchy</phrase>
+ </textobject>
+ </inlinemediaobject>
+ </figure>
+</para>
+
+<para>
+The <literal>Ewl_Container</literal> object is built off of the
+<literal>Ewl_Widget</literal> object and provides the functionality for
+widgets that are to hold other widgets. This includes anything from the main
+window, to boxes, to scrollpanes.
+</para>
+
+<para>
+To add new widgets into EWL you just need to create a new struct that has
+the appropriate type of subclass as the first element. This subclass object
+must not be a pointer.
+</para>
+
+<example>
+ <title>Creating EWL Widgets</title>
+ <programlisting>
+struct Ewl_Foo {
+ Ewl_Container container;
+ int bar;
+}
+ </programlisting>
+</example>
+<para>
+This would create a new Ewl_Foo widget that inherits from the
+<literal>Ewl_Container</literal> so you would be able to pack other widgets
+into this new widget type.
+</para>
+
</chapter>
===================================================================
RCS file: /cvsroot/enlightenment/e17/docs/ewlbook/xml/widget_packing.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -3 -r1.1 -r1.2
--- widget_packing.xml 9 Jul 2004 03:21:44 -0000 1.1
+++ widget_packing.xml 16 Jul 2004 04:11:17 -0000 1.2
@@ -1,5 +1,11 @@
<chapter id="ch-WidgetPacking">
<title>Widget Packing</title>
+<para>
+As your writting an EWL application you will need to start laying out the
+widgets into the different boxes. To do so, you'll need a bit of information
+on how EWL packs widgets together.
+</para>
+
</chapter>
===================================================================
RCS file: /cvsroot/enlightenment/e17/docs/ewlbook/xml/widgets.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -3 -r1.3 -r1.4
--- widgets.xml 11 Jul 2004 04:33:45 -0000 1.3
+++ widgets.xml 16 Jul 2004 04:11:17 -0000 1.4
@@ -2,7 +2,7 @@
<title>Widgets</title>
<para>
We will now look at each widget individually. See the code that creates the widget
and a
-screen shot of the widget in action.
+screen shot of the widget in action (if applicable).
</para>
<!-- ################################### -->
@@ -139,7 +139,14 @@
</inlinemediaobject>
</figure>
</para>
+
<para>
+<example id="sec-EwlComboCode">
+ <title>Creating a combo box</title>
+ <programlisting role="C">
+ </programlisting>
+</example>
+
</para>
</sect1>
@@ -148,6 +155,12 @@
<sect1 id="sec-EwlDialog">
<title>ewl_dialog</title>
<para>
+The <literal>Ewl_Dialog</literal> widget provides a way to display a simple
+dialog box to the user which can then prompt for a response, give warnings
+or just display simple messages.
+</para>
+
+<para>
<figure>
<title>An Ewl Dialog</title>
<inlinemediaobject>
@@ -161,6 +174,107 @@
</figure>
</para>
<para>
+<example id="sec-EwlDialogCode">
+<title>EWL Dialog code</title>
+<programlisting role="C">
+ Ewl_Widget *dialog = NULL;
+ Ewl_Widget *o = NULL;
+
+ o = ewl_text_new("a dialog eh");
+ ewl_object_set_alignment(EWL_OBJECT(o),
+ EWL_FLAG_ALIGN_CENTER);
+ ewl_widget_show(o);
+
+ dialog = ewl_dialog_new(EWL_POSITION_BOTTOM);
+ ewl_dialog_set_has_separator(EWL_DIALOG(dialog), 0);
+ ewl_dialog_add_widget(EWL_DIALOG(dialog), o);
+ ewl_object_set_alignment(EWL_OBJECT(dialog), EWL_FLAG_ALIGN_CENTER);
+ ewl_widget_show(dialog);
+
+ o = ewl_dialog_set_button(EWL_STOCK_OK, EWL_RESPONSE_OK);
+ ewl_container_append_child(EWL_CONTAINER(dialog), o);
+ ewl_callback_append(o, EWL_CALLBACK_CLICKED, dialog_clicked_cb, dialog);
+ ewl_widget_show(o);
+
+ o = ewl_dialog_set_button(EWL_STOCK_CANCEL, EWL_RESPONSE_CANCEL);
+ ewl_container_append_child(EWL_CONTAINER(dialog), o);
+ ewl_callback_append(o, EWL_CALLBACK_CLICKED, dialog_clicked_cb, dialog);
+ ewl_widget_show(o);
+</programlisting>
+</example>
+This example will create an <literal>Ewl_Dialog</literal> with two buttons
+an OK button and a Cancel button. The dialog itself is created with the
+call to <function>ewl_dialog_new()</function> passing the position of the
+buttons relative to the window itself. The possible values are:
+<itemizedlist mark="bullet" spacing="compact">
+ <listitem><para>EWL_POSITION_TOP</para></listitem>
+ <listitem><para>EWL_POSITION_BOTTOM</para></listitem>
+ <listitem><para>EWL_POSITION_LEFT</para></listitem>
+ <listitem><para>EWL_POSITION_RIGHT</para></listitem>
+</itemizedlist>
+</para>
+
+<para>
+A <literal>Ewl_Dialog</literal> can optionally have a horizontal line drawn
+to seperate the two sections of the dialog. The line is controlled with the
+<function>ewl_dialog_set_has_separator()</function> where 0 means do not
+draw separator and 1 means to draw the separator. There is a corresponding
+<function>ewl_dialog_get_has_separator()</function> returning 1 if there is
+a separator and 0 otherwise.
+</para>
+
+<para>
+The content of the main display area of the box is controlled through the
+function <function>ewl_dialog_add_widget()</function>. In this instance we
+add a <literal>Ewl_Text</literal> object into the dialog.
+</para>
+
+<para>
+Once the dialog is initialized we need to create any desired buttons. The
+buttons are created by calling <function>ewl_dialog_set_button()</function>
+this will create a button. The parameters are the label of the button and
+the response code to return from the button. There are several pre-defined
+labels, including:
+<itemizedlist mark="bullet" spacing="compact">
+ <listitem><para>EWL_STOCK_OK</para></listitem>
+ <listitem><para>EWL_STOCK_APPLY</para></listitem>
+ <listitem><para>EWL_STOCK_CANCEL</para></listitem>
+ <listitem><para>EWL_STOCK_OPEN</para></listitem>
+ <listitem><para>EWL_STOCK_SAVE</para></listitem>
+</itemizedlist>
+The pre-defined response codes are:
+<itemizedlist mark="bullet" spacing="compact">
+ <listitem><para>EWL_RESPONSE_OPEN</para></listitem>
+ <listitem><para>EWL_RESPONSE_SAVE</para></listitem>
+ <listitem><para>EWL_RESPONSE_OK</para></listitem>
+ <listitem><para>EWL_RESPONSE_CANCEL</para></listitem>
+ <listitem><para>EWL_RESPONSE_APPLY</para></listitem>
+</itemizedlist>
+Once the buttons are created they need to be added to the dialog and have a
+callback append for there <literal>EWL_CALLBACK_CLICKED</literal> state.
+</para>
+
+<para>
+<example id="sec-EwlDialogCB">
+<title>EWL Dialog callback</title>
+<programlisting role="C">
+void dialog_clicked_cb(Ewl_Widget *w, void *event, void *data) {
+ int d = EWL_BUTTON_STOCK(w)->response_id;
+
+ if (d == EWL_RESPONSE_OK)
+ printf("OK\n");
+ else if (d == EWL_RESPONSE_CANCEL)
+ printf("CANCEL\n");
+
+ ewl_widget_destroy(EWL_WIDGET(data));
+}
+</programlisting>
+</example>
+The response code of the button that was clicked is available from the
+<literal>Ewl_Button_Stock</literal> widget itself through its response_id
+parameter. Using this value we can determine which of the buttons was
+clicked. We also passed the <literal>Ewl_Dialog</literal> itself through the
+data parameter so that we could destroy the dialog when we were finished.
</para>
</sect1>
@@ -439,6 +553,88 @@
<sect1 id="sec-EwlText">
<title>ewl_text</title>
<para>
+The <literal>Ewl_Text</literal> widget provides for a multi-line text layout
+widget. It can be utillized whenever the display of text is required in an
+application. It works well with the <literal>Ewl_Scrollpane</literal> to
+provide a scrollable text area.
+</para>
+<para>
+<example id="sec-EwlTextCode">
+<title>Ewl_Text code</title>
+<programlisting role="C">
+ Ewl_Widget *text = ewl_text_new("text");
+ ewl_widget_show(text);
+</programlisting>
+</example>
+Creating the basic <literal>Ewl_Text</literal> object is pretty simple, the
+object will be setup to diplay the parameter to
+<function>ewl_text_new()</function>.
+</para>
+
+<para>
+Once the text object is created you can change the text, retrieve the
+current text contents or get the text length with:
+<itemizedlist mark="bullet" spacing="compact">
+ <listitem><para><function>ewl_text_text_set(Ewl_Text *, char
*)</function></para></listitem>
+ <listitem><para><function>ewl_text_text_prepend(Ewl_Text *, char
*)</function></para></listitem>
+ <listitem><para><function>ewl_text_text_append(Ewl_Text *, char
*)</function></para></listitem>
+ <listitem><para><function>ewl_text_text_insert(Ewl_Text *, char *, int
index)</function></para></listitem>
+ <listitem><para><function>char *ewl_text_text_get(Ewl_Text
*)</function></para></listitem>
+ <listitem><para><function>int ewl_text_length_get(Ewl_Text
*)</function></para></listitem>
+</itemizedlist>
+</para>
+
+<para>
+The <literal>Ewl_Text</literal> widget allows you to preform styling changes
+to the text in the widget. Different portions of the text can be different
+colours, fonts or styles. The styling that is applied to a widget is based
+on what is setup when the text is added to the widget. So, if you want your
+text to be red, you need to set the colour of the
+<literal>Ewl_Text</literal> object <emphasis>before</emphasis> adding the
+text.
+</para>
+
+<para>
+The colour of the text can be manipulated with the
+<function>ewl_text_color_set(Ewl_Text *, int r, int g, int b, int a</function>
+call while the current colour information can be retrieved with the
+<function>ewl_text_color_get(Ewl_Text *, int *r, int *g, int *b, int *a</function>.
+</para>
+
+<para>
+The font settings of the text can be manipulated with the
+<function>ewl_text_font_set(Ewl_Text *, char *font, int size)</function>
+call. With the calls to get the current font name as size defined as:
+<function>char *ewl_text_font_get(Ewl_Text *)</function> and
+<function>int ewl_text_font_size_get(Ewl_Text *)</function>.
+</para>
+
+<para>
+To retrieve or set the alignment of the text widget there are the two
+functions <function>ewl_text_align_set(Ewl_Text *, unsigned int align)</function>
+and <function>unsigned int ewl_text_align_get(Ewl_Text *)</function>. Where
+the align parameter is one of the EWL alignment flags:
+<itemizedlist mark="bullet" spacing="compact">
+ <listitem><para>EWL_FLAG_ALIGN_CENTER</para></listitem>
+ <listitem><para>EWL_FLAG_ALIGN_LEFT</para></listitem>
+ <listitem><para>EWL_FLAG_ALIGN_RIGHT</para></listitem>
+ <listitem><para>EWL_FLAG_ALIGN_TOP</para></listitem>
+ <listitem><para>EWL_FLAG_ALIGN_BOTTOM</para></listitem>
+</itemizedlist>
+</para>
+
+<para>
+It is also possible to set the style of the text. This can include things
+such as bolding the text or setting soft shadows. The styles that are
+available are shipped through the Etox library and currently include:
+<itemizedlist mark="bullet" spacing="compact">
+ <listitem><para>bold</para></listitem>
+ <listitem><para>outline</para></listitem>
+ <listitem><para>plain</para></listitem>
+ <listitem><para>raised</para></listitem>
+ <listitem><para>shadow</para></listitem>
+ <listitem><para>soft_shadow</para></listitem>
+</itemizedlist>
</para>
</sect1>
@@ -472,6 +668,79 @@
</sect1>
<!-- ################################### -->
+<!-- EWL MEDIA -->
+<sect1 id="sec-EwlMedia">
+<title>ewl_media</title>
+<para>
+The <literal>Ewl_Media</literal> widget allows for the embedding of video
+objects into your application. This is done by wrapping around the Emotion
+library.
+</para>
+
+<para>
+ <figure>
+ <title>An EWL media object</title>
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="img/ewl_media.png" format="png" />
+ </imageobject>
+ <textobject>
+ <phrase>Example of an EWL Media object</phrase>
+ </textobject>
+ </inlinemediaobject>
+ </figure>
+</para>
+
+<para>
+<example id="sec-EwlMediaCode">
+<title>Ewl_Media code</title>
+<programlisting role="C">
+ Ewl_Media *m = ewl_media_new(file);
+ ewl_widget_show(m);
+</programlisting>
+</example>
+Creating the basic video object is no simpler then creating the object and
+showning it (assuming you've appending it to whatever container it is being
+placed into).
+</para>
+
+<para>
+The video that is being displayed can be changed by calling
+<function>ewl_media_media_set(Ewl_Media *, char *)</function> or if you just
+wish to know what is currently playing you can call
+<function>char *ewl_media_media_get(Ewl_Media *)</function>. The length of
+the current video can be retrieved by calling <function>int
+ewl_media_length_get(Ewl_Media *)</function>.
+</para>
+
+<para>
+You can start the video playing by passing 1 to
+<function>ewl_media_play_set(Ewl_Media *, int)</function> or stop the video
+by passing 0 to the same function.
+</para>
+
+<para>
+To determine if the video codec allows for seeking in the video you can call
+<function>int ewl_media_seekable_get(Ewl_Media *)</function> which will
+return 1 if the video is seekable, 0 otherwise.
+<function>double ewl_media_position_get(Ewl_Media *)</function> is used to determine
+the current position in the video, while
+<function>ewl_media_position_set(Ewl_Media *, double position)</function>
+can be used to set the position in the video.
+</para>
+
+<para>
+If you wish to change the audio settings of the video there are several
+functions available. These including the ability to get/set the current mute
+settings: <function>int ewl_media_audio_mute_get(Ewl_Media *)</function> and
+<function>ewl_media_audio_mute_set(Ewl_Media *, int)</function>. You can
+also get/set the volume of the video through the calls:
+<function>int ewl_media_audio_volume_get(Ewl_Media *)</function> and
+<function>ewl_media_audio_volume_set(Ewl_Media *, int)</function>.
+</para>
+</sect1>
+
+<!-- ################################### -->
<!-- EWL WINDOW -->
<sect1 id="sec-EwlWindow">
<title>ewl_window</title>
-------------------------------------------------------
This SF.Net email is sponsored by BEA Weblogic Workshop
FREE Java Enterprise J2EE developer tools!
Get your free copy of BEA WebLogic Workshop 8.1 today.
http://ads.osdn.com/?ad_id=4721&alloc_id=10040&op=click
_______________________________________________
enlightenment-cvs mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/enlightenment-cvs
