LibreOffice Module svx (master)  1
Public Types | Public Member Functions | Private Attributes | List of all members
accessibility::AccessibleTextHelper Class Referencefinal

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
 
AccessibleTextHelperoperator= (const AccessibleTextHelper &)=delete
 
const SvxEditSourceGetEditSource () 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 (const VectorOfStates &rChildStates)
 Sets a vector 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_Int32 GetChildCount () const
 Implements getAccessibleChildCount. More...
 
css::uno::Reference< css::accessibility::XAccessible > GetChild (sal_Int32 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_ImplmpImpl
 

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:
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 also
SvxEditSource
SvxTextForwarder
SvxViewForwarder
SvxEditViewForwarder

Definition at line 110 of file AccessibleTextHelper.hxx.

Member Typedef Documentation

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

Definition at line 114 of file AccessibleTextHelper.hxx.

Constructor & Destructor Documentation

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

Create accessible text object for given edit source.

Parameters
pEditSourceThe 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 1524 of file AccessibleTextHelper.cxx.

References SetEditSource().

accessibility::AccessibleTextHelper::~AccessibleTextHelper ( )

Definition at line 1532 of file AccessibleTextHelper.cxx.

accessibility::AccessibleTextHelper::AccessibleTextHelper ( const AccessibleTextHelper )
delete

Member Function Documentation

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

Implements addEventListener.

Attention:
Don't call with locked mutexes

Definition at line 1735 of file AccessibleTextHelper.cxx.

References mpImpl.

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 1682 of file AccessibleTextHelper.cxx.

References mpImpl.

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

Implements getAccessibleAt.

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

Definition at line 1762 of file AccessibleTextHelper.cxx.

References mpImpl.

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

Implements getAccessibleChild.

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

Definition at line 1718 of file AccessibleTextHelper.cxx.

References mpImpl.

sal_Int32 accessibility::AccessibleTextHelper::GetChildCount ( ) const

Implements getAccessibleChildCount.

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

Definition at line 1701 of file AccessibleTextHelper.cxx.

References mpImpl.

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

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.

Definition at line 1536 of file AccessibleTextHelper.cxx.

References mpImpl.

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 1643 of file AccessibleTextHelper.cxx.

References mpImpl.

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 1596 of file AccessibleTextHelper.cxx.

References mpImpl.

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

Implements removeEventListener.

Attention:
Don't call with locked mutexes

Definition at line 1748 of file AccessibleTextHelper.cxx.

References mpImpl.

void accessibility::AccessibleTextHelper::SetAdditionalChildStates ( const VectorOfStates rChildStates)

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

Definition at line 1658 of file AccessibleTextHelper.cxx.

References mpImpl.

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

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.

Parameters
pEditSourceThe new edit source to set. Object ownership is transferred from the caller to the callee.

Definition at line 1551 of file AccessibleTextHelper.cxx.

References DBG_TESTSOLARMUTEX, and mpImpl.

Referenced by AccessibleTextHelper().

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:
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
rInterfaceThe interface that should be set as the source for accessibility events sent by this object.

Definition at line 1567 of file AccessibleTextHelper.cxx.

References mpImpl.

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:
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
bHaveFocusWhether we got or we lost the focus. Set to true if focus is gotten, false otherwise.
See also
HaveFocus()

Definition at line 1580 of file AccessibleTextHelper.cxx.

References DBG_TESTSOLARMUTEX, and mpImpl.

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

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:
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
rPointThe offset in screen coordinates (i.e. pixel)

Definition at line 1611 of file AccessibleTextHelper.cxx.

References DBG_TESTSOLARMUTEX, and mpImpl.

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:
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
nOffsetThe offset to add to every children's index.

Definition at line 1627 of file AccessibleTextHelper.cxx.

References DBG_TESTSOLARMUTEX, and mpImpl.

void accessibility::AccessibleTextHelper::UpdateChildren ( )

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.

Definition at line 1663 of file AccessibleTextHelper.cxx.

References DBG_TESTSOLARMUTEX, and mpImpl.

Member Data Documentation

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

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