diff options
Diffstat (limited to 'include/svx/AccessibleTextHelper.hxx')
| -rw-r--r-- | include/svx/AccessibleTextHelper.hxx | 602 |
1 files changed, 305 insertions, 297 deletions
diff --git a/include/svx/AccessibleTextHelper.hxx b/include/svx/AccessibleTextHelper.hxx index 5f646d83253c..d57736e14f26 100644 --- a/include/svx/AccessibleTextHelper.hxx +++ b/include/svx/AccessibleTextHelper.hxx @@ -27,10 +27,20 @@ #include <sal/types.h> #include <svx/svxdllapi.h> -namespace com::sun::star { - namespace accessibility { class XAccessible; } - namespace accessibility { class XAccessibleEventListener; } - namespace awt { struct Point; } +namespace com::sun::star +{ +namespace accessibility +{ +class XAccessible; +} +namespace accessibility +{ +class XAccessibleEventListener; +} +namespace awt +{ +struct Point; +} } class Point; @@ -38,326 +48,324 @@ class SvxEditSource; namespace accessibility { +class AccessibleTextHelper_Impl; + +/** Helper class for objects containing EditEngine/Outliner text + + This class provides the methods from the XAccessibleContext, + XAccessibleEventBroadcaster and XAccessibleComponent + interfaces, that are common to all accessible objects + containing an edit engine. + + The text contained in the EditEngine/Outliner is presented as + children of this class, namely for every text paragraph a + AccessibleEditableTextPara child object is generated. As this + class manages these children for itself, it has to send out + AccessibleEventId::CHILD events on your + behalf. Thus, you must forward every call to your + addEventListener()/removeEventListener() methods to the + AccessibleTextHelper (methods + AddEventListener/RemoveEventListener), otherwise none or not + everyone of your event listener will notice child changes. + + You have to implement the SvxEditSource, SvxTextForwarder, + SvxViewForwarder and SvxEditViewForwarder interfaces in order + to enable your object to cooperate with this + class. SvxTextForwarder encapsulates the fact that text + objects do not necessarily have an EditEngine at their + disposal, SvxViewForwarder and SvxEditViewForwarder do the + same for the document and the edit view. The three mentioned + forwarder objects are not stored by the AccessibleTextHelper, + but fetched every time from the SvxEditSource. So you are best + off making your SvxEditSource::Get*Forwarder methods cache the + current forwarder. + + To support changes in edit mode or conversion of fixed text + into EditEngine text, you can change the SvxEditSource this + class is referring to. This might render all children invalid + and change the child count, since the AccessibleTextHelper + reinitializes itself from scratch. + + This class registers itself at the SvxEditSource as a state + listener and manages the state of its children (i.e. the + paragraphs). See the method documentation of + AccessibleTextHelper::SetEditSource for the expected + events. Generally, be prepared that when sending any of these + events via SvxEditSource::GetBroadcaster() broadcaster, the + AccessibleTextHelper will call the SvxEditSource and their + forwarder to update it's state. Avoid being inconsistent in + the facts you tell in the events, e.g. when sending a + SfxHintId::TextParaInserted event, the + SvxEditSource::GetTextForwarder().GetParagraphCount() should + already include the newly inserted paragraph. + + @attention All public methods must not be called with any + mutex hold, except when calling from the main thread (with + holds the solar mutex), unless stated otherwise. This is + because they themselves might need the solar mutex in addition + to the object mutex, and the ordering of the locking must be: + first solar mutex, then object mutex. Furthermore, state + change events might be fired internally. + + @derive Use this class in an aggregation and forward, or + derive from it and overwrite. + too. + + @see SvxEditSource + @see SvxTextForwarder + @see SvxViewForwarder + @see SvxEditViewForwarder +*/ +class SVX_DLLPUBLIC AccessibleTextHelper final +{ +public: + typedef ::std::vector<sal_Int16> VectorOfStates; + + /** Create accessible text object for given edit source + + @param pEditSource + The edit source to use. Object ownership is transferred + from the caller to the callee. The object listens on the + SvxEditSource for object disposal, so no provisions have + to be taken if the caller destroys the data (e.g. the + model) contained in the given SvxEditSource. + + */ + explicit AccessibleTextHelper(::std::unique_ptr<SvxEditSource>&& pEditSource); + + ~AccessibleTextHelper(); + + AccessibleTextHelper(const AccessibleTextHelper&) = delete; + AccessibleTextHelper& operator=(const AccessibleTextHelper&) = delete; + + /** Query the current edit source - class AccessibleTextHelper_Impl; - - /** Helper class for objects containing EditEngine/Outliner text - - This class provides the methods from the XAccessibleContext, - XAccessibleEventBroadcaster and XAccessibleComponent - interfaces, that are common to all accessible objects - containing an edit engine. - - The text contained in the EditEngine/Outliner is presented as - children of this class, namely for every text paragraph a - AccessibleEditableTextPara child object is generated. As this - class manages these children for itself, it has to send out - AccessibleEventId::CHILD events on your - behalf. Thus, you must forward every call to your - addEventListener()/removeEventListener() methods to the - AccessibleTextHelper (methods - AddEventListener/RemoveEventListener), otherwise none or not - everyone of your event listener will notice child changes. - - You have to implement the SvxEditSource, SvxTextForwarder, - SvxViewForwarder and SvxEditViewForwarder interfaces in order - to enable your object to cooperate with this - class. SvxTextForwarder encapsulates the fact that text - objects do not necessarily have an EditEngine at their - disposal, SvxViewForwarder and SvxEditViewForwarder do the - same for the document and the edit view. The three mentioned - forwarder objects are not stored by the AccessibleTextHelper, - but fetched every time from the SvxEditSource. So you are best - off making your SvxEditSource::Get*Forwarder methods cache the - current forwarder. - - To support changes in edit mode or conversion of fixed text - into EditEngine text, you can change the SvxEditSource this - class is referring to. This might render all children invalid - and change the child count, since the AccessibleTextHelper - reinitializes itself from scratch. - - This class registers itself at the SvxEditSource as a state - listener and manages the state of its children (i.e. the - paragraphs). See the method documentation of - AccessibleTextHelper::SetEditSource for the expected - events. Generally, be prepared that when sending any of these - events via SvxEditSource::GetBroadcaster() broadcaster, the - AccessibleTextHelper will call the SvxEditSource and their - forwarder to update it's state. Avoid being inconsistent in - the facts you tell in the events, e.g. when sending a - SfxHintId::TextParaInserted event, the - SvxEditSource::GetTextForwarder().GetParagraphCount() should - already include the newly inserted paragraph. - - @attention All public methods must not be called with any - mutex hold, except when calling from the main thread (with - holds the solar mutex), unless stated otherwise. This is - because they themselves might need the solar mutex in addition - to the object mutex, and the ordering of the locking must be: - first solar mutex, then object mutex. Furthermore, state - change events might be fired internally. - - @derive Use this class in an aggregation and forward, or - derive from it and overwrite. - too. - - @see SvxEditSource - @see SvxTextForwarder - @see SvxViewForwarder - @see SvxEditViewForwarder + @attention This method returns by reference, so you are + responsible for serialization (typically, you acquired the + solar mutex when calling this method). Thus, the method + should only be called from the main office thread. + + */ + const SvxEditSource& GetEditSource() const; + + /** Set the current edit source + + @attention Might fire state change events, therefore, + don't hold any mutex except solar mutex, which you are + required to lock before. This method should only be called + from the main office thread. + + The EditSource set here is required to broadcast out the + following hints: SfxHintId::EditSourceParasMoved, + SfxHintId::EditSourceSelectionChanged, SfxHintId::TextModified, + SfxHintId::TextParaInserted, SfxHintId::TextParaRemoved, + SfxHintId::TextHeightChanged, + SfxHintId::TextViewScrolled. Otherwise, not all state changes + will get noticed by the accessibility object. Further + more, when the corresponding core object or the model is + dying, either the edit source must be set to NULL or it + has to broadcast a SfxHintId::Dying hint. + + If the SvxEditSource's managed text can change between + edit/non-edit mode (i.e. there are times when + SvxEditSource::GetEditViewForwarder(sal_False) returns + NULL), then the two additional hints are required: + SdrHintKind::BeginEdit and SdrHintKind::EndEdit. When the + AccessibleTextHelper receives a SdrHintKind::BeginEdit, it expects + the SvxEditSource already in edit mode. On a SdrHintKind::EndEdit, + edit mode must already been left. The rationale for these + events are the fact that focus and selection have to be + updated in edit mode, and completely relinquished and + reset to the parent (for the focus) in non-edit mode. + + This class does not have a dispose method, since it is not + a UNO component. Nevertheless, it holds C++ references to + several core objects, so you should issue a + SetEditSource(::std::unique_ptr<SvxEditSource>()) in + your dispose() method. + + @param pEditSource + The new edit source to set. Object ownership is transferred + from the caller to the callee. */ - class SVX_DLLPUBLIC AccessibleTextHelper final - { - - public: - typedef ::std::vector< sal_Int16 > VectorOfStates; - - /** Create accessible text object for given edit source - - @param pEditSource - The edit source to use. Object ownership is transferred - from the caller to the callee. The object listens on the - SvxEditSource for object disposal, so no provisions have - to be taken if the caller destroys the data (e.g. the - model) contained in the given SvxEditSource. - - */ - explicit AccessibleTextHelper( ::std::unique_ptr< SvxEditSource > && pEditSource ); - - ~AccessibleTextHelper(); - - AccessibleTextHelper( const AccessibleTextHelper& ) = delete; - AccessibleTextHelper& operator= ( const AccessibleTextHelper& ) = delete; - - /** Query the current edit source - - @attention This method returns by reference, so you are - responsible for serialization (typically, you acquired the - solar mutex when calling this method). Thus, the method - should only be called from the main office thread. - - */ - const SvxEditSource& GetEditSource() const; - - /** Set the current edit source - - @attention Might fire state change events, therefore, - don't hold any mutex except solar mutex, which you are - required to lock before. This method should only be called - from the main office thread. - - The EditSource set here is required to broadcast out the - following hints: SfxHintId::EditSourceParasMoved, - SfxHintId::EditSourceSelectionChanged, SfxHintId::TextModified, - SfxHintId::TextParaInserted, SfxHintId::TextParaRemoved, - SfxHintId::TextHeightChanged, - SfxHintId::TextViewScrolled. Otherwise, not all state changes - will get noticed by the accessibility object. Further - more, when the corresponding core object or the model is - dying, either the edit source must be set to NULL or it - has to broadcast a SfxHintId::Dying hint. - - If the SvxEditSource's managed text can change between - edit/non-edit mode (i.e. there are times when - SvxEditSource::GetEditViewForwarder(sal_False) returns - NULL), then the two additional hints are required: - SdrHintKind::BeginEdit and SdrHintKind::EndEdit. When the - AccessibleTextHelper receives a SdrHintKind::BeginEdit, it expects - the SvxEditSource already in edit mode. On a SdrHintKind::EndEdit, - edit mode must already been left. The rationale for these - events are the fact that focus and selection have to be - updated in edit mode, and completely relinquished and - reset to the parent (for the focus) in non-edit mode. - - This class does not have a dispose method, since it is not - a UNO component. Nevertheless, it holds C++ references to - several core objects, so you should issue a - SetEditSource(::std::unique_ptr<SvxEditSource>()) in - your dispose() method. - - @param pEditSource - The new edit source to set. Object ownership is transferred - from the caller to the callee. - */ - void SetEditSource( ::std::unique_ptr< SvxEditSource > && pEditSource ); - - /** Set the event source - - You should set the event source before registering any - event listener and before requesting any child. Children - of this object receive the event source as their parent - accessible object. That is, the event source is best set - in your object's init method. - - @attention When setting a reference here, you should call - Dispose() when you as the owner are disposing, since until - then this object will hold that reference - - @param rInterface - The interface that should be set as the source for - accessibility events sent by this object. - */ - void SetEventSource( const css::uno::Reference< css::accessibility::XAccessible >& rInterface ); - - /** Set offset of EditEngine/Outliner from parent - - If the origin of the underlying EditEngine/Outliner does - not correspond to the upper left corner of the object - using this class, you have to specify the offset. - - @attention Might fire state change events, therefore, - don't hold any mutex except solar mutex, which you are - required to lock before. This method should only be called - from the main office thread. - - @param rPoint - The offset in screen coordinates (i.e. pixel) - */ - void SetOffset( const Point& rPoint ); - - /** Set offset the object adds to all children's indices - - This can be used if the owner of this object has children - handled by itself. Setting an offset different from 0 - leads to this object mimicking that all its children are - within the range [nOffset, GetChildCount()+nOffset). That - means, GetChild() also expects the index to be in this - range. - - @attention Might fire state change events, therefore, - don't hold any mutex except solar mutex, which you are - required to lock before. This method should only be called - from the main office thread. - - @param nOffset - The offset to add to every children's index. - */ - void SetStartIndex( sal_Int32 nOffset ); - - /** Query offset the object adds to all children's indices - - @return the offset to add to every children's index. - */ - sal_Int32 GetStartIndex() const; - - /** Sets a vector of additional accessible states. - - The states are passed to every created child object - (text paragraph). The state values are defined in - css::accessibility::AccessibleStateType. - - This function has to be called before querying for - any children (e.g. with GetChild()). - */ - void SetAdditionalChildStates( const VectorOfStates& rChildStates ); - - /** Update the visible children - - @attention Might fire state change events, therefore, - don't hold any mutex except solar mutex, which you are - required to lock before. This method should only be called - from the main office thread. - - This method reevaluates the visibility of all - children. Call this method if your visibility state has - changed somehow, e.g. if the visible area has changed and - the AccessibleTextHelper isn't notified internally - (e.g. via SfxHintId::TextViewScrolled). Normally, there should - not be a need to call this method. - */ - void UpdateChildren(); + void SetEditSource(::std::unique_ptr<SvxEditSource>&& pEditSource); - /** Drop all references and enter disposed state + /** Set the event source - This method drops all references to external objects (also - the event source reference set via SetEventSource()) and - sets the object into the disposed state (i.e. the methods - return default values or throw a uno::DisposedException - exception). - */ - void Dispose(); + You should set the event source before registering any + event listener and before requesting any child. Children + of this object receive the event source as their parent + accessible object. That is, the event source is best set + in your object's init method. - /** Set the focus state of the accessibility object + @attention When setting a reference here, you should call + Dispose() when you as the owner are disposing, since until + then this object will hold that reference - Since this class handles children which also might get the - focus, the user of this class is encouraged to delegate - focus handling. Whenever the focus state of the - surrounding object changes, this method has to be called. + @param rInterface + The interface that should be set as the source for + accessibility events sent by this object. + */ + void SetEventSource(const css::uno::Reference<css::accessibility::XAccessible>& rInterface); - The protocol of focus handling for a user of this class is - then to call SetFocus() with the appropriate focus state, - and HaveFocus() to determine the focus state you tell the - outside. + /** Set offset of EditEngine/Outliner from parent - @attention Might fire state change events, therefore, - don't hold any mutex except solar mutex, which you are - required to lock before. This method should only be called - from the main office thread. + If the origin of the underlying EditEngine/Outliner does + not correspond to the upper left corner of the object + using this class, you have to specify the offset. - @param bHaveFocus - Whether we got or we lost the focus. Set to true if - focus is gotten, false otherwise. + @attention Might fire state change events, therefore, + don't hold any mutex except solar mutex, which you are + required to lock before. This method should only be called + from the main office thread. - @see HaveFocus() - */ - void SetFocus( bool bHaveFocus = true ); + @param rPoint + The offset in screen coordinates (i.e. pixel) + */ + void SetOffset(const Point& rPoint); - /** Query the focus state of the surrounding object + /** Set offset the object adds to all children's indices - If focus handling is delegated to this class, determine - focus state with this method. Be prepared that even if you - set the focus with SetFocus(true), this method might - return false. This is the case if one of the children - actually got the focus. + This can be used if the owner of this object has children + handled by itself. Setting an offset different from 0 + leads to this object mimicking that all its children are + within the range [nOffset, GetChildCount()+nOffset). That + means, GetChild() also expects the index to be in this + range. - @return the state of the focus ownership - */ - bool HaveFocus(); + @attention Might fire state change events, therefore, + don't hold any mutex except solar mutex, which you are + required to lock before. This method should only be called + from the main office thread. - // XAccessibleContext child handling methods + @param nOffset + The offset to add to every children's index. + */ + void SetStartIndex(sal_Int32 nOffset); - /** Implements getAccessibleChildCount + /** Query offset the object adds to all children's indices - @attention Don't call with locked mutexes. You may hold - the solar mutex, but this method acquires it anyway. - */ - sal_Int32 GetChildCount() const; - /** Implements getAccessibleChild + @return the offset to add to every children's index. + */ + sal_Int32 GetStartIndex() const; - @attention Don't call with locked mutexes. You may hold - the solar mutex, but this method acquires it anyway. - */ - css::uno::Reference< css::accessibility::XAccessible > GetChild( sal_Int32 i ); + /** Sets a vector of additional accessible states. - // XAccessibleEventBroadcaster child related methods + The states are passed to every created child object + (text paragraph). The state values are defined in + css::accessibility::AccessibleStateType. - /** Implements addEventListener + This function has to be called before querying for + any children (e.g. with GetChild()). + */ + void SetAdditionalChildStates(const VectorOfStates& rChildStates); - @attention Don't call with locked mutexes - */ - void AddEventListener( const css::uno::Reference< css::accessibility::XAccessibleEventListener >& xListener ); - /** Implements removeEventListener + /** Update the visible children - @attention Don't call with locked mutexes - */ - void RemoveEventListener( const css::uno::Reference< css::accessibility::XAccessibleEventListener >& xListener ); + @attention Might fire state change events, therefore, + don't hold any mutex except solar mutex, which you are + required to lock before. This method should only be called + from the main office thread. - // XAccessibleComponent child related methods + This method reevaluates the visibility of all + children. Call this method if your visibility state has + changed somehow, e.g. if the visible area has changed and + the AccessibleTextHelper isn't notified internally + (e.g. via SfxHintId::TextViewScrolled). Normally, there should + not be a need to call this method. + */ + void UpdateChildren(); - /** Implements getAccessibleAt + /** Drop all references and enter disposed state - @attention Don't call with locked mutexes. You may hold - the solar mutex, but this method acquires it anyway. - */ - css::uno::Reference< css::accessibility::XAccessible > GetAt( const css::awt::Point& aPoint ); + This method drops all references to external objects (also + the event source reference set via SetEventSource()) and + sets the object into the disposed state (i.e. the methods + return default values or throw a uno::DisposedException + exception). + */ + void Dispose(); - private: + /** Set the focus state of the accessibility object - /// @dyn - const std::unique_ptr< AccessibleTextHelper_Impl > mpImpl; + Since this class handles children which also might get the + focus, the user of this class is encouraged to delegate + focus handling. Whenever the focus state of the + surrounding object changes, this method has to be called. + + The protocol of focus handling for a user of this class is + then to call SetFocus() with the appropriate focus state, + and HaveFocus() to determine the focus state you tell the + outside. + + @attention Might fire state change events, therefore, + don't hold any mutex except solar mutex, which you are + required to lock before. This method should only be called + from the main office thread. + + @param bHaveFocus + Whether we got or we lost the focus. Set to true if + focus is gotten, false otherwise. + + @see HaveFocus() + */ + void SetFocus(bool bHaveFocus = true); + + /** Query the focus state of the surrounding object + + If focus handling is delegated to this class, determine + focus state with this method. Be prepared that even if you + set the focus with SetFocus(true), this method might + return false. This is the case if one of the children + actually got the focus. + + @return the state of the focus ownership + */ + bool HaveFocus(); + + // XAccessibleContext child handling methods + + /** Implements getAccessibleChildCount + + @attention Don't call with locked mutexes. You may hold + the solar mutex, but this method acquires it anyway. + */ + sal_Int32 GetChildCount() const; + /** Implements getAccessibleChild + + @attention Don't call with locked mutexes. You may hold + the solar mutex, but this method acquires it anyway. + */ + css::uno::Reference<css::accessibility::XAccessible> GetChild(sal_Int32 i); + + // XAccessibleEventBroadcaster child related methods + + /** Implements addEventListener + + @attention Don't call with locked mutexes + */ + void AddEventListener( + const css::uno::Reference<css::accessibility::XAccessibleEventListener>& xListener); + /** Implements removeEventListener + + @attention Don't call with locked mutexes + */ + void RemoveEventListener( + const css::uno::Reference<css::accessibility::XAccessibleEventListener>& xListener); + + // XAccessibleComponent child related methods + + /** Implements getAccessibleAt + + @attention Don't call with locked mutexes. You may hold + the solar mutex, but this method acquires it anyway. + */ + css::uno::Reference<css::accessibility::XAccessible> GetAt(const css::awt::Point& aPoint); - }; +private: + /// @dyn + const std::unique_ptr<AccessibleTextHelper_Impl> mpImpl; +}; } // end of namespace accessibility |