From f499de5bc476bed8ec7ac61be192db9b6c3354dd Mon Sep 17 00:00:00 2001 From: Woochanlee Date: Mon, 25 Oct 2021 19:37:43 +0900 Subject: [PATCH] libaurum: Add doc for Accessible, AtspiAccessible classes Change-Id: I3ddc06de57dea697a2a522c6750beeed6b576e08 --- .../inc/Accessibility/AccessibleApplication.h | 57 ++++++++ .../inc/Accessibility/AccessibleWatcher.h | 73 ++++++---- libaurum/inc/Accessibility/AccessibleWindow.h | 51 +++++-- libaurum/inc/Accessibility/IEventConsumer.h | 38 +++++- libaurum/inc/Accessibility/IEventSource.h | 40 +++++- .../AtspiAccessibleApplication.h | 26 +++- .../Accessibility/AtspiAccessibleWatcher.h | 128 ++++++------------ .../Accessibility/AtspiAccessibleWindow.h | 22 ++- .../inc/Impl/Accessibility/AtspiWrapper.h | 11 +- libaurum/src/Accessibility/AccessibleNode.cc | 4 +- .../src/Accessibility/AccessibleWatcher.cc | 4 +- .../Accessibility/AtspiAccessibleWatcher.cc | 4 +- 12 files changed, 314 insertions(+), 144 deletions(-) diff --git a/libaurum/inc/Accessibility/AccessibleApplication.h b/libaurum/inc/Accessibility/AccessibleApplication.h index 9701b30..097d141 100644 --- a/libaurum/inc/Accessibility/AccessibleApplication.h +++ b/libaurum/inc/Accessibility/AccessibleApplication.h @@ -23,18 +23,75 @@ #include +/** + * @class AccessibleApplication + * + * @ingroup aurum + * + * @brief Class that matches atspi Application Node. + * It provides information such as active window, application name. + */ class AccessibleApplication { public: + /** + * @brief AccessibleApplication constructor. + * + * @since_tizen 5.5 + */ AccessibleApplication(std::shared_ptr node); + + /** + * @brief AccessibleApplication destructor. + * + * @since_tizen 5.5 + */ virtual ~AccessibleApplication(); public: + /** + * @brief Gets matched @AccessibleNode. + * + * @return @AccessibleNode + * + * @since_tizen 5.5 + */ std::shared_ptr getAccessibleNode(); + + /** + * @brief Checks this active or not. + * + * @return true if it actives, else false + * + * @since_tizen 5.5 + */ bool isActive(void); public: + /** + * @brief Gets application's window. + * + * @return @AccessibleWindow vector + * + * @since_tizen 5.5 + */ virtual std::vector> getWindows(void) = 0; + + /** + * @brief Gets currently active window. + * + * @return @AccessibleWindow vector + * + * @since_tizen 5.5 + */ virtual std::vector> getActiveWindows(void); + + /** + * @brief Gets application package name. + * + * @return string + * + * @since_tizen 5.5 + */ virtual std::string getPackageName(void) = 0; private: diff --git a/libaurum/inc/Accessibility/AccessibleWatcher.h b/libaurum/inc/Accessibility/AccessibleWatcher.h index 6c77556..d2977f2 100644 --- a/libaurum/inc/Accessibility/AccessibleWatcher.h +++ b/libaurum/inc/Accessibility/AccessibleWatcher.h @@ -34,95 +34,116 @@ #include "config.h" /** - * @brief AccessibleWatcher class - * @since_tizen 5.5 + * @class AccessibleWatcher + * + * @ingroup aurum + * + * @brief Class that communicates with the atspi sever and generates an event, + * and generates a node that matches with atspi node. */ class AccessibleWatcher : public IEventSource { public: /** - * @brief TBD + * @brief AccessibleWatcher constructor. + * * @since_tizen 5.5 */ AccessibleWatcher(); /** - * @brief TBD + * @brief AccessibleWatcher destructor. + * * @since_tizen 5.5 */ virtual ~AccessibleWatcher(); /** - * @brief TBD + * @brief Gets @AccessibleWatcher instance. + * * @since_tizen 5.5 */ static AccessibleWatcher *getInstance(AccessibleWatcher *watcherImpl = nullptr); public: /** - * @brief TBD + * @brief Gets current running application count in device. + * + * @return application count + * * @since_tizen 5.5 */ virtual int getApplicationCount(void) const = 0; /** - * @brief TBD + * @brief Gets application class at specific index. + * + * @param[in] index application index + * + * @return @AccessibleApplication ptr + * * @since_tizen 5.5 */ virtual std::shared_ptr getApplicationAt(int index) const = 0; /** - * @brief TBD + * @brief Gets application node vector. + * + * @return @AccessibleApplication vector + * * @since_tizen 5.5 */ virtual std::vector> getApplications(void) const = 0; /** - * @brief TBD + * @brief Executes runnable command and wait given event. + * + * @param[in] cmd @Runnable + * @param[in] type @A11yEvent + * @param[in] timeout time(millisecond) to wait event occur + * + * @return true if event occur in time, else false + * * @since_tizen 6.5 */ virtual bool executeAndWaitForEvents(const Runnable *cmd, const A11yEvent type, const int timeout) = 0; /** - * @brief TBD + * @brief Gets active application map. + * + * @return map (pure Atspi Node ptr(@AtspiAccessible), @AccessibleApplication) * @since_tizen 6.5 */ virtual std::map> getActiveAppMap(void) = 0; public: /** - * @brief TBD + * @brief Gets active application vector. + * + * @return @AccessibleApplication vector + * * @since_tizen 5.5 */ virtual std::vector> getActiveApplications(void) const; + public: /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc @IEventSource::attach() */ void attach(std::shared_ptr source) override; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc @IEventSource::detach() */ void detach(std::shared_ptr source) override; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc @IEventSource::notifyAll() */ - void notifyAll(int type, int type2, void *src) override; + void notifyAll(int type1, int type2, void *src) override; private: - /** - * @brief TBD - */ std::set> mSources; - - /** - * @brief TBD - */ std::mutex mLock; }; -#endif \ No newline at end of file +#endif diff --git a/libaurum/inc/Accessibility/AccessibleWindow.h b/libaurum/inc/Accessibility/AccessibleWindow.h index 751a774..f422d68 100644 --- a/libaurum/inc/Accessibility/AccessibleWindow.h +++ b/libaurum/inc/Accessibility/AccessibleWindow.h @@ -25,60 +25,81 @@ class AccessibleApplication; +/** + * @class AccessibleWindow + * + * @ingroup aurum + * + * @brief Class that matches atspi Window Node. + * It provides information such as window title, window properties. + */ class AccessibleWindow { public: /** - * @brief TBD + * @brief AccessibleWindow constructor. + * + * @param[in] app @AccessibleApplication + * @param[in] node @AccessibleNode + * * @since_tizen 6.0 */ AccessibleWindow(std::shared_ptr app, std::shared_ptr node); /** - * @brief TBD + * @brief AccessibleWindow destructor. + * * @since_tizen 6.0 */ virtual ~AccessibleWindow(); public: /** - * @brief TBD + * @brief Gets window title. + * + * @return string + * * @since_tizen 6.0 */ std::string getTitle(void); /** - * @brief TBD + * @brief Checks current window showing or not. + * + * @return true if it is showing, else false + * * @since_tizen 6.0 */ bool isShowing(); /** - * @brief TBD + * @brief Checks current window active or not. + * + * @return true if it actives, else false + * * @since_tizen 6.0 */ bool isActive(); /** - * @brief TBD + * @brief Gets the application node that this window belongs. + * + * @return @AccessibleApplication ptr + * * @since_tizen 6.0 */ std::shared_ptr getApplication(void); /** - * @brief TBD - * @since_tizen 6.0 + * @brief Gets matched @AccessibleNode. + * + * @return @AccessibleNode + * + * @since_tizen 5.5 */ std::shared_ptr getAccessibleNode(void); private: - /** - * @brief TBD - */ std::shared_ptr mApp; - - /** - * @brief TBD - */ std::shared_ptr mNode; }; diff --git a/libaurum/inc/Accessibility/IEventConsumer.h b/libaurum/inc/Accessibility/IEventConsumer.h index fe4b7d8..d8cd29a 100644 --- a/libaurum/inc/Accessibility/IEventConsumer.h +++ b/libaurum/inc/Accessibility/IEventConsumer.h @@ -18,21 +18,57 @@ #ifndef _IEVENT_CONSUMER_H_ #define _IEVENT_CONSUMER_H_ +/** + * @class EventType + * + * @ingroup aurum + * + * @brief Enum class for Event Type. + */ enum class EventType { none = 0, Object = 1, }; +/** + * @class ObjectEventType + * + * @ingroup aurum + * + * @brief Enum class for Object Event Type. + */ enum class ObjectEventType { none = 0, ObjectStateDefunct = 1, }; +/** + * @class IEventConsumer + * + * @ingroup aurum + * + * @brief Class for Event generate. + */ class IEventConsumer { public: + /** + * @brief IEventConsumer destructor. + * + * @since_tizen 5.5 + */ virtual ~IEventConsumer() {}; - virtual void notify(int type, int type2, void *src) = 0; + + /** + * @brief Notifies event to source node. + * + * @param[in] type1 @EventType + * @param[in] type2 @ObjectEventType + * @param[in] src source Node ptr + * + * @since_tizen 5.5 + */ + virtual void notify(int type1, int type2, void *src) = 0; }; #endif diff --git a/libaurum/inc/Accessibility/IEventSource.h b/libaurum/inc/Accessibility/IEventSource.h index cdb2196..d1f6ce4 100644 --- a/libaurum/inc/Accessibility/IEventSource.h +++ b/libaurum/inc/Accessibility/IEventSource.h @@ -21,13 +21,51 @@ #include "IEventConsumer.h" #include +/** + * @class IEventSource + * + * @ingroup aurum + * + * @brief Class for Event generate. + */ class IEventSource { public: + /** + * @brief IEventSource destructor. + * + * @since_tizen 5.5 + */ virtual ~IEventSource() {}; + + /** + * @brief Attaches event source. + * + * @param[in] source @IEventConsumer + * + * @since_tizen 5.5 + */ virtual void attach(std::shared_ptr source) = 0; + + /** + * @brief Detaches event source. + * + * @param[in] source @IEventConsumer + * + * @since_tizen 5.5 + */ virtual void detach(std::shared_ptr source) = 0; - virtual void notifyAll(int type, int type2, void *src) = 0; + + /** + * @brief Notifies all attached event. + * + * @param[in] type1 @EventType + * @param[in] type2 @ObjectEventType + * @param[in] src source Node ptr + * + * @since_tizen 5.5 + */ + virtual void notifyAll(int type1, int type2, void *src) = 0; }; #endif diff --git a/libaurum/inc/Impl/Accessibility/AtspiAccessibleApplication.h b/libaurum/inc/Impl/Accessibility/AtspiAccessibleApplication.h index 626abb9..a6cdb80 100644 --- a/libaurum/inc/Impl/Accessibility/AtspiAccessibleApplication.h +++ b/libaurum/inc/Impl/Accessibility/AtspiAccessibleApplication.h @@ -23,32 +23,44 @@ #include #include +/** + * @internal + * + * @class AtspiAccessibleApplication + * + * @ingroup aurum + * + * @brief Class that matches atspi Application Node. + * It provides information such as active window, application name. + */ class AtspiAccessibleApplication : public AccessibleApplication, public std::enable_shared_from_this { public: /** - * @brief TBD + * @brief AtspiAccessibleApplication constructor. + * + * @param[in] node @AccessibleNode + * * @since_tizen 6.0 */ AtspiAccessibleApplication(std::shared_ptr node); /** - * @brief TBD + * @brief AtspiAccessibleApplication destructor. + * * @since_tizen 6.0 */ virtual ~AtspiAccessibleApplication(); public: /** - * @brief TBD - * @since_tizen 6.0 + * @copydoc @AccessibleApplication::getWindows() */ std::vector> getWindows(void) override; /** - * @brief TBD - * @since_tizen 6.0 + * @copydoc @AccessibleApplication::getPackageName() */ std::string getPackageName(void) override; }; -#endif \ No newline at end of file +#endif diff --git a/libaurum/inc/Impl/Accessibility/AtspiAccessibleWatcher.h b/libaurum/inc/Impl/Accessibility/AtspiAccessibleWatcher.h index e53dc38..f4ed61f 100644 --- a/libaurum/inc/Impl/Accessibility/AtspiAccessibleWatcher.h +++ b/libaurum/inc/Impl/Accessibility/AtspiAccessibleWatcher.h @@ -33,7 +33,10 @@ #include /** - * @brief WindowActivateInfoType enum class + * @internal + * + * @brief WindowActivateInfoType enum class. + * * @since_tizen 5.5 */ enum class WindowActivateInfoType { @@ -44,6 +47,8 @@ enum class WindowActivateInfoType { }; /** + * @internal + * * @brief IAtspiEvents Interface * @since_tizen 5.5 */ @@ -62,7 +67,16 @@ public: virtual void onObjectDefunct(AtspiAccessible *node) = 0; }; - +/** + * @internal + * + * @class AtspiAccessibleWatcher + * + * @ingroup aurum + * + * @brief Class that communicates with the atspi sever and generates an event, + * and generates a node that matches with atspi node. + */ class AtspiAccessibleWatcher : public AccessibleWatcher, public IAtspiEvents { public: AtspiAccessibleWatcher(); @@ -70,128 +84,76 @@ public: public: /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc @AccessibleWatcher::getApplicationCount() */ virtual int getApplicationCount(void) const override; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc @AccessibleWatcher::getApplicationAt() */ virtual std::shared_ptr getApplicationAt(int index) const override; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc @AccessibleWatcher::getApplications() */ virtual std::vector> getApplications(void) const override; /** - * @brief TBD - * @since_tizen 6.5 + * @copydoc @AccessibleWatcher::executeAndWaitForEvents() */ virtual bool executeAndWaitForEvents(const Runnable *cmd, const A11yEvent type, const int timeout) override; + /** + * @copydoc @AccessibleWatcher::getActiveAppMap() + */ virtual std::map> getActiveAppMap(void) override; public: /** - * @brief TBD + * @brief Listen atspi events. + * + * @param[in] event AtspiEvent + * @param[in] watcher @AtspiAccessibleWatcher + * * @since_tizen 5.5 */ - static void onAtspiEvents(AtspiEvent *event, void *user_data); + static void onAtspiEvents(AtspiEvent *event, void *watcher); /** - * @brief TBD + * @brief Notifies when object defunct. + * + * @param[in] node @AtspiAccessible + * * @since_tizen 5.5 */ void onObjectDefunct(AtspiAccessible *node) override; /** - * @brief TBD + * @brief AtspiEvent listener. + * + * @param[in] event AtspiEvent + * @param[in] user_data data for event by user + * * @since_tizen 6.5 */ static void onEventListener(AtspiEvent *event, void *user_data); private: - /** - * @brief TBD - * @since_tizen 5.5 - */ + /** Private methods for Mock Test **/ bool removeFromActivatedList(AtspiAccessible *node); - - /** - * @brief TBD - * @since_tizen 5.5 - */ bool addToActivatedList(AtspiAccessible *node); - - /** - * @brief TBD - * @since_tizen 5.5 - */ bool removeFromWindowSet(AtspiAccessible *node); - - /** - * @brief TBD - * @since_tizen 5.5 - */ bool addToWindowSet(AtspiAccessible *node); - - /** - * @brief TBD - * @since_tizen 6.5 - */ void addEventListener(AtspiEventListener *listener, A11yEvent type); - - /** - * @brief TBD - * @since_tizen 6.5 - */ void removeEventListener(AtspiEventListener *listener, A11yEvent type); -public: - /** - * @brief TBD - */ - static guint timeoutId; - private: - /** - * @brief TBD - */ - GDBusProxy * mDbusProxy; - - /** - * @brief TBD - */ - std::list mActivatedWindowList; - - /** - * @brief TBD - */ - std::list mActivatedApplicationList; - - /** - * @brief TBD - */ - std::set mWindowSet; - - /** - * @brief TBD - */ + GDBusProxy *mDbusProxy; + std::list mActivatedWindowList; + std::list mActivatedApplicationList; + std::set mWindowSet; std::map> mActiveAppMap; - - /** - * @brief TBD - */ - static GThread * mEventThread; - - /** - * @brief TBD - */ - static std::vector> mEventQueue; - + static GThread *mEventThread; + static std::vector> mEventQueue; static std::mutex mMutex; }; diff --git a/libaurum/inc/Impl/Accessibility/AtspiAccessibleWindow.h b/libaurum/inc/Impl/Accessibility/AtspiAccessibleWindow.h index a303bc0..e9d6f71 100644 --- a/libaurum/inc/Impl/Accessibility/AtspiAccessibleWindow.h +++ b/libaurum/inc/Impl/Accessibility/AtspiAccessibleWindow.h @@ -20,17 +20,31 @@ #include "AccessibleWindow.h" +/** + * @internal + * + * @class AtspiAccessibleWindow + * + * @ingroup aurum + * + * @brief Class that matches atspi Window Node. + */ class AtspiAccessibleWindow : public AccessibleWindow { public: /** - * @brief TBD - * @since_tizen 6.0 + * @brief AtspiAccessibleWindow constructor. + * + * @param[in] app @AccessibleApplication + * @param[in] node @AccessibleNode + * + * @since_tizen 5.5 */ AtspiAccessibleWindow(std::shared_ptr app, std::shared_ptr node); /** - * @brief TBD - * @since_tizen 6.0 + * @brief AtspiAccessibleWindow desturctor. + * + * @since_tizen 5.5 */ ~AtspiAccessibleWindow(); diff --git a/libaurum/inc/Impl/Accessibility/AtspiWrapper.h b/libaurum/inc/Impl/Accessibility/AtspiWrapper.h index 9ff87f6..ee603d6 100644 --- a/libaurum/inc/Impl/Accessibility/AtspiWrapper.h +++ b/libaurum/inc/Impl/Accessibility/AtspiWrapper.h @@ -21,8 +21,18 @@ #include #include +/** + * @internal + * + * @class AtspiWrapper + * + * @ingroup aurum + * + * @brief Class that matches atspi Window Node. + */ class AtspiWrapper { public: + /** Wrapper methods for Atspi APIs **/ static GArray *Atspi_state_set_get_states(AtspiStateSet *set); static GArray *Atspi_accessible_get_interfaces(AtspiAccessible *node); static gchar *Atspi_accessible_get_name(AtspiAccessible *node, GError **error); @@ -49,7 +59,6 @@ public: private: static std::recursive_mutex mMutex; - //static std::unique_lock mLock; }; #endif diff --git a/libaurum/src/Accessibility/AccessibleNode.cc b/libaurum/src/Accessibility/AccessibleNode.cc index 5bd1a4f..45c3993 100644 --- a/libaurum/src/Accessibility/AccessibleNode.cc +++ b/libaurum/src/Accessibility/AccessibleNode.cc @@ -50,11 +50,11 @@ std::string AccessibleNode::description() { return ss.str(); } -void AccessibleNode::notify(int type, int type2, void *src) +void AccessibleNode::notify(int type1, int type2, void *src) { void *handler = getRawHandler(); - if ((EventType)type == EventType::Object && (ObjectEventType)type2 == ObjectEventType::ObjectStateDefunct) { + if ((EventType)type1 == EventType::Object && (ObjectEventType)type2 == ObjectEventType::ObjectStateDefunct) { if (handler == src) invalidate(); } } diff --git a/libaurum/src/Accessibility/AccessibleWatcher.cc b/libaurum/src/Accessibility/AccessibleWatcher.cc index 77b571f..5b6bc3a 100644 --- a/libaurum/src/Accessibility/AccessibleWatcher.cc +++ b/libaurum/src/Accessibility/AccessibleWatcher.cc @@ -88,10 +88,10 @@ void AccessibleWatcher::detach(std::shared_ptr source) } } -void AccessibleWatcher::notifyAll(int type, int type2, void *src) +void AccessibleWatcher::notifyAll(int type1, int type2, void *src) { std::unique_lock lock(mLock); std::for_each(mSources.begin(), mSources.end(), [&](auto source){ - source->notify(type, type2, src); + source->notify(type1, type2, src); }); } diff --git a/libaurum/src/Impl/Accessibility/AtspiAccessibleWatcher.cc b/libaurum/src/Impl/Accessibility/AtspiAccessibleWatcher.cc index 9a6441e..a167104 100644 --- a/libaurum/src/Impl/Accessibility/AtspiAccessibleWatcher.cc +++ b/libaurum/src/Impl/Accessibility/AtspiAccessibleWatcher.cc @@ -155,14 +155,14 @@ AtspiAccessibleWatcher::~AtspiAccessibleWatcher() atspi_exit(); } -void AtspiAccessibleWatcher::onAtspiEvents(AtspiEvent *event, void *user_data) +void AtspiAccessibleWatcher::onAtspiEvents(AtspiEvent *event, void *watcher) { if (!event->source) { return; } char *name = NULL, *pkg = NULL; - AtspiAccessibleWatcher *instance = (AtspiAccessibleWatcher *)user_data; + AtspiAccessibleWatcher *instance = (AtspiAccessibleWatcher *)watcher; name = AtspiWrapper::Atspi_accessible_get_name(event->source, NULL); AtspiAccessible *app = AtspiWrapper::Atspi_accessible_get_application(event->source, NULL); -- 2.34.1