Enlightenment CVS committal
Author : rbdpngn
Project : e17
Module : libs/ewl
Dir : e17/libs/ewl/src
Modified Files:
ewl_checkbutton.c ewl_checkbutton.h ewl_macros.h ewl_spacer.c
ewl_spacer.h ewl_theme.c ewl_theme.h
Log Message:
More widget documentation.
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_checkbutton.c,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -3 -r1.33 -r1.34
--- ewl_checkbutton.c 28 Aug 2003 06:10:03 -0000 1.33
+++ ewl_checkbutton.c 29 Aug 2003 17:56:13 -0000 1.34
@@ -5,10 +5,9 @@
void *user_data);
/**
- * ewl_checkbutton_new - allocate and initialize a new check button
- * @label: the label to display with the checkbutton, NULL for no label
- *
- * Returns the newly allocated checkbutton on success, NULL on failure.
+ * @param label: the label to display with the checkbutton, NULL for no label
+ * @return Returns the newly allocated checkbutton on success, NULL on failure.
+ * @brief Allocate and initialize a new check button
*/
Ewl_Widget *ewl_checkbutton_new(char *label)
{
@@ -27,12 +26,13 @@
}
/**
- * ewl_checkbutton_init - initialize the members and callbacks of a check button
- * @cb: the check button to initialize
- * @label: the label to give the initialized check button
+ * @param cb: the check button to initialize
+ * @param label: the label to give the initialized check button
+ * @return Returns no value.
+ * @brief Initialize the members and callbacks of a check button
*
- * Returns no vlalue.The internal structures and callbacks of the checkbutton
- * are initialized ot default values.
+ * The internal structures and callbacks of the checkbutton are initialized to
+ * default values.
*/
void ewl_checkbutton_init(Ewl_CheckButton * cb, char *label)
{
@@ -65,12 +65,12 @@
}
/**
- * ewl_checkbutton_set_label_position - set the check buttons label position
- * @w: the widget to change the label positioning
- * @p: the new position of the label
+ * @param w: the widget to change the label positioning
+ * @param p: the new position of the label
+ * @return Returns no value.
+ * @brief Set the check buttons label position
*
- * Returns no value. Changes the position of the label associated with the
- * check button.
+ * Changes the position of the label associated with the check button.
*/
void ewl_checkbutton_set_label_position(Ewl_Widget * w, Ewl_Position p)
{
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_checkbutton.h,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -3 -r1.13 -r1.14
--- ewl_checkbutton.h 25 May 2002 05:46:40 -0000 1.13
+++ ewl_checkbutton.h 29 Aug 2003 17:56:13 -0000 1.14
@@ -1,33 +1,37 @@
-/*
- * The button class is a basic button with a label. This class is inherited by
- * the check button and radio button classes.
- */
-
#ifndef __EWL_CHECKBUTTON_H__
#define __EWL_CHECKBUTTON_H__
-typedef struct _ewl_checkbutton Ewl_CheckButton;
+/**
+ * @file ewl_checkbutton.h
+ * @brief Defines an Ewl_CheckButton that inherits from Ewl_Widget and
+ * provides an Ewl_Check that changes value on each click.
+ */
+
+/**
+ * The button class is a basic button with a label. This class is inherited by
+ * the check button and radio button classes.
+ */
+typedef struct Ewl_CheckButton Ewl_CheckButton;
+/**
+ * @def EWL_CHECKBUTTON(button)
+ * Typecasts a pointer to an Ewl_CheckButton pointer.
+ */
#define EWL_CHECKBUTTON(button) ((Ewl_CheckButton *) button)
-struct _ewl_checkbutton {
+/**
+ * @struct Ewl_CheckButton
+ * Inherits from Ewl_Widget and expands to provide a stateful check button.
+ */
+struct Ewl_CheckButton
+{
+ Ewl_Button button; /**< Inherit the basic button properties */
+
+
+ Ewl_Position label_position; /**< Order of label and check */
- /*
- * Inherit the basic button properties
- */
- Ewl_Button button;
-
- /*
- * Label positition determines packing order of the label and the
- * check
- */
- Ewl_Position label_position;
-
- /*
- * Public references to the check and label widgets.
- */
- Ewl_Widget *check;
+ Ewl_Widget *check; /**< Check widget represented */
};
Ewl_Widget *ewl_checkbutton_new(char *l);
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_macros.h,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -3 -r1.15 -r1.16
--- ewl_macros.h 25 May 2002 05:46:40 -0000 1.15
+++ ewl_macros.h 29 Aug 2003 17:56:13 -0000 1.16
@@ -1,17 +1,25 @@
-/*\
-|*|
-|*| Convension macros used to provide some debug information.
-|*|
-\*/
-
#ifndef __EWL_MACROS_H__
#define __EWL_MACROS_H__
+/**
+ * @file ewl_macros.h
+ * Defines a variety of utility macros.
+ */
+
#undef NEW
-#define NEW(dat, num) malloc(sizeof(dat) * (num));
+/**
+ * @def NEW(type, num)
+ * Allocates memory of @a num elements of sizeof(@a type).
+ */
+#define NEW(type, num) malloc(sizeof(type) * (num));
#undef REALLOC
+/**
+ * @def REALLOC(dat, type, num)
+ * Reallocates memory pointed to by @a dat to @a num elements of sizeof(@a
+ * type).
+ */
#define REALLOC(dat, type, num) \
{ \
if (dat) \
@@ -21,6 +29,10 @@
}
#undef FREE
+/**
+ * @def FREE(dat)
+ * Free the data pointed to by @a dat and it to NULL.
+ */
#define FREE(dat) \
{ \
free(dat); dat = NULL; \
@@ -28,12 +40,21 @@
#undef IF_FREE
+/**
+ * @def IF_FREE(dat)
+ * If @a dat is non-NULL, free @a dat and assign it to NULL.
+ */
#define IF_FREE(dat) \
{ \
- if (dat) free(dat); dat = NULL; \
+ if (dat) FREE(dat); \
}
#undef ZERO
-#define ZERO(ptr, dat, num) ptr = memset(ptr, 0, sizeof(dat) * (num))
+/**
+ * @def ZERO(ptr, type, num)
+ * Set the first @a num elements of sizeof(@a type) pointed to by @a ptr to
+ * zero.
+ */
+#define ZERO(ptr, type, num) ptr = memset(ptr, 0, sizeof(type) * (num))
#endif /* __EWL_MACROS_H__ */
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_spacer.c,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -3 -r1.2 -r1.3
--- ewl_spacer.c 14 Jan 2003 21:45:04 -0000 1.2
+++ ewl_spacer.c 29 Aug 2003 17:56:13 -0000 1.3
@@ -2,9 +2,8 @@
#include <Ewl.h>
/**
- * ewl_spacer_new - allocate and initialize a new spacer
- *
- * Returns NULL on failure, a pointer to a new spacer on success
+ * @return Returns NULL on failure, a pointer to a new spacer on success
+ * @brief Allocate and initialize a new spacer
*/
Ewl_Widget *ewl_spacer_new()
{
@@ -23,11 +22,11 @@
}
/**
- * ewl_spacer_init - initialize a spacer to starting values
- * @b: the spacer to initialize
- * @label: set the label of the spacer @b to @label
+ * @param s: the spacer to initialize
+ * @return Returns no value.
+ * @brief Initialize a spacer to starting values
*
- * Returns no value. Initializes a spacer to default values and callbacks.
+ * Initializes a spacer to default values and callbacks.
*/
void ewl_spacer_init(Ewl_Spacer * s)
{
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_spacer.h,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -3 -r1.1 -r1.2
--- ewl_spacer.h 15 Aug 2002 00:33:12 -0000 1.1
+++ ewl_spacer.h 29 Aug 2003 17:56:13 -0000 1.2
@@ -1,14 +1,31 @@
-/*
- * The spacer class is a simple widget that has no visible parts, it is used
- * to tweak spacing in an app.
- */
-
#ifndef __EWL_SPACER_H__
#define __EWL_SPACER_H__
-typedef Ewl_Widget Ewl_Spacer;
+/**
+ * @file ewl_spacer.h
+ */
+
+/**
+ * The Ewl_Spacer is a simple widget that is used to tweak spacing in an app.
+ */
+typedef struct Ewl_Spacer Ewl_Spacer;
+
+/**
+ * @struct Ewl_Spacer
+ * Inherits from Ewl_Widget, and does not provide any further functionality,
+ * it is intended to be themed as transparent, and used to tweak spacing in an
+ * application.
+ */
+struct Ewl_Spacer
+{
+ Ewl_Widget widget; /**< Inherit from Ewl_Widget */
+};
+/**
+ * @def EWL_SPACER(spacer)
+ * Typecasts a pointer to an Ewl_Spacer pointer.
+ */
#define EWL_SPACER(spacer) ((Ewl_Spacer *) spacer)
Ewl_Widget *ewl_spacer_new();
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_theme.c,v
retrieving revision 1.44
retrieving revision 1.45
diff -u -3 -r1.44 -r1.45
--- ewl_theme.c 13 Jul 2003 05:52:49 -0000 1.44
+++ ewl_theme.c 29 Aug 2003 17:56:13 -0000 1.45
@@ -12,11 +12,16 @@
static Ewd_Hash *cached_theme_data = NULL;
static Ewd_Hash *def_theme_data = NULL;
+void __ewl_theme_init_font_path(void);
+
/**
- * ewl_theme_init - initialize the themeing system
+ * @return Returns TRUE on success, FALSE on failure.
+ * @brief Initialize the themeing system
*
- * Returns TRUE on success, FALSE on failure. Initializes the data structures
- * involved with theme handling. This involves finding the specified theme file. */
+ * Initializes the data structures involved with theme handling. Involves
+ * finding the specified theme file. This is called by ewl_init, and is not
+ * necessary for the end programmer to call.
+ */
int ewl_theme_init(void)
{
struct stat st;
@@ -77,19 +82,18 @@
}
}
- ewl_theme_init_font_path();
+ __ewl_theme_init_font_path();
IF_FREE(theme_name);
DRETURN_INT(TRUE, DLEVEL_STABLE);
}
-/**
- * ewl_theme_init_font_path - initialize the font path from the theme
- *
- * Returns no value. Initializes the font path based on the theme.
+/*
+ * Initializes the font path based on the theme. Also called by ewl_init, and
+ * is not recommended to be called separately.
*/
-void ewl_theme_init_font_path()
+void __ewl_theme_init_font_path()
{
char *font_path;
char key[PATH_MAX];
@@ -117,11 +121,11 @@
}
/**
- * ewl_theme_init_widget - initialize a widgets theme information to the default
- * @w: the widget to initialize theme information
+ * @param w: the widget to initialize theme information
+ * @return Returns no value.
+ * @brief Initialize a widgets theme information to the default
*
- * Returns no value. Sets the widget @w's theme information to the default
- * values.
+ * Sets the widget @a w's theme information to the default values.
*/
void ewl_theme_init_widget(Ewl_Widget * w)
{
@@ -134,11 +138,11 @@
}
/**
- * ewl_theme_deinit_widget - remove the theme information from a widget
- * @w: the widget to remove theme information
+ * @param w: the widget to remove theme information
+ * @return Returns no value.
+ * @brief remove the theme information from a widget
*
- * Returns no value. Removes and frees (if not default) the theme information
- * from the widget @w.
+ * Removes and frees the theme information from the widget @a w.
*/
void ewl_theme_deinit_widget(Ewl_Widget * w)
{
@@ -158,17 +162,18 @@
DLEAVE_FUNCTION(DLEVEL_STABLE);
}
-/* Return the path of the current theme */
+/*
+ * @brief Return the path of the current theme
+ * @return Returns a copy of the current theme path on success, NULL on failure
+ */
char *ewl_theme_path()
{
DRETURN_PTR(strdup(theme_path), DLEVEL_STABLE);
}
/**
- * ewl_theme_font_path - retrieve the path of a widgets theme's fonts
- * @w: the widget to search
- *
- * Returns the font path associated with widget @w on success, NULL on failure.
+ * @return Returns the font path of widget @a w on success, NULL on failure.
+ * @brief retrieve the path of a widgets theme's fonts
*/
Ewd_List *ewl_theme_font_path_get()
{
@@ -178,10 +183,11 @@
}
/**
- * ewl_theme_font_path_add - add a specified path to the font search path
- * @path: the font to add to the search path
+ * @param path: the font to add to the search path
+ * @return Returns no value.
+ * @brief Add a specified path to the font search path
*
- * Returns no value. Duplicates the string pointed to by @path and adds it to
+ * Duplicates the string pointed to by @a path and adds it to
* the list of paths that are searched for fonts.
*/
void ewl_theme_font_path_add(char *path)
@@ -200,11 +206,10 @@
}
/**
- * ewl_theme_image_get - retrieve the path to an image from a widgets theme
- * @w: the widget to search
- * @k: the image to search for
- *
- * Returns the path associated with image key @k on success, NULL on failure.
+ * @param w: the widget to search
+ * @param k: the image to search for
+ * @return Returns the path of image key @a k on success, NULL on failure.
+ * @brief retrieve the path to an image from a widgets theme
*/
char *ewl_theme_image_get(Ewl_Widget * w, char *k)
{
@@ -238,11 +243,10 @@
/**
- * ewl_theme_data_get_str - retrieve an string value from a widgets theme
- * @w: the widget to search
- * @k: the key to search for
- *
- * Returns the string associated with key @k on success, NULL on failure.
+ * @param w: the widget to search
+ * @param k: the key to search for
+ * @return Returns the string associated with @a k on success, NULL on failure.
+ * @brief Retrieve an string value from a widgets theme
*/
char *ewl_theme_data_get_str(Ewl_Widget * w, char *k)
{
@@ -284,11 +288,10 @@
}
/**
- * ewl_theme_data_get_int - retrieve an integer value from a widgets theme
- * @w: the widget to search
- * @k: the key to search for
- *
- * Returns the integer associated with key @k on success, 0 on failure.
+ * @param w: the widget to search
+ * @param k: the key to search for
+ * @return Returns the integer associated with key @a k on success, 0 on failure.
+ * @brief Retrieve an integer value from a widgets theme
*/
int ewl_theme_data_get_int(Ewl_Widget * w, char *k)
{
@@ -314,13 +317,14 @@
}
/**
- * ewl_theme_data_set_str - store data into a widgets theme
- * @w: the widget to change theme data
- * @k: the key to change
- * @v: the data to assign to the key
+ * @param w: the widget to change theme data
+ * @param k: the key to change
+ * @param v: the data to assign to the key
+ * @return Returns no value.
+ * @brief Store data into a widgets theme
*
- * Returns no value. Changes the theme data in widget @w so that key @k now is
- * associated with value @v.
+ * Changes the theme data in widget @a w so that key @a k now is
+ * associated with value @a v.
*/
void ewl_theme_data_set_str(Ewl_Widget * w, char *k, char *v)
{
@@ -342,13 +346,14 @@
}
/**
- * ewl_theme_data_set_int - store data into a widgets theme
- * @w: the widget to change theme data
- * @k: the key to change
- * @v: the data to assign to the key
+ * @param w: the widget to change theme data
+ * @param k: the key to change
+ * @param v: the data to assign to the key
+ * @return Returns no value.
+ * @brief Store data into a widgets theme
*
- * Returns no value. Changes the theme data in widget @w so that key @k now is
- * associated with value @v.
+ * Changes the theme data in widget @a w so that key @a k now is
+ * associated with value @a v.
*/
void ewl_theme_data_set_int(Ewl_Widget * w, char *k, int v)
{
@@ -367,12 +372,13 @@
}
/**
- * ewl_theme_data_set_default_str - set a theme key to a default value
- * @k: the key to be set
- * @v: the value to set for the key
+ * @param k: the key to be set
+ * @param v: the value to set for the key
+ * @return Returns no value.
+ * @brief Set a theme key to a default value
*
- * Returns no value. Sets the data associated with key @k to value @v in the
- * default theme data.
+ * Sets the data associated with key @a k to value @a v in the default theme
+ * data.
*/
void ewl_theme_data_set_default_str(char *k, char *v)
{
@@ -384,11 +390,12 @@
}
/**
- * ewl_theme_data_set_default_int - set a theme key to a default value
- * @k: the key to be set
- * @v: the value to set for the key
+ * @param k: the key to be set
+ * @param v: the value to set for the key
+ * @return Returns no value.
+ * @brief Set a theme key to a default value
*
- * Returns no value. Sets the data associated with key @k to value @v in the
+ * Sets the data associated with key @a k to value @a v in the
* default theme data.
*/
void ewl_theme_data_set_default_int(char *k, int v)
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_theme.h,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -3 -r1.15 -r1.16
--- ewl_theme.h 14 Jan 2003 21:45:06 -0000 1.15
+++ ewl_theme.h 29 Aug 2003 17:56:13 -0000 1.16
@@ -2,8 +2,13 @@
#ifndef __EWL_THEME_H__
#define __EWL_THEME_H__
+/**
+ * @file ewl_theme.h
+ * Provides methods for accessing theme data, global theme data or per-widget
+ * theme data.
+ */
+
int ewl_theme_init(void);
-void ewl_theme_init_font_path(void);
void ewl_theme_init_widget(Ewl_Widget * w);
void ewl_theme_deinit_widget(Ewl_Widget * w);
char *ewl_theme_path(void);
-------------------------------------------------------
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
