From: Woochan Lee Date: Wed, 11 May 2016 14:25:37 +0000 (+0900) Subject: Doxygen update. X-Git-Tag: submit/tizen/20160617.075742~35^2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=37680bc2ef4e315d0fe36d54bfac74a683d8a516;p=platform%2Fcore%2Fuifw%2Fui-viewmgr.git Doxygen update. Change-Id: I596583d6f9c744ef345de83c340700b5e1bebdc3 --- diff --git a/src/include/efl/mobile/ui_app.h b/src/include/efl/mobile/ui_app.h index 6898589..7201188 100644 --- a/src/include/efl/mobile/ui_app.h +++ b/src/include/efl/mobile/ui_app.h @@ -25,25 +25,91 @@ class ui_viewmgr; class ui_app { public: + ///Constructor. ui_app(const char *pkg, const char *locale_dir); + + ///Destructor. virtual ~ui_app(); + /** + * @brief Return the viewmgr instance. + * + * @return ui_viewmgr instance. + */ ui_viewmgr *get_viewmgr(); + + /** + * @brief Return ui_app instance. + */ static ui_app *get_instance(); + /** + * @brief Application life-cycle start and add application event callback functions add. + * + * @note This is calling ui_app_main function to start application life-cycle start. + * and adding all of the functions for application events handling such as + * create, terminate, pause, resume, app_control, APP_EVENT_LOW_BATTERY, APP_EVENT_LOW_MEMORY + * APP_EVENT_DEVICE_ORIENTATION_CHANGED, APP_EVENT_LANGUAGE_CHANGED, APP_EVENT_REGION_FORMAT_CHANGED. + * Application can add those events using wrapping functions by viewmgr supported. + */ virtual int run(int argc, char **argv); protected: + /** + * @brief Calling before the main event loop start. + * + * @note Take necessary actions like a Initialize UI resources and application data. + * + * @return If this function returns true, the application main loop starts. + * If this function returns false, the application terminates. + */ virtual bool on_create(); + + /** + * @brief Calling before the main event loop finish. + * + * @note Release all resources here. + */ virtual void on_terminate(); + + /** + * @brief Calling when application becomes invisible. + */ virtual void on_pause(); + + /** + * @brief Calling when application becomes visible. + */ virtual void on_resume(); + + /** + * @brief Calling when gets a launch request event. + */ virtual void on_control(app_control_h app_control); + /** + * @brief Calling when device low battery. + */ virtual void on_low_battery(app_event_info_h event_info); + + /** + * @brief Calling when device low memory. + */ virtual void on_low_memory(app_event_info_h event_info); + + /** + * @brief Calling when device region changed. + */ virtual void on_region_changed(app_event_info_h event_info); + + /** + * @brief Calling when device orient changed. + */ virtual void on_orient_changed(app_event_info_h event_info); + + /** + * @brief Calling when language changed. + */ virtual void on_lang_changed(app_event_info_h event_info); private: diff --git a/src/include/efl/mobile/ui_key_listener.h b/src/include/efl/mobile/ui_key_listener.h index 8f9724a..bed9327 100644 --- a/src/include/efl/mobile/ui_key_listener.h +++ b/src/include/efl/mobile/ui_key_listener.h @@ -32,9 +32,21 @@ class ui_viewmgr; class ui_key_listener : public ui_base_key_listener { public: + ///Constructor. ui_key_listener(ui_viewmgr *viewmgr); + /** + * @brief Init H/W key listener to grab key event(menu key). + * + * @note Add menu key to target of key grabber. + */ virtual bool init(); + + /** + * @brief Check the menu key event. + * + * @note This is checking H/W key is menu or not. + */ virtual void extend_event_proc(ui_base_view *view, Evas_Event_Key_Down *ev); }; diff --git a/src/include/efl/mobile/ui_menu.h b/src/include/efl/mobile/ui_menu.h index 29f19ee..0cbc841 100644 --- a/src/include/efl/mobile/ui_menu.h +++ b/src/include/efl/mobile/ui_menu.h @@ -36,18 +36,76 @@ class ui_view; class ui_menu: public ui_base_overlay { public: + /** @brief menu activate. + * + * @note It makes menu state as show. + * + * @return true if it succeed, false otherwise. + * + * @see deactivate() + */ virtual bool activate(); + + /** @brief menu deactivate. + * + * @note It makes menu state as hide. + * + * @return true if it succeed, false otherwise. + * + * @see activate() + */ virtual bool deactivate(); + + /** @brief This is for replacing or setting a content of the menu. + * + * @param ctxpopup ctxpopup object. It allows @c NULL for canceling the previous content. + * + * @return true if it succeed, false otherwise. + */ virtual bool set_content(Elm_Ctxpopup* ctxpopup); + + /** @brief This is for unsetting a content of the menu. + * + * @return A previous content. If it wasn't, return value will be @c NULL. + */ virtual Elm_Ctxpopup *unset_content(); + + /** + * @brief Return the active status of menu. + * + * @return @c true if overlay is activated, @c false otherwise. + * + * @see activate() + * @see deactivate() + */ virtual bool is_activated(); + /** + * @brief Get a base window of viewmgr. + * + * @return viewmgr's window object. + */ virtual Evas_Object *get_base(); + + /** + * @brief Get current menu's degree. + * + * @return Current rotation degree, -1 if it fails to get degree information. + */ virtual int get_degree(); protected: + ///Constructor. ui_menu(ui_view *view); + + ///Destructor. virtual ~ui_menu(); + + /** + * @brief Get a base window of viewmgr. + * + * @return viewmgr's window object. + */ Elm_Win *get_window(); private: diff --git a/src/include/efl/mobile/ui_popup.h b/src/include/efl/mobile/ui_popup.h index 9b0233e..52132ee 100644 --- a/src/include/efl/mobile/ui_popup.h +++ b/src/include/efl/mobile/ui_popup.h @@ -38,19 +38,76 @@ class ui_view; class ui_popup : public ui_base_overlay { public: + ///Constructor. ui_popup(ui_view *view); + + ///Destructor. virtual ~ui_popup(); + /** @brief popup activate. + * + * @note It makes popup state as show. + * + * @return true if it succeed, false otherwise. + * + * @see deactivate() + */ virtual bool activate(); + + /** @brief popup deactivate. + * + * @note It makes popup state as hide. + * + * @return true if it succeed, false otherwise. + * + * @see activate() + */ virtual bool deactivate(); + + /** @brief This is for replacing or setting a content of the popup. + * + * @param popup popup object. It allows @c NULL for canceling the previous content. + * + * @return true if it succeed, false otherwise. + */ virtual bool set_content(Elm_Popup* popup); + + /** @brief This is for unsetting a content of the popup. + * + * @return A previous content. If it wasn't, return value will be @c NULL. + */ virtual Elm_Popup *unset_content(); + + /** + * @brief Return the active status of popup. + * + * @return @c true if overlay is activated, @c false otherwise. + * + * @see activate() + * @see deactivate() + */ virtual bool is_activated(); + /** + * @brief Get a base window of viewmgr. + * + * @return viewmgr's window object. + */ virtual Evas_Object *get_base(); + + /** + * @brief Get current popup's degree. + * + * @return Current rotation degree, -1 if it fails to get degree information. + */ virtual int get_degree(); protected: + /** + * @brief Get a base window of viewmgr. + * + * @return viewmgr's window object. + */ virtual Elm_Win *get_window(); private: diff --git a/src/include/efl/mobile/ui_standard_view.h b/src/include/efl/mobile/ui_standard_view.h index 063fd31..1da1cff 100644 --- a/src/include/efl/mobile/ui_standard_view.h +++ b/src/include/efl/mobile/ui_standard_view.h @@ -36,32 +36,162 @@ namespace efl_viewmanager class ui_standard_view: public ui_view { public: + ///Constructor. ui_standard_view(const char *name = NULL); + + ///Destructor. virtual ~ui_standard_view(); + /** @brief This is for replacing or setting a content of the view. + * + * @param content a new content. It allows @c NULL for canceling the previous content. + * @param title title_label The label in the title area. The name of the title label part is "elm.text.title" + * + * @return true if it succeed, false otherwise. + */ bool set_content(Evas_Object *content, const char *title = NULL); + + /** @brief This is for replacing or setting a content of the view. + * + * @param content a new content. It allows @c NULL for canceling the previous content. + * @param title The label in the title area. The name of the title label part is "elm.text.title". + * @param subtitle The label in the subtitle area. The name of the subtitle label part is "elm.text.subtitle". + * @param title_left_btn The button in the left part of title area. + * @param title_right_btn The button in the right part of title area. + * + * @return true if it succeed, false otherwise. + */ bool set_content(Evas_Object *content, const char *title, const char *subtitle, Elm_Button *title_left_btn, Elm_Button *title_right_btn); + + /** + * @brief This is for setting title badge text. + * + * @param text The label in the title badge area. + */ bool set_title_badge(const char *text); + + /** + * @brief This is for setting subtitle text. + * + * @param text The label in the subtitle area. + */ bool set_subtitle(const char *text); + + /** + * @brief This is for setting title_left_btn. + * + * @param title_left_btn The button in the left part of title area. + */ bool set_title_left_btn(Elm_Button *title_left_btn); + + /** + * @brief This is for setting title_right_btn. + * + * @param title_right_btn The button in the right part of title area. + */ bool set_title_right_btn(Elm_Button *title_right_btn); + + /** + * @brief This is for setting title text. + * + * @param text The label in the title area. + */ bool set_title(const char *text); + + /** + * @brief This is for setting toolbar below title. + * + * @param toolbar Toolbar object. + */ bool set_toolbar(Elm_Toolbar *toolbar); + + /** + * @brief This is handling title visible state. + * + * @param visible title state set as visible if the given param is true, otherwise title area set as invisible. + * @param anim title area will be shown with animation if the given param is true, otherwise title area will be shown without animation. + */ bool set_title_visible(bool visible, bool anim); + + /** + * @brief This is for unsetting a content of the view. + * + * @return A previous content. If it wasn't, return value will be @c NULL. + */ Evas_Object *unset_content(); + + /** + * @brief This is for unsetting a title left button of title area. + * + * @return A previous content. If it wasn't, return value will be @c NULL. + */ Elm_Button *unset_title_left_btn(); + + /** + * @brief This is for unsetting a title right button of title area. + * + * @return A previous content. If it wasn't, return value will be @c NULL. + */ Elm_Button *unset_title_right_btn(); + + /** + * @brief This is for unsetting a toolbar. + * + * @return A previous content. If it wasn't, return value will be @c NULL. + */ Elm_Toolbar *unset_toolbar(); + /** + * @brief Return a title left button of the view. + * + * @return title left button of the view. + */ Elm_Button *get_title_left_btn(); + + /** + * @brief Return a title right button of the view. + * + * @return title right button of the view. + */ Elm_Button *get_title_right_btn(); + + /** + * @brief Return a toolbar of the view. + * + * @return toolbar of the view. + */ Elm_Toolbar *get_toolbar(); + /** + * @brief Get a base layout of viewmgr. + * + * @return viewmgr's base layout object. + */ virtual Evas_Object *get_base(); protected: + /** + * @brief view load state. + * + * @note this state will be triggered by ui_iface_viewmgr. + * + */ virtual void on_load(); + + /** @brief view unload state. + * + * @note this state will be triggered by ui_iface_viewmgr. + * + */ virtual void on_unload(); + + /** @brief toggle event block. + * + * @note This interface is designed for toggling touch event on view transition. + * ui_iface_viewmgr will call this interface for notifying event blocking toggling on transition time. + * + * @param block @c true, when blocking is enabled, otherwise @c false. + */ virtual void set_event_block(bool block); private: diff --git a/src/include/efl/mobile/ui_view.h b/src/include/efl/mobile/ui_view.h index 20b62ee..48156e7 100644 --- a/src/include/efl/mobile/ui_view.h +++ b/src/include/efl/mobile/ui_view.h @@ -36,18 +36,82 @@ class ui_key_listener; class ui_view: public ui_base_view { public: + ///Constructor. ui_view(const char *name = NULL); + + ///Destructor. virtual ~ui_view(); + /** + * @brief Get menu object. + * + * @return menu object if any. + */ const ui_menu *get_menu(); protected: + /** + * @brief This is making ui_menu instance. + * + * @note It creates ui_menu instance, if there is no ui_menu instance of this view. + * It hides menu if there is already menu activated. + * + * @return menu instance of this view. NULL If the menu already activated. + */ virtual ui_menu *on_menu_pre(); + + /** + * @brief Activate menu. + * + * @note It calls activate() for posting menu. If there is a menu instance. + */ virtual void on_menu_post(); + + /** + * @brief H/W back key event occurs on view. + * + * @param menu menu instance, This is made by key listener when menu key occured. + */ virtual void on_menu(ui_menu *menu); + + /** + * @brief H/W back key event occurs on view. + * + * @note User can override this function to define application specific action when H/W back key + * event occurs. otherwise current view will be popped. + */ virtual void on_back(); + + /** + * @brief view rotate changed. + * + * @note This state will be called when view rotation changed. + * + * @param degree Current view's degree. + * + * @see on_portrait() + * @see on_landscpae() + */ virtual void on_rotate(int degree); + + /** + * @brief view portrait state. + * + * @note This state will be called when view rotation changed to portrait. + * + * @see on_landscpae() + * @see on_rotate() + */ virtual void on_portrait(); + + /** + * @brief view landscape state. + * + * @note This state will be called when view rotation changed to landscape. + * + * @see on_portrait() + * @see on_rotate() + */ virtual void on_landscape(); /** @brief view deactivate state. @@ -58,7 +122,18 @@ protected: virtual void on_deactivate(); private: + /** + * @brief Push given popup instance in the internal popup stack. + * + * @param popup ui_popup instance + */ void connect_popup(ui_popup *popup); + + /** + * @brief pop given popup instance in the internal popup stack. + * + * @param popup ui_popup instance + */ void disconnect_popup(ui_popup *popup); _UI_DECLARE_PRIVATE_IMPL(ui_view); diff --git a/src/include/efl/ui_base_key_listener.h b/src/include/efl/ui_base_key_listener.h index b14b3e1..e41ab32 100644 --- a/src/include/efl/ui_base_key_listener.h +++ b/src/include/efl/ui_base_key_listener.h @@ -35,14 +35,49 @@ class ui_base_viewmgr; class ui_base_key_listener { protected: + ///Constructor. ui_base_key_listener(ui_base_viewmgr *viewmgr); + + ///Destructor. virtual ~ui_base_key_listener(); + /** + * @brief Init H/W key listener to grab key event(back key). + * + * @note It makes evas_object_rectangle and add key up callback. + * + * @see term() + */ virtual bool init(); + + /** + * @brief Terminate H/W key listener. + * + * @note Delete key grabber(evas_object_rectangle). + * + * @see init() + */ virtual bool term(); + + /** + * @brief Check the menu key event. + * + * @note This is checking H/W key is menu or not. + */ virtual void extend_event_proc(ui_base_view *view, Evas_Event_Key_Down *ev) {} + /** + * @brief Return the viewmgr instance. + * + * @return ui_base_viewmgr instance. + */ ui_base_viewmgr *get_viewmgr(); + + /** + * @brief Return the key grabber(evas_object_rectangle). + * + * @return key grabber object. + */ Evas_Object *get_keygrab_obj(); private: diff --git a/src/include/efl/ui_base_overlay.h b/src/include/efl/ui_base_overlay.h index 3781c80..f81854b 100644 --- a/src/include/efl/ui_base_overlay.h +++ b/src/include/efl/ui_base_overlay.h @@ -35,7 +35,10 @@ class ui_base_view; class ui_base_overlay: public ui_iface_overlay { protected: + ///Constructor. ui_base_overlay(ui_base_view *view); + + ///Destructor. virtual ~ui_base_overlay(); }; diff --git a/src/include/efl/ui_base_view.h b/src/include/efl/ui_base_view.h index 75937e0..607d751 100644 --- a/src/include/efl/ui_base_view.h +++ b/src/include/efl/ui_base_view.h @@ -84,8 +84,36 @@ protected: */ virtual void set_event_block(bool block); + /** + * @brief view rotate changed. + * + * @note This state will be called when view rotation changed. + * + * @param degree Current view's degree. + * + * @see on_portrait() + * @see on_landscpae() + */ virtual void on_rotate(int degree); + + /** + * @brief view portrait state. + * + * @note This state will be called when view rotation changed to portrait. + * + * @see on_landscpae() + * @see on_rotate() + */ virtual void on_portrait(); + + /** + * @brief view landscape state. + * + * @note This state will be called when view rotation changed to landscape. + * + * @see on_portrait() + * @see on_rotate() + */ virtual void on_landscape(); private: diff --git a/src/include/efl/ui_base_viewmgr.h b/src/include/efl/ui_base_viewmgr.h index 024db21..f37fa19 100644 --- a/src/include/efl/ui_base_viewmgr.h +++ b/src/include/efl/ui_base_viewmgr.h @@ -153,11 +153,17 @@ public: Evas_Object *get_base(); protected: + /** + * @brief Set indicator of the view. + * + * @param indicator The mode to set, one of #ui_view_indicator + */ bool set_indicator(ui_view_indicator indicator); ///Constructor ui_base_viewmgr(const char *pkg, ui_base_key_listener *key_listener); ui_base_viewmgr(const char *pkg); + ///Destructor. virtual ~ui_base_viewmgr(); diff --git a/src/include/interface/ui_iface_overlay.h b/src/include/interface/ui_iface_overlay.h index 981edf0..21ca0f4 100644 --- a/src/include/interface/ui_iface_overlay.h +++ b/src/include/interface/ui_iface_overlay.h @@ -35,18 +35,78 @@ class ui_iface_view; class ui_iface_overlay: public ui_iface_rotatable { public: + /** @brief This is for replacing or setting a content of the view. + * + * @note @p content is a logical object that represents a view in your framework. The actual type of the content could be translated to any certain types. + * For instance, the type could be Evas_Object * in EFL and Layer * in Dali. + * + * @param content a new content. It allows @c NULL for canceling the previous content. + * + * @return true if it succeed, false otherwise. + */ virtual bool set_content(T content); + + /** @brief This is for unsetting a content of the view. + * + * @return A previous content. If it wasn't, return value will be @c NULL. + */ virtual T unset_content(); + + /** @brief H/W back key event occurs on view. + * + * @note User can override this function to define application specific action when H/W back key + * event occurs. otherwise current view will be popped. + */ virtual void on_back(); + + /** @brief Overlay activate. + * + * @note It makes overlay state as show. + * + * @return true if it succeed, false otherwise. + * + * @see deactivate() + */ virtual bool activate(); + + /** @brief Overlay deactivate. + * + * @note It makes overlay state as hide. + * + * @return true if it succeed, false otherwise. + * + * @see activate() + */ virtual bool deactivate(); + + /** + * @brief Return the active status of overlay. + * + * @return @c true if overlay is activated, @c false otherwise. + * + * @see activate() + * @see deactivate() + */ virtual bool is_activated(); + /** + * @brief Return a view which is matched with the overlay. + * + * @return The view which is matched with overlay. + */ ui_iface_view *get_view(); + + /** @brief Return a content instance of this overlay. + * + * @return content of overlay. + */ virtual T get_content(); protected: + ///Constructor. ui_iface_overlay(ui_iface_view *view); + + ///Destructor. virtual ~ui_iface_overlay(); private: diff --git a/src/include/interface/ui_iface_rotatable.h b/src/include/interface/ui_iface_rotatable.h index da2e569..fda9abd 100644 --- a/src/include/interface/ui_iface_rotatable.h +++ b/src/include/interface/ui_iface_rotatable.h @@ -31,8 +31,36 @@ namespace ui_viewmanager class ui_iface_rotatable { protected: + /** + * @brief view portrait state. + * + * @note This state will be called when view rotation changed to portrait. + * + * @see on_landscpae() + * @see on_rotate() + */ virtual void on_portrait() {} + + /** + * @brief view landscape state. + * + * @note This state will be called when view rotation changed to landscape. + * + * @see on_portrait() + * @see on_rotate() + */ virtual void on_landscape() {} + + /** + * @brief view rotate changed. + * + * @note This state will be called when view rotation changed. + * + * @param degree Current view's degree. + * + * @see on_portrait() + * @see on_landscpae() + */ virtual void on_rotate(int degree) {} public: diff --git a/src/include/interface/ui_iface_view.h b/src/include/interface/ui_iface_view.h index 3e17f9b..60ad785 100644 --- a/src/include/interface/ui_iface_view.h +++ b/src/include/interface/ui_iface_view.h @@ -143,6 +143,11 @@ public: */ ui_view_indicator get_indicator(); + /** @brief H/W back key event occurs on view. + * + * @note User can override this function to define application specific action when H/W back key + * event occurs. otherwise current view will be popped. + */ virtual void on_back(); protected: @@ -220,7 +225,21 @@ protected: bool get_event_block(); private: + + /** @brief Connect with given viewmgr. + * + * @return true if it succeed, false otherwise. + * + * @see get_viewmgr() + */ bool set_viewmgr(ui_iface_viewmgr *viewmgr); + + /** @brief Return the viewmgr instance. + * + * @return ui_iface_viewmgr instance. + * + * @see set_viewmgr() + */ ui_iface_viewmgr *get_viewmgr(); _UI_DECLARE_PRIVATE_IMPL(ui_iface_view); diff --git a/src/include/interface/ui_iface_viewmanager.h b/src/include/interface/ui_iface_viewmanager.h index abb9251..7ebe660 100644 --- a/src/include/interface/ui_iface_viewmanager.h +++ b/src/include/interface/ui_iface_viewmanager.h @@ -19,16 +19,22 @@ #include +/** + * Possible values for indicator state. + */ enum ui_view_indicator { - UI_VIEW_INDICATOR_DEFAULT = 0, - UI_VIEW_INDICATOR_OPTIMAL, - UI_VIEW_INDICATOR_OVERLAP, - UI_VIEW_INDICATOR_HIDE, - UI_VIEW_INDICATOR_SHOW, + UI_VIEW_INDICATOR_DEFAULT = 0, ///