Enlightenment CVS committal
Author : raster
Project : e17
Module : libs/evas
Dir : e17/libs/evas/src/lib/canvas
Modified Files:
evas_focus.c evas_key.c evas_key_grab.c evas_object_image.c
evas_object_text.c
Log Message:
documentation from brett... tiler can compiler again.
===================================================================
RCS file: /cvs/e/e17/libs/evas/src/lib/canvas/evas_focus.c,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -3 -r1.6 -r1.7
--- evas_focus.c 6 Jan 2006 23:05:17 -0000 1.6
+++ evas_focus.c 4 Jun 2007 09:48:27 -0000 1.7
@@ -8,10 +8,22 @@
/* public calls */
/**
- * To be documented.
- *
- * FIXME: To be fixed.
- *
+ * Sets focus to the given object.
+ *
+ * @param obj The object to be focused or unfocused.
+ * @param focus set or remove focus to the object.
+ *
+ * Changing focus only affects where key events go.
+ * There can be only one object focused at any time.
+ * <p>
+ * If the parameter (@p focus) is set, the passed object will be set as the
+ * currently focused object. It will receive all keyboard events that are not
+ * exclusive key grabs on other objects.
+ *
+ * @see evas_object_focus_get
+ * @see evas_focus_get
+ * @see evas_object_key_grab
+ * @see evas_object_key_ungrab
*/
EAPI void
evas_object_focus_set(Evas_Object *obj, Evas_Bool focus)
@@ -39,10 +51,19 @@
}
/**
- * To be documented.
+ * Test if the object has focus.
*
- * FIXME: To be fixed.
+ * @param obj The object to be tested.
+ *
+ * If the passed object is the currently focused object 1 is returned,
+ * 0 otherwise.
+ *
+ * @see evas_object_focus_set
+ * @see evas_focus_get
+ * @see evas_object_key_grab
+ * @see evas_object_key_ungrab
*
+ * @return 1 if the object has the focus, 0 otherwise.
*/
EAPI Evas_Bool
evas_object_focus_get(Evas_Object *obj)
@@ -54,10 +75,18 @@
}
/**
- * To be documented.
+ * Retrieve the object that currently has focus.
*
- * FIXME: To be fixed.
+ * @param e The @c Evas canvas to query focus on.
+ *
+ * Returns the object that currently has focus, NULL otherwise.
+ *
+ * @see evas_object_focus_set
+ * @see evas_object_focus_get
+ * @see evas_object_key_grab
+ * @see evas_object_key_ungrab
*
+ * @return The object that has focus or NULL is there is not one.
*/
EAPI Evas_Object *
evas_focus_get(Evas *e)
===================================================================
RCS file: /cvs/e/e17/libs/evas/src/lib/canvas/evas_key.c,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -3 -r1.10 -r1.11
--- evas_key.c 6 Jan 2006 23:05:17 -0000 1.10
+++ evas_key.c 4 Jun 2007 09:48:27 -0000 1.11
@@ -35,10 +35,20 @@
/* public calls */
/**
- * To be documented.
+ * Returns a handle to the modifiers available in the system. This is
required to check
+ * for modifiers with the evas_key_modifier_is_set_get function.
*
- * FIXME: To be fixed.
*
+ * @see evas_key_modifier_add
+ * @see evas_key_modifier_del
+ * @see evas_key_modifier_on
+ * @see evas_key_modifier_off
+ * @see evas_key_modifier_is_set_get
+ *
+ * @param e The pointer to the Evas Canvas
+ *
+ * @return An Evas_Modifier handle to query the modifier subsystem with
+ * evas_key_modifier_is_set_get, or NULL on error.
*/
EAPI Evas_Modifier *
evas_key_modifier_get(Evas *e)
@@ -50,10 +60,19 @@
}
/**
- * To be documented.
+ * Returns a handle to the locks available in the system. This is required to
check for
+ * locks with the evas_key_lock_is_set_get function.
*
- * FIXME: To be fixed.
+ * @see evas_key_lock_add
+ * @see evas_key_lock_del
+ * @see evas_key_lock_on
+ * @see evas_key_lock_off
*
+ * @see evas_key_lock_is_set_get
+ * @param e The pointer to the Evas Canvas
+ *
+ * @return An Evas_Lock handle to query the lock subsystem with
+ * evas_key_lock_is_set_get, or NULL on error.
*/
EAPI Evas_Lock *
evas_key_lock_get(Evas *e)
@@ -65,10 +84,19 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Checks the state of a given modifier. If the modifier is set, such as
shift being pressed
+ * this function returns true.
+ *
+ * @see evas_key_modifier_add
+ * @see evas_key_modifier_del
+ * @see evas_key_modifier_get
+ * @see evas_key_modifier_on
+ * @see evas_key_modifier_off
+ *
+ * @param m The current modifier set as returned by evas_key_modifier_get.
+ * @param keyname The name of the key to check its status.
*
+ * @return 1 if the @p keyname is on, 0 otherwise.
*/
EAPI Evas_Bool
evas_key_modifier_is_set(Evas_Modifier *m, const char *keyname)
@@ -87,10 +115,19 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Checks the state of a given lock. If the lock is set, such as caps lock,
this function
+ * returns true.
*
+ * @see evas_key_lock_get
+ * @see evas_key_lock_add
+ * @see evas_key_lock_del
+ * @see evas_key_lock_on
+ * @see evas_key_lock_off
+ *
+ * @param l The current lock set as returned by evas_key_lock_get.
+ * @param keyname The name of the lock to add the the list.
+ *
+ * @param 1 if the @p keyname kock is set, 0 otherwise.
*/
EAPI Evas_Bool
evas_key_lock_is_set(Evas_Lock *l, const char *keyname)
@@ -109,10 +146,20 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
- *
+ * Adds the @p keyname to the current list of modifiers.
+ *
+ * Modifiers can be keys like shift, alt and ctrl, as well as user defined.
This allows
+ * custom modifiers to be added to the evas system as run time. It is then
possible to set
+ * and unset the modifier for other parts of the program to check and act on.
+ *
+ * @see evas_key_modifier_del
+ * @see evas_key_modifier_get
+ * @see evas_key_modifier_on
+ * @see evas_key_modifier_off
+ * @see evas_key_modifier_is_set_get
+ *
+ * @param e The pointer to the Evas Canvas
+ * @param keyname The name of the modifier to add to the list.
*/
EAPI void
evas_key_modifier_add(Evas *e, const char *keyname)
@@ -130,10 +177,16 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Removes the @p keyname from the current list of modifiers.
*
+ * @see evas_key_modifier_add
+ * @see evas_key_modifier_get
+ * @see evas_key_modifier_on
+ * @see evas_key_modifier_off
+ * @see evas_key_modifier_is_set_get
+ *
+ * @param e The pointer to the Evas Canvas
+ * @param keyname The name of the key to remove from the modifiers list.
*/
EAPI void
evas_key_modifier_del(Evas *e, const char *keyname)
@@ -161,10 +214,19 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Adds the @p keyname to the current list of locks.
*
+ * Locks can be keys like caps lock, num lock or scroll lock, as well as user
defined. This
+ * allows custom locks to be added to the evas system at run time. It is then
possible to
+ * set and unset the lock for other parts of the program to check and act on.
+ *
+ * @see evas_key_lock_get
+ * @see evas_key_lock_del
+ * @see evas_key_lock_on
+ * @see evas_key_lock_off
+ *
+ * @param e The pointer to the Evas Canvas
+ * @param keyname The name of the key to remove from the modifier list.
*/
EAPI void
evas_key_lock_add(Evas *e, const char *keyname)
@@ -182,10 +244,15 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Removes The @p keyname from the current list of locks.
*
+ * @see evas_key_lock_get
+ * @see evas_key_lock_add
+ * @see evas_key_lock_on
+ * @see evas_key_lock_off
+ *
+ * @param e The pointer to the Evas Canvas
+ * @param keyname The name of the key to remove from the lock list.
*/
EAPI void
evas_key_lock_del(Evas *e, const char *keyname)
@@ -214,10 +281,15 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
- *
+ * Enables or turns on the modifier with name @p keyname.
+ *
+ * @see evas_key_modifier_add
+ * @see evas_key_modifier_get
+ * @see evas_key_modifier_off
+ * @see evas_key_modifier_is_set_get
+ *
+ * @param e The pointer to the Evas Canvas
+ * @param keyname The name of the modifier to set.
*/
EAPI void
evas_key_modifier_on(Evas *e, const char *keyname)
@@ -236,10 +308,15 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
- *
+ * Disables or turns off the modifier with name @p keyname.
+ *
+ * @see evas_key_modifier_add
+ * @see evas_key_modifier_get
+ * @see evas_key_modifier_on
+ * @see evas_key_modifier_is_set_get
+ *
+ * @param e The pointer to the Evas Canvas
+ * @param keyname The name of the modifier to un-set.
*/
EAPI void
evas_key_modifier_off(Evas *e, const char *keyname)
@@ -258,10 +335,15 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Enables or turns on the lock with name @p keyname.
*
+ * @see evas_key_lock_get
+ * @see evas_key_lock_add
+ * @see evas_key_lock_del
+ * @see evas_key_lock_off
+ *
+ * @param e The pointer to the Evas Canvas
+ * @param keyname The name of the lock to set.
*/
EAPI void
evas_key_lock_on(Evas *e, const char *keyname)
@@ -280,10 +362,15 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Disables or turns off the lock with name @p keyname.
*
+ * @see evas_key_lock_get
+ * @see evas_key_lock_add
+ * @see evas_key_lock_del
+ * @see evas_key_lock_on
+ *
+ * @param e The pointer to the Evas Canvas
+ * @param keyname The name of the lock to un-set.
*/
EAPI void
evas_key_lock_off(Evas *e, const char *keyname)
@@ -304,10 +391,18 @@
/* errr need to add key grabbing/ungrabbing calls - missing modifier stuff. */
/**
- * To be documented.
+ * Creates a bit mask from the @p keyname for use with events to check for the
presence
+ * of the @p keyname modifier.
*
- * FIXME: To be fixed.
+ * @see evas_key_modifier_add
+ * @see evas_key_modifier_get
+ * @see evas_key_modifier_on
+ * @see evas_key_modifier_off
+ * @see evas_key_modifier_is_set_get
+ *
+ * @param keyname The name of the modifier to create the mask for.
*
+ * @returns the bit mask or 0 if the @p keyname wasn't registered as a
modifier.
*/
EAPI Evas_Modifier_Mask
evas_key_modifier_mask_get(Evas *e, const char *keyname)
===================================================================
RCS file: /cvs/e/e17/libs/evas/src/lib/canvas/evas_key_grab.c,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -3 -r1.12 -r1.13
--- evas_key_grab.c 6 Jan 2006 23:05:17 -0000 1.12
+++ evas_key_grab.c 4 Jun 2007 09:48:27 -0000 1.13
@@ -141,10 +141,41 @@
/* public calls */
/**
- * To be documented.
+ * Requests @p keyname key events be directed to @p obj.
*
- * FIXME: To be fixed.
+ * Key grabs allow an object to receive key events for specific key strokes
+ * even if another object has focus. If the grab is non-exclusive then all
+ * objects that have grabs on the key will get the event, however if the
+ * grab is exclusive, no other object can get a grab on the key and only
+ * that object will get the event.
*
+ * @p keyname is a platform dependent symbolic name for the key pressed.
+ * It is sometimes possible to convert the string to an ASCII value of the
+ * key, but not always for example the enter key may be returned as the
+ * string 'Enter'.
+ *
+ * Typical platforms are Linux frame buffer (Ecore_FB) and X server (Ecore_X)
+ * when using Evas with Ecore and Ecore_Evas.
+ *
+ * For a list of keynames for the Linux frame buffer, please refer to the
+ * Ecore_FB documentation.
+ *
+ * @p modifiers and @p not_modifiers are bit masks of all the modifiers that
are required and
+ * not required respectively for the new grab. Modifiers can be things such
as shift and ctrl
+ * as well as user defigned types via evas_key_modifier_add.
+ *
+ * @see evas_object_key_ungrab
+ * @see evas_object_focus_set
+ * @see evas_object_focus_get
+ * @see evas_focus_get
+ * @see evas_key_modifier_add
+ *
+ * @param obj the object to direct @p keyname events to.
+ * @param keyname the key to request events for.
+ * @param modifiers a mask of modifiers that should be present to trigger the
event.
+ * @param not_modifiers a mask of modifiers that should not be present to
trigger the event.
+ * @param exclusive request that the @p obj is the only object receiving the
@p keyname events.
+ * @return Boolean indicating whether the grab succeeded
*/
EAPI Evas_Bool
evas_object_key_grab(Evas_Object *obj, const char *keyname, Evas_Modifier_Mask
modifiers, Evas_Modifier_Mask not_modifiers, Evas_Bool exclusive)
@@ -167,10 +198,20 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Request that the grab on @p obj be removed.
+ *
+ * Removes the grab on @p obj if @p keyname, @p modifiers, and @p not_modifiers
+ * match.
+ *
+ * @see evas_object_key_grab
+ * @see evas_object_focus_set
+ * @see evas_object_focus_get
+ * @see evas_focus_get
*
+ * @param obj the object that has an existing grab.
+ * @param keyname the key the grab is for.
+ * @param modifiers a mask of modifiers that should be present to trigger the
event.
+ * @param not_modifiers a mask of modifiers that should not be present to
trigger the event.
*/
EAPI void
evas_object_key_ungrab(Evas_Object *obj, const char *keyname,
Evas_Modifier_Mask modifiers, Evas_Modifier_Mask not_modifiers)
===================================================================
RCS file: /cvs/e/e17/libs/evas/src/lib/canvas/evas_object_image.c,v
retrieving revision 1.50
retrieving revision 1.51
diff -u -3 -r1.50 -r1.51
--- evas_object_image.c 6 May 2007 11:29:37 -0000 1.50
+++ evas_object_image.c 4 Jun 2007 09:48:27 -0000 1.51
@@ -677,10 +677,39 @@
}
/**
- * To be documented.
+ * @defgroup Evas_Object_Image_Data Image Object Image Data Functions
*
- * FIXME: To be fixed.
+ * Functions that allow you to access or modify the image pixel data of an
+ * image object.
+ */
+
+/**
+ * Replaces an image object's internal image data buffer.
*
+ * This function lets the application replace an image object's internal pixel
+ * buffer with a user-allocated one. For best results, you should generally
+ * first call evas_object_image_size_set() with the width and height for the
+ * new buffer.
+ *
+ * This call is best suited for when you will be using image data with
+ * different dimensions than the existing image data, if any. If you only need
+ * to modify the existing image in some fashion, then using
+ * evas_object_image_data_get() is probably what you are after.
+ *
+ * The buffer should be a single planar array (not 2-dimensional), with
+ * consecutive rows following on from each other. Pixels should be in 32-bit
+ * ARGB format.
+ *
+ * Note that the caller is responsible for freeing the buffer when finished
+ * with it, as user-set image data will not be automatically freed when the
+ * image object is deleted.
+ *
+ * @see evas_object_image_data_get
+ *
+ * @param obj The given image object.
+ * @param data pointer to the new pixel buffer
+ * @ingroup Evas_Object_Image_Data
+ * @ingroup Evas_Object_Image_Size
*/
EAPI void
evas_object_image_data_copy_set(Evas_Object *obj, void *data)
@@ -745,10 +774,24 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Get a pointer to an image object's internal image data buffer.
*
+ * This function returns a pointer to an image object's internal pixel buffer,
+ * for reading only or read/write. If you request it for writing, the image
+ * will be marked dirty so that it gets redrawn at the next update.
+ *
+ * Note that this is best suited when you want to modify an existing image,
+ * without changing its dimensions. If you need to modify an image's
+ * dimensions at the same time, you will need to allocate your own buffer and
+ * call evas_object_image_data_set() to instruct the image object to use it.
+ *
+ * @see evas_object_image_data_set
+ *
+ * @param obj The given image object.
+ * @param for_writing Boolean indicating whether or not we desire the buffer
for writing
+ * @return Pointer to the image object's image data
+ * @ingroup Evas_Object_Image_Data
+ *
*/
EAPI void
evas_object_image_alpha_set(Evas_Object *obj, Evas_Bool has_alpha)
@@ -796,10 +839,20 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Mark a sub-region of an image to be redrawn.
*
+ * This function schedules a particular rectangular region of an image object
+ * to be updated (redrawn) at the next render.
+ *
+ * @see evas_object_image_dirty_set
+ *
+ * @param obj The given image object.
+ * @param x X-offset of region to be updated
+ * @param y Y-offset of region to be updated
+ * @param w Width of region to be updated
+ * @param h Height of region to be updated
+ * @ingroup Evas_Object_Image_Data
+ *
*/
EAPI void
evas_object_image_smooth_scale_set(Evas_Object *obj, Evas_Bool smooth_scale)
@@ -842,10 +895,25 @@
}
/**
- * To be documented.
+ * @defgroup Evas_Object_Image_Alpha Image Object Image Alpha Functions
*
- * FIXME: To be fixed.
+ * Functions that change the alpha of an image object.
+ */
+
+/**
+ * Enable or disable alpha channel on an image.
+ *
+ * This function sets a flag on an image object indicating whether or not to
+ * use alpha channel data. A value of 1 indicates to use alpha channel data,
+ * and 0 indicates to ignore any alpha channel data. Note that this has
+ * nothing to do with an object's color as manipulated by
+ * evas_object_color_set().
*
+ * @see evas_object_image_alpha_get
+ *
+ * @param obj The given image object.
+ * @param has_alpha Boolean flag indicating to use alpha or not
+ * @ingroup Evas_Object_Image_Alpha
*/
EAPI void
evas_object_image_reload(Evas_Object *obj)
@@ -871,10 +939,17 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
- *
+ * Obtain alpha channel setting of an image object
+ *
+ * This function returns 1 if the image object's alpha channel is being used,
+ * or 0 otherwise. Note that this has nothing to do with an object's color as
+ * manipulated by evas_object_color_set().
+ *
+ * @see evas_object_image_alpha_set
+ *
+ * @param obj The given image object.
+ * @return Boolean indicating if the alpha channel is being used
+ * @ingroup Evas_Object_Image_Alpha
*/
EAPI Evas_Bool
evas_object_image_save(Evas_Object *obj, const char *file, const char *key,
const char *flags)
@@ -1026,9 +1101,23 @@
}
/**
- * To be documented.
+ * @defgroup Evas_Object_Image_Scale Image Object Image Scaling Functions
*
- * FIXME: To be fixed.
+ * Functions that change the scaling quality of an image object.
+ */
+
+/**
+ * Set/unset the use of high-quality image scaling
+ *
+ * When enabled, a higher quality image scaling algorithm is used when scaling
+ * images to sizes other than the source image. This gives better results but
+ * is more computationally expensive.
+ *
+ * @see evas_object_image_smooth_scale_get
+ *
+ * @param obj The given image object.
+ * @param smooth_scale Boolean flag indicating to use alpha or not.
+ * @ingroup Evas_Object_Image_Scale
*
*/
EAPI void
@@ -1072,9 +1161,16 @@
}
/**
- * To be documented.
+ * Test if smooth scaling is enabled on an image object
*
- * FIXME: To be fixed.
+ * This function returns 1 if smooth scaling is enabled on the image object,
+ * or 0 otherwise.
+ *
+ * @see evas_object_image_smooth_scale_set
+ *
+ * @param obj The given image object.
+ * @return Boolean indicating if smooth scaling is enabled.
+ * @ingroup Evas_Object_Image_Scale
*
*/
EAPI Evas_Bool
===================================================================
RCS file: /cvs/e/e17/libs/evas/src/lib/canvas/evas_object_text.c,v
retrieving revision 1.63
retrieving revision 1.64
diff -u -3 -r1.63 -r1.64
--- evas_object_text.c 6 May 2007 11:29:37 -0000 1.63
+++ evas_object_text.c 4 Jun 2007 09:48:27 -0000 1.64
@@ -68,10 +68,15 @@
/* it has no other api calls as all properties are standard */
/**
- * To be documented.
+ * Creates a new text @c Evas_Object on the provided @c Evas canvas.
*
- * FIXME: To be fixed.
+ * @param e The @c Evas canvas to create the text object upon.
*
+ * @see evas_object_text_font_source_set
+ * @see evas_object_text_font_set
+ * @see evas_object_text_text_set
+ *
+ * @returns NULL on error, A pointer to a new @c Evas_Object on success.
*/
EAPI Evas_Object *
evas_object_text_add(Evas *e)
@@ -246,10 +251,16 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Query evas for font information of a text @c Evas_Object.
*
+ * This function allows the font name and size of a text @c Evas_Object as
+ * created with evas_object_text_add() to be queried. Be aware that the font
+ * name string is still owned by Evas and should NOT have free() called on
+ * it by the caller of the function.
+ *
+ * @param obj The evas text object to query for font information.
+ * @param font A pointer to the location to store the font name in (may be
NULL).
+ * @param size A pointer to the location to store the font size in (may be
NULL).
*/
EAPI void
evas_object_text_font_get(Evas_Object *obj, const char **font, Evas_Font_Size
*size)
@@ -511,10 +522,22 @@
}
/**
- * To be documented.
+ * Retrieve position and dimension information of a character within a text @c
Evas_Object.
*
- * FIXME: To be fixed.
+ * This function is used to obtain the X, Y, width and height of a the
character
+ * located at @p pos within the @c Evas_Object @p obj. @p obj must be a text
object
+ * as created with evas_object_text_add(). Any of the @c Evas_Coord parameters
(@p cx,
+ * @p cy, @p cw, @p ch) may be NULL in which case no value will be assigned to
that
+ * parameter.
+ *
+ * @param obj The text object to retrieve position information for.
+ * @param pos The character position to request co-ordinates for.
+ * @param cx A pointer to an @c Evas_Coord to store the X value in (can be
NULL).
+ * @param cy A pointer to an @c Evas_Coord to store the Y value in (can be
NULL).
+ * @param cw A pointer to an @c Evas_Coord to store the Width value in (can
be NULL).
+ * @param ch A pointer to an @c Evas_Coord to store the Height value in (can
be NULL).
*
+ * @returns 0 on error, 1 on success.
*/
EAPI int
evas_object_text_char_pos_get(Evas_Object *obj, int pos, Evas_Coord *cx,
Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch)
-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
enlightenment-cvs mailing list
enlightenment-cvs@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-cvs
