From 4340140e4f617ec4a0d303c9fb8722fa565924c1 Mon Sep 17 00:00:00 2001 From: Woochanlee Date: Wed, 20 Oct 2021 15:49:30 +0900 Subject: [PATCH] libaurum: Add doc for Object(Node) classes Change-Id: I6c2272926e6b3f2e0faa5bfc613170af37f66586 --- libaurum/inc/Accessibility/AccessibleNode.h | 242 +++++++-------- .../Impl/Accessibility/AtspiAccessibleNode.h | 73 ++--- libaurum/inc/UiDevice.h | 2 +- libaurum/inc/UiObject.h | 280 ++++++++++++------ 4 files changed, 335 insertions(+), 262 deletions(-) diff --git a/libaurum/inc/Accessibility/AccessibleNode.h b/libaurum/inc/Accessibility/AccessibleNode.h index cf80129..a6956a4 100644 --- a/libaurum/inc/Accessibility/AccessibleNode.h +++ b/libaurum/inc/Accessibility/AccessibleNode.h @@ -30,6 +30,7 @@ /** * @brief AccessibleNodeInterface enum class + * * @since_tizen 5.5 */ enum class AccessibleNodeInterface { @@ -53,6 +54,7 @@ enum class AccessibleNodeInterface { /** * @brief NodeFeatureProperties enum class + * * @since_tizen 5.5 */ enum class NodeFeatureProperties { @@ -75,381 +77,351 @@ enum class NodeFeatureProperties { }; /** - * @brief AccessibleNode Class + * @brief AccessibleNode Class that provides the abstracted object information to uses. + * * @since_tizen 5.5 */ class AccessibleNode : public std::enable_shared_from_this, public IEventConsumer { public: /** - * @brief TBD + * @brief AccessibleNode constructor. + * * @since_tizen 5.5 */ AccessibleNode(); /** - * @brief TBD + * @brief AccessibleNode desctructor. + * * @since_tizen 5.5 */ virtual ~AccessibleNode(); /** - * @brief TBD + * @brief Gets Node information as string. + * + * @return string + * * @since_tizen 5.5 */ std::string description(); public: /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::getChildCount() */ virtual int getChildCount() const = 0; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::getChildAt() */ virtual std::shared_ptr getChildAt(int index) const = 0; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::getChildren() */ virtual std::vector> getChildren() const = 0; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::getParent() */ virtual std::shared_ptr getParent() const = 0; /** - * @brief TBD + * @brief Called by @AccessibleWatcher::notifyAll. + * Changes Node property If it's @EventType, @ObjectEventType are matches. + * + * @param[in] type @EventType + * @param[in] type2 @ObjectEventType + * @param[in] src Atspi Node ptr + * * @since_tizen 5.5 */ void notify(int type, int type2, void *src) override; /** - * @brief TBD + * @brief Changes Node state to invalidate. + * * @since_tizen 5.5 */ void invalidate(); public: /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::getText() */ std::string getText() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::getPkg() */ std::string getPkg() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::getId() */ std::string getId() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::getAutomationId() */ std::string getAutomationId() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::getRole() */ std::string getRole() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::getType() */ std::string getType() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::getStyle() */ std::string getStyle() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::getScreenBoundingBox() */ Rect getScreenBoundingBox() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::getWindowBoundingBox() */ Rect getWindowBoundingBox() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::isCheckable() */ bool isCheckable() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::isChecked() */ bool isChecked() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::isClickable() */ bool isClickable() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::isEnabled() */ bool isEnabled() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::isFocusable() */ bool isFocusable() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::isFocused() */ bool isFocused() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::isLongClickable() */ bool isLongClickable() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::isScrollable() */ bool isScrollable() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::isSelectable() */ bool isSelectable() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::isSelected() */ bool isSelected() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::isVisible() */ bool isVisible() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::isShowing() */ bool isShowing() const; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::isActive() */ bool isActive() const; public: /** - * @brief TBD + * @brief Print Node information. + * + * @param[in] int depth + * * @since_tizen 5.5 */ void print(int); /** - * @brief TBD + * @brief Print Node information. + * + * @param[in] int depth + * @param[in] int maxdepth + * * @since_tizen 5.5 */ void print(int, int); /** - * @brief TBD + * @brief Gets matched Atspi node ptr. + * + * @return Atspi node ptr + * * @since_tizen 5.5 */ virtual void* getRawHandler(void) const = 0; /** - * @brief TBD - * @since_tizen 6.5 + * @copydoc UiObject::updateRoleName() */ virtual void updateRoleName() = 0; /** - * @brief TBD - * @since_tizen 6.5 + * @copydoc UiObject::updateUniqueId() */ virtual void updateUniqueId() = 0; /** - * @brief TBD - * @since_tizen 6.5 + * @copydoc UiObject::updateName() */ virtual void updateName() = 0; /** - * @brief TBD - * @since_tizen 6.5 + * @copydoc UiObject::updateApplication() */ virtual void updateApplication() = 0; /** - * @brief TBD - * @since_tizen 6.5 + * @copydoc UiObject::updateAttributes() */ virtual void updateAttributes() = 0; /** - * @brief TBD - * @since_tizen 6.5 + * @copydoc UiObject::updateStates() */ virtual void updateStates() = 0; /** - * @brief TBD - * @since_tizen 6.5 + * @copydoc UiObject::updateExtents() */ virtual void updateExtents() = 0; /** - * @brief TBD + * @brief Updates Node information from atspi server. + * * @since_tizen 5.5 */ virtual void refresh() = 0; /** - * @brief TBD + * @brief Gets available atspi action name. + * + * @return string vector + * * @since_tizen 5.5 */ virtual std::vector getActions() const = 0; /** - * @brief TBD + * @brief Do atspi action. + * + * @param[in] action name of action + * + * @return true if success, else false + * * @since_tizen 5.5 */ virtual bool doAction(std::string action) = 0; /** - * @brief TBD + * @brief Sets Node's value. + * + * @param[in] text string + * * @since_tizen 5.5 */ virtual void setValue(std::string text) = 0; /** - * @brief TBD + * @brief Check object valid or not. + * + * @return true if valid, else false + * * @since_tizen 5.5 */ virtual bool isValid() const; public: /** - * @brief TBD + * @brief Check Node support given interface or not. + * + * @param[in] thisIface @AccessibleNodeInterface + * + * @return true if supporting, else false + * * @since_tizen 5.5 */ bool isSupporting(AccessibleNodeInterface thisIface) const; /** - * @brief TBD + * @brief Check Node has given property or not. + * + * @param[in] prop @NodeFeatureProperties + * + * @return true if has, else false + * * @since_tizen 5.5 */ bool hasFeatureProperty(NodeFeatureProperties prop) const; /** - * @brief TBD + * @brief Sets Node's property. + * + * @param[in] prop @NodeFeatureProperties + * @param[in] has Node has given property ot not + * * @since_tizen 5.5 */ void setFeatureProperty(NodeFeatureProperties prop, bool has); /** - * @brief TBD + * @brief Resets all the property value on Node. + * * @since_tizen 6.5 */ void resetFeatureProperty(); protected: - /** - * @brief TBD - */ std::string mText; - - /** - * @brief TBD - */ std::string mPkg; - - /** - * @brief TBD - */ std::string mRole; - - /** - * @brief TBD - */ std::string mId; - - /** - * @brief TBD - */ std::string mAutomationId; - - /** - * @brief TBD - */ std::string mType; - - /** - * @brief TBD - */ std::string mStyle; - - /** - * @brief TBD - */ Rect mScreenBoundingBox; - - /** - * @brief TBD - */ Rect mWindowBoundingBox; - - /** - * @brief TBD - */ int mSupportingIfaces; - - /** - * @brief TBD - */ int mFeatureProperty; private: - /** - * @brief TBD - */ bool mValid; - - /** - * @brief TBD - */ mutable std::mutex mLock; }; -#endif \ No newline at end of file +#endif diff --git a/libaurum/inc/Impl/Accessibility/AtspiAccessibleNode.h b/libaurum/inc/Impl/Accessibility/AtspiAccessibleNode.h index 2f3da1d..b916c1b 100644 --- a/libaurum/inc/Impl/Accessibility/AtspiAccessibleNode.h +++ b/libaurum/inc/Impl/Accessibility/AtspiAccessibleNode.h @@ -21,137 +21,126 @@ #include "AccessibleNode.h" #include +/** + * @brief AtspiAccessibleNode is inherited from AccessibleNode class. + * It manages object informations which from atspi server. + * + * @since_tizen 5.5 + */ class AtspiAccessibleNode : public AccessibleNode { public: /** - * @brief TBD + * @brief AtspiAccessibleNode constructor. + * + * @param[in] node AtspiAccessible ptr + * * @since_tizen 5.5 */ AtspiAccessibleNode(AtspiAccessible *node); /** - * @brief TBD + * @brief AtspiAccessibleNode desctructor. + * * @since_tizen 5.5 */ ~AtspiAccessibleNode() override; public: /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::getChildCount() */ int getChildCount() const override; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::getChildAt() */ std::shared_ptr getChildAt(int index) const override; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::getChildren() */ std::vector> getChildren() const override; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc UiObject::getParent() */ std::shared_ptr getParent() const override; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc AccessibleNode::isValid() */ bool isValid() const override; public: /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc AccessibleNode::getRawHandler() */ void* getRawHandler(void) const override; /** - * @brief TBD - * @since_tizen 6.5 + * @copydoc UiObject::updateRoleName() */ void updateRoleName() override; /** - * @brief TBD - * @since_tizen 6.5 + * @copydoc UiObject::updateUniqueId() */ void updateUniqueId() override; /** - * @brief TBD - * @since_tizen 6.5 + * @copydoc UiObject::updateName() */ void updateName() override; /** - * @brief TBD - * @since_tizen 6.5 + * @copydoc UiObject::updateApplication() */ void updateApplication() override; /** - * @brief TBD - * @since_tizen 6.5 + * @copydoc UiObject::updateAttributes() */ void updateAttributes() override; /** - * @brief TBD - * @since_tizen 6.5 + * @copydoc UiObject::updateStates() */ void updateStates() override; /** - * @brief TBD - * @since_tizen 6.5 + * @copydoc UiObject::updateExtents() */ void updateExtents() override; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc AccessibleNode::refresh() */ void refresh() override; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc AccessibleNode::getActions() */ std::vector getActions() const override; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc AccessibleNode::doAction() */ bool doAction(std::string action) override; /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc AccessibleNode::setValue() */ void setValue(std::string text) override; private: using AccessibleNode::setFeatureProperty; + /** - * @brief TBD - * @since_tizen 5.5 + * @copydoc AccessibleNode::setFeatureProperty() */ void setFeatureProperty(AtspiStateType type); private: - /** - * @brief TBD - * @since_tizen 5.5 - */ AtspiAccessible *mNode; }; diff --git a/libaurum/inc/UiDevice.h b/libaurum/inc/UiDevice.h index dc40632..f3ddcbb 100644 --- a/libaurum/inc/UiDevice.h +++ b/libaurum/inc/UiDevice.h @@ -41,7 +41,7 @@ * @ingroup aurum * * @brief UiDevice provides access to state information about the device. - * You can also use this class to simulate user actions on the device. + * You can also use this class to simulate user actions on the device. */ class UiDevice : public IDevice, public ISearchable { public: diff --git a/libaurum/inc/UiObject.h b/libaurum/inc/UiObject.h index 5699b7d..b725b7d 100644 --- a/libaurum/inc/UiObject.h +++ b/libaurum/inc/UiObject.h @@ -30,6 +30,9 @@ class UiDevice; +/** + * @brief This class keep object's descendant tree. + */ class Node : public std::enable_shared_from_this { public: Node(std::shared_ptr node, std::vector> children) @@ -40,362 +43,471 @@ public: }; /** - * @brief UiObject class - * @since_tizen 5.5 + * @class UiObject + * + * @ingroup aurum + * + * @brief A UiObject is a representation of a actual object in view. + * As a class that abstracts the actual object, it has the information of the object + * such as object's properties, states, geometry information. + * also user can send and receive event via this class. */ class UiObject : public ISearchable , public std::enable_shared_from_this { public: /** - * @brief TBD + * @brief UiObject constructor with device, selector, node pointer. + * * @since_tizen 5.5 */ UiObject(const std::shared_ptr device, const std::shared_ptr selector, const AccessibleNode *node); /** - * @brief TBD + * @brief UiObject constructor with device, selector, node. + * * @since_tizen 5.5 */ UiObject(const std::shared_ptr device, const std::shared_ptr selector, std::shared_ptr node); -// UiObject(const UiObject &src); // copy constroctur /** - * @brief TBD + * @brief UiObject constructor with object source. + * * @since_tizen 5.5 */ - UiObject(UiObject &&src); // move constructor + UiObject(UiObject &&src); /** - * @brief TBD + * @brief UiObject constructor. (default constructor) + * * @since_tizen 5.5 */ UiObject(); /** - * @brief TBD + * @brief UiObject destructor. + * * @since_tizen 5.5 */ virtual ~UiObject(); /** - * @brief TBD + * @brief Gets selector. + * + * @return UiSelector pointer + * * @since_tizen 5.5 */ std::shared_ptr getSelector(); /** - * @brief TBD + * @brief Checks that there is object that satisfied with the selector condition in the object tree. + * + * @param[in] selector @UiSelector + * + * @return true if object exist, otherwise false + * * @since_tizen 5.5 */ bool hasObject(const std::shared_ptr selector) const override; /** - * @brief TBD + * @brief Finds that object that satisfied with the selector condition in the object tree. + * + * @param[in] selector @UiSelector + * + * @return Found UiObject pointer + * * @since_tizen 5.5 */ std::shared_ptr findObject( const std::shared_ptr selector) const override; /** - * @brief TBD + * @brief Finds that objects that satisfied with the selector condition in the object tree. + * + * @param[in] selector @UiSelector + * + * @return the list of found UiObject pointer vector + * * @since_tizen 5.5 */ std::vector> findObjects( const std::shared_ptr selector) const override; /** - * @brief TBD - * @since_tizen 5.5 + * TODO */ bool waitFor( const std::function condition) const; /** - * @brief TBD - * @since_tizen 5.5 + * TODO */ std::shared_ptr waitFor( const std::function(const ISearchable *)> condition) const; /** - * @brief TBD - * @since_tizen 5.5 + * TODO */ bool waitFor(const std::function condition) const; public: /** - * @brief TBD + * @brief Gets object's parent. + * + * @return UiObject pointer + * * @since_tizen 5.5 */ - UiObject * getParent() const; + UiObject *getParent() const; /** - * @brief TBD + * @brief Gets object's child count. + * + * @return number of child + * * @since_tizen 5.5 */ - int getChildCount() const; + int getChildCount() const; /** - * @brief TBD + * @brief Gets object's children. + * + * @return UiObject pointer vector + * * @since_tizen 5.5 */ std::vector> getChildren() const; /** - * @brief TBD + * @brief Gets object's child at specific index. + * + * @return UiObject pointer + * * @since_tizen 5.5 */ std::shared_ptr getChildAt(int index) const; /** - * @brief TBD + * @brief Gets object's Descendant tree . + * + * @return Node pointer vector + * * @since_tizen 5.5 */ std::shared_ptr getDescendant(); /** - * @brief TBD + * @brief Gets object's package name. + * + * @return string + * * @since_tizen 5.5 */ std::string getApplicationPackage() const; /** - * @brief TBD + * @brief Gets object's Id. + * + * @return string + * * @since_tizen 5.5 */ std::string getId() const; /** - * @brief TBD + * @brief Gets object's automation Id. + * + * @return string + * * @since_tizen 5.5 */ std::string getAutomationId() const; /** - * @brief TBD + * @brief Gets object's type. + * + * @return string + * * @since_tizen 5.5 */ std::string getElementType() const; /** - * @brief TBD + * @brief Gets object's style. + * + * @return string + * * @since_tizen 5.5 */ std::string getElementStyle() const; /** - * @brief TBD + * @brief Gets object's text. + * + * @return string + * * @since_tizen 5.5 */ std::string getText() const; /** - * @brief TBD + * @brief Gets object's role. + * + * @return string + * * @since_tizen 5.5 */ std::string getRole() const; /** - * @brief TBD + * @brief Sets object's text. + * + * @param[in] text string + * + * @return string + * * @since_tizen 5.5 */ void setText(std::string text); /** - * @brief TBD + * @brief Gets object's geometry of the screen. + * + * @return @Rect + * * @since_tizen 5.5 */ const Rect getScreenBoundingBox() const; /** - * @brief TBD - * @since_tizen 6.5 + * @brief Gets object's geometry of the window. + * + * @return @Rect + * + * @since_tizen 5.5 */ const Rect getWindowBoundingBox() const; /** - * @brief TBD + * @brief Gets object's checkable property. + * + * @return true if checkable else false + * * @since_tizen 5.5 */ bool isCheckable() const; /** - * @brief TBD + * @brief Gets object's checked property. + * + * @return true if checked else false + * * @since_tizen 5.5 */ bool isChecked() const; /** - * @brief TBD + * @brief Gets object's clickable property. + * + * @return true if clickable else false + * * @since_tizen 5.5 */ bool isClickable() const; /** - * @brief TBD + * @brief Gets object's enabled property. (to get object enabled. disabled state) + * + * @return true if enabled else false + * * @since_tizen 5.5 */ bool isEnabled() const; /** - * @brief TBD + * @brief Gets object's focusable property. + * + * @return true if focusable else false + * * @since_tizen 5.5 */ bool isFocusable() const; /** - * @brief TBD + * @brief Gets object's focused property. + * + * @return true if focused else false + * * @since_tizen 5.5 */ bool isFocused() const; /** - * @brief TBD + * @brief Gets object's longclickable property. + * + * @return true if longclickable else false + * * @since_tizen 5.5 */ bool isLongClickable() const; /** - * @brief TBD + * @brief Gets object's scrollable property. + * + * @return true if scrollable else false + * * @since_tizen 5.5 */ bool isScrollable() const; /** - * @brief TBD + * @brief Gets object's selectable property. + * + * @return true if selectable else false + * * @since_tizen 5.5 */ bool isSelectable() const; /** - * @brief TBD + * @brief Gets object's selected property. + * + * @return true if selected else false + * * @since_tizen 5.5 */ bool isSelected() const; /** - * @brief TBD + * @brief Gets object's visible property. + * + * @return true if visible else false + * * @since_tizen 5.5 */ bool isVisible() const; /** - * @brief TBD + * @brief Gets object's showing property. + * + * @return true if showing else false + * * @since_tizen 5.5 */ bool isShowing() const; /** - * @brief TBD + * @brief Gets object's active property. + * + * @return true if active else false + * * @since_tizen 5.5 */ bool isActive() const; /** - * @brief TBD + * @brief Performs a click action on object. + * * @since_tizen 5.5 */ void click() const; /** - * @brief TBD + * @brief Performs a long click action on object. + * + * @param[in] durationMs total time to maintain down action (default = 500ms) + * * @since_tizen 5.5 */ void longClick(const unsigned int durationMs = LOGNCLICK_INTERVAL) const; /** - * @brief TBD - * @since_tizen 5.5 + * TODO */ bool DoAtspiActivate() const; /** - * @brief TBD + * @brief Updates object's role name information from atspi server. + * * @since_tizen 6.5 */ void updateRoleName() const; /** - * @brief TBD + * @brief Updates object's Id information from atspi server. + * * @since_tizen 6.5 */ void updateUniqueId() const; /** - * @brief TBD + * @brief Updates object's name information from atspi server. + * * @since_tizen 6.5 */ void updateName() const; /** - * @brief TBD + * @brief Updates object's application name information from atspi server. + * * @since_tizen 6.5 */ void updateApplication() const; /** - * @brief TBD + * @brief Updates object's attributes information from atspi server. + * * @since_tizen 6.5 */ void updateAttributes() const; /** - * @brief TBD + * @brief Updates object's states information from atspi server. + * * @since_tizen 6.5 */ void updateStates() const; /** - * @brief TBD + * @brief Updates object's geometry information from atspi server. + * * @since_tizen 6.5 */ void updateExtents() const; /** - * @brief TBD - * @since_tizen 5.5 + * @brief Updates object's information from atspi server. + * + * @since_tizen 6.5 */ void refresh() const; /** - * @brief TBD + * @brief Checks object is valid or not. + * + * @return true if valid else false + * * @since_tizen 5.5 */ bool isValid() const; /** - * @brief TBD + * @brief Gets object's AccessibleNode class + * + * @return AccessibleNode pointer + * * @since_tizen 5.5 */ std::shared_ptr getAccessibleNode() const; private: - /** - * @brief TBD - */ std::shared_ptr mDevice; - - /** - * @brief TBD - */ std::shared_ptr mSelector; - - /** - * @brief TBD - */ std::shared_ptr mNode; - - /** - * @brief TBD - */ const Waiter *mWaiter; - - /** - * @brief TBD - */ static const unsigned int LOGNCLICK_INTERVAL = 500; }; -- 2.34.1