Enlightenment CVS committal
Author : rbdpngn
Project : e17
Module : libs/ewl
Dir : e17/libs/ewl/src
Modified Files:
ewl_seeker.c ewl_seeker.h ewl_spacer.h ewl_tree.c ewl_tree.h
Log Message:
More widget docs.
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_seeker.c,v
retrieving revision 1.41
retrieving revision 1.42
diff -u -3 -r1.41 -r1.42
--- ewl_seeker.c 25 Aug 2003 19:40:42 -0000 1.41
+++ ewl_seeker.c 31 Aug 2003 02:59:46 -0000 1.42
@@ -21,11 +21,9 @@
/**
- * ewl_seeker_new - allocate and initialize a new seeker with orientation
- *
- * @o: the orientation for the new seeker
- *
- * Returns NULL on failure, or a pointer to the new seeker on success.
+ * @param o: the orientation for the new seeker
+ * @return Returns NULL on failure, or a pointer to the new seeker on success.
+ * @brief Allocate and initialize a new seeker with orientation
*/
Ewl_Widget *ewl_seeker_new(Ewl_Orientation o)
{
@@ -46,12 +44,13 @@
/**
- * ewl_seeker_init - initialize the seeker to some sane starting values
- * @s: the seeker to be initialized
- * @orientation: the orientation of the seeker
+ * @param s: the seeker to be initialized
+ * @param orientation: the orientation of the seeker
+ * @return Returns no value.
+ * @brief Initialize the seeker to some sane starting values
*
- * Returns no value. Initializes the seeker @s to the orientation @orientation
- * to default values and callbacks.
+ * Initializes the seeker @a s to the orientation @a orientation to default
+ * values and callbacks.
*/
void ewl_seeker_init(Ewl_Seeker * s, Ewl_Orientation orientation)
{
@@ -129,12 +128,11 @@
/**
- * ewl_seeker_set_value - set the value of pointer of the seekers locator
- *
- * @s: the seeker whose value will be changed
- * @v: the new value of the locator, it will be checked against the valid range
*
- * Returns no value.
+ * @param s: the seeker whose value will be changed
+ * @param v: the new value of the locator, checked against the valid range
+ * @return Returns no value.
+ * @brief Set the value of pointer of the seekers locator
*/
void ewl_seeker_set_value(Ewl_Seeker * s, double v)
{
@@ -160,11 +158,9 @@
/**
- * ewl_seeker_get_value - retrieve the current value of the seekers locator
- *
- * @s: the seekers to retrieve the value
- *
- * Returns 0 on failure, the value of the seekers locator on success.
+ * @param s: the seekers to retrieve the value
+ * @return Returns 0 on failure, the value of the seekers locator on success.
+ * @brief Retrieve the current value of the seekers locator
*/
double ewl_seeker_get_value(Ewl_Seeker * s)
{
@@ -176,12 +172,10 @@
/**
- * ewl_seeker_set_range - specify the range of values represented by the seeker
- *
- * @s: the seeker to change the range
- * @r: the largest bound on the range of the seekers value
- *
- * Returns no value.
+ * @param s: the seeker to change the range
+ * @param r: the largest bound on the range of the seekers value
+ * @return Returns no value.
+ * @brief specify the range of values represented by the seeker
*/
void ewl_seeker_set_range(Ewl_Seeker * s, double r)
{
@@ -202,11 +196,9 @@
/**
- * ewl_seeker_get_range - retrieve the range of values represented by the seeker
- *
- * @s: the seeker to return the range of values
- *
- * Returns 0 on failure, or the upper bound on the seeker on success.
+ * @param s: the seeker to return the range of values
+ * @return Returns 0 on failure, or the upper bound on the seeker on success.
+ * @brief Retrieve the range of values represented by the seeker
*/
double ewl_seeker_get_range(Ewl_Seeker * s)
{
@@ -218,12 +210,13 @@
/**
- * ewl_seeker_set_step - set the steps between increments
- * @s: the seeker to change step
- * @step: the new step value for the seeker
+ * @param s: the seeker to change step
+ * @param step: the new step value for the seeker
+ * @return Returns no value.
+ * @brief Set the steps between increments
*
- * Returns no value. Changes the amount that each increment or decrement
- * changes the value of the seeker @s.
+ * Changes the amount that each increment or decrement changes the value of the
+ * seeker @a s.
*/
void ewl_seeker_set_step(Ewl_Seeker * s, double step)
{
@@ -240,10 +233,9 @@
/**
- * ewl_seeker_get_step - retrieve the step size of the seeker
- * @s: the seeker to retrieve step size
- *
- * Returns the step size of the seeker @s.
+ * @param s: the seeker to retrieve step size
+ * @return Returns the step size of the seeker @a s.
+ * @brief Retrieve the step size of the seeker
*/
double ewl_seeker_get_step(Ewl_Seeker * s)
{
@@ -257,11 +249,11 @@
/**
- * ewl_seeker_increase - increase the value of a seeker by it's step size
- * @s: the seeker to increase
+ * @param s: the seeker to increase
+ * @return Returns no value.
+ * @brief Increase the value of a seeker by it's step size
*
- * Returns no value. Increases the value of the seeker @s by one increment of
- * it's step size.
+ * Increases the value of the seeker @a s by one increment of it's step size.
*/
void ewl_seeker_increase(Ewl_Seeker * s)
{
@@ -284,11 +276,11 @@
/**
- * ewl_seeker_decrease - decrease the value of a seeker by it's step size
- * @s: the seeker to decrease
+ * @param s: the seeker to decrease
+ * @return Returns no value.
+ * @brief Decrease the value of a seeker by it's step size
*
- * Returns no value. Decreases the value of the seeker @s by one increment of
- * it's step size.
+ * Decreases the value of the seeker @a s by one increment of it's step size.
*/
void ewl_seeker_decrease(Ewl_Seeker * s)
{
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_seeker.h,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -3 -r1.13 -r1.14
--- ewl_seeker.h 25 May 2002 05:46:42 -0000 1.13
+++ ewl_seeker.h 31 Aug 2003 02:59:46 -0000 1.14
@@ -2,22 +2,53 @@
#ifndef __EWL_SEEKER_H__
#define __EWL_SEEKER_H__
-typedef struct _ewl_seeker Ewl_Seeker;
+/**
+ * @file ewl_seeker.h
+ * Defines an Ewl_Widget with a draggable button enclosed, used to select a
+ * value from a range.
+ *
+ * @todo Add value labels and hash marks.
+ */
+/**
+ * The Ewl_Seeker provides a means to select a value from a range using a
+ * draggable button.
+ */
+typedef struct Ewl_Seeker Ewl_Seeker;
+
+/**
+ * @def EWL_SEEKER(seeker)
+ * Typecasts a pointer to an Ewl_Seeker pointer.
+ */
#define EWL_SEEKER(seeker) ((Ewl_Seeker *) seeker)
-struct _ewl_seeker {
- Ewl_Container container;
- Ewl_Orientation orientation;
- Ewl_Widget *dragbar;
- double value;
- double range;
- double step;
+/**
+ * @struct Ewl_Seeker
+ * Inherits from Ewl_Container and creates internal Ewl_Widget's to provide a
+ * range and a draggable area to select a value from that range.
+ */
+struct Ewl_Seeker
+{
+ Ewl_Container container; /**< Inherit from Ewl_Container */
+ Ewl_Orientation orientation; /**< Indicates layout direction */
+ Ewl_Widget *dragbar; /**< Draggable widget for selecting value */
+ double value; /**< Currently chosen value */
+ double range; /**< Total selectable range */
+ double step; /**< Size of increments in the range */
- int dragstart;
+ int dragstart; /**< The coordinate where the drag starts */
};
+/**
+ * @def ewl_vseeker_new()
+ * Shorthand to allocate a vertical seeker.
+ */
#define ewl_vseeker_new() ewl_seeker_new(EWL_ORIENTATION_VERTICAL);
+
+/**
+ * @def ewl_hseeker_new()
+ * Shorthand to allocate a horizontal seeker.
+ */
#define ewl_hseeker_new() ewl_seeker_new(EWL_ORIENTATION_HORIZONTAL);
Ewl_Widget *ewl_seeker_new(Ewl_Orientation orientation);
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_spacer.h,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -3 -r1.2 -r1.3
--- ewl_spacer.h 29 Aug 2003 17:56:13 -0000 1.2
+++ ewl_spacer.h 31 Aug 2003 02:59:46 -0000 1.3
@@ -4,6 +4,8 @@
/**
* @file ewl_spacer.h
+ * Defines an Ewl_Widget to be used for adding space between widgets in a
+ * layout.
*/
/**
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_tree.c,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -3 -r1.17 -r1.18
--- ewl_tree.c 25 Aug 2003 19:40:43 -0000 1.17
+++ ewl_tree.c 31 Aug 2003 02:59:46 -0000 1.18
@@ -24,11 +24,11 @@
void *user_data);
/**
- * ewl_tree_new - allocate and initialize a new tree widget
- * @columns: the number of columns to display
+ * @param columns: the number of columns to display
+ * @return Returns NULL on failure, a new tree widget on success.
+ * @brief Allocate and initialize a new tree widget
*
- * Returns NULL on failure, a newly allocated and initialized widget on
- * success. The paramater @columns can be modified at a later time to display
+ * The paramater @a columns can be modified at a later time to display
* a different number of columns.
*/
Ewl_Widget *ewl_tree_new(unsigned short columns)
@@ -53,13 +53,14 @@
}
/**
- * ewl_tree_init - initialize the contents of a tree widget
- * @tree: the tree widget to be initialized
- * @columns: the number of columns in the tree
- *
- * Returns TRUE on success, FALSE on failure. The contents of the tree widget
- * @tree are initialized to their defaults, and the number of columns to
- * display is set to @columns.
+ * @param tree: the tree widget to be initialized
+ * @param columns: the number of columns in the tree
+ * @return Returns TRUE on success, FALSE on failure.
+ * @brief Initialize the contents of a tree widget
+ *
+ * The contents of the tree widget
+ * @a tree are initialized to their defaults, and the number of columns to
+ * display is set to @a columns.
*/
int ewl_tree_init(Ewl_Tree *tree, unsigned short columns)
{
@@ -103,12 +104,12 @@
}
/**
- * ewl_tree_set_headers - change the widgets in a trees column headers
- * @tree: the tree to change column headers
- * @headers: the array of widget pointers containing the new headers
+ * @param tree: the tree to change column headers
+ * @param headers: the array of widget pointers containing the new headers
+ * @return Returns no value.
+ * @brief Change the widgets in a trees column headers
*
- * Returns no value. Stores the widgets in @headers to the header row of
- * @tree.
+ * Stores the widgets in @a headers to header row of @a tree.
*/
void ewl_tree_set_headers(Ewl_Tree *tree, char **headers)
{
@@ -135,12 +136,11 @@
}
/**
- * ewl_tree_add_row - add a group of widgets to a row in the tree
- * @tree: the tree to hold the widgets
- * @prow: the parent row of the new row for the added widgets
- * @children: a NULL terminated array of widgets to add to the tree
- *
- * Returns a pointer to the newly created row on success, NULL on failure.
+ * @param tree: the tree to hold the widgets
+ * @param prow: the parent row of the new row for the added widgets
+ * @param children: a NULL terminated array of widgets to add to the tree
+ * @return Returns a pointer to a new row on success, NULL on failure.
+ * @brief Add a group of widgets to a row in the tree
*/
Ewl_Widget *
ewl_tree_add_row(Ewl_Tree *tree, Ewl_Row *prow, Ewl_Widget **children)
@@ -220,12 +220,12 @@
}
/**
- * ewl_tree_add_text_row - add a row of text to a tree
- * @tree: the tree to hold the new text row
- * @prow: the parent row of the new text row
- * @text: the array of strings that hold the text to be added
+ * @param tree: the tree to hold the new text row
+ * @param prow: the parent row of the new text row
+ * @param text: the array of strings that hold the text to be added
+ * @brief Add a row of text to a tree
*
- * Returns a pointer to the newly created row on success, NULL on failure.
+ * @return Returns a pointer to a new row on success, NULL on failure.
*/
Ewl_Widget *ewl_tree_add_text_row(Ewl_Tree *tree, Ewl_Row *prow, char **text)
{
@@ -256,11 +256,12 @@
}
/**
- * ewl_tree_remove_row - remove a specified row from the tree
- * @tree: the tree to remove a row from
- * @row: the row to be removed from the tree
+ * @param tree: the tree to remove a row from
+ * @param row: the row to be removed from the tree
+ * @return Returns no value.
+ * @brief Remove a specified row from the tree
*
- * Returns no value. Removes @row from @tree if it is present in @tree. The
+ * Removes @a row from @a tree if it is present in @a tree. The
* widgets in the row will not be destroyed, so they can be accessed at a
* later time.
*/
@@ -285,11 +286,12 @@
}
/**
- * ewl_tree_destroy_row - destroy a specified row from the tree
- * @tree: the tree to destroy a row from
- * @row: the row to be destroyed from the tree
+ * @param tree: the tree to destroy a row from
+ * @param row: the row to be destroyed from the tree
+ * @return Returns no value.
+ * @brief Destroy a specified row from the tree
*
- * Returns no value. Removes @row from @tree if it is present in @tree. The
+ * Removes @a row from @a tree if it is present in @a tree. The
* widgets in the row will be destroyed, so they should not be accessed at a
* later time.
*/
@@ -310,12 +312,13 @@
}
/**
- * ewl_tree_set_columns - change the number of columns displayed in a tree
- * @tree: the tree to change the number of columns
- * @columns: the new number of columns to be displayed
+ * @param tree: the tree to change the number of columns
+ * @param columns: the new number of columns to be displayed
+ * @return Returns no value.
+ * @brief Change the number of columns displayed in a tree
*
- * Returns no value. The number of columns displayed in @tree is changed to
- * @columns. When rows are added, pre-existing rows have empty contents in the
+ * The number of columns displayed in @a tree is changed to
+ * @a columns. When rows are added, pre-existing rows have empty contents in the
* additional columns which are appended. When rows are removed, previously
* existing rows destroy column contents that are removed from the end. If you
* need finer grain control over where columns are added or removed, see
@@ -332,11 +335,12 @@
}
/**
- * ewl_tree_set_row_expand - set the expand state of a specific row
- * @row: the row to change the expanded state
- * @expanded: the new expanded state for the row
+ * @param row: the row to change the expanded state
+ * @param expanded: the new expanded state for the row
+ * @return Returns no value.
+ * @brief Set the expand state of a specific row
*
- * Returns no value. Changes the expanded state of @row to @expanded, which
+ * Changes the expanded state of @a row to @a expanded, which
* should be TRUE or FALSE.
*/
void ewl_tree_set_row_expand(Ewl_Row *row, Ewl_Tree_Node_Flags expanded)
@@ -362,9 +366,8 @@
}
/**
- * ewl_tree_node_new - allocate and initialize a new node
- *
- * Returns a newly allocated node on success, NULL on failure.
+ * @return Returns a newly allocated node on success, NULL on failure.
+ * @brief Allocate and initialize a new node
*/
Ewl_Widget *ewl_tree_node_new()
{
@@ -386,11 +389,11 @@
}
/**
- * ewl_tree_node_init - initialize the node fields of an inheriting object
- * @node: the node object to initialize
+ * @param node: the node object to initialize
+ * @return Returns TRUE on success, FALSE on failure.
+ * @brief Initialize the node fields of an inheriting object
*
- * Returns TRUE on success, FALSE on failure. The fields of the @node object
- * are initialized to their defaults.
+ * The fields of the @a node object are initialized to their defaults.
*/
int ewl_tree_node_init(Ewl_Tree_Node *node)
{
@@ -414,10 +417,9 @@
}
/**
- * ewl_tree_node_collapse - collapse a node in the tree
- * @node: the node in the tree to collapse
- *
- * Returns no value. Hides the rows below a node @node.
+ * @param node: the node in the tree to collapse
+ * @return Returns no value. Hides the rows below @a node.
+ * @brief Collapse a node in the tree
*/
void ewl_tree_node_collapse(Ewl_Tree_Node *node)
{
@@ -444,10 +446,9 @@
}
/**
- * ewl_tree_node_expand - expand a node in the tree
- * @node: the node in the tree to expand
- *
- * Returns no value. Hides the rows below a node @node.
+ * @param node: the node in the tree to expand
+ * @return Returns no value. Hides the rows below @a node.
+ * @brief Expand a node in the tree
*/
void ewl_tree_node_expand(Ewl_Tree_Node *node)
{
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ewl/src/ewl_tree.h,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -3 -r1.11 -r1.12
--- ewl_tree.h 28 Jun 2003 06:50:32 -0000 1.11
+++ ewl_tree.h 31 Aug 2003 02:59:46 -0000 1.12
@@ -1,29 +1,45 @@
#ifndef _EWL_TREE_H
#define _EWL_TREE_H
+/**
+ * @file ewl_tree.h
+ * Defines a widget for laying out other widgets in a tree or list like
+ * manner.
+ */
+
+typedef struct Ewl_Tree Ewl_Tree;
-typedef struct _ewl_tree Ewl_Tree;
+/**
+ * @def EWL_TREE(t)
+ * Typecasts a pointer to an Ewl_Tree pointer.
+ */
#define EWL_TREE(t) ((Ewl_Tree *)t)
-/*
+/**
+ * @struct Ewl_Tree
* The tree is a columnar listing, where items in the list may be nested below
* other items.
*/
-struct _ewl_tree
+struct Ewl_Tree
{
- Ewl_Container container;
+ Ewl_Container container; /**< Inherit from Ewl_Container */
- unsigned short ncols;
- unsigned short nrows;
+ unsigned short ncols; /**< Number of columns in tree */
+ unsigned short nrows; /**< Number of rows in tree */
unsigned int **colbases;
unsigned int **colbounds;
- Ewl_Widget *header;
+ Ewl_Widget *header; /**< Array of widgets in the header */
- Ewl_Widget *selected;
+ Ewl_Widget *selected; /**< The currently selected row */
};
typedef struct _ewl_tree_node Ewl_Tree_Node;
+
+/**
+ * @def EWL_TREE_NODE(t)
+ * Typecasts a pointer to an Ewl_Tree_Node pointer.
+ */
#define EWL_TREE_NODE(t) ((Ewl_Tree_Node *)t)
/*
@@ -32,10 +48,10 @@
*/
struct _ewl_tree_node
{
- Ewl_Container container;
- Ewl_Tree *tree;
- Ewl_Widget *row;
- int expanded;
+ Ewl_Container container; /**< Inherit from Ewl_Container */
+ Ewl_Tree *tree; /**< Pointer to the tree this is inside */
+ Ewl_Widget *row; /**< The child row */
+ int expanded; /**< Indicator of expansion state */
};
/*
-------------------------------------------------------
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
