dimmus
/
efl
forked from enlightenment/efl
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve documentation for Evas, Ecore, Edje and Elementary. 

Work by:
 - Thiago R. Masaki (mostly)
 - Fabiano Fidencio
 - Gustavo Lima


SVN revision: 42552
This commit is contained in:
Iván Briano 2009-09-17 22:38:35 +00:00
parent 6cf87428a4
commit 4e33c6fd65
7 changed files with 932 additions and 238 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
legacy/edje/src/lib/edje_cache.c
View File

@ -1,6 +1,25 @@
/*
* vim:ts=8:sw=3:sts=8:noexpandtab:cino=>5n-3f0^-2{2
*/
/* EDJE - EFL graphical design and layout library based on Evas
* Copyright (C) 2008 Cedric Bail
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library;
* if not, see <http://www.gnu.org/licenses/>.
*/
#ifdef HAVE_CONFIG_H
# include <config.h>
@ -438,8 +457,43 @@ _edje_file_cache_shutdown(void)
/**
* @endcond
*/
/*============================================================================*
* Global *
*============================================================================*/
/*============================================================================*
* API *
*============================================================================*/
/**
* @addtogroup Edje_cache_Group Cache
*
* @brief These functions provide an abstraction layer between the
* application code and the interface, while allowing extremely
* flexible dynamic layouts and animations.
*
* For more information, you can look at the @ref tutorial_list_page.
*
* @{
*/
/**
* @brief Set the file cache size.
*
* @param count The file cache size in edje file units. Default is 16.
*
* This function sets the file cache size. Edje keeps this cache in
* order to prevent duplicates of edje file entries in memory. The
* file cache size can be retrieved with edje_file_cache_get().
*
* @see edje_file_cache_get()
* @see edje_file_cache_flush()
*
*/
EAPI void
edje_file_cache_set(int count)
@ -449,12 +503,38 @@ edje_file_cache_set(int count)
_edje_cache_file_clean();
}
/**
* @brief Return the file cache size.
*
* @return The file cache size in edje file units. Default is 16.
*
* This function returns the file cache size set by
* edje_file_cache_set().
*
* @see edje_file_cache_set()
* @see edje_file_cache_flush()
*
*/
EAPI int
edje_file_cache_get(void)
{
return _edje_file_cache_size;
}
/**
* @brief Clean the file cache.
*
* @return The file cache size.
*
* This function cleans the file cache entries, but keeps this cache's
* size to the last value set.
*
* @see edje_file_cache_set()
* @see edje_file_cache_get()
*
*/
EAPI void
edje_file_cache_flush(void)
{
@ -466,6 +546,21 @@ edje_file_cache_flush(void)
_edje_file_cache_size = ps;
}
/**
* @brief Set the collection cache size.
*
* @param count The collection cache size, in edje object units. Default is 16.
*
* This function sets the collection cache size. Edje keeps this cache
* in order to prevent duplicates of edje {collection,group,part}
* entries in memory. The collection cache size can be retrieved with
* edje_collection_cache_get().
*
* @see edje_collection_cache_get()
* @see edje_collection_cache_flush()
*
*/
EAPI void
edje_collection_cache_set(int count)
{
@ -479,12 +574,38 @@ edje_collection_cache_set(int count)
/* FIXME: freach in file hash too! */
}
/**
* @brief Return the collection cache size.
*
* @return The collection cache size, in edje object units. Default is 16.
*
* This function returns the collection cache size set by
* edje_collection_cache_set().
*
* @see edje_collection_cache_set()
* @see edje_collection_cache_flush()
*
*/
EAPI int
edje_collection_cache_get(void)
{
return _edje_collection_cache_size;
}
/**
* @brief Clean the collection cache.
*
* @return The collection cache size.
*
* This function cleans the collection cache, but keeps this cache's
* size to the last value set.
*
* @see edje_collection_cache_set()
* @see edje_collection_cache_get()
*
*/
EAPI void
edje_collection_cache_flush(void)
{

93
legacy/edje/src/lib/edje_container.c
View File

@ -168,6 +168,46 @@ _edje_item_recalc(Edje_Item *ei)
/*****************************/
/**
* @endcond
*/
/*============================================================================*
* Global *
*============================================================================*/
/*============================================================================*
* API *
*============================================================================*/
/**
* @addtogroup Edje_container_Group Container
*
* @brief These functions provides an abstraction layer between the application
* code and the interface, while allowing extremely flexible dynamic layouts
* and animations.
*
* For more information, you can look at the @ref tutorial_list_page.
*
* @{
*/
/**
* @brief Create an edje item.
*
* @param cl The edje item of type Edje_Item_Class.
* @param data The edje item data.
*
* @return The new edje item created.
*
* This function creates an new edje item. The edje item data can be
* retrieved with edje_item_data_get().
*
* @see edje_item_del()
* @see edje_item_data_set()
* @see edje_item_data_get()
*
*/
Edje_Item *
edje_item_add(Edje_Item_Class *cl, void *data)
@ -182,6 +222,19 @@ edje_item_add(Edje_Item_Class *cl, void *data)
return ei;
}
/**
* @brief Delete an edje item.
*
* @param ei The edje item to be deleted.
*
* This function deletes the edje item from memory.
*
* @see edje_item_add()
* @see edje_item_data_set()
* @see edje_item_data_get()
*
*/
void
edje_item_del(Edje_Item *ei)
{
@ -197,6 +250,16 @@ edje_item_del(Edje_Item *ei)
_edje_container_recalc(sd);
}
/**
* @brief Return the smart object of the edje item.
*
* @param ei The edje item wich the smart object of type Evas_Object is get
* from.
*
* This function returns the smart object in the edje item.
*
*/
Evas_Object *
edje_item_container_get(Edje_Item *ei)
{
@ -205,6 +268,20 @@ edje_item_container_get(Edje_Item *ei)
}
/* an arbitary data pointer to use to track other data */
/**
* @brief Set the edje item data.
*
* @param ei The edje item of type Edje_Item_Class.
* @param data The edje item data.
*
* This function set the data of the edje item. The edje item data can be
* retrieved with edje_item_data_get().
*
* @see edje_item_add()
* @see edje_item_del()
* @see edje_item_data_get()
*
*/
void
edje_item_data_set(Edje_Item *ei, void *data)
@ -212,6 +289,19 @@ edje_item_data_set(Edje_Item *ei, void *data)
ei->data = data;
}
/**
* @brief Get the data of the edje item.
*
* @param ei The edje item of type Edje_Item_Class.
*
* This function get the data of the edje item set by edje_item_data_set().
*
* @see edje_item_data_set()
* @see edje_item_add()
* @see edje_item_del()
*
*/
void *
edje_item_data_get(Edje_Item *ei)
{
@ -219,6 +309,7 @@ edje_item_data_get(Edje_Item *ei)
}
/* this object covers the entire item */
void
edje_item_overlay_object_set(Edje_Item *ei, Evas_Object *obj)
{
@ -231,6 +322,8 @@ edje_item_overlay_object_set(Edje_Item *ei, Evas_Object *obj)
evas_object_smart_member_add(((Smart_Data *)(ei->sd))->smart_obj, obj);
}
Evas_Object *
edje_item_overlay_object_get(Edje_Item *ei)
{

31
legacy/edje/src/lib/edje_edit.c
View File

@ -74,6 +74,7 @@ _alloc(size_t size)
/* INTERNALS */
/*************/
static Edje_Part_Description *
_edje_part_description_find_byname(Edje *ed, const char *part, const char *state) //state include the value in the string (ex. "default 0.00")
{
@ -625,6 +626,23 @@ edje_edit_compiler_get(Evas_Object *obj)
/* GROUPS API */
/****************/
/**
* @brief Add an edje (empty) group to an edje object's group set.
*
* @param obj The pointer to edje object.
* @param name The name of the group.
*
* @return 1 If it could allocate memory to the part group added
* or zero if not.
*
* This function adds, at run time, one more group, which will reside
* in memory, to the group set found in the .edj file which @a obj was
* loaded with. This group can be manipulated by other API functions,
* like @c edje_edit_part_add(), for example. If desired, the new
* group can be actually commited the respective .edj by use of @c
* edje_edit_save().
*
*/
EAPI Eina_Bool
edje_edit_group_add(Evas_Object *obj, const char *name)
{
@ -703,7 +721,18 @@ edje_edit_group_add(Evas_Object *obj, const char *name)
return 1;
}
/**
* @brief Delete an edje object's current group.
*
* @param obj The pointer to the edje object.
*
* @return @c 1 on success, @c 0 on failure.
*
* This function deletes the group which @a obj is set to. This
* operation can be commited the the .edj file the object was loaded
* with by use of @c edje_edit_save().
*
*/
EAPI Eina_Bool
edje_edit_group_del(Evas_Object *obj)
{

54
legacy/edje/src/lib/edje_main.c
View File

@ -10,12 +10,42 @@ static int initted = 0;
Eina_Mempool *_edje_real_part_mp = NULL;
Eina_Mempool *_edje_real_part_state_mp = NULL;
/************************** API Routines **************************/
/** Initialize the EDJE library.
/*============================================================================*
* API *
*============================================================================*/
/**
* @addtogroup Edje_main_Group Main
*
* @return The new init count.
* @brief These functions provide an abstraction layer between the
* application code and the interface, while allowing extremely
* flexible dynamic layouts and animations.
*
* For more information, you can look at the @ref tutorial_list_page.
*
* @{
*/
/**
* @brief Initialize the edje library.
*
* @return The new init count. The initial value is zero.
*
* This function initializes the ejde library, making the propers
* calls to initialization functions. It makes calls to functions
* eina_init(), ecore_job_init(), embryo_init() and eet_init() so
* there is no need to call those functions again in your code. To
* shutdown edje there is a function edje_shutdown().
*
* @see edje_shutdown()
* @see eina_init()
* @see ecore_job_init()
* @see embryo_init()
* @see eet_init()
*
*/
EAPI int
edje_init(void)
{
@ -61,10 +91,24 @@ edje_init(void)
return 0;
}
/** Shutdown the EDJE library.
/**
* @brief Shutdown the edje library.
*
* @return Zero, always.
*
* This function shuts down the edje library. It calls the functions
* eina_shutdown(), ecore_job_shutdown(), embryo_shutdown() and
* eet_shutdown(), so there is no need to call these functions again
* in your code.
*
* @see edje_init()
* @see eina_shutdown()
* @see ecore_job_shutdown()
* @see embryo_shutdown()
* @see eet_shutdown()
*
* @return The new init count.
*/
EAPI int
edje_shutdown(void)
{

67
legacy/edje/src/lib/edje_message_queue.c
View File

@ -12,6 +12,40 @@ static Ecore_Timer *job_loss_timer = NULL;
static Eina_List *msgq = NULL;
static Eina_List *tmp_msgq = NULL;
/*============================================================================*
* API *
*============================================================================*/
/**
* @addtogroup Edje_message_queue_Group Message_Queue
*
* @brief These functions provide an abstraction layer between the
* application code and the interface, while allowing extremely
* flexible dynamic layouts and animations.
*
* For more information, you can look at the @ref tutorial_list_page.
*
* @{
*/
/**
* @brief Send message to object.
*
* @param obj The edje object reference.
* @param type The type of message to send.
* @param id A identification number for the message.
* @param msg The message to be send.
*
*
* This function sends messages to this object and to all of its child
* objects, if applicable. The function that handles messages arriving
* at this edje object is is set with
* edje_object_message_handler_set().
*
* @see edje_object_message_handler_set()
*
*/
EAPI void
edje_object_message_send(Evas_Object *obj, Edje_Message_Type type, int id, void *msg)
{
@ -30,6 +64,19 @@ edje_object_message_send(Evas_Object *obj, Edje_Message_Type type, int id, void
}
}
/**
* @brief Set the message handler function for this an object.
*
* @param obj The edje object reference.
* @param func The function to handle messages.
* @param data The data to be associated to the message handler.
*
*
* This function associates a message handler function and data to the
* edje object.
*
*/
EAPI void
edje_object_message_handler_set(Evas_Object *obj, void (*func) (void *data, Evas_Object *obj, Edje_Message_Type type, int id, void *msg), void *data)
{
@ -40,6 +87,17 @@ edje_object_message_handler_set(Evas_Object *obj, void (*func) (void *data, Evas
_edje_message_cb_set(ed, func, data);
}
/**
* @brief Process an object's message queue.
*
* @param obj The edje object reference.
*
* This function goes through the object message queue processing the
* pending messages for *this* specific edje object. Normally they'd
* be processed only at idle time.
*
*/
EAPI void
edje_object_message_signal_process(Evas_Object *obj)
{
@ -84,12 +142,21 @@ edje_object_message_signal_process(Evas_Object *obj)
}
}
/**
* @brief Process all queued up edje messages.
*
* This function triggers the processing of messages addressed to any
* (alive) edje objects.
*
*/
EAPI void
edje_message_signal_process(void)
{
_edje_message_queue_process();
}
static int
_edje_dummy_timer(void *data __UNUSED__)
{

191
legacy/edje/src/lib/edje_program.c
View File

@ -13,13 +13,35 @@ int _edje_anim_count = 0;
Ecore_Animator *_edje_timer = NULL;
Eina_List *_edje_animators = NULL;
/************************** API Routines **************************/
/* FIXDOC: Expand */
/** Set the frametime
* @param t The frametime
/*============================================================================*
* API *
*============================================================================*/
/**
* @addtogroup Edje_program_Group Program
*
* @brief These functions provide an abstraction layer between the
* application code and the interface, while allowing extremely
* flexible dynamic layouts and animations.
*
* For more information, you can look at the @ref tutorial_list_page.
*
* @{
*/
/**
* @brief Set edje trasitions' frame time.
*
* @param t The frame time, in seconds. Default value is 1/30.
*
* This function sets the edje built-in animations' frame time (thus,
* affecting their resolution) by calling
* ecore_animator_frametime_set(). This frame time can be retrieved
* with edje_frametime_get().
*
* @see edje_frametime_get()
*
* Sets the global frametime in seconds, by default this is 1/30.
*/
EAPI void
edje_frametime_set(double t)
@ -27,11 +49,16 @@ edje_frametime_set(double t)
ecore_animator_frametime_set(t);
}
/* FIXDOC: Expand */
/** Get the frametime
* @return The frametime
/**
* @brief Get edje trasitions' frame time.
*
* @return The frame time, in seconds.
*
* This function returns the edje frame time set by
* edje_frametime_set().
*
* @see edje_frametime_set()
*
* Returns the frametime in seconds, by default this is 1/30.
*/
EAPI double
edje_frametime_get(void)
@ -39,13 +66,15 @@ edje_frametime_get(void)
return ecore_animator_frametime_get();
}
/* FIXDOC: Expand */
/** Add a callback for a signal emitted by @a obj.
* @param obj A valid Evas_Object handle
* @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
/**
* @brief Add a callback for a signal emitted by @a obj.
*
* @param obj A valid Evas_Object handle.
* @param emission The signal's name.
* @param source The signal's 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:
@ -69,21 +98,21 @@ edje_frametime_get(void)
* 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.
* Here, @a data is an arbitrary pointer to be used as desired. Note
* that @a emission and @a source correspond respectively to the first
* and the second parameters at the SIGNAL_EMIT action.
*
* Internal edje signals can also be attached to, and globs can be in either
* the emission or source name. e.g.
* Internal edje signals can also be attached to, and globs can occur
* 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").
* "button." will trigger the callback. The actual signal and source
* names 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)
@ -112,17 +141,23 @@ edje_object_signal_callback_add(Evas_Object *obj, const char *emission, const ch
_edje_callbacks_patterns_clean(ed);
}
/** Remove a callback from an object
* @param obj A valid Evas_Object handle
* @param emission the emission string
* @param source the source string
* @param func the callback function
* @return the data pointer
/**
* @brief Remove a signal-triggered callback from an object.
*
* @param obj A valid Evas_Object handle.
* @param emission The emission string.
* @param source The source string.
* @param func The callback function.
* @return The data pointer
*
* This function removes a callback, previously attached to the
* emittion of a signal, from the object @a obj. 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.
*
* @see edje_object_signal_callback_add().
*
* 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))
@ -166,24 +201,22 @@ edje_object_signal_callback_del(Evas_Object *obj, const char *emission, const ch
return NULL;
}
/* FIXDOC: Verify/Expand */
/** Send a signal to the Edje object
* @param obj A vaild Evas_Object handle
* @param emission The signal
* @param source The signal source
/**
* @brief Send a signal to an edje object.
*
* This sends a signal to the edje object.
* @param obj A valid Evas_Object handle.
* @param emission The signal's name.
* @param source The signal's source.
*
* An edje program can respond to a signal by specifying matching 'signal'
* and 'source' fields.
*
* E.g.
* This function sends a signal to the object @a obj. An edje program
* can respond to a signal by specifying matching 'signal' and
* 'source' fields.
*
* @code
* edje_object_signal_emit(obj, "a_signal", "");
* @endcode
*
* will trigger a program whose edc is:
* will trigger a program whose EDC block is:
*
* @code
* program {
@ -194,7 +227,7 @@ edje_object_signal_callback_del(Evas_Object *obj, const char *emission, const ch
* }
* @endcode
*
* FIXME should this signal be sent to children also?
* FIXME: should this signal be sent to children also?
*/
EAPI void
edje_object_signal_emit(Evas_Object *obj, const char *emission, const char *source)
@ -209,12 +242,18 @@ edje_object_signal_emit(Evas_Object *obj, const char *emission, const char *sour
}
/* FIXDOC: Verify/Expand */
/** Set the Edje to play or pause
* @param obj A valid Evas_Object handle
* @param play Play instruction (1 to play, 0 to pause)
/**
* @brief Set the edje object to playing or paused states.
*
* @param obj A valid Evas_Object handle.
* @param play Object state (1 to playing, 0 to pauseed).
*
* This function sets the edje object @a obj to playing or paused
* states, depending on the parameter @a play. This has no effect if
* the object was already at that state.
*
* @see edje_object_play_get().
*
* This sets the Edje to play or pause depending on the parameter.
* This has no effect if the Edje is already in that state.
*/
EAPI void
edje_object_play_set(Evas_Object *obj, int play)
@ -252,11 +291,19 @@ edje_object_play_set(Evas_Object *obj, int play)
}
}
/* FIXDOC: Verify/Expand */
/** Get the Edje play/pause state
* @param obj A valid Evas_Object handle
* @return 0 if Edje not connected, Edje delete_me, or Edje paused\n
* 1 if Edje set to play
/**
* @brief Get the edje object's play/pause state.
*
* @param obj A valid Evas_Object handle.
* @return @c 0 if the object is not connected, its @c delete_me flag
* is set, or it is at paused state; @c 1 if the object is at playing
* state.
*
* This function tells if an edje object is playing or not. This state
* is set by edje_object_play_set().
*
* @see edje_object_play_set().
*
*/
EAPI int
edje_object_play_get(const Evas_Object *obj)
@ -271,11 +318,18 @@ edje_object_play_get(const Evas_Object *obj)
}
/* FIXDOC: Verify/Expand */
/** Set Animation state
* @param obj A valid Evas_Object handle
* @param on Animation State
/**
* @brief Set the object's animation state.
*
* @param obj A valid Evas_Object handle.
* @param on Animation State.
*
* This function starts or stops an edje object's animation. The
* information if it's runnig can be retrieved by
* edje_object_animation_get().
*
* @see edje_object_animation_get()
*
* Stop or start an Edje animation.
*/
EAPI void
edje_object_animation_set(Evas_Object *obj, int on)
@ -334,12 +388,19 @@ edje_object_animation_set(Evas_Object *obj, int on)
_edje_unblock(ed);
}
/* FIXDOC: Verify/Expand */
/** Get the animation state
* @param obj A valid Evas_Object handle
* @return 0 on Error or if not animated\n
* 1 if animated
/**
* @brief Get the edje object's animation state.
*
* @param obj A valid Evas_Object handle.
* @return @c 0 on error or if object is not animated; @c 1 if animated.
*
* This function returns if the animation is playing or not. The
* animation state is set by edje_object_play_set().
*
* @see edje_object_animation_set().
*
*/
EAPI int
edje_object_animation_get(const Evas_Object *obj)
{

613
legacy/edje/src/lib/edje_util.c
View File

File diff suppressed because it is too large Load Diff