Enlightenment CVS committal
Author : rephorm
Project : e17
Module : libs/edje
Dir : e17/libs/edje/src/lib
Modified Files:
edje_program.c
Log Message:
some more docs
===================================================================
RCS file: /cvs/e/e17/libs/edje/src/lib/edje_program.c,v
retrieving revision 1.51
retrieving revision 1.52
diff -u -3 -r1.51 -r1.52
--- edje_program.c 13 Feb 2007 09:58:49 -0000 1.51
+++ edje_program.c 15 Apr 2007 04:05:41 -0000 1.52
@@ -13,7 +13,7 @@
/** Set the frametime
* @param t The frametime
*
- * Sets the frametime in seconds, by default this is 1/30.
+ * Sets the global frametime in seconds, by default this is 1/30.
*/
EAPI void
edje_frametime_set(double t)
@@ -34,14 +34,50 @@
}
/* FIXDOC: Expand */
-/** Adds a callback for the object.
+/** Add a callback for a signal emitted by @a obj.
* @param obj A valid Evas_Object handle
- * @param emission Signal to activate callback FIXDOC: Naming Convention?
- * @param source Source of signal
- * @param func The function to be executed when the callback is signaled
- * @param data ? FIXDOC
+ * @param emission The signal name
+ * @param source The signal source
+ * @param func The callback function to be executed when the signal is emitted
+ * @param data A pointer to data to pass in to the callback function
+ *
+ * Connects a callback function to a signal emitted by @a obj.
+ * In EDC, a program can emit a signal as follows:
+ *
+ * @code
+ * program {
+ * name: "emit_example";
+ * action: SIGNAL_EMIT "a_signal" "a_source";
+ * }
+ * @endcode
+ *
+ * Assuming a function with the following declaration is definded:
+ *
+ * @code
+ * void cb_signal(void *data, Evas_Object *o, const char *emission, const char
*source);
+ * @endcode
+ *
+ * a callback is attached using:
+ *
+ * @code
+ * edje_object_callback_add(obj, "a_signal", "a_source", cb_signal, data);
+ * @endcode
+ *
+ * Here, @a data is an arbitrary pointer to be used as desired.
+ * Note that @a emission and @a source correspond respectively to first and
+ * second parameters to the SIGNAL_EMIT action.
*
- * Creates a callback for the object to execute the given function.
+ * Internal edje signals can also be attached to, and globs can be in either
+ * the emission or source name. e.g.
+ *
+ * @code
+ * edje_object_callback_add(obj, "mouse,down,*", "button.*", NULL);
+ * @endcode
+ *
+ * Here, any mouse down events on an edje part whose name begins with
+ * "button." will trigger the callback. The actual signal and source name
+ * will be passed in to the @a emission and @a source parameters of the
+ * callback function. (e.g. "mouse,down,2" and "button.close").
*/
EAPI void
edje_object_signal_callback_add(Evas_Object *obj, const char *emission, const
char *source, void (*func) (void *data, Evas_Object *o, const char *emission,
const char *source), void *data)
@@ -68,14 +104,17 @@
}
}
-/* FIXDOC: Expand */
-/** Delete an object's callback
+/** Remove a callback from an object
* @param obj A valid Evas_Object handle
- * @param emission ? FIXDOC
- * @param source ? FIXDOC
- * @param func ? FIXDOC
+ * @param emission the emission string
+ * @param source the source string
+ * @param func the callback function
+ * @return the data pointer
*
- * Deletes an existing callback
+ * Removes a callback from an object. The parameters @a emission, @a source
+ * and @a func must match exactly those passed to a previous call to
+ * edje_object_signal_callback_add(). The data pointer that was passed to
+ * this call will be returned.
*/
EAPI void *
edje_object_signal_callback_del(Evas_Object *obj, const char *emission, const
char *source, void (*func) (void *data, Evas_Object *o, const char *emission,
const char *source))
@@ -120,13 +159,32 @@
}
/* FIXDOC: Verify/Expand */
-/** Send a signal to the Edje
+/** Send a signal to the Edje object
* @param obj A vaild Evas_Object handle
* @param emission The signal
* @param source The signal source
*
- * This sends a signal to the edje. These are defined in the programs
- * section of an edc.
+ * This sends a signal to the edje object.
+ *
+ * An edje program can respond to a signal by specifying matching 'signal'
+ * and 'source' fields.
+ *
+ * E.g.
+ *
+ * @code
+ * edje_object_signal_emit(obj, "a_signal", "");
+ * @endcode
+ *
+ * will trigger a program whose edc is:
+ *
+ * @code
+ * program {
+ * name: "a_program";
+ * signal: "a_signal";
+ * source: "";
+ * action: ...
+ * }
+ * @endcode
*/
EAPI void
edje_object_signal_emit(Evas_Object *obj, const char *emission, const char
*source)
-------------------------------------------------------------------------
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
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/enlightenment-cvs
