From: Radoslaw Czerski Date: Fri, 12 Aug 2016 08:59:20 +0000 (+0200) Subject: Snippets added to doxygen doc. Doc fixes. X-Git-Tag: submit/tizen/20160812.094339~1 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=8b90bb3aaccc3618a1c9eb5daedda3c2d271d65b;p=profile%2Fmobile%2Fapps%2Fnative%2Findicator.git Snippets added to doxygen doc. Doc fixes. Change-Id: I8ff1afab4dd4c7d8419ae10dc4d4f87f8e06cb5d Signed-off-by: Radoslaw Czerski --- diff --git a/inc/bg_color.h b/inc/bg_color.h index 242a9ff..09c9cf4 100644 --- a/inc/bg_color.h +++ b/inc/bg_color.h @@ -25,6 +25,15 @@ * @file bg_color.h */ +/** + * @defgroup bg_color Background color + */ + +/** + * @addtogroup bg_color + * @{ + */ + /** * @brief Registers port for receiving messages from other applications. * @remarks For now it is only used to change indicator background @@ -40,5 +49,8 @@ void message_port_register(void *data); */ void message_port_unregister(void); +/** + * @} + */ #endif /* BG_COLOR_H_ */ diff --git a/inc/box.h b/inc/box.h index 2d45b47..0b51499 100644 --- a/inc/box.h +++ b/inc/box.h @@ -29,6 +29,19 @@ * @file box.h */ +/** + * @defgroup box Box + */ + +/** + * @addtogroup box + * @{ + */ + +/** + * @brief Enumeration for type of addin icons + * + */ typedef enum _Icon_AddType { CANNOT_ADD = -1, CAN_ADD_WITH_DEL_SYSTEM, @@ -37,6 +50,10 @@ typedef enum _Icon_AddType { CAN_ADD_WITHOUT_DEL, } Icon_AddType; +/** + * @brief Enumeration for count of displayed icons per area + * + */ typedef enum _Icon_Display_Count { BATTERY_TEXT_ON_COUNT = 0, BATTERY_TEXT_OFF_COUNT = 0, @@ -54,6 +71,11 @@ typedef enum _Icon_Display_Count { LAND_CONNECTION_SYSTEM_ICON_COUNT = 2, } Icon_Display_Count; + +/** + * @brief Box list + * + */ typedef enum Box_List { FIXED_LIST = 0, SYSTEM_LIST, @@ -62,7 +84,7 @@ typedef enum Box_List { CONNECTION_SYSTEM_LIST } Box_List; -/*** +/** * @brief Adds @a icon to list of icons to show. * * @param[in] icon the icon to add @@ -71,7 +93,7 @@ typedef enum Box_List { */ extern int box_add_icon_to_list(icon_s *icon); -/*** +/** * @brief Appends @a icon to list of icons to show. * * @param[in] icon the icon to append @@ -146,7 +168,7 @@ extern int box_get_max_count_in_non_fixed_list(void); * @retval CAN_ADD_WITHOUT_DEL */ -extern Icon_AddType box_is_enable_to_insert_in_non_fixed_list(icon_s *obj); +extern Icon_AddType box_is_enable_to_insert_in_non_fixed_list(icon_s *icon); /** * @brief Gets priority in move area. @@ -202,7 +224,7 @@ extern int box_handle_animated_gif(icon_s *icon); /** * @brief Handles notification animation. * - * @param[in] icon icon which animation need to be handled + * @param[in] bStart triggers animation start and stop * */ extern void box_noti_ani_handle(int bStart); @@ -250,4 +272,8 @@ extern void box_update_display(win_info *win); */ Evas_Object *box_add(Evas_Object *parent); +/** + * @} + */ + #endif /*__INDICATOR_BOX_UTIL_H__*/ diff --git a/inc/common.h b/inc/common.h index 511e9bb..b5b4bd3 100644 --- a/inc/common.h +++ b/inc/common.h @@ -35,6 +35,15 @@ * @file common.h */ +/** + * @defgroup common Common + */ + +/** + * @addtogroup common + * @{ + */ + /** * @brief Definition of error logs printing function * @@ -105,3 +114,6 @@ #define ECORE_FILE_MONITOR_DELIF(p) ({if (p) {ecore_file_monitor_del(p); p = NULL; }}) +/** + * @} + */ diff --git a/inc/icon.h b/inc/icon.h index 3e3e417..9db00fa 100644 --- a/inc/icon.h +++ b/inc/icon.h @@ -127,4 +127,8 @@ extern void icon_reset_list(void); void check_to_show_more_noti(win_info *win); +/** + * @} + */ + #endif /*__INDICATOR_ICON_UTIL_H__*/ diff --git a/inc/list.h b/inc/list.h index 638537f..91c8715 100644 --- a/inc/list.h +++ b/inc/list.h @@ -26,6 +26,15 @@ * @file list.h */ +/** + * @defgroup list List + */ + +/** + * @addtogroup list + * @{ + */ + /** * @brief Deletes evas object related to specified icon and frees all related data. * @@ -62,26 +71,11 @@ Eina_List *list_list_get(indicator_icon_area_type type); * This is due to limited space on indicator and GUI Guide. * * @param[in] area type of icons are that uniquely defines list of icons - * #INDICATOR_ICON_AREA_FIXED - * #INDICATOR_ICON_AREA_SYSTEM - * #INDICATOR_ICON_AREA_MINICTRL - * #INDICATOR_ICON_AREA_NOTI * * @return count of icons that are set to be visible */ unsigned int list_get_wish_to_show_icons_cnt(enum indicator_icon_area_type area); -/** - * @brief Retrieves count of notification icons that are set to be visible on indicator. - * - * @remarks Number of visible icons may be different that returned value. - * This is due to limited space on indicator and GUI Guide. - * - * @param[in] count_more_noti indicates if more_noti icon should be taken into account or not - * @return count of icons that are set to be visible in notification area - */ -unsigned int list_get_wish_to_show_noti_icons_cnt(bool count_more_noti); - /** * @brief Updates list related to the given icon with the icon. * @@ -91,7 +85,6 @@ unsigned int list_get_wish_to_show_noti_icons_cnt(bool count_more_noti); */ extern void list_update(icon_s *icon); -void list_move_noti_icon_to_top(icon_s *icon); /** * @brief Inserts icon to the list related to the given icon. * @@ -111,9 +104,9 @@ extern void list_insert_icon(icon_s *icon); extern void list_remove_icon(icon_s *icon); /** - * @brief Searches for icon that is pending to be shown, but have not been shown yet. + * @brief Searches for icon that is pending to be shown, but is not shown yet. * - * @param[in] area area of icon - #indicator_icon_area_type + * @param[in] area area of icon - indicator_icon_area_type * @param[in] priority priority of icon * * @return pointer to icon to show, NULL if icon were not found @@ -121,13 +114,19 @@ extern void list_remove_icon(icon_s *icon); extern icon_s *list_try_to_find_icon_to_show(int area, int priority); /** - * @brief Searches for icon to hide due to icons overflow.. + * @brief Searches for icon to be removed from indicator. * - * @param[in] area area of icon - #indicator_icon_area_type - * @param[in] priority priority of icon + * @remarks It searches for visible icon. In fixed are the icon is specified by priority. + * In other areas icon with lowest priority will be choosen. + * + * @param[in] area area from which the icon must be removed - indicator_icon_area_type + * @param[in] priority priority of icon to remove (only for INDICATOR_ICON_AREA_FIXED area) * * @return pointer to icon to show, NULL if icon were not found */ extern icon_s *list_try_to_find_icon_to_remove(int area, int priority); +/** + * @} + */ #endif /*__INDICATOR_ICON_LIST_H__*/ diff --git a/inc/main.h b/inc/main.h index 9f21976..7e7f701 100644 --- a/inc/main.h +++ b/inc/main.h @@ -22,8 +22,6 @@ #define __DEF_indicator_H_ #include -//#include -//FIXME #if 0 #include #endif @@ -33,13 +31,132 @@ /** * @mainpage Indicator documentation * - * @section Overview + * @section overview Overview * * @image html indicator.png * * \n\n * Indiacator app main purpose is to give user quick preview for what is going on in the system - * connections and battery state, time, apps notifications etc. + * \n + * + * @section h_s Helpful snippets + * + * @ref post_noti \n + * @ref update_noti \n + * @ref delete_noti \n\n + * + * @ref bg_change \n + * + * \n\n + * + * + * @subsection post_noti Post notification icon to Indicator app + * + * @code + * #define TAG_FOR_NOTI "example_unique_tag_to_set" + * + * void example_notification_prepare_and_post(void) + * { + * notification_h noti; + * notification_type_e noti_type = NOTIFICATION_TYPE_NOTI; + * notification_image_type_e img_type = NOTIFICATION_IMAGE_TYPE_ICON_FOR_INDICATOR; + * const char *img_path = "example_path_to_notification_icon_in_shared res_folder"; + * int applist = NOTIFICATION_DISPLAY_APP_INDICATOR; + * + * noti = notification_create(noti_type); + * notification_set_image(noti, img_type, img_path); + * notification_set_display_applist(noti, applist); + * notification_set_tag(noti, TAG_FOR_NOTI); + * + * notification_post(noti); + * notification_free(noti); + * } + * @endcode + * @remarks If you want to post notification with icon that is related to minicontroller(play/pause/record etc), + * you need to add tag that consists of "minicontrol_" \n + * \ must be established in cooperation with indicator maintainers. \n\n + * For now six actions/apps are supported in showing minicontrol icons: + * - "call" - notifies about call status(ongoing/outgoing/established) + * - "call_mute" - mute microphone during call + * - "call_speaker" - speaker on during call + * - "music" - play/pause music + * - "video" - play/pause video + * - "voice_recorder" - while recording voice \n\n + * + * e.g. + * To notify about music playing status(play/pause) use following tag: + * @code + * const char *tag = "minicontrol_music"; + * notification_set_tag(noti, tag); + * @endcode + * \n + * + * @subsection update_noti Update notification icon + * + * @code + * void example_notification_update(void) + * { + * const char *img_path_new = "example_path_to_new_notification_icon"; + * notification_image_type_e img_type = NOTIFICATION_IMAGE_TYPE_ICON_FOR_INDICATOR; + * notification_h noti = NULL; + * + * noti = notification_load_by_tag(TAG_FOR_NOTI); + * notification_set_image(noti, img_type, img_path_new); + * + * notification_update(noti); + * notification_free(noti); + * } + * @endcode + * \n + * + * @subsection delete_noti Delete notification icon + * + * @code + * void example_notification_delete(void) + * { + * notification_h noti = NULL; + * noti = notification_load_by_tag(TAG_FOR_NOTI); + * + * notification_delete(noti); + * notification_free(noti); + * } + * @endcode + * \n\n + * + * @subsection bg_change Change indicator background color + * Please note that default state is (0, 0, 0, 255) + * @code + * void example_indicator_bg_change(void) + * { + * bundle *message; + * int ret = 0; + * int rgba_r = 255; + * int rgba_g = 0; + * int rgba_b = 100; + * int rgba_a = 100; + * + * + * char *remote_port_name = "indicator/bg/color"; //That name must not be changed + * + * // Register message port + * port_id = message_port_register_trusted_local_port("port/name/defined/by/you", message_port_cb, NULL); + * // Create and set bundle message + * message = bundle_create(); + * + * ret = bundle_add_str(message, KEY_INDICATOR_BG, VALUE_INDICATOR_BG_RGB); + * ret = bundle_add_byte(message, KEY_R, (const void *)&rgba_r, sizeof(int)); + * ret = bundle_add_byte(message, KEY_G, (const void *)&rgba_g, sizeof(int)); + * ret = bundle_add_byte(message, KEY_B, (const void *)&rgba_b, sizeof(int)); + * ret = bundle_add_byte(message, KEY_A, (const void *)&rgba_a, sizeof(int)); + * + * //Send message + * ret = message_port_send_trusted_message_with_local_port("org.tizen.indicator", remote_port_name, message, port_id); + * + * bundle_free(message); + * } + * @endcode + * */ diff --git a/inc/modules.h b/inc/modules.h index 80c7b4d..1daf046 100644 --- a/inc/modules.h +++ b/inc/modules.h @@ -30,6 +30,16 @@ * @file modules.h */ + +/** + * @defgroup modules Modules + */ + +/** + * @addtogroup modules + * @{ + */ + #define TIMER_STOP ECORE_CALLBACK_CANCEL #define TIMER_CONTINUE ECORE_CALLBACK_RENEW @@ -64,6 +74,8 @@ extern void modules_region_changed(void *data); /** * @brief Propagates minicontrol action request to all initialized modules. * + * @param[in] action action + * @param[in] name name * @param[in] data the app data */ extern void modules_minictrl_control(int action, const char* name, void *data); @@ -89,4 +101,10 @@ extern void modules_init_first(void *data); #ifdef _SUPPORT_SCREEN_READER extern void modules_register_tts(void *data); #endif -#endif + +/** + * @} + */ + +#endif /* __INDICATOR_MODULES_H__ */ + diff --git a/inc/more_notify.h b/inc/more_notify.h index b43c44a..06d7c4a 100644 --- a/inc/more_notify.h +++ b/inc/more_notify.h @@ -25,13 +25,26 @@ * @file more_notify.h */ +/** + * @defgroup more_noti More Notification + */ + +/** + * @addtogroup more_noti + * @{ + */ + /** * @brief Shows or Hides more notify icon. * - * @remarks The icon should be shown only if non fixed icon count exceeds #PORT_NONFIXED_ICON_COUNT + * @remarks The icon should be shown only if non fixed icon count exceeds PORT_NONFIXED_ICON_COUNT * * @param[in] val If EINA_TRUE, the icon will be shown, If EINA_FALSE, the icon will be hidden */ void indicator_more_notify_icon_change(Eina_Bool val); +/** + * @} + */ + #endif /* MORE_NOTIFY_H_ */ diff --git a/inc/ticker.h b/inc/ticker.h index 7ce0df2..a632e92 100644 --- a/inc/ticker.h +++ b/inc/ticker.h @@ -25,25 +25,39 @@ * @file ticker.h */ +/** + * @defgroup ticker Ticker + */ + +/** + * @addtogroup ticker + * @{ + */ + +/** + * @brief Enumeration for animated icon type + */ typedef enum _indicator_animated_icon_type { INDICATOR_ANIMATED_ICON_NONE = -1, INDICATOR_ANIMATED_ICON_DOWNLOAD = 1, INDICATOR_ANIMATED_ICON_UPLOAD, INDICATOR_ANIMATED_ICON_INSTALL, } indicator_animated_icon_type; - +/** + * @brief Definition for ticker data structure + */ typedef struct ticker { - Evas_Object *scroller; - Evas_Object *textblock; - Ecore_Timer *timer; - Eina_List *ticker_list; - int current_page; - int pages; + Evas_Object *scroller; /**< Scroller*/ + Evas_Object *textblock; /**< text block for notification content*/ + Ecore_Timer *timer; /**< timer*/ + Eina_List *ticker_list; /**< List for notifications*/ + int current_page; /**< Current page*/ + int pages; /**< Number of pages*/ } ticker_info_s; -/*** +/** * @brief Initializes ticker module. * * @remarks Ticker module is registered for receiving notifications @@ -54,7 +68,7 @@ typedef struct ticker { */ extern int ticker_init(void *data); -/*** +/** * @brief Deinitializes ticker module. * * @param[in] data the app data @@ -63,4 +77,9 @@ extern int ticker_init(void *data); */ extern int ticker_fini(void *data); -#endif + +/** + * @} + */ + +#endif /* __INDICATOR_TICKER_H__ */ diff --git a/inc/toast_popup.h b/inc/toast_popup.h index 43c2223..9be82c4 100644 --- a/inc/toast_popup.h +++ b/inc/toast_popup.h @@ -25,6 +25,15 @@ * @file toast_popup.h */ +/** + * @defgroup toast_popup Toast Popup + */ + +/** + * @addtogroup toast_popup + * @{ + */ + /** * @brief Initializes toast popup module. * @@ -41,4 +50,8 @@ int indicator_toast_popup_init(void *data); */ int indicator_toast_popup_fini(void); +/** + * @} + */ + #endif /* __INDICATOR_TOAST_POPUP_H___ */ diff --git a/inc/util.h b/inc/util.h index 0efab08..c4f4742 100644 --- a/inc/util.h +++ b/inc/util.h @@ -31,6 +31,15 @@ * @file util.h */ +/** + * @defgroup util Util + */ + +/** + * @addtogroup util + * @{ + */ + typedef enum { INDICATOR_ERROR_NONE = 0, INDICATOR_ERROR_FAIL = -1, @@ -117,7 +126,7 @@ extern const char *util_get_icon_dir(void); * @brief Emits specified signal. * * @param[in] data the app data - * @paran[in] emission signal to emit + * @param[in] emission signal to emit * @param[in] source signal source * */ @@ -127,7 +136,7 @@ extern void util_signal_emit(void* data, const char *emission, const char *sourc * @brief Emits text to specified part. * * @param[in] data the app data - * @paran[in] part part name + * @param[in] part part name * @param[in] text text to emit */ extern void util_part_text_emit(void* data, const char *part, const char *text); @@ -136,7 +145,7 @@ extern void util_part_text_emit(void* data, const char *part, const char *text); * @brief Emits text to specified part using win info structure to get layout. * * @param[in] data win info - * @paran[in] emission signal to emit + * @param[in] emission signal to emit * @param[in] source signal source */ extern void util_signal_emit_by_win(void* data, const char *emission, const char *source); @@ -145,7 +154,7 @@ extern void util_signal_emit_by_win(void* data, const char *emission, const char * @brief Emits text to specified part using win info structure to get layout. * * @param[in] data win info - * @paran[in] part part name + * @param[in] part part name * @param[in] text text to emit */ extern void util_part_text_emit_by_win(void* data, const char *part, const char *text); @@ -154,7 +163,7 @@ extern void util_part_text_emit_by_win(void* data, const char *part, const char * @brief Sets image to part content. * * @param[in] data the app data - * @paran[in] part part name + * @param[in] part part name * @param[in] img_path path to image to set */ extern void util_part_content_img_set(void *data, const char *part, const char *img_path); @@ -171,17 +180,17 @@ extern void util_launch_search(void* data); * * @return 0 if PWLOCK is set to VCONFKEY_PWLOCK_BOOTING_UNLOCK or VCONFKEY_PWLOCK_RUNNING_UNLOCK, -1 otherwise * - * @see #VCONFKEY_PWLOCK_BOOTING_UNLOCK - * @see #VCONFKEY_PWLOCK_BOOTING_LOCK - * @see #VCONFKEY_PWLOCK_RUNNING_UNLOCK - * @see #VCONFKEY_PWLOCK_RUNNING_LOCK + * @see VCONFKEY_PWLOCK_BOOTING_UNLOCK + * @see VCONFKEY_PWLOCK_BOOTING_LOCK + * @see VCONFKEY_PWLOCK_RUNNING_UNLOCK + * @see VCONFKEY_PWLOCK_RUNNING_LOCK */ extern int util_check_system_status(void); /** * @brief Gets timezone from vconf. * - * @param[in/out] timezone id or "N/A" on failure + * @param[in,out] timezone id or "N/A" on failure */ extern void util_get_timezone_str(char **timezone); @@ -242,6 +251,7 @@ extern void util_send_status_message_start(void *data, double duration); /** * @brief Replaces char in string. * + * @param text text to replace in * @param to_replace char to replace * @param replacer char that will replace @a to_replace char */ @@ -273,9 +283,12 @@ extern Ecore_File_Monitor *util_file_monitor_add(const char *file_path, Ecore_Fi extern void util_file_monitor_remove(Ecore_File_Monitor *file_monitor); /** - * @brief Gets substring that starts with specified @str_search string. + * @brief Gets substring that starts with specified @a str_search string. + * + * @param str string to search in + * @param str_search string to search * - * @param substring or NULL if substring not found + * @return substring or NULL if substring not found */ extern char *util_safe_str(const char *str, const char *str_search); @@ -315,7 +328,7 @@ enum app_subdir { /** * @brief Returns absolute path to resource file located in applications directory. * - * @param subdir type of subdirectory + * @param dir type of subdirectory * @param relative path of resource in application's subdir. * eg. for DATA_DIR subdir and relative "database.db" => "/home/owner/apps/org.tizen.homescreen-efl/data/database.db" * @return absolute path string. @@ -335,7 +348,7 @@ const char *util_get_file_path(enum app_subdir dir, const char *relative); /** * @brief Initializes WiFi using wifi_initialize API - * @remarks If WiFi is already initialized, #WIFI_ERROR_NONE will be returned. + * @remarks If WiFi is already initialized, WIFI_ERROR_NONE will be returned. * @return 0 on success, other value on failure */ int util_wifi_initialize(void); @@ -418,4 +431,8 @@ int util_runtime_info_set_changed_cb(runtime_info_key_e key, runtime_info_change */ void util_runtime_info_unset_changed_cb(runtime_info_key_e key, runtime_info_changed_cb cb); +/** + * @} + */ + #endif /* __INDICATOR_UTIL_H__ */