Enlightenment CVS committal
Author : rbdpngn
Project : e17
Module : libs/ewl
Dir : e17/libs/ewl/src
Modified Files:
Ewl.h ewl_embed.c ewl_embed.h ewl_fileselector.c ewl_object.c
ewl_object.h ewl_widget.c ewl_widget.h ewl_window.c
ewl_window.h
Log Message:
Begin conversion of source code documentation to doxygen format.
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/Ewl.h,v
retrieving revision 1.32
retrieving revision 1.33
diff -u -3 -r1.32 -r1.33
--- Ewl.h 13 Jul 2003 05:52:49 -0000 1.32
+++ Ewl.h 27 Aug 2003 06:27:52 -0000 1.33
@@ -1,8 +1,210 @@
#ifndef _EWL_H
#define _EWL_H
+/**
+ * @file Ewl.h
+ * @brief The file that should be included by any project using EWL.
+ * It provides all the necessary headers and includes to work with EWL,
+ * it is discouraged to include each header file individually.
+ */
+
+/**
+ * @mainpage Enlightened Widget Library Documentation
+ *
+ * @image html evas_mini.png
+ *
+ * @section intro Introduction
+ *
+ * The Enlightenment Widget Library (EWL) is a widget toolkit based on the
+ * libraries provided for Enlightenment 17 development. Rendering is performed
+ * using Evas, a fast abstracted canvas library that supports multiple
+ * backends. The appearances of the widgets are described by Edje files,
+ * which are essentially files containing a collection of images and
+ * descriptions for laying out those images. The goal of EWL is to abstract
+ * the use of these backends and to present an easy to use object model to the
+ * end programmer.
+ *
+ * Overall, EWL is similar in design and functionality to other common
+ * toolkits such as GTK+ and QT. The API's differ, but the overall concepts
+ * and ideas are similar. If you are familiar with these other toolkits,
+ * getting into EWL should be relatively simple.
+ *
+ * EWL uses the concept of inheritance for describing it's widgets. When a
+ * class inherits from another class, the functions that operated on the base
+ * class can also operate on the inheriting class. For example, in EWL the
+ * class Ewl_Button inherits from Ewl_Box, which inherits from Ewl_Container.
+ * This means you can add widgets to the button, just like you could to the
+ * box or any other container by using ewl_container_append.
+ *
+ * @image html evas_mini.png
+ *
+ * @section model The Object Model
+ *
+ * The basis for all widgets in EWL is the Ewl_Object. Ewl_Objects are never
+ * allocated outside of another widget, it provides size and position
+ * information for the widget as well as info about it's padding and insets.
+ * There are also fields for indicating object alignment and fill policies.
+ * Eventually, it will also contain a type field, which will essentially be a
+ * colon separated listing of all the inheriting classes for a particular
+ * widget.
+ *
+ * The next step above the Ewl_Object is the Ewl_Widget. Again, these are
+ * never allocated by themselves, but are part of all the other widgets
+ * available in EWL. The Ewl_Widget class provides necessary information about
+ * a widget that relates to it's appearance, it's parent container, event
+ * handling, as well as a few miscellaneous tasks common to all widgets.
+ *
+ * A necessary class that some widgets inherit from is Ewl_Container. This is
+ * used for holding collections of widgets and laying them out. Containers are
+ * the building blocks of the widget set, they allow for creating heirarchies
+ * of widgets that are bounded within their parent containers. The class
+ * inherits from Ewl_Widget, so that any container can also be treated as a
+ * widget, and thus you can put containers within other containers. Examples
+ * of inheriting classes are Ewl_Window and Ewl_Box. In the case of the
+ * Ewl_Window, widgets inside the window are given any position they request
+ * within the insets of the window. For the Ewl_Box, contained widgets are
+ * layed out either from top to bottom, or from left to right, depending on
+ * the box orientation.
+ *
+ * @image html evas_mini.png
+ *
+ * @section callbacks Callbacks
+ *
+ * To do work in a GUI, it is necessary to know when certain actions occur.
+ * EWL handles notification of actions using a common technique called
+ * callbacks. When the end programmer wants to know when a specific event
+ * occurs to a widget, they can add a callback to it using ewl_callback_append
+ * or one of the similar functions. One of the arguments to these functions is
+ * a pointer to a function. This function will get called when EWL receives
+ * the specified event on that widget. You can attach callbacks to any widget,
+ * and with containers you can even mark them to intercept events to their
+ * child widgets.
+ *
+ * One feature of EWL that is different from other toolkits is that it makes
+ * extensive use of internal callbacks. In fact, almost all appearance changes
+ * for widgets are actually callbacks, and most of the ewl_widget calls
+ * actually do very little work, but trigger specific callbacks. This feature
+ * allows for overriding specific actions on a widget, or for ordering user
+ * specified callbacks relative to internal ones.
+ * Example Application Walk-through
+ *
+ * One of the easiest applications to build for EWL is a simple image viewer.
+ * The basic image viewer needs a window, and an image widget. The following
+ * app is a fully functional simple image viewer based on code written by Ben
+ * Rockwood of Cuddletech. The first part necessary for creating an EWL
+ * application is to include the necessary header Ewl.h. Following the include
+ * statements are global variable declarations.
+ *
+ * @code
+ * #include <Ewl.h>
+ *
+ * Ewl_Widget *main_win;
+ * Ewl_Widget *main_box;
+ * Ewl_Widget *images;
+ * @endcode
+ *
+ * Now declarations of function callbacks are
+ * made, normally when writing an application
+ * these are added after the GUI code is written.
+ * The next piece of code is common to most apps,
+ * the windows in EWL are not closed unless they
+ * are destroyed, so a callback must be attached
+ * for the windows delete callback.
+ *
+ * @code
+ * void
+ * __destroy_main_window(Ewl_Widget *main_win, void *ev_data, void *user_data)
+ * {
+ * ewl_widget_destroy(main_win);
+ * ewl_main_quit();
+ *
+ * return;
+ * }
+ * @endcode
+ *
+ * For this simple application, that is the only necessary callback, now we
+ * have the main function. This is where EWL is initialized,
+ * widgets are created, and the main EWL loop is started. First,
+ * declare the main function and check to be sure that an image
+ * file was specified, then initialize the EWL library.
+ *
+ * @code
+ * int main (int argc, char ***argv)
+ * {
+ * if (argc < 2) {
+ * fprintf(stderr, "Usage: %s <image>\n", argv[0]);
+ * return 1;
+ * }
+ * ewl_init(argc, argv);
+ * @endcode
+ *
+ * Next allocate the window, set it's title and attach a callback to catch it's
+ * delete event. Also, set a minimum size on the window, also mark it to be
+ * auto-sized, and visible. Marking it auto-sized will cause the widget to
+ * resize to fit the contents.
+ *
+ * @code
+ * main_win = ewl_window_new();
+ * ewl_window_set_title(EWL_WINDOW(main_win), "EWL Simple Image Viewer");
+ * ewl_callback_append(main_win, EWL_CALLBACK_DELETE_WINDOW,
+ * __destroy_main_window, NULL);
+ * ewl_window_set_min_size(EWL_WINDOW(main_win), 100, 100);
+ * ewl_window_set_auto_size(EWL_WINDOW(main_win), TRUE);
+ * ewl_widget_show(main_win);
+ * @endcode
+ *
+ * Now we create a box for holding the image, this is not really necessary for
+ * this app, but it demonstrates further how to use containers, and makes it
+ * easier to add more widgets later.
+ *
+ * @code
+ * main_box = *ewl_vbox_new();
+ * ewl_container_append_child(EWL_CONTAINER(main_win), *main_box);
+ * ewl_widget_show(main_box);
+ * @endcode
+ *
+ * Next, create the image widget, we just attempt to load the image
+ * file that was specified on the command line, and add it to the
+ * box in the window.
+ *
+ * @code
+ * image *= *ewl_image_load(argv[1]);
+ * ewl_container_append_child(EWL_CONTAINER(main_box), image);
+ * ewl_widget_show(image);
+ * @endcode
+ *
+ * Finally, we call the main function that starts the EWL event
+ * processing loop, and with that our app is complete.
+ *
+ * @code
+ * ewl_main();
+ *
+ * return 0;
+ * }
+ * @endcode
+ *
+ * Now that the application source has been written, it must be
+ * compiled. This is fairly simple with EWL, if you name the app
+ * simple_viewer.c just use the command:
+ *
+ * gcc -o simple_viewer `ewl-config --cflags --libs` simple_viewer.c
+ *
+ * @image html evas_mini.png
+ *
+ * @section conclusion Conclusion
+ *
+ * Obviously, creating a simple image viewer does not take much
+ * effort at all, but it is a good basis for understanding the
+ * basics of EWL. Hopefully, readers will extend this app, and
+ * possibly create more robust image viewers, and with any luck,
+ * other applications to demonstrate EWL's capabilities.
+ *
+ * If you have questions, corrections, or improvements, please send
+ * them to <a href="mailto: [EMAIL PROTECTED]">RbdPngn</a>.
+ */
+
#ifdef __cplusplus
-extern "C" {
+extern"C" {
#endif
#include <Edje.h>
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_embed.c,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -3 -r1.2 -r1.3
--- ewl_embed.c 25 Aug 2003 19:40:42 -0000 1.2
+++ ewl_embed.c 27 Aug 2003 06:27:52 -0000 1.3
@@ -52,9 +52,8 @@
void __ewl_embed_evas_key_up(void *data, Evas *e, Evas_Object *obj, void *event_info);
/**
- * ewl_embed_new - allocate and initialize a new embed
- *
- * Returns a new embed on success, or NULL on failure.
+ * @return Returns a new embed on success, or NULL on failure.
+ * @brief Allocate and initialize a new embed
*/
Ewl_Widget *ewl_embed_new()
{
@@ -76,11 +75,11 @@
}
/**
- * ewl_embed_init - initialize a embed to default values and callbacks
- * @w: the embed to be initialized to default values and callbacks
+ * @param w: the embed to be initialized to default values and callbacks
+ * @return Returns TRUE or FALSE depending on if initialization succeeds.
+ * @brief initialize a embed to default values and callbacks
*
- * Returns TRUE or FALSE depending on if initialization succeeds. Sets the
- * values and callbacks of a embed @w to their defaults.
+ * Sets the values and callbacks of a embed @a w to their defaults.
*/
int ewl_embed_init(Ewl_Embed * w)
{
@@ -115,12 +114,13 @@
}
/**
- * ewl_embed_set_evas - change the evas used by the embedded container
- * @emb: the embedded container to change the target evas
- * @evas: the new evas to draw the container and it's contents
+ * @param emb: the embedded container to change the target evas
+ * @param evas: the new evas to draw the container and it's contents
+ * @return Returns an evas smart object on success, NULL on failure.
+ * @brief Change the evas used by the embedded container
*
- * Returns an evas smart object for manipulating the target embedded container
- * on success, NULL on failure.
+ * The returned smart object can be used to manipulate the area used by EWL
+ * through standard evas functions.
*/
Evas_Object *ewl_embed_set_evas(Ewl_Embed *emb, Evas *evas)
{
@@ -198,11 +198,12 @@
}
/**
- * ewl_embed_font_path_add - add a font path to all embeds after realized
- * @path: the font path to add to the embeds
+ * @param path: the font path to add to the embeds
+ * @return Returns no value.
+ * @brief Add a font path to all embeds after realized
*
- * Returns no value. Adds the search path @path to the evases created in the
- * embeds. Using ewl_theme_font_path_add is preferred.
+ * Adds the search path to the evases created in the embeds. Using
+ * ewl_theme_font_path_add is preferred.
*/
void ewl_embed_font_path_add(char *path)
{
@@ -221,10 +222,9 @@
}
/**
- * ewl_embed_find_by_evas_window - find an ewl embed by its evas window
- * @embed: the evas window to search for on the list of embeds
- *
- * Returns the found embed on success, NULL on failure to find the embed.
+ * @param window: the evas window to search for on the list of embeds
+ * @return Returns the found embed on success, NULL on failure.
+ * @brief Find an ewl embed by its evas window
*/
Ewl_Embed *ewl_embed_find_by_evas_window(Window window)
{
@@ -244,10 +244,9 @@
}
/**
- * ewl_embed_find_by_widget - find an ewl embed by a widget inside
- * @w: the widget to search for its embed
- *
- * Returns the found embed on success, NULL on failure to find the embed.
+ * @param w: the widget to search for its embed
+ * @return Returns the found embed on success, NULL on failure.
+ * @brief Find an ewl embed by a widget inside
*/
Ewl_Embed *ewl_embed_find_by_widget(Ewl_Widget * w)
{
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_embed.h,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -3 -r1.1 -r1.2
--- ewl_embed.h 13 Jul 2003 05:52:49 -0000 1.1
+++ ewl_embed.h 27 Aug 2003 06:27:52 -0000 1.2
@@ -2,30 +2,38 @@
#ifndef __EWL_EMBED_H__
#define __EWL_EMBED_H__
-/*
+/**
+ * @file ewl_embed.h
+ * Defines the Ewl_Embed class to provide EWL with the ability to work with an
+ * evas.
+ */
+
+/**
* The embed structure is mostly a container for holding widgets and a
* wrapper evas smart object.
*/
-typedef struct _ewl_embed Ewl_Embed;
+typedef struct Ewl_Embed Ewl_Embed;
+
+/**
+ * @def EWL_EMBED(widget)
+ * @brief Typecast a pointer to an Ewl_Embed pointer.
+ */
+#define EWL_EMBED(widget) ((Ewl_Embed *) widget)
-struct _ewl_embed
+/**
+ * @struct Ewl_Embed
+ * @brief The class inheriting from Ewl_Container that acts as a top level
+ * widget for interacting with the evas.
+ */
+struct Ewl_Embed
{
- Ewl_Container widget;
+ Ewl_Container container; /**< Inherits from the Ewl_Container class */
- /*
- * The following fields allow for drawing the widgets
- */
- Evas *evas;
- Window evas_window;
+ Evas *evas; /**< Evas where drawing takes place. */
+ Window evas_window; /**< The window holding the evas. */
- /*
- * This smart object can be used by a lower level evas access library
- * to manipulate the size and position of the embedded container.
- */
- Evas_Object *smart;
+ Evas_Object *smart; /**< Object to manipulate Ewl_Embed from evas */
};
-
-#define EWL_EMBED(widget) ((Ewl_Embed *) widget)
Ewl_Widget *ewl_embed_new();
int ewl_embed_init(Ewl_Embed * win);
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_fileselector.c,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -3 -r1.6 -r1.7
--- ewl_fileselector.c 3 Feb 2003 00:21:09 -0000 1.6
+++ ewl_fileselector.c 27 Aug 2003 06:27:52 -0000 1.7
@@ -70,12 +70,12 @@
/**
* ewl_fileselector_new - create a new fileselector
- * @file_clicked: callback for file clicked event
+ * @clicked: callback for file clicked event
*
* Returns a pointer to a newly allocated fileselector on success, NULL
* on failure.
*/
-Ewl_Widget *ewl_fileselector_new(Ewl_Callback_Function file_clicked)
+Ewl_Widget *ewl_fileselector_new(Ewl_Callback_Function clicked)
{
Ewl_Fileselector *fs;
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_object.c,v
retrieving revision 1.39
retrieving revision 1.40
diff -u -3 -r1.39 -r1.40
--- ewl_object.c 25 Aug 2003 19:40:42 -0000 1.39
+++ ewl_object.c 27 Aug 2003 06:27:52 -0000 1.40
@@ -2,10 +2,11 @@
#include <Ewl.h>
/**
- * ewl_object_init - initialize the fields of an object
- * @o: the object to initialize
+ * @param o: the object to initialize
+ * @return Returns no value.
+ * @brief Initialize the fields of an object
*
- * Returns no value. Sets all of the fields of the object @o to their default
+ * Sets all of the fields of the object @a o to their default
* values. NEVER, EVER inherit directly from this class, inherit from the
* widget instead. The separation is really just a convenience factor, a
* Widget really is the lowest common class.
@@ -33,15 +34,16 @@
}
/**
- * ewl_object_get_current_geometry - retrieve the size and position of object
- * @o: the object to retrieve size and position
- * @x: a pointer to the integer to store the x coordinate
- * @y: a pointer to the integer to store the y coordinate
- * @w: a pointer to the integer to store the width
- * @h: a pointer to the integer to store the height
+ * @param o: the object to retrieve size and position
+ * @param x: a pointer to the integer to store the x coordinate
+ * @param y: a pointer to the integer to store the y coordinate
+ * @param w: a pointer to the integer to store the width
+ * @param h: a pointer to the integer to store the height
+ * @return Returns no value.
+ * @brief Retrieve the size and position of object
*
- * Returns no value. Examines @o and stores it's size and position into the
- * integers pointed to by the parameters @x, @y, @w, and @h.
+ * Examines @a o and stores it's size and position into the
+ * integers pointed to by the parameters @a x, @a y, @a w, and @a h.
*/
void
ewl_object_get_current_geometry(Ewl_Object * o, int *x, int *y,
@@ -60,12 +62,13 @@
}
/**
- * ewl_object_get_current_size - retrieve the current size of an object
- * @o: the object to retrieve size information
- * @w: a pointer to the integer to store the width of the object
- * @h: a pointer to the integer to store the height of the object
+ * @param o: the object to retrieve size information
+ * @param w: a pointer to the integer to store the width of the object
+ * @param h: a pointer to the integer to store the height of the object
+ * @return Returns no value.
+ * @brief Retrieve the current size of an object
*
- * Returns no value. Stores the width and height of object @o into @w and @h
+ * Stores the width and height of the object into @a w and @a h
* respectively.
*/
void
@@ -80,10 +83,9 @@
}
/**
- * ewl_object_get_current_x - get the current x position of the object
- * @o: the object to retrieve the current x position
- *
- * Returns the current x position of the object @o.
+ * @param o: the object to retrieve the current x position
+ * @return Returns the current x position of the object @a o.
+ * @brief get the current x position of the object
*/
int ewl_object_get_current_x(Ewl_Object * o)
{
@@ -94,10 +96,9 @@
}
/**
- * ewl_object_get_current_y - get the current y position of the object
- * @o: the object to retrieve the current y position
- *
- * Returns the current y position of the object @o.
+ * @param o: the object to retrieve the current y position
+ * @return Returns the current y position of the object.
+ * @brief Get the current y position of the object
*/
int ewl_object_get_current_y(Ewl_Object * o)
{
@@ -108,10 +109,9 @@
}
/**
- * ewl_object_get_current_w - get the current width of the object
- * @o: the object to retrieve the current width
- *
- * Returns the current width of the object @o.
+ * @param o: the object to retrieve the current width
+ * @return Returns the current width of the object.
+ * @brief Get the current width of the object
*/
unsigned int ewl_object_get_current_w(Ewl_Object * o)
{
@@ -122,10 +122,9 @@
}
/**
- * ewl_object_get_current_h - get the current height of the object
- * @o: the object to retrieve the current height
- *
- * Returns the current height of the object @o.
+ * @param o: the object to retrieve the current height
+ * @return Returns the current height of the object.
+ * @brief Get the current height of the object
*/
unsigned int ewl_object_get_current_h(Ewl_Object * o)
{
@@ -136,13 +135,14 @@
}
/**
- * ewl_object_set_preferred_size - set the preferred size of the object
- * @o: the object to change size
- * @w: the new width of the object
- * @h: the new height of the object
+ * @param o: the object to change size
+ * @param w: the new width of the object
+ * @param h: the new height of the object
+ * @return Returns no value.
+ * @brief Set the preferred size of the object
*
- * Returns no value. The dimensions of the object @o are set to the values of
- * the parameters @w, and @h unless these values are greater than the objects
+ * The dimensions of the object @a o are set to the values of
+ * the parameters @a w, and @a h unless these values are greater than the objects
* maximum value or smaller than the objects minimum value. If they are
* outside these bounds, the size is not altered.
*/
@@ -160,12 +160,13 @@
}
/**
- * ewl_object_set_preferred_w - set the preferred width of the object
- * @o: the object to change preferred width
- * @w: the value to use as the preferred width
+ * @param o: the object to change preferred width
+ * @param w: the value to use as the preferred width
+ * @return Returns no value.
+ * @brief Set the preferred width of the object
*
- * Returns no value. Sets the preferred of @o width to @w or as close as
- * possible according to the bounds.
+ * Sets the preferred of @a o width to @a w or as close as possible according to
+ * the bounds.
*/
void ewl_object_set_preferred_w(Ewl_Object * o, unsigned int w)
{
@@ -198,12 +199,13 @@
}
/**
- * ewl_object_set_preferred_h - set the preferred height of the object
- * @o: the object to change preferred height
- * @h: the value to use as the preferred height
+ * @param o: the object to change preferred height
+ * @param h: the value to use as the preferred height
+ * @return Returns no value.
+ * @brief Set the preferred height of the object
*
- * Returns no value. Sets the preferred of @o height to @w or as close as
- * possible according to the bounds.
+ * Sets the preferred of @a o height to @a w or as close as possible according
+ * to the bounds.
*/
void ewl_object_set_preferred_h(Ewl_Object * o, unsigned int h)
{
@@ -236,12 +238,13 @@
}
/**
- * ewl_object_get_preferred_size - retrieve the preferred size of an object
- * @o: the object to retrieve size information
- * @w: a pointer to the integer to store the width of the object
- * @h: a pointer to the integer to store the height of the object
+ * @param o: the object to retrieve size information
+ * @param w: a pointer to the integer to store the width of the object
+ * @param h: a pointer to the integer to store the height of the object
+ * @return Returns no value.
+ * @brief Retrieve the preferred size of an object
*
- * Returns no value. Stores the width and height of object @o into @w and @h
+ * Stores the width and height of object @a o into @a w and @a h
* respectively.
*/
void ewl_object_get_preferred_size(Ewl_Object * o,
@@ -256,10 +259,9 @@
}
/**
- * ewl_object_get_preferred_w - get the preferred width of the object
- * @o: the object to retrieve the preferred width
- *
- * Returns the preferred width of the object @o.
+ * @param o: the object to retrieve the preferred width
+ * @return Returns the preferred width of the object @a o.
+ * @brief Get the preferred width of the object
*/
unsigned int ewl_object_get_preferred_w(Ewl_Object * o)
{
@@ -282,10 +284,9 @@
}
/**
- * ewl_object_get_preferred_h - get the preferred height of the object
- * @o: the object to retrieve the preferred height
- *
- * Returns the preferred height of the object @o.
+ * @param o: the object to retrieve the preferred height
+ * @return Returns the preferred height of the object.
+ * @brief Get the preferred height of the object
*/
unsigned int ewl_object_get_preferred_h(Ewl_Object * o)
{
@@ -308,16 +309,16 @@
}
/**
- * ewl_object_request_geometry - request a new geometry be applied to an object
- * @o: the object to request a new size
- * @x: the x coordinate to request be applied to the object
- * @y: the y coordinate to request be applied to the object
- * @w: the width to request be applied to the object
- * @h: the height to request be applied to the object
- *
- * Returns no value. The given geometry is requested to be applied to the
- * object @o. This is the usual method for requesting a new geometry for an
- * object.
+ * @param o: the object to request a new size
+ * @param x: the x coordinate to request be applied to the object
+ * @param y: the y coordinate to request be applied to the object
+ * @param w: the width to request be applied to the object
+ * @param h: the height to request be applied to the object
+ * @return Returns no value.
+ * @brief Request a new geometry be applied to an object
+ *
+ * The given geometry is requested to be applied to the object. This is the
+ * usual method for requesting a new geometry for an object.
*/
void ewl_object_request_geometry(Ewl_Object * o, int x, int y,
unsigned int w, unsigned int h)
@@ -331,14 +332,14 @@
/**
- * ewl_object_request_size - request a new size be applied to an object
- * @o: the object to request a new size
- * @w: the width to request be applied to the object
- * @h: the height to request be applied to the object
- *
- * Returns no value. The given size is requested to be applied to the
- * object @o at a later time. This is the usual method for requesting a new
- * size for an object.
+ * @param o: the object to request a new size
+ * @param w: the width to request be applied to the object
+ * @param h: the height to request be applied to the object
+ * @return Returns no value.
+ * @brief Request a new size be applied to an object
+ *
+ * The given size is requested to be applied to the object @a o at a later time.
+ * This is the usual method for requesting a new size for an object.
*/
void ewl_object_request_size(Ewl_Object * o, unsigned int w, unsigned int h)
{
@@ -352,14 +353,14 @@
/**
- * ewl_object_request_position - request a new position be applied to an object
- * @o: the object to request a new size
- * @x: the x coordinate to request be applied to the object
- * @y: the y coordinate to request be applied to the object
- *
- * Returns no value. The given position is requested to be applied to the
- * object @o at a later time. This is the usual method for requesting a new
- * position for an object.
+ * @param o: the object to request a new size
+ * @param x: the x coordinate to request be applied to the object
+ * @param y: the y coordinate to request be applied to the object
+ * @return Returns no value.
+ * @brief Request a new position be applied to an object
+ *
+ * The given position is requested to be applied to the object @a o at a later
+ * time. This is the usual method for requesting a new position for an object.
*/
void ewl_object_request_position(Ewl_Object * o, int x, int y)
{
@@ -372,12 +373,13 @@
}
/**
- * ewl_object_request_x - request a new x position for an object
- * @o: the object to request a new x position
- * @x: the new x coordinate to be applied to the object
+ * @param o: the object to request a new x position
+ * @param x: the new x coordinate to be applied to the object
+ * @return Returns no value.
+ * @brief Request a new x position for an object
*
- * Returns no value. The given x coordinate is stored to be applied to the
- * object @o at a later time.
+ * The given x coordinate is stored to be applied to the object @a o at a later
+ * time.
*/
inline void ewl_object_request_x(Ewl_Object * o, int x)
{
@@ -393,12 +395,13 @@
/**
- * ewl_object_request_y - request a new y position for an object
- * @o: the object to request a new y position
- * @y: the new y coordinate to be applied to the object
+ * @param o: the object to request a new y position
+ * @param y: the new y coordinate to be applied to the object
+ * @return Returns no value.
+ * @brief Request a new y position for an object
*
- * Returns no value. The given y coordinate is stored to be applied to the
- * object @o at a later time.
+ * The given y coordinate is stored to be applied to the object @a o at a later
+ * time.
*/
inline void ewl_object_request_y(Ewl_Object * o, int y)
{
@@ -414,12 +417,12 @@
/**
- * ewl_object_request_w - request a new width for an object
- * @o: the object to request a new width
- * @w: the new width to be applied to the object
+ * @param o: the object to request a new width
+ * @param w: the new width to be applied to the object
+ * @return Returns no value.
+ * @brief Request a new width for an object
*
- * Returns no value. The given width is stored to be applied to the
- * object @o at a later time.
+ * The given width is stored to be applied to the object @a o at a later time.
*/
void ewl_object_request_w(Ewl_Object * o, unsigned int w)
{
@@ -453,12 +456,12 @@
/**
- * ewl_object_request_h - request a new width for an object
- * @o: the object to request a new height
- * @h: the new height to be applied to the object
+ * @param o: the object to request a new height
+ * @param h: the new height to be applied to the object
+ * @return Returns no value.
+ * @brief Request a new width for an object
*
- * Returns no value. The given height is stored to be applied to the
- * object @o at a later time.
+ * The given height is stored to be applied to the object @a o at a later time.
*/
void ewl_object_request_h(Ewl_Object * o, unsigned int h)
{
@@ -491,12 +494,13 @@
}
/**
- * ewl_object_set_minimum_size - set the minimum size of an object
- * @o: the object to change the minimum size
- * @w: the new minimum width
- * @h: the new minimum height
+ * @param o: the object to change the minimum size
+ * @param w: the new minimum width
+ * @param h: the new minimum height
+ * @return Returns no value.
+ * @brief Set the minimum size of an object
*
- * Returns no value. Sets the minimum size of the object @o to @w x @h. If the
+ * Sets the minimum size of the object @a o to @a w x @a h. If the
* current size or maximum size are less than the new minimum, they are set to
* the new minimum size.
*/
@@ -513,13 +517,14 @@
/**
- * ewl_object_set_minimum_w - set the minimum width of an object
- * @o: the object to change the minimum width
- * @w: the new minimum width
- *
- * Returns no value. Sets the minimum width of the object @o to @w. If the
- * current width or maximum width are less than the new minimum, they are set to
- * the new minimum width.
+ * @param o: the object to change the minimum width
+ * @param w: the new minimum width
+ * @return Returns no value.
+ * @brief Set the minimum width of an object
+ *
+ * Sets the minimum width of the object @a o to @a w. If the current width or
+ * maximum width are less than the new minimum, they are set to the new minimum
+ * width.
*/
inline void ewl_object_set_minimum_w(Ewl_Object * o, unsigned int w)
{
@@ -553,13 +558,14 @@
/**
- * ewl_object_set_minimum_h - set the minimum height of an object
- * @o: the object to change the minimum height
- * @h: the new minimum height
- *
- * Returns no value. Sets the minimum height of the object @o to @h. If the
- * current height or maximum height are less than the new minimum, they are set
- * to the new minimum height.
+ * @param o: the object to change the minimum height
+ * @param h: the new minimum height
+ * @brief Set the minimum height of an object
+ *
+ * @return Returns no value.
+ * Sets the minimum height of the object @a o to @a h. If the current height or
+ * maximum height are less than the new minimum, they are set to the new minimum
+ * height.
*/
inline void ewl_object_set_minimum_h(Ewl_Object * o, unsigned int h)
{
@@ -592,10 +598,9 @@
}
/**
- * ewl_object_get_minimum_w - get the minimum width of an object
- * @o: the object to get the minimum width
- *
- * Returns the minimum width of the object @o.
+ * @param o: the object to get the minimum width
+ * @return Returns the minimum width of the object @a o.
+ * @brief Get the minimum width of an object
*/
inline unsigned int ewl_object_get_minimum_w(Ewl_Object * o)
{
@@ -614,10 +619,9 @@
}
/**
- * ewl_object_get_minimum_h - get the minimum height of an object
- * @o: the object to get the minimum height
- *
- * Returns the minimum height of the object @o.
+ * @param o: the object to get the minimum height
+ * @return Returns the minimum height of the object.
+ * @brief Get the minimum height of an object
*/
inline unsigned int ewl_object_get_minimum_h(Ewl_Object * o)
{
@@ -636,13 +640,14 @@
}
/**
- * ewl_object_get_minimum_size - retrieve the minimum dimensions of an object
- * @o: the object to retrieve the minimum dimensions
- * @w: a pointer to an integer to store the minimum width
- * @h: a pointer to an integer to store the minimum height
+ * @param o: the object to retrieve the minimum dimensions
+ * @param w: a pointer to an integer to store the minimum width
+ * @param h: a pointer to an integer to store the minimum height
+ * @return Returns no value.
+ * @brief Retrieve the minimum dimensions of an object
*
- * Returns no value. Stores the minimum height and width of object @o into the
- * integers pointed to by @w and @h respectively.
+ * Stores the minimum height and width of object @a o into the integers pointed
+ * to by @a w and @a h respectively.
*/
void
ewl_object_get_minimum_size(Ewl_Object * o, unsigned int *w, unsigned int *h)
@@ -661,12 +666,13 @@
/**
- * ewl_object_set_maximum_size - set the maximum size of an object
- * @o: the object to change the maximum size
- * @w: the new maximum width
- * @h: the new maximum height
+ * @param o: the object to change the maximum size
+ * @param w: the new maximum width
+ * @param h: the new maximum height
+ * @return Returns no value.
+ * @brief Set the maximum size of an object
*
- * Returns no value. Sets the maximum size of the object @o to @w x @h. If the
+ * Sets the maximum size of the object @a o to @a w x @a h. If the
* current size or minimum size are less than the new maximum, they are set to
* the new maximum size.
*/
@@ -684,13 +690,14 @@
/**
- * ewl_object_set_maximum_w - set the minimum width of an object
- * @o: the object to change the maximum width
- * @w: the new maximum width
- *
- * Returns no value. Sets the maximum width of the object @o to @w. If the
- * current width or minimum width are less than the new maximum, they are set to
- * the new maximum width.
+ * @param o: the object to change the maximum width
+ * @param w: the new maximum width
+ * @return Returns no value.
+ * @brief Set the minimum width of an object
+ *
+ * Sets the maximum width of the object @a o to @a w. If the current width or
+ * minimum width are less than the new maximum, they are set to the new
+ * maximum width.
*/
inline void ewl_object_set_maximum_w(Ewl_Object * o, unsigned int w)
{
@@ -713,11 +720,12 @@
/**
- * ewl_object_set_maximum_h - set the minimum height of an object
- * @o: the object to change the maximum height
- * @h: the new maximum height
+ * @param o: the object to change the maximum height
+ * @param h: the new maximum height
+ * @return Returns no value.
+ * @brief Set the minimum height of an object
*
- * Returns no value. Sets the maximum height of the object @o to @h. If the
+ * Sets the maximum height of the object @a o to @a h. If the
* current height or minimum width are less than the new maximum, they are set
* to the new maximum height.
*/
@@ -742,10 +750,9 @@
/**
- * ewl_object_get_maximum_w - get the maximum width of an object
- * @o: the object to get the maximum width
- *
- * Returns the maximum width of the object @o.
+ * @param o: the object to get the maximum width
+ * @return Returns the maximum width of the object.
+ * @brief Get the maximum width of an object
*/
inline unsigned int ewl_object_get_maximum_w(Ewl_Object * o)
{
@@ -765,10 +772,9 @@
/**
- * ewl_object_get_maximum_h - get the maximum height of an object
- * @o: the object to get the maximum height
- *
- * Returns the maximum height of the object @o.
+ * @param o: the object to get the maximum height
+ * @return Returns the maximum height of the object.
+ * @brief Get the maximum height of an object
*/
inline unsigned int ewl_object_get_maximum_h(Ewl_Object * o)
{
@@ -788,13 +794,14 @@
/**
- * ewl_object_get_maximum_size - retrieve the minimum dimensions of an object
- * @o: the object to retrieve the maximum dimensions
- * @w: a pointer to an integer to store the maximum width
- * @h: a pointer to an integer to store the maximum height
+ * @param o: the object to retrieve the maximum dimensions
+ * @param w: a pointer to an integer to store the maximum width
+ * @param h: a pointer to an integer to store the maximum height
+ * @return Returns no value.
+ * @brief Retrieve the minimum dimensions of an object
*
- * Returns no value. Stores the maximum height and width of object @o into the
- * integers pointed to by @w and @h respectively.
+ * Stores the maximum height and width of the object into the
+ * integers pointed to by @a w and @a h respectively.
*/
void
ewl_object_get_maximum_size(Ewl_Object * o, unsigned int *w, unsigned int *h)
@@ -812,14 +819,15 @@
}
/**
- * ewl_object_set_padding - set the padding around an objects edges
- * @o: the object to change the padding
- * @l: the new padding along the left side of the object
- * @r: the new padding along the right side of the object
- * @t: the new padding along the top side of the object
- * @b: the new padding along the bottom side of the object
+ * @param o: the object to change the padding
+ * @param l: the new padding along the left side of the object
+ * @param r: the new padding along the right side of the object
+ * @param t: the new padding along the top side of the object
+ * @param b: the new padding along the bottom side of the object
+ * @return Returns no value.
+ * @brief Set the padding around an objects edges
*
- * Returns no value. Stores the values of @l, @r, @t and @b into the object to
+ * Stores the values of @a l, @a r, @a t and @a b into the object to
* be used for distancing it's edges from other widgets when laying out.
*/
void ewl_object_set_padding(Ewl_Object * o, int l, int r, int t, int b)
@@ -849,15 +857,16 @@
}
/**
- * ewl_object_get_padding - retrieve the edge padding of an object
- * @o: the object to retrieve padding
- * @l: a pointer to an integer that will receive the padding of the left side
- * @r: a pointer to an integer that will receive the padding of the right side
- * @t: a pointer to an integer that will receive the padding of the top side
- * @b: a pointer to an integer that will receive the padding of the bottom side
+ * @param o: the object to retrieve padding
+ * @param l: a pointer to an integer that receives padding of the left side
+ * @param r: a pointer to an integer that receives padding of the right side
+ * @param t: a pointer to an integer that receives padding of the top side
+ * @param b: a pointer to an integer that receives padding of the bottom side
+ * @return Returns no value.
+ * @brief Retrieve the edge padding of an object
*
- * Returns no value. Stores the edge padding of the object @o into the integer
- * pointer parameters passed in.
+ * Stores the edge padding of the object @a o into the integer pointer
+ * parameters passed in.
*/
void ewl_object_get_padding(Ewl_Object * o, int *l, int *r, int *t, int *b)
{
@@ -877,10 +886,9 @@
}
/**
- * ewl_object_top_padding - get the top padding for the object
- * @o: the ewl object to retrieve the top padding
- *
- * Returns the top padding for the object @o.
+ * @param o: the ewl object to retrieve the top padding
+ * @return Returns the top padding for the object.
+ * @brief Get the top padding for the object
*/
int ewl_object_top_padding(Ewl_Object * o)
{
@@ -890,10 +898,9 @@
}
/**
- * ewl_object_bottom_padding - get the bottom padding for the object
- * @o: the ewl object to retrieve the bottom padding
- *
- * Returns the bottom padding for the object @o.
+ * @param o: the ewl object to retrieve the bottom padding
+ * @return Returns the bottom padding for the object.
+ * @brief Get the bottom padding for the object
*/
int ewl_object_bottom_padding(Ewl_Object * o)
{
@@ -903,10 +910,9 @@
}
/**
- * ewl_object_left_padding - get the left padding for the object
- * @o: the ewl object to retrieve the left padding
- *
- * Returns the left padding for the object @o.
+ * @param o: the ewl object to retrieve the left padding
+ * @return Returns the left padding for the object.
+ * @brief Get the left padding for the object
*/
int ewl_object_left_padding(Ewl_Object * o)
{
@@ -916,10 +922,9 @@
}
/**
- * ewl_object_right_padding - get the right padding for the object
- * @o: the ewl object to retrieve the right padding
- *
- * Returns the right padding for the object @o.
+ * @param o: the ewl object to retrieve the right padding
+ * @return Returns the right padding for the object.
+ * @brief Get the right padding for the object
*/
int ewl_object_right_padding(Ewl_Object * o)
{
@@ -930,14 +935,15 @@
/**
- * ewl_object_set_insets - set the insets around an objects edges
- * @o: the object to change the insets
- * @l: the new insets along the left side of the object
- * @r: the new insets along the right side of the object
- * @t: the new insets along the top side of the object
- * @b: the new insets along the bottom side of the object
+ * @param o: the object to change the insets
+ * @param l: the new insets along the left side of the object
+ * @param r: the new insets along the right side of the object
+ * @param t: the new insets along the top side of the object
+ * @param b: the new insets along the bottom side of the object
+ * @return Returns no value.
+ * @brief Set the insets around an objects edges
*
- * Returns no value. Stores the values of @l, @r, @t and @b into the object to
+ * Stores the values of @a l, @a r, @a t and @a b into the object to
* be used for distancing it's edges from other widgets when laying out.
*/
void ewl_object_set_insets(Ewl_Object * o, int l, int r, int t, int b)
@@ -967,15 +973,16 @@
}
/**
- * ewl_object_get_insets - retrieve the edge insets of an object
- * @o: the object to retrieve insets
- * @l: a pointer to an integer that will receive the insets of the left side
- * @r: a pointer to an integer that will receive the insets of the right side
- * @t: a pointer to an integer that will receive the insets of the top side
- * @b: a pointer to an integer that will receive the insets of the bottom side
+ * @param o: the object to retrieve insets
+ * @param l: a pointer to an integer that receives the insets of the left side
+ * @param r: a pointer to an integer that receives the insets of the right side
+ * @param t: a pointer to an integer that receives the insets of the top side
+ * @param b: a pointer to an integer that receives the insets of the bottom side
+ * @return Returns no value.
+ * @brief Retrieve the edge insets of an object
*
- * Returns no value. Stores the edge insets of the object @o into the integer
- * pointer parameters passed in.
+ * Stores the edge insets of the object @a o into the integer pointer parameters
+ * passed in.
*/
void ewl_object_get_insets(Ewl_Object * o, int *l, int *r, int *t, int *b)
{
@@ -995,10 +1002,9 @@
}
/**
- * ewl_object_top_insets - get the top insets for the object
- * @o: the ewl object to retrieve the top insets
- *
- * Returns the top insets for the object @o.
+ * @param o: the ewl object to retrieve the top insets
+ * @return Returns the top insets for the object.
+ * @brief Get the top insets for the object
*/
int ewl_object_top_insets(Ewl_Object * o)
{
@@ -1009,10 +1015,9 @@
}
/**
- * ewl_object_bottom_insets - get the bottom insets for the object
- * @o: the ewl object to retrieve the bottom insets
- *
- * Returns the bottom insets for the object @o.
+ * @param o: the ewl object to retrieve the bottom insets
+ * @return Returns the bottom insets for the object.
+ * @brief Get the bottom insets for the object
*/
int ewl_object_bottom_insets(Ewl_Object * o)
{
@@ -1023,10 +1028,9 @@
}
/**
- * ewl_object_left_insets - get the left insets for the object
- * @o: the ewl object to retrieve the left insets
- *
- * Returns the left insets for the object @o.
+ * @param o: the ewl object to retrieve the left insets
+ * @return Returns the left insets for the object.
+ * @brief Get the left insets for the object
*/
int ewl_object_left_insets(Ewl_Object * o)
{
@@ -1037,10 +1041,9 @@
}
/**
- * ewl_object_right_insets - get the right insets for the object
- * @o: the ewl object to retrieve the right insets
- *
- * Returns the right insets for the object @o.
+ * @param o: the ewl object to retrieve the right insets
+ * @return Returns the right insets for the object.
+ * @brief Get the right insets for the object
*/
int ewl_object_right_insets(Ewl_Object * o)
{
@@ -1051,11 +1054,12 @@
}
/**
- * ewl_object_set_alignment - change the alignment of the specified object
- * @o: the object to change alignment
- * @align: the new alignment for the object
+ * @param o: the object to change alignment
+ * @param align: the new alignment for the object
+ * @return Returns no value.
+ * @brief Change the alignment of the specified object
*
- * Returns no value. Stores the new alignment value into the object for use
+ * Stores the new alignment value into the object for use
* when laying out the object.
*/
inline void ewl_object_set_alignment(Ewl_Object * o, Ewl_Alignment align)
@@ -1074,14 +1078,15 @@
}
/**
- * ewl_object_place - assign a specific area to an object
- * @o: the object to place
- * @x: the x coordinate of the available area
- * @y: the y coordinate of the available area
- * @w: the width of the available area
- * @h: the height of the available area
+ * @param o: the object to place
+ * @param x: the x coordinate of the available area
+ * @param y: the y coordinate of the available area
+ * @param w: the width of the available area
+ * @param h: the height of the available area
+ * @return Returns no value.
+ * @brief Assign a specific area to an object
*
- * Returns no value. Attempts to fill the object to the specified area, aligns
+ * Attempts to fill the object to the specified area, aligns
* the object within that area.
*/
void
@@ -1123,12 +1128,13 @@
}
/**
- * ewl_object_set_fill_policy - change the fill policy of the specified object
- * @o: the object to change fill policy
- * @fill: the new fill policy for the object
+ * @param o: the object to change fill policy
+ * @param fill: the new fill policy for the object
+ * @return Returns no value.
+ * @brief Change the fill policy of the specified object
*
- * Returns no value. Stores the new fill policy value into the object for use
- * when laying out the object.
+ * Stores the new fill policy value into the object for use when laying out
+ * the object.
*/
inline void ewl_object_set_fill_policy(Ewl_Object * o, Ewl_Fill_Policy fill)
{
@@ -1181,10 +1187,10 @@
}
/**
- * ewl_object_get_alignment - retrieve the value of the objects alignment
- * @o: the object to retrieve the alignment value
+ * @param o: the object to retrieve the alignment value
+ * @return Returns the value stored in the objects alignment attribute.
+ * @brief Retrieve the value of the objects alignment
*
- * Returns the value stored in the objects alignment attribute.
*/
inline Ewl_Alignment ewl_object_get_alignment(Ewl_Object * o)
{
@@ -1197,10 +1203,9 @@
/**
- * ewl_object_get_fill_policy - retrieve the value of the objects fill policy
- * @o: the object to retrieve the fill policy value
- *
- * Returns the value stored in the objects fill policy attribute.
+ * @param o: the object to retrieve the fill policy value
+ * @return Returns the value stored in the objects fill policy attribute.
+ * @brief Retrieve the value of the objects fill policy
*/
inline Ewl_Fill_Policy ewl_object_get_fill_policy(Ewl_Object * o)
{
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_object.h,v
retrieving revision 1.30
retrieving revision 1.31
diff -u -3 -r1.30 -r1.31
--- ewl_object.h 30 Apr 2003 15:43:55 -0000 1.30
+++ ewl_object.h 27 Aug 2003 06:27:52 -0000 1.31
@@ -1,37 +1,92 @@
#ifndef __EWL_OBJECT_H__
#define __EWL_OBJECT_H__
+/**
+ * @file ewl_object.h
+ * @brief Defines the Ewl_Object class along with methods and macros related
+ * to it.
+ */
+
+/**
+ * @def EWL_OBJECT_MIN_SIZE The minimum possible size any object can receive.
+ */
#define EWL_OBJECT_MIN_SIZE 1
+/**
+ * @def EWL_OBJECT_MIN_SIZE The maximum possible size any object can receive.
+ */
#define EWL_OBJECT_MAX_SIZE 1 << 30
-typedef struct _ewl_object Ewl_Object;
-
+/**
+ * The base class inherited by all widgets. Provides methods for size and
+ * position.
+ */
+typedef struct Ewl_Object Ewl_Object;
+
+/**
+ * @def EWL_OBJECT(object) A typecast for accessing the inherited object
+ * fields.
+ */
#define EWL_OBJECT(object) ((Ewl_Object *) object)
-struct _ewl_object
+/**
+ * @struct Ewl_Object
+ * @brief Provides facilities for sizing, position, alignment and fill policy.
+ *
+ * The fields of the object, while their explanations are fairly clear, can be
+ * visualized with the following diagram:
+ *
+ * @image html object_fields.png
+ *
+ * The CURRENT_W(w) and CURRENT_H(w) are macros that provide easy access to the
+ * data fields describing the internal area of the Ewl_Object. While the
+ * functions ewl_object_get_current_w(w) and ewl_object_get_current_h(w) are
+ * to access the overall size of the area this Ewl_Object resides in. There
+ * are corresponding macros and functions for preferred, minimum and maximum
+ * sizes as well. There are also functions for setting each of these values.
+ *
+ * The affect of the fields when performing layout is as follows:
+ *
+ * @image html object_sizing.png
+ *
+ * As illustrated, the fill policy determines how much space an object will
+ * use when the request for a specific size is made. When the fill policy
+ * contains EWL_FILL_POLICY_HSHRINK, EWL_FILL_POLICY_VSHRINK or both, the
+ * Ewl_Object can be resized down to it's minimum size in width, height or both
+ * respectively.
+ *
+ * The opposite is true for a fill policy containing EWL_FILL_POLICY_HFILL,
+ * EWL_FILL_POLICY_VFILL or both, The Ewl_Object will now expand to fill the
+ * space up to it's maximum size in the respective direction.
+ */
+struct Ewl_Object
{
struct
{
- int x, y;
- unsigned int w, h;
- } current;
+ int x, /**< Horizontal position */
+ y; /**< Vertical position */
+ unsigned int w, /**< Width */
+ h; /**< Height */
+ } current; /**< The current size and position of an object. */
struct
{
- unsigned int w, h;
- } preferred, maximum, minimum;
+ unsigned int w, /**< Width */
+ h; /**< Height */
+ }
+ preferred, /**< The optimal size of the object in ideal circumstances */
+ maximum, /**< The guaranteed maximum size this object will receive. */
+ minimum; /**< The guaranteed minimum size this object will receive. */
- /*
- * pad refers to the space padded around the outside of the widget.
- * insets refers to the space padded inside the widget where children
- * should not be laid out.
- */
struct
{
- int l, r, t, b;
- } pad, insets;
+ int l, /**< Left value */
+ r, /**< Right value */
+ t, /**< Top value */
+ b; /**< Bottom value */
+ } pad, /**< The space padded around the outside of the object. */
+ insets; /**< The space inside where children should not be laid out. */
- unsigned int flags;
+ unsigned int flags; /**< Bitmask indicating fill policy and alignment */
};
void ewl_object_init(Ewl_Object * o);
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_widget.c,v
retrieving revision 1.67
retrieving revision 1.68
diff -u -3 -r1.67 -r1.68
--- ewl_widget.c 25 Aug 2003 19:40:43 -0000 1.67
+++ ewl_widget.c 27 Aug 2003 06:27:52 -0000 1.68
@@ -48,11 +48,13 @@
static inline void __ewl_widget_cleanup_fx_clip(Ewl_Widget *w);
/**
- * ewl_widget_init - initialize a widgets to default values and callbacks
- * @w: the widget to initialize
- * @appearance: the key for the widgets theme appearance
+ * @param w: the widget to initialize
+ * @param appearance: the key for the widgets theme appearance
*
- * Returns no value. The widget @w is initialized to default values and is
+ * @return No value.
+ * @brief Initialize a widget to default values and callbacks
+ *
+ * The widget w is initialized to default values and is
* assigned the default callbacks. The appearance key is assigned for easy
* access to theme information.
*/
@@ -116,11 +118,12 @@
}
/**
- * ewl_widget_realize - realize the specified widget
- * @w: the widget to realize
+ * @param w: the widget to realize
+ * @return Returns no value.
+ * @brief Realize the specified widget.
+ *
*
- * Returns no value. The specified widget is realized (ie. actually displayed to
- * the screen).
+ * The specified widget is realized, ie. actually displayed to the screen.
*/
void ewl_widget_realize(Ewl_Widget * w)
{
@@ -132,7 +135,7 @@
w->flags |= EWL_FLAGS_REALIZED;
- if (w->parent && !REALIZED(w->parent))
+ f (w->parent && !REALIZED(w->parent))
ewl_widget_realize(w->parent);
ewl_callback_call(w, EWL_CALLBACK_REALIZE);
@@ -142,11 +145,11 @@
}
/**
- * ewl_widget_unrealize - unrealize the specified widget
- * @w: the widget to unrealize
+ * @param w: the widget to unrealize
+ * @return Returns no value.
+ * @brief Unrealize the specified widget
*
- * Returns no value. The specified widget is unrealized (ie. no longer
- * displayed to the screen).
+ * The specified widget is unrealized, ie. no longer displayed to the screen.
*/
void ewl_widget_unrealize(Ewl_Widget * w)
{
@@ -164,11 +167,12 @@
}
/**
- * ewl_widget_show - mark a widget as visible
- * @w: the widget to be marked as visible
+ * @param w: the widget to be marked as visible
+ * @return Returns no value.
+ * @brief mark a widget as visible
*
- * Returns no value. Marks the widget as visible so that it will be displayed
- * the next time through the rendering loop.
+ * Marks the widget as visible so that it will be displayed the next time
+ * through the rendering loop.
*/
void ewl_widget_show(Ewl_Widget * w)
{
@@ -194,11 +198,12 @@
/**
- * ewl_widget_hide - mark a widget as invisible
- * @w: the widget to be marked as invisible
+ * @param w: the widget to be marked as invisible
+ * @return Returns no value.
+ * @brief Mark a widget as invisible
*
- * Returns no value. Marks the widget as invisible so that it will not be
- * displayed the next time through the rendering loop.
+ * Marks the widget as invisible so that it will not be displayed the next time
+ * through the rendering loop.
*/
void ewl_widget_hide(Ewl_Widget * w)
{
@@ -222,11 +227,12 @@
}
/**
- * ewl_widget_destroy - destroy the specified widget
- * @w: the widget to be destroyed
+ * @param w: the widget to be destroyed
+ * @return Returns no value.
+ * @brief Destroy the specified widget
*
- * Returns no value. The widget calls it's destroy callback to do any clean up
- * necessary and then free's the widget.
+ * The widget calls it's destroy callback to do any clean up necessary and then
+ * free's the widget.
*/
void ewl_widget_destroy(Ewl_Widget * w)
{
@@ -256,11 +262,12 @@
/**
- * ewl_widget_configure - initiate configuring of the specified widget
- * @w: the widget to configure
+ * @param w: the widget to configure
+ * @return Returns no value.
+ * @brief Initiate configuring of the specified widget
*
- * Returns no value. The configure callback is triggered for the specified
- * widget, this should adjust the widgets size and position.
+ * The configure callback is triggered for the specified widget, this should
+ * adjust the widgets size and position.
*/
void ewl_widget_configure(Ewl_Widget * w)
{
@@ -276,11 +283,12 @@
}
/**
- * ewl_widget_theme_update - initiate theme update of the specified widget
- * @w: the widget to update the theme
+ * @param w: the widget to update the theme
+ * @return Returns no value.
+ * @brief Initiate theme update of the specified widget
*
- * Returns no value. The theme update callback is triggered for the specified
- * widget, this should adjust the widgets appearance.
+ * The theme update callback is triggered for the specified widget, this should
+ * adjust the widgets appearance.
*/
void ewl_widget_theme_update(Ewl_Widget * w)
{
@@ -297,11 +305,12 @@
/**
- * ewl_widget_reparent - initiate reparent of the specified widget
- * @w: the widget to reparent
+ * @param w: the widget to reparent
+ * @return Returns no value.
+ * @brief initiate reparent of the specified widget
*
- * Returns no value. The reparent callback is triggered for the specified
- * widget, this should adjust the widgets attributes based on the new parent.
+ * The reparent callback is triggered for the specified widget, this should
+ * adjust the widgets attributes based on the new parent.
*/
void ewl_widget_reparent(Ewl_Widget * w)
{
@@ -314,13 +323,14 @@
}
/**
- * ewl_widget_set_data - attach the specified key / value pair to the widget
- * @w: the widget to own the key value pair
- * @k: the key that is associated with the data
- * @v: the data that is to be tracked
+ * @param w: the widget to own the key value pair
+ * @param k: the key that is associated with the data
+ * @param v: the data that is to be tracked
+ * @return Returns no value.
+ * @brief Attach the specified key / value pair to the widget
*
- * Returns no value. Assigns a key / value pair with @k as the key and @v as
- * the value to the specified widget @w.
+ * Assigns a key / value pair with k as the key and v as the value to the
+ * specified widget w.
*/
void ewl_widget_set_data(Ewl_Widget * w, void *k, void *v)
{
@@ -338,12 +348,12 @@
/**
- * ewl_widget_del_data - remove the specified key / value pair from the widget
- * @w: the widget that owns the key value pair
- * @k: the key that is associated with the data
+ * @param w: the widget that owns the key value pair
+ * @param k: the key that is associated with the data
+ * @return Returns no value.
+ * @brief Remove the specified key / value pair from the widget
*
- * Returns no value. Removes a key / value pair with @k as the key from the
- * specified widget @w.
+ * Removes a key / value pair with k as the key from the specified widget w.
*/
void ewl_widget_del_data(Ewl_Widget * w, void *k)
{
@@ -359,12 +369,12 @@
/**
- * ewl_widget_get_data - retrieve the specified key / value pair from the widget
- * @w: the widget that owns the key value pair
- * @k: the key that is associated with the data
+ * @param w: the widget that owns the key value pair
+ * @param k: the key that is associated with the data
+ * @return Returns the value associated with k on success, NULL on failure.
+ * @brief retrieve the specified key / value pair from the widget
*
- * Returns the value associated with @k on success, NULL on failure. Retrieves a
- * key / value pair with @k as the key from the specified widget @w.
+ * Retrieves a key / value pair with k as the key from the specified widget w.
*/
void *ewl_widget_get_data(Ewl_Widget * w, void *k)
{
@@ -379,12 +389,13 @@
}
/**
- * ewl_widget_set_appearance - change the appearance of the specified widget
- * @w: the widget to change the appearance
- * @appearance: the new key for the widgets appearance
+ * @param w: the widget to change the appearance
+ * @param appearance: the new key for the widgets appearance
+ * @return Returns no value.
+ * @brief Change the appearance of the specified widget
*
- * Returns no value. Changes the key associated with the widgets appearance
- * and calls the theme update callback to initiate the change.
+ * Changes the key associated with the widgets appearance and calls the theme
+ * update callback to initiate the change.
*/
void ewl_widget_set_appearance(Ewl_Widget * w, char *appearance)
{
@@ -407,10 +418,10 @@
}
/**
- * ewl_widget_get_appearance - retrieve the appearance key of the widget
- * @w: the widget to retrieve the appearance key
- *
- * Returns a pointer to the appearance key string on success, NULL on failure.
+ * @param w: the widget to retrieve the appearance key
+ * @return Returns a pointer to the appearance key string on success, NULL on
+ * failure.
+ * @brief Retrieve the appearance key of the widget
*/
char *ewl_widget_get_appearance(Ewl_Widget * w)
{
@@ -422,12 +433,13 @@
}
/**
- * ewl_widget_set_state - update the appearance of the widget to a state
- * @w: the widget to update the appearance
- * @state: the new state of the widget
+ * @param w: the widget to update the appearance
+ * @param state: the new state of the widget
+ * @return Returns no value.
+ * @brief Update the appearance of the widget to a state
*
- * Returns no value. Changes the appearance of the widget @w depending on the
- * state string passed by @state.
+ * Changes the appearance of the widget depending on the state string passed by
+ * the state parameter.
*/
void ewl_widget_set_state(Ewl_Widget * w, char *state)
{
@@ -448,13 +460,13 @@
}
/**
- * ewl_widget_set_parent - change the parent of the specified widget
- * @w: the widget to change the parent
- * @p: the new parent of the widget
- *
- * Returns no value. Changes the parent of the widget @w, to the container @p.
- * The reparent callback is triggered to notify children of @w of the change
- * in parent.
+ * @param w: the widget to change the parent
+ * @param p: the new parent of the widget
+ * @return Returns no value.
+ * @brief change the parent of the specified widget
+ *
+ * Changes the parent of the widget w, to the container p. The reparent
+ * callback is triggered to notify children of w of the change in parent.
*/
void ewl_widget_set_parent(Ewl_Widget * w, Ewl_Widget * p)
{
@@ -476,6 +488,13 @@
DLEAVE_FUNCTION(DLEVEL_STABLE);
}
+/**
+ * @param w: the widget to re-enable
+ * @return Returns no value.
+ * @brief Re-enable a disabled widget
+ *
+ * Re-enables a previously disabled widget.
+ */
void ewl_widget_enable(Ewl_Widget * w)
{
DENTER_FUNCTION(DLEVEL_STABLE);
@@ -491,6 +510,13 @@
DLEAVE_FUNCTION(DLEVEL_STABLE);
}
+/**
+ * @param w: the widget to disable
+ * @return Returns no value. Disables a specified widget.
+ * @brief Prevent a widget from receiving any events
+ *
+ * This prevents that widget from receiving any user input events.
+ */
void ewl_widget_disable(Ewl_Widget * w)
{
DENTER_FUNCTION(DLEVEL_STABLE);
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_widget.h,v
retrieving revision 1.30
retrieving revision 1.31
diff -u -3 -r1.30 -r1.31
--- ewl_widget.h 25 Aug 2003 19:40:43 -0000 1.30
+++ ewl_widget.h 27 Aug 2003 06:27:52 -0000 1.31
@@ -3,56 +3,46 @@
/**
* @file ewl_widget.h
- * Defines the widget class and it's accessor/modifier functions.
+ * Defines the Ewl_Widget class and it's accessor/modifier functions.
*/
-typedef struct _ewl_widget Ewl_Widget;
+/**
+ * The class that all widgets should inherit. Provides reference to a parent
+ * widget/container, callbacks, and appearance information.
+ */
+typedef struct Ewl_Widget Ewl_Widget;
+/**
+ * @def EWL_WIDGET(widget)
+ * @brief Typecast a pointer to an Ewl_Widget pointer.
+ */
#define EWL_WIDGET(widget) ((Ewl_Widget *) widget)
/**
* @struct Ewl_Widget
+ * The class inheriting from Ewl_Object that provides appearance, parent, and
+ * callback capabilities.
*/
-struct _ewl_widget
+struct Ewl_Widget
{
- /*
- * These fields are the basic information about how this widget
- * relates to others.
- */
- Ewl_Object object;
- Ewl_Widget *parent;
-
- /*
- * List of callbacks for this widget
- */
- Ewd_List *callbacks[EWL_CALLBACK_MAX];
-
- Evas_Object *fx_clip_box;
-
- Evas_Object *theme_object;
- char *bit_state;
- char *appearance;
- int layer;
-
- /**
- * And these are for keeping track of the appearance, behavior
- * states of the widget and the data attached to the widget.
- */
- Ewl_State state;
- Ewd_Hash *theme;
- Ewd_Hash *data;
-
- /**
- * Flags for determining the current visibility of the widget as well
- * as if it has been realized
- */
- Ewl_Widget_Flags flags;
-};
+ Ewl_Object object; /**< Inherit the base Object class */
+ Ewl_Widget *parent; /**< The parent widget, actually a container */
-/*
- * Returns a allocated widget structure
- */
-Ewl_Widget *ewl_widget_new();
+ Ewd_List *callbacks[EWL_CALLBACK_MAX]; /**< Callback list array */
+
+ Evas_Object *fx_clip_box; /**< Clipping rectangle of widget */
+
+ Evas_Object *theme_object; /**< Appearance shown on canvas */
+ char *bit_state; /**< State of the appaarance */
+ char *appearance; /**< Key to lookup appearance in theme */
+ int layer; /**< Current layer of widget on canvas */
+
+ Ewl_State state; /**< Present widget state bitmask */
+ Ewd_Hash *theme; /**< Overriding theme settings of this widget */
+ Ewd_Hash *data; /**< Arbitrary data attached to this widget */
+
+ Ewl_Widget_Flags flags; /**< Bitmask indicating visibility and status */
+};
/*
* Initialize a widget to it's default values
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_window.c,v
retrieving revision 1.50
retrieving revision 1.51
diff -u -3 -r1.50 -r1.51
--- ewl_window.c 13 Jul 2003 05:52:49 -0000 1.50
+++ ewl_window.c 27 Aug 2003 06:27:52 -0000 1.51
@@ -20,9 +20,8 @@
int size, Ewl_Orientation o);
/**
- * ewl_window_new - allocate and initialize a new window
- *
- * Returns a new window on success, or NULL on failure.
+ * @return Returns a new window on success, or NULL on failure.
+ * @brief Allocate and initialize a new window
*/
Ewl_Widget *ewl_window_new()
{
@@ -44,11 +43,9 @@
}
/**
- * ewl_window_find_window - find an ewl window by it's X window
- * @window: the X window to search for on the list of ewl window's
- *
- * Returns the found ewl window on success, NULL on failure to find the
- * window.
+ * @param window: the X window to search for on the list of ewl window's
+ * @return Returns the found ewl window on success, NULL on failure.
+ * @brief Find an ewl window by it's X window
*/
Ewl_Window *ewl_window_find_window(Window window)
{
@@ -67,12 +64,13 @@
}
/**
- * ewl_window_set_title - set the title of the specified window
- * @win: the window to change the title
- * @title: the title to set for the window
+ * @param win: the window to change the title
+ * @param title: the title to set for the window
+ * @return Returns no value.
+ * @brief Set the title of the specified window
*
- * Returns no value. Sets the title of window @w to @title and calls the
- * necessary X lib functions to update the window.
+ * Sets the title of window @a w to @a title and calls the necessary X lib
+ * functions to update the window.
*/
void ewl_window_set_title(Ewl_Window * win, char *title)
{
@@ -93,10 +91,10 @@
}
/**
- * ewl_window_get_title - retrieve the title of the specified window
- * @win: the window to retrieve the window
+ * @param win: the window to retrieve the window
+ * @return Returns a pointer to a new copy of the title, NULL on failure.
+ * @brief Retrieve the title of the specified window
*
- * Returns a pointer to a newly allocated copy of the title, NULL on failure.
* The returned title should be freed.
*/
char *ewl_window_get_title(Ewl_Window * win)
@@ -108,11 +106,11 @@
}
/**
- * ewl_window_set_borderless - remove the border from the specified window
- * @win: the window to remove the border
- * @value: the boolean to indicate borderless settings
+ * @param win: the window to remove the border
+ * @return Returns no value.
+ * @brief Remove the border from the specified window
*
- * Returns no value. Remove the border from the specified widget and call the
+ * Remove the border from the specified widget and call the
* necessary X lib functions to update the appearance.
*/
void ewl_window_set_borderless(Ewl_Window * win)
@@ -129,12 +127,13 @@
}
/**
- * ewl_window_move - move the specified window to the given position
- * @win: the window to move
- * @x: the x coordinate of the new position
- * @y: the y coordinate of the new position
+ * @param win: the window to move
+ * @param x: the x coordinate of the new position
+ * @param y: the y coordinate of the new position
+ * @return Returns no value.
+ * @brief Move the specified window to the given position
*
- * Returns no value. Moves the window into the specified position in the
+ * Moves the window into the specified position in the
* window manager environment.
*/
void ewl_window_move(Ewl_Window * win, int x, int y)
@@ -149,11 +148,13 @@
}
/**
- * ewl_window_get_position - retrieve the position of the window
- * @x: a pointer to the integer that should receive the x coordinate
- * @y: a pointer to the integer that should receive the y coordinate
+ * @param win: the window to query for position
+ * @param x: a pointer to the integer that should receive the x coordinate
+ * @param y: a pointer to the integer that should receive the y coordinate
+ * @return Returns no value.
+ * @brief Retrieve the position of the window
*
- * Returns no value. Stores the window position into the parameters @x and @y.
+ * Stores the window position into the parameters @a x and @a y.
*/
void ewl_window_get_position(Ewl_Window * win, int *x, int *y)
{
@@ -169,11 +170,11 @@
}
/**
- * ewl_window_init - initialize a window to default values and callbacks
- * @w: the window to be initialized to default values and callbacks
+ * @param w: the window to be initialized to default values and callbacks
+ * @return Returns TRUE or FALSE depending on if initialization succeeds.
+ * @brief Initialize a window to default values and callbacks
*
- * Returns TRUE or FALSE depending on if initialization succeeds. Sets the
- * values and callbacks of a window @w to their defaults.
+ * Sets the values and callbacks of a window @a w to their defaults.
*/
int ewl_window_init(Ewl_Window * w)
{
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_window.h,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -3 -r1.20 -r1.21
--- ewl_window.h 13 Jul 2003 05:52:49 -0000 1.20
+++ ewl_window.h 27 Aug 2003 06:27:52 -0000 1.21
@@ -2,29 +2,43 @@
#ifndef __EWL_WINDOW_H__
#define __EWL_WINDOW_H__
-/*
+/**
+ * @file ewl_window.h
+ * Defines the Ewl_Window class which extends the Ewl_Embed class by creating
+ * it's own window and evas.
+ */
+
+/**
* The window structure is mostly a container for holding widgets and a
* wrapper around the xlib window.
*/
-typedef struct _ewl_window Ewl_Window;
+typedef struct Ewl_Window Ewl_Window;
+
+/**
+ * @def EWL_WINDOW(win)
+ * Typecasts a pointer to an Ewl_Window pointer.
+ */
+#define EWL_WINDOW(win) ((Ewl_Window *) win)
-struct _ewl_window
+/**
+ * @struct Ewl_Window
+ * Extends the Ewl_Embed class to create it's own window and evas for drawing,
+ * sizing and positioning.
+ */
+struct Ewl_Window
{
- Ewl_Embed embed;
+ Ewl_Embed embed; /**< Inherits from the Ewl_Embed class */
- Window window;
+ Window window; /**< Provides a window for drawing */
- char *title;
+ char *title; /**< The current title on the provided window */
- /*
- * Flag to indicate if the window has a border.
- */
- Ewl_Window_Flags flags;
+
+ Ewl_Window_Flags flags; /**< Flags indicating window properties */
- int x, y;
+ int x; /**< Screen relative horizontal position of window */
+ int y; /**< Screen relative vertical position of window */
};
-
-#define EWL_WINDOW(widget) ((Ewl_Window *) widget)
Ewl_Widget *ewl_window_new();
int ewl_window_init(Ewl_Window * win);
-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
http://thinkgeek.com/sf
_______________________________________________
enlightenment-cvs mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/enlightenment-cvs
