From 42ceb58540bd78466badbd4499353787c0caca7e Mon Sep 17 00:00:00 2001 From: Mike Blumenkrantz Date: Fri, 6 Jul 2012 10:53:22 +0000 Subject: [PATCH] merge a big e17 doc patch ticket #91 SVN revision: 73408 --- src/bin/e_config.c | 19 +++++++++++++++++++ src/bin/e_config_data.h | 28 ++++++++++++++++++++++++++++ src/bin/e_config_dialog.c | 13 +++++++++++++ src/bin/e_configure.c | 32 ++++++++++++++++++++++++++++++++ src/bin/e_gadcon.c | 21 +++++++++++++++++++++ src/bin/e_theme.c | 9 +++++++++ src/bin/e_widget_check.c | 32 ++++++++++++++++++++++++++++++++ src/bin/e_widget_entry.c | 5 ++++- src/bin/e_widget_label.c | 13 +++++++++++++ src/bin/e_widget_list.c | 18 ++++++++++++++++++ src/bin/e_widget_slider.c | 2 +- 11 files changed, 190 insertions(+), 2 deletions(-) diff --git a/src/bin/e_config.c b/src/bin/e_config.c index 0aaecc729..8a027458e 100644 --- a/src/bin/e_config.c +++ b/src/bin/e_config.c @@ -1556,6 +1556,15 @@ e_config_save_block_get(void) return _e_config_save_block; } +/** + * Loads configurations from file located in the working profile + * The configurations are stored in a struct declated by the + * macros E_CONFIG_DD_NEW and E_CONFIG_TYPE + * + * @param domain of the configuration file. + * @param edd to struct definition + * @return returns allocated struct on success, if unable to find config returns null + */ EAPI void * e_config_domain_load(const char *domain, E_Config_DD *edd) { @@ -1703,6 +1712,16 @@ e_config_profile_save(void) return ok; } +/** + * Saves configurations to file located in the working profile + * The configurations are read from a struct declated by the + * macros E_CONFIG_DD_NEW and E_CONFIG_TYPE + * + * @param domain name of the configuration file. + * @param edd pointer to struct definition + * @param data struct to save as configuration file + * @return 1 if save success, 0 on failure + */ EAPI int e_config_domain_save(const char *domain, E_Config_DD *edd, const void *data) { diff --git a/src/bin/e_config_data.h b/src/bin/e_config_data.h index bfb645dbf..2a65a05ad 100644 --- a/src/bin/e_config_data.h +++ b/src/bin/e_config_data.h @@ -1,11 +1,39 @@ #ifdef E_TYPEDEFS +/** \def E_CONFIG_DD_NEW(str, typ) + * is used to create definition of a struct + * \str str name to give to struct + * \typ typ the actual struct type + */ #define E_CONFIG_DD_NEW(str, typ) \ e_config_descriptor_new(str, sizeof(typ)) + +/** \def E_CONFIG_DD_FREE(eed) + * is used to free definition of a struct + * \eed eed the pointer created by \link #E_CONFIG_DD_NEW + */ #define E_CONFIG_DD_FREE(eed) if (eed) { eet_data_descriptor_free((eed)); (eed) = NULL; } #define E_CONFIG_VAL(edd, type, member, dtype) EET_DATA_DESCRIPTOR_ADD_BASIC(edd, type, #member, member, dtype) #define E_CONFIG_SUB(edd, type, member, eddtype) EET_DATA_DESCRIPTOR_ADD_SUB(edd, type, #member, member, eddtype) + +/** \def E_CONFIG_LIST(edd, type, member, eddtype) + * declares a struct member to be included definition + * list type must be Evas_List and not Ecore_List + * \edd edd the pointer created by \link #E_CONFIG_DD_NEW + * \type type struct type + * \member member member of struct + * \eddtype struct definition to use for each entry in the list + */ #define E_CONFIG_LIST(edd, type, member, eddtype) EET_DATA_DESCRIPTOR_ADD_LIST(edd, type, #member, member, eddtype) + +/** \def E_CONFIG_HASH(edd, type, member, eddtype) + * declares a struct member to be included definition + * list type must be Evas_Hash and not Ecore_Hash + * \edd edd the pointer created by \link #E_CONFIG_DD_NEW + * \type type struct type + * \member member member of struct + * \eddtype struct definition to use for each entry in the hash + */ #define E_CONFIG_HASH(edd, type, member, eddtype) EET_DATA_DESCRIPTOR_ADD_HASH(edd, type, #member, member, eddtype) #define CHAR EET_T_CHAR diff --git a/src/bin/e_config_dialog.c b/src/bin/e_config_dialog.c index e18104240..6b6147d10 100644 --- a/src/bin/e_config_dialog.c +++ b/src/bin/e_config_dialog.c @@ -18,6 +18,19 @@ static Eina_List *_e_config_dialog_list = NULL; /* externally accessible functions */ +/** + * Creates a new dialog + * + * @param con the container the dialog will be added too + * @param title to display for the dialog + * @param name the name used to register the window in e + * @param class the call used to register the window in e + * @param icon the path to the icon file + * @param icon_size is of the width and height of the icon + * @param view the callbacks used to create the dialog and save the settings + * @param data additional data to attach to the dialog, will be passed to the callbacks + * @return returns the created dialog. Null on failure + */ EAPI E_Config_Dialog * e_config_dialog_new(E_Container *con, const char *title, const char *name, const char *class, const char *icon, int icon_size, E_Config_Dialog_View *view, void *data) { diff --git a/src/bin/e_configure.c b/src/bin/e_configure.c index 868f0e65a..58d749e42 100644 --- a/src/bin/e_configure.c +++ b/src/bin/e_configure.c @@ -100,6 +100,11 @@ e_configure_registry_item_params_add(const char *path, int pri, const char *labe _e_configure_registry_item_full_add(path, pri, label, icon_file, icon, func, NULL, NULL, params); } +/** + * Delete an item in the configuration panel. + * + * @param path location the item to delete + */ EAPI void e_configure_registry_item_del(const char *path) { @@ -132,6 +137,16 @@ e_configure_registry_item_del(const char *path) free(cat); } +/** + * Add a category to the configuration panel. + * + * @param path location the new category + * @param pri the priority for sorting the category in the category list + * @param label the name the user will see in configuration panel + * @param icon_file the edje file that holds the icon for the category. + * Can be null to use current theme. + * @param icon the name of the edje group to use as icon + */ EAPI void e_configure_registry_category_add(const char *path, int pri, const char *label, const char *icon_file, const char *icon) { @@ -161,6 +176,11 @@ e_configure_registry_category_add(const char *path, int pri, const char *label, e_configure_registry = eina_list_append(e_configure_registry, ecat); } +/** + * Delete a category in the configuration panel. + * + * @param path location the category to delete + */ EAPI void e_configure_registry_category_del(const char *path) { @@ -185,6 +205,18 @@ e_configure_registry_category_del(const char *path) free(cat); } +/** + * Add a item to the configuration panel. + * + * @param path location the location to place configuration item + * @param pri the priority for sorting the item in the category list + * @param label the name the user will see in configuration panel + * @param icon_file the edje file that holds the icon for the category. + * Can be null to use current theme. + * @param icon the name of the edje group to use as icon + * @param func the callback to use when the configuration item is clicked + */ + EAPI void e_configure_registry_custom_desktop_exec_callback_set(void (*func)(const void *data, E_Container *con, const char *params, Efreet_Desktop *desktop), const void *data) { diff --git a/src/bin/e_gadcon.c b/src/bin/e_gadcon.c index 260cb0b4d..d725e601e 100644 --- a/src/bin/e_gadcon.c +++ b/src/bin/e_gadcon.c @@ -220,6 +220,12 @@ e_gadcon_shutdown(void) return 1; } +/** + * Registers a new gadget class in e + * + * @param cc version of gadcon, name and callbacks to use + * for handling creation and destroying a gadget + */ EAPI void e_gadcon_provider_register(const E_Gadcon_Client_Class *cc) { @@ -229,6 +235,11 @@ e_gadcon_provider_register(const E_Gadcon_Client_Class *cc) _e_gadcon_provider_populate_request(cc); } +/** + * unregisters a gadget class in e + * + * @param cc the gadget class that was used to register the gadget + */ EAPI void e_gadcon_provider_unregister(const E_Gadcon_Client_Class *cc) { @@ -848,6 +859,16 @@ e_gadcon_client_config_del(E_Config_Gadcon *cf_gc, E_Config_Gadcon_Client *cf_gc free(cf_gcc); } +/** + * Creates a new gadget + * + * @param gc gadcon pointer + * @param name to use for gadget + * @param id assigned to gadget + * @param style to for gadget + * @param base_obj the evas object that will show up in the shelf or gadget module + * @return returns pointer to created gadget, on failure returns null + */ EAPI E_Gadcon_Client * e_gadcon_client_new(E_Gadcon *gc, const char *name, const char *id __UNUSED__, const char *style, Evas_Object *base_obj) { diff --git a/src/bin/e_theme.c b/src/bin/e_theme.c index 3ae15e52d..efe020420 100644 --- a/src/bin/e_theme.c +++ b/src/bin/e_theme.c @@ -83,6 +83,15 @@ e_theme_shutdown(void) return 1; } +/** + * Assigns a edje group from the current theme to + * a recently created edje object + * + * @param o edje object to assign group to + * @param category that hold the required edj file + * @param group the edje group to use + * @return returns true on success, false if unable to assign group + */ EAPI int e_theme_edje_object_set(Evas_Object *o, const char *category, const char *group) { diff --git a/src/bin/e_widget_check.c b/src/bin/e_widget_check.c index 74f6a86cb..fbfb9378e 100644 --- a/src/bin/e_widget_check.c +++ b/src/bin/e_widget_check.c @@ -19,6 +19,15 @@ static void _e_wid_focus_steal(void *data, Evas *e, Evas_Object *obj, void *even /* local subsystem functions */ /* externally accessible functions */ + +/** + * Creates a check box widget + * + * @param evas pointer + * @param label the text to asign to check widget + * @param val pointer to int where changes are stored + * @return the newly created evas object + */ EAPI Evas_Object * e_widget_check_add(Evas *evas, const char *label, int *val) { @@ -57,6 +66,12 @@ e_widget_check_add(Evas *evas, const char *label, int *val) return obj; } +/** + * Sets the value of the check box + * + * @param check the check box widget + * @param checked the value to set the widget too + */ EAPI void e_widget_check_checked_set(Evas_Object *check, int checked) { @@ -71,6 +86,12 @@ e_widget_check_checked_set(Evas_Object *check, int checked) edje_object_signal_emit(wd->o_check, "e,state,unchecked", "e"); } +/** + *Get the value of the check box + * + * @param check the check box widget + * @return the value of the check box + */ EAPI int e_widget_check_checked_get(Evas_Object *check) { @@ -86,6 +107,17 @@ e_widget_check_checked_get(Evas_Object *check) return ret; } +/** + * Creates a check box widget with icon + * + * @param evas pointer + * @param label the text to asign to check widget + * @param icon the path to the icon file + * @param icon_w the minimum wdith of the icon + * @param icon_h the minumum height of the icon + * @param val pointer to int where changes are stored + * @return the newly created evas object + */ EAPI Evas_Object * e_widget_check_icon_add(Evas *evas, const char *label, const char *icon, int icon_w, int icon_h, int *val) { diff --git a/src/bin/e_widget_entry.c b/src/bin/e_widget_entry.c index 4657761aa..1ab41d13f 100644 --- a/src/bin/e_widget_entry.c +++ b/src/bin/e_widget_entry.c @@ -27,6 +27,9 @@ static void _e_wid_keydown(void *data, Evas *e, Evas_Object *obj, void *event_in * * @param evas the evas where to add the new entry widget * @param text_location the location where to store the text of the entry. + * @param func DOCUMENT ME! + * @param data DOCUMENT ME! + * @param data2 DOCUMENT ME! * The current value will be used to initialize the entry * @return Returns the new entry widget */ @@ -140,7 +143,7 @@ e_widget_entry_password_set(Evas_Object *entry, int password_mode) * allows copying and selecting, just no inserting or deleting of text. * * @param entry an entry widget - * @param readonly 1 to enable read-only mode, 0 to turn it off + * @param readonly_mode 1 to enable read-only mode, 0 to turn it off */ EAPI void e_widget_entry_readonly_set(Evas_Object *entry, int readonly_mode) diff --git a/src/bin/e_widget_label.c b/src/bin/e_widget_label.c index 5b07a75d8..7c34aa05d 100644 --- a/src/bin/e_widget_label.c +++ b/src/bin/e_widget_label.c @@ -11,6 +11,13 @@ static void _e_wid_del_hook(Evas_Object *obj); static void _e_wid_disable_hook(Evas_Object *obj); /* externally accessible functions */ +/** + * Creates a new label widget + * + * @param evas pointer + * @param text to assign to the widget + * @return the label widget + */ EAPI Evas_Object * e_widget_label_add(Evas *evas, const char *label) { @@ -39,6 +46,12 @@ e_widget_label_add(Evas *evas, const char *label) return obj; } +/** + * Changes the text for the label + * + * @param the label widget + * @param text to assign to the widget + */ EAPI void e_widget_label_text_set(Evas_Object *obj, const char *text) { diff --git a/src/bin/e_widget_list.c b/src/bin/e_widget_list.c index b20c7011d..25e1e35f7 100644 --- a/src/bin/e_widget_list.c +++ b/src/bin/e_widget_list.c @@ -11,6 +11,14 @@ static void _e_wid_del_hook(Evas_Object *obj); /* local subsystem functions */ /* externally accessible functions */ +/** + * Creates a new list widget + * + * @param evas the evas pointer + * @param homogenous should widgets append to the list be evenly spaced out + * @param horiz the direction the list should be displayed + * @return the new list wdiget + */ EAPI Evas_Object * e_widget_list_add(Evas *evas, int homogenous, int horiz) { @@ -34,6 +42,16 @@ e_widget_list_add(Evas *evas, int homogenous, int horiz) return obj; } +/** + * Append a widget to the list + * + * @param obj the list widget to append the sub widget too + * @param sobj the sub widget + * @param fill DOCUMENT ME! + * @param expand DOCUMENT ME! + * @param align who the sub widget to be aligned, to wards the center or sides + * @return the new list wdiget + */ EAPI void e_widget_list_object_append(Evas_Object *obj, Evas_Object *sobj, int fill, int expand, double align) { diff --git a/src/bin/e_widget_slider.c b/src/bin/e_widget_slider.c index 6344113e9..971899a1b 100644 --- a/src/bin/e_widget_slider.c +++ b/src/bin/e_widget_slider.c @@ -87,7 +87,7 @@ e_widget_slider_value_double_set(Evas_Object *slider, double dval) * if the slider was not created with an integer value. * * @param slider pointer to the slider to be modified - * @param int the integer value to set the slider to + * @param ival the integer value to set the slider to * @return 1 if value set, return 0 if value not set */ EAPI int