Helper class for objects containing EditEngine/Outliner text. More...

#include <AccessibleTextHelper.hxx>

Public Types
typedef ::std::vector< sal_Int16 >	VectorOfStates

Public Member Functions
	AccessibleTextHelper (::std::unique_ptr< SvxEditSource > &&pEditSource)
	Create accessible text object for given edit source. More...

	~AccessibleTextHelper ()

	AccessibleTextHelper (const AccessibleTextHelper &)=delete

AccessibleTextHelper &	operator= (const AccessibleTextHelper &)=delete

const SvxEditSource &	GetEditSource () const
	Query the current edit source. More...

void	SetEditSource (::std::unique_ptr< SvxEditSource > &&pEditSource)
	Set the current edit source. More...

void	SetEventSource (const css::uno::Reference< css::accessibility::XAccessible > &rInterface)
	Set the event source. More...

void	SetOffset (const Point &rPoint)
	Set offset of EditEngine/Outliner from parent. More...

void	SetStartIndex (sal_Int32 nOffset)
	Set offset the object adds to all children's indices. More...

sal_Int32	GetStartIndex () const
	Query offset the object adds to all children's indices. More...

void	SetAdditionalChildStates (sal_Int64 rChildStates)
	Sets a bitset of additional accessible states. More...

void	UpdateChildren ()
	Update the visible children. More...

void	Dispose ()
	Drop all references and enter disposed state. More...

void	SetFocus (bool bHaveFocus=true)
	Set the focus state of the accessibility object. More...

bool	HaveFocus ()
	Query the focus state of the surrounding object. More...

sal_Int64	GetChildCount () const
	Implements getAccessibleChildCount. More...

css::uno::Reference< css::accessibility::XAccessible >	GetChild (sal_Int64 i)
	Implements getAccessibleChild. More...

void	AddEventListener (const css::uno::Reference< css::accessibility::XAccessibleEventListener > &xListener)
	Implements addEventListener. More...

void	RemoveEventListener (const css::uno::Reference< css::accessibility::XAccessibleEventListener > &xListener)
	Implements removeEventListener. More...

css::uno::Reference< css::accessibility::XAccessible >	GetAt (const css::awt::Point &aPoint)
	Implements getAccessibleAt. More...

Private Attributes
const std::unique_ptr< AccessibleTextHelper_Impl >	mpImpl
	@dyn More...

Detailed Description

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: \n 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: \n Use this class in an aggregation and forward, or: derive from it and overwrite. too.

See also: SvxEditSource; SvxTextForwarder; SvxViewForwarder; SvxEditViewForwarder

Definition at line 119 of file AccessibleTextHelper.hxx.

Member Typedef Documentation

◆ VectorOfStates

typedef ::std::vector<sal_Int16> accessibility::AccessibleTextHelper::VectorOfStates

Definition at line 122 of file AccessibleTextHelper.hxx.

Constructor & Destructor Documentation

◆ AccessibleTextHelper() [1/2]

accessibility::AccessibleTextHelper::AccessibleTextHelper ( ::std::unique_ptr< SvxEditSource > && pEditSource )

explicit

Create accessible text object for given edit source.

Parameters

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.

Definition at line 1522 of file AccessibleTextHelper.cxx.

References SetEditSource().

◆ ~AccessibleTextHelper()

accessibility::AccessibleTextHelper::~AccessibleTextHelper ( )

Definition at line 1530 of file AccessibleTextHelper.cxx.

◆ AccessibleTextHelper() [2/2]

accessibility::AccessibleTextHelper::AccessibleTextHelper ( const AccessibleTextHelper & )

delete

Member Function Documentation

◆ AddEventListener()

void accessibility::AccessibleTextHelper::AddEventListener ( const css::uno::Reference< css::accessibility::XAccessibleEventListener > & xListener )

Implements addEventListener.

Attention: \n Don't call with locked mutexes

Definition at line 1733 of file AccessibleTextHelper.cxx.

References mpImpl.

◆ Dispose()

void accessibility::AccessibleTextHelper::Dispose ( )

Drop all references and enter disposed state.

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).

Definition at line 1680 of file AccessibleTextHelper.cxx.

References mpImpl.

◆ GetAt()

uno::Reference< XAccessible > accessibility::AccessibleTextHelper::GetAt ( const css::awt::Point & aPoint )

Implements getAccessibleAt.

Attention: \n Don't call with locked mutexes. You may hold: the solar mutex, but this method acquires it anyway.

Definition at line 1760 of file AccessibleTextHelper.cxx.

References mpImpl.

◆ GetChild()

uno::Reference< XAccessible > accessibility::AccessibleTextHelper::GetChild ( sal_Int64 i )

Implements getAccessibleChild.

Attention: \n Don't call with locked mutexes. You may hold: the solar mutex, but this method acquires it anyway.

Definition at line 1716 of file AccessibleTextHelper.cxx.

References i, and mpImpl.

◆ GetChildCount()

sal_Int64 accessibility::AccessibleTextHelper::GetChildCount ( ) const

Implements getAccessibleChildCount.

Attention: \n Don't call with locked mutexes. You may hold: the solar mutex, but this method acquires it anyway.

Definition at line 1699 of file AccessibleTextHelper.cxx.

References mpImpl.

◆ GetEditSource()

const SvxEditSource & accessibility::AccessibleTextHelper::GetEditSource ( ) const

Query the current edit source.

Attention: \n 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.

Definition at line 1534 of file AccessibleTextHelper.cxx.

References mpImpl.

◆ GetStartIndex()

sal_Int32 accessibility::AccessibleTextHelper::GetStartIndex ( ) const

Query offset the object adds to all children's indices.

Returns: the offset to add to every children's index.

Definition at line 1641 of file AccessibleTextHelper.cxx.

References mpImpl.

◆ HaveFocus()

bool accessibility::AccessibleTextHelper::HaveFocus ( )

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.

Returns: the state of the focus ownership

Definition at line 1594 of file AccessibleTextHelper.cxx.

References mpImpl.

◆ operator=()

AccessibleTextHelper & accessibility::AccessibleTextHelper::operator= ( const AccessibleTextHelper & )

delete

References Dispose().

◆ RemoveEventListener()

void accessibility::AccessibleTextHelper::RemoveEventListener ( const css::uno::Reference< css::accessibility::XAccessibleEventListener > & xListener )

Implements removeEventListener.

Attention: \n Don't call with locked mutexes

Definition at line 1746 of file AccessibleTextHelper.cxx.

References mpImpl.

◆ SetAdditionalChildStates()

void accessibility::AccessibleTextHelper::SetAdditionalChildStates ( sal_Int64 rChildStates )

Sets a bitset 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()).

Definition at line 1656 of file AccessibleTextHelper.cxx.

References mpImpl.

◆ SetEditSource()

void accessibility::AccessibleTextHelper::SetEditSource ( ::std::unique_ptr< SvxEditSource > && pEditSource )

Set the current edit source.

Attention: \n 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.

Parameters

pEditSource The new edit source to set. Object ownership is transferred from the caller to the callee.

Definition at line 1549 of file AccessibleTextHelper.cxx.

References DBG_TESTSOLARMUTEX, and mpImpl.

Referenced by AccessibleTextHelper().

◆ SetEventSource()

void accessibility::AccessibleTextHelper::SetEventSource ( const css::uno::Reference< css::accessibility::XAccessible > & rInterface )

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: \n 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

Parameters

rInterface The interface that should be set as the source for accessibility events sent by this object.

Definition at line 1565 of file AccessibleTextHelper.cxx.

References mpImpl.

◆ SetFocus()

void accessibility::AccessibleTextHelper::SetFocus ( bool bHaveFocus = true )

Set the focus state of the accessibility object.

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: \n 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.

Parameters

bHaveFocus Whether we got or we lost the focus. Set to true if focus is gotten, false otherwise.

See also: HaveFocus()

Definition at line 1578 of file AccessibleTextHelper.cxx.

References DBG_TESTSOLARMUTEX, and mpImpl.

Referenced by WeldEditView::GetFocus(), and WeldEditView::LoseFocus().

◆ SetOffset()

void accessibility::AccessibleTextHelper::SetOffset ( const Point & rPoint )

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: \n 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.

Parameters

rPoint The offset in screen coordinates (i.e. pixel)

Definition at line 1609 of file AccessibleTextHelper.cxx.

References DBG_TESTSOLARMUTEX, and mpImpl.

◆ SetStartIndex()

void accessibility::AccessibleTextHelper::SetStartIndex ( sal_Int32 nOffset )

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: \n 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.

Parameters

nOffset The offset to add to every children's index.

Definition at line 1625 of file AccessibleTextHelper.cxx.

References DBG_TESTSOLARMUTEX, and mpImpl.

◆ UpdateChildren()

void accessibility::AccessibleTextHelper::UpdateChildren ( )

Update the visible children.

Attention: \n 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.

Definition at line 1661 of file AccessibleTextHelper.cxx.

References DBG_TESTSOLARMUTEX, and mpImpl.

Member Data Documentation

◆ mpImpl

const std::unique_ptr<AccessibleTextHelper_Impl> accessibility::AccessibleTextHelper::mpImpl

private

@dyn

Definition at line 367 of file AccessibleTextHelper.hxx.

Referenced by AddEventListener(), Dispose(), GetAt(), GetChild(), GetChildCount(), GetEditSource(), GetStartIndex(), HaveFocus(), RemoveEventListener(), SetAdditionalChildStates(), SetEditSource(), SetEventSource(), SetFocus(), SetOffset(), SetStartIndex(), and UpdateChildren().

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ VectorOfStates

Constructor & Destructor Documentation

◆ AccessibleTextHelper() [1/2]

◆ ~AccessibleTextHelper()

◆ AccessibleTextHelper() [2/2]

Member Function Documentation

◆ AddEventListener()

◆ Dispose()

◆ GetAt()

◆ GetChild()

◆ GetChildCount()

◆ GetEditSource()

◆ GetStartIndex()

◆ HaveFocus()

◆ operator=()

◆ RemoveEventListener()

◆ SetAdditionalChildStates()

◆ SetEditSource()

◆ SetEventSource()

◆ SetFocus()

◆ SetOffset()

◆ SetStartIndex()

◆ UpdateChildren()

Member Data Documentation

◆ mpImpl