Hi,
with OOo 2.2, a first draft of a Smart Tag API has been introduced. That
API only provided some basic Smart Tag functionality which had to be
enhanced in many regards. An overview about Smart Tags and the current
Smart Tag API can be found be:
http://wiki.services.openoffice.org/wiki/Smart_Tags
So here comes my proposal for the new API:
The new/changed services/interfaces are
com.sun.star.smarttags.SmartTagRecognizer
com.sun.star.smarttags.XSmartTagRecognizer
com.sun.star.smarttags.SmartTagAction
com.sun.star.smarttags.XSmartTagAction
com.sun.star.smarttags.SmartTagRecognizerMode
com.sun.star.text.XTextMarkup
com.sun.star.text.TextMarkupType
com.sun.star.container.XStringKeyMap
Short Description of the services/interfaces:
- A SmartTagRecognizer is used to find smart tags in a document. Usually
there are a couple of SmartTagRecognizer components installed.
- A SmartTagAction defines actions associated with smart tags. Usually
there are a couple of SmartTagAction components installed.
- SmartTagRecognizerMode defines some constants which are used to
specify the type of text (paragraph, cell content, single word) passed
to the recognize function of the SmartTagRecognizer service.
- The XTextMarkup interface provides functionality to highlight the text
of a paragraph. This interface is used by the recognize function of the
SmartTagRecognizer service to mark text as smart tags.
- TextMarkupType defines some constants to specify the type of the
highlighted text (smart tag, spell check, grammar check).
- The interface XStringKeyMap provides functions to map strings to anys.
This is used to associate user defined data with the smart tag
identified by a SmartTagRecognizer. This user defined data will be
stored together with the smart tag and passed to a SmartTagAction on
invocation.
Feedback is very much appreciated!
Thanks,
Frank
--%<------------------------------------------------------------------
module com { module sun { module star { module smarttags {
//=====================================================================
/** recognizes smart tags.
<p>Implementations of this service are used to scan the document
text for smart tags. Smart tags are pieces of text that can be
associated with specific actions which are defined by
implementations of the <type>SmartTagAction</type> service.</p>
@since OOo 2.3.0
*/
service SmartTagRecognizer : XSmartTagRecognizer {};
//=====================================================================
}; }; }; };
--%<------------------------------------------------------------------
module com { module sun { module star { module smarttags {
//======================================================================
/**
provides access to a smart tag recognizer.
@since OOo 2.3.0
*/
interface XSmartTagRecognizer: com::sun::star::lang::XInitialization
{
//------------------------------------------------------------------
/** obtains a name that describes this recognizer component.
@param aLocale
Is used for localization of the name.
@return
the name of the recognizer component.
*/
string getName( [in] ::com::sun::star::lang::Locale aLocale );
//------------------------------------------------------------------
/** obtains a detailed description of this recognizer component.
@param aLocale
Is used for localization of the description.
@return
the description of the recognizer component.
*/
string getDescription([in] ::com::sun::star::lang::Locale aLocale );
//------------------------------------------------------------------
/** The number of smart tag types supported by this recognizer
component.
*/
[attribute, readonly] long SmartTagCount;
//------------------------------------------------------------------
/** obtains the name of one specific smart tag type supported by
this recognizer component.
@param nSmartTagIndex
Index of the wanted smart tag type. Value needs to be
between 0 and the number of smarttags available
(exclusively).
@return
the unique name of the smart tag type. Smart tag type
names are always in the format of namespaceURI#tagname.
@throws com::sun::star::lang::IndexOutOfBoundsException
if nSmartTagIndex is greater than SmartTagCount
*/
string getSmartTagName( [in] long nSmartTagIndex )
raises( com::sun::star::lang::IndexOutOfBoundsException );
//------------------------------------------------------------------
/** obtains the URL that can be used to download new or updated
recognizers.
@param nSmartTagIndex
Index of the wanted smart tag type. Value needs to be
between 0 and the number of smarttags available
(exclusively).
@return
the download URL.
@throws com::sun::star::lang::IndexOutOfBoundsException
if nSmartTagIndex is greater than SmartTagCount
*/
string getSmartTagDownloadURL( [in] long nSmartTagIndex )
raises( com::sun::star::lang::IndexOutOfBoundsException );
//------------------------------------------------------------------
/** recognizes smart tags.
@param aText
The text that should be scanned by the recognizer.
@param nStartPos
Denotes the start position of the region to scan.
@param nLength
Denotes the length of the text to scan.
@param nDataType
This value indicates the type of the passed text.
@param aLocale
Is used to indicate the language of the passed text.
@param xTextMarkup
This object is used to submit any recognized smart tags
to the calling application.
@param aApplicationName
A string containing the name of the calling application.
@param xTokenizer
This can be used to tokenize the string to recognize.
*/
void recognize( [in] string aText,
[in] long nStart,
[in] long nLength,
[in] short nDataType,
[in] com::sun::star::lang::Locale aLocale,
[in] com::sun::star::text::XTextMarkup xTextMarkup,
[in] string aApplicationName,
[in] com::sun::star::i18n::XBreakIterator xTokenizer);
//------------------------------------------------------------------
/** indicates whether there is a property page for a smart tag type.
@param nSmartTagIndex
Index of the wanted smart tag type. Value needs to be
between 0 and the number of smarttags available
(exclusively).
@param aLocale
Is used for localization of the property page.
@return
true if there is a property page matching the requested
smart tag type and locale.
@throws com::sun::star::lang::IndexOutOfBoundsException
if nSmartTagIndex is greater than SmartTagCount
*/
boolean hasPropertyPage( [in] long nSmartTagIndex,
[in] ::com::sun::star::lang::Locale aLocale )
raises( com::sun::star::lang::IndexOutOfBoundsException );
//------------------------------------------------------------------
/** launches the property page for a smart tag type.
@param nSmartTagIndex
Index of the wanted smart tag type. Value needs to be
between 0 and the number of smarttags available
(exclusively).
@param aLocale
Is used for localization of the property page.
@throws com::sun::star::lang::IndexOutOfBoundsException
if nSmartTagIndex is greater than SmartTagCount
*/
void displayPropertyPage( [in] long nSmartTagIndex,
[in] ::com::sun::star::lang::Locale aLocale )
raises( com::sun::star::lang::IndexOutOfBoundsException );
};
}; }; }; };
--%<------------------------------------------------------------------
module com { module sun { module star { module smarttags {
//=====================================================================
/** provides one or more actions for smart tags.
<p>An implementation of this service defines one or more actions
that can be performed for a smart tag which has been recognized
by a <type>SmartTagRecognizer</type> service.</p>
@since OOo 2.3.0
*/
service SmartTagAction : XSmartTagAction {};
//=====================================================================
}; }; }; };
--%<------------------------------------------------------------------
module com { module sun { module star { module smarttags {
//======================================================================
/** provides access to smart tag actions.
@since OOo 2.3.0
*/
interface XSmartTagAction: com::sun::star::lang::XInitialization
{
//------------------------------------------------------------------
/** obtains a name that describes this action component.
@param aLocale
Is used for localization of the name.
@return
the name describing the action component.
*/
string getName( [in] ::com::sun::star::lang::Locale aLocale );
//------------------------------------------------------------------
/** obtains a detailed description of this action component.
@param aLocale
Is used for localization of the description.
@return
the description of the action component.
*/
string getDescription([in] ::com::sun::star::lang::Locale aLocale );
//------------------------------------------------------------------
/** the number of smart tag types supported by this action
component.
*/
[attribute, readonly] long SmartTagCount;
//------------------------------------------------------------------
/** obtains the name of one specific smart tag type supported by
this action component.
@param nSmartTagIndex
Index of the wanted smart tag type. Value needs to be
between 0 and the number of smarttags available
(exclusively).
@return
an unique name of the smart tag type. Smart tag type
names are always in the format of namespaceURI#tagname.
@throws com::sun::star::lang::IndexOutOfBoundsException
if nSmartTagIndex is greater than SmartTagCount.
*/
string getSmartTagName( [in] long nSmartTagIndex )
raises( com::sun::star::lang::IndexOutOfBoundsException );
//------------------------------------------------------------------
/** obtains the caption of the smart tag type for using in user
interfaces.
@param nSmartTagIndex
Index of the wanted smart tag type. Value needs to be
between 0 and the number of smarttags available
(exclusively).
@param aLocale
Is used for localization of the caption.
@return
the caption associated with the smart tag type.
@throws com::sun::star::lang::IndexOutOfBoundsException
if nSmartTagIndex is greater than SmartTagCount
*/
string getSmartTagCaption([in] long nSmartTagIndex,
[in] ::com::sun::star::lang::Locale aLocale )
raises( com::sun::star::lang::IndexOutOfBoundsException );
//------------------------------------------------------------------
/** obtains the number of actions provided for a specifiy smart tag
type.
@param aSmartTagName
Name of the wanted smart tag type. This is one of the
names obtained by getSmartTagName()
@return
the number of actions available for the given smart tag
type.
*/
long getActionCount( [in] string aSmartTagName );
//------------------------------------------------------------------
/** obtains a unique integer identifier for an action.
@param nSmartTagName
Name of the wanted smart tag type. This is one of the
names obtained by getSmartTagName()
@param nActionIndex
The index of the action for the given smart tag type.
@return
the unique integer identifier for the requested action.
@throws com::sun::star::lang::IllegalArgumentException
if the specified nActionIndex is greater than the number
of available actions for the specified smart tag type.
*/
long getActionID([in] string aSmartTagName, [in] long nActionIndex )
raises( com::sun::star::lang::IllegalArgumentException );
//------------------------------------------------------------------
/** obtains a caption for a specified action for use in user
interfaces.
@param nActionID
The identifier of the requested action.
@param aApplicationName
A string containing the name of the calling application.
@param aLocale
Is used for localization of the caption.
@param xProperties
Contains additional smart tag properties collected by
the smart tag recognizer.
@param aText
The calling application can pass the text of the smart
tag to the action component.
@param aXml
A string that is a Xml representation of the smart tag.
@param xController
The current controller of the document.
@param xTarget
A text range representing the smart tag in the document.
@return
the caption of the requested action.
@throws com::sun::star::lang::IllegalArgumentException
if the ActionID is not recognized.
*/
string getActionCaptionFromID( [in] long nActionID,
[in] string aApplicationName,
[in] ::com::sun::star::lang::Locale aLocale,
[in] com::sun::star::container::XStringKeyMap xProperties,
[in] string aText,
[in] string aXml,
[in] com::sun::star::frame::XController xController,
[in] com::sun::star::text::XTextRange xTarget )
raises( com::sun::star::lang::IllegalArgumentException );
//------------------------------------------------------------------
/** obtains a language independant name of an action.
@param nActionID
The identifier of the requested action.
@return
the language independant name of the specified action.
@throws com::sun::star::lang::IllegalArgumentException
if the ActionID is not recognized.
*/
string getActionNameFromID( [in] long nActionID )
raises( com::sun::star::lang::IllegalArgumentException );
//------------------------------------------------------------------
/** invokes an action.
@param nActionID
The identifier of the requested action.
@param aApplicationName
A string containing the name of the calling application.
@param xController
The current controller of the document.
@param xTarget
A text range representing the smart tag in the document.
@param xProperties
Contains the smart tag properties collected by the smart
tag recognizer.
@param aText
The calling application can pass the text of the smart
tag to the action component.
@param aXml
A string that is a Xml representation of the smart tag.
@param aLocale
Is used for localization of the action.
@throws com::sun::star::lang::IllegalArgumentException
if the ActionID is not recognized.
*/
void invokeAction( [in] long nActionID,
[in] string aApplicationName,
[in] com::sun::star::frame::XController xController,
[in] com::sun::star::text::XTextRange xTarget,
[in] com::sun::star::container::XStringKeyMap xProperties,
[in] string aText,
[in] string aXml,
[in] ::com::sun::star::lang::Locale aLocale )
raises( com::sun::star::lang::IllegalArgumentException );
//------------------------------------------------------------------
/** determines whether a caption is dynamic.
@param nActionID
The identifier of the requested action.
@param aApplicationName
A string containing the name of the calling application.
@param aLocale
Is used for localization.
@return
a boolean indicating whether the caption is dynamic.
@throws com::sun::star::lang::IllegalArgumentException
if the ActionID is not recognized.
*/
boolean isCaptionDynamic([in] long nActionID,
[in] string aApplicationName,
[in] ::com::sun::star::lang::Locale aLocale )
raises( com::sun::star::lang::IllegalArgumentException );
//------------------------------------------------------------------
/** determines whether the smart tag indicator should be visible.
@param nActionID
The identifier of the requested action.
@param aApplicationName
A string containing the name of the calling application.
@param aLocale
Is used for localization.
@return
a boolean indicating whether the smart tag indicator
should be visible.
@throws com::sun::star::lang::IllegalArgumentException
if the ActionID is not recognized.
*/
boolean isShowSmartTagIndicator( [in] long nActionID,
[in] string aApplicationName,
[in] ::com::sun::star::lang::Locale aLocale )
raises( com::sun::star::lang::IllegalArgumentException );
};
}; }; }; };
--%<------------------------------------------------------------------
module com { module sun { module star { module smarttags {
//======================================================================
/** The smart tag recognizer modes constants.
@since OOo 2.3.0
*/
constants SmartTagRecognizerMode
{
/// Text passed to the recognizer is a single character.
const short CHAR = 1;
/// Text passed to the recognizer is a single word.
const short SINGLE_WORD = 2;
/// Text passed to the recognizer is a regular expression.
const short REGEXP = 4;
/// Text passed to the recognizer is a paragraph.
const short PARAGRAPH = 8;
/// Text passed to the recognizer is a cell.
const short CELL = 16;
};
//======================================================================
}; }; }; };
--%<------------------------------------------------------------------
module com { module sun { module star { module text {
//======================================================================
/** provides functionality to markup text.
@since OOo 2.3.0
*/
interface XTextMarkup
{
//------------------------------------------------------------------
/** obtains a container to store additional user defined text markup
information.
@return
a container to store additional user defined text markup
information.
*/
com::sun::star::container::XStringKeyMap getMarkupInfoContainer();
//------------------------------------------------------------------
/** submits a new markup range.
@param nType
Type of text markup see <type>TextMarkupType</type>.
@param aIdentifier
A string used to identify the caller.
@param nStart
Start of the markup range.
@param nLength
Length of the markup range.
@param xMarkupInfoContainer
contains additional information about the markup.
*/
void commitTextMarkup( [in] short nType,
[in] string aIdentifier,
[in] long nStart,
[in] long nLength,
[in] com::sun::star::container::XStringKeyMap xMarkupInfoContainer );
};
}; }; }; };
--%<------------------------------------------------------------------
module com { module sun { module star { module text {
//=============================================================================
/** Constants to specify the type of text markup.
<p>These constants are used with
<method>XTextMarkup::commitTextMarkup()</method></p>
@since OOo 2.3.0
*/
constants TextMarkupType
{
/// Markup originates from spell checking.
const short SPELLCHECK = 1;
/// Markup originates from grammar checking.
const short GRAMMAR = 2;
/// Markup originates from smart tag checking.
const short SMARTTAG = 3;
};
}; }; }; };
--%<------------------------------------------------------------------
module com { module sun { module star { module container {
//=============================================================================
/** maps strings to anys
@since OOo 2.3.0
*/
interface XStringKeyMap
{
//------------------------------------------------------------------
/** reads data from the map.
@param aKey
The key string which should be searched for.
@return
the value matching aKey.
@throws com::sun::star::container::NoSuchElementException
if an element under aKey does not exist.
*/
any getValue( [in] string aKey )
raises( com::sun::star::container::NoSuchElementException );
//------------------------------------------------------------------
/** checks for element existance.
@param aKey
The key string which should be searched for.
@return
true if an element with key aKey exists.
*/
boolean hasValue( [in] string aKey );
//------------------------------------------------------------------
/** writes data to the map.
@param aKey
The key string which should be used to store the value.
@param aValue
The value that should be stored.
@throws com::sun::star::lang::IllegalArgumentException
if the element could not be inserted.
@throws com::sun::star::container::ElementExistException
if there is already a value stored under the key aKey.
*/
void insertValue( [in] string aKey, [in] any aValue )
raises( com::sun::star::lang::IllegalArgumentException,
com::sun::star::container::ElementExistException );
//------------------------------------------------------------------
/** obtains the number of elements in the map.
@return
the number of elements.
*/
[attribute, readonly] long Count;
//------------------------------------------------------------------
/** obtains the key of an element by index.
@param nIndex
is the index of the element.
@return
the key string matching the given index.
@throws com::sun::star::lang::IndexOutOfBoundsException
if the specified index is greater than the number of
elements
*/
string getKeyByIndex( [in] long nIndex )
raises( com::sun::star::lang::IndexOutOfBoundsException );
//------------------------------------------------------------------
/** obtains the value of an element by index.
@param nIndex
is the index of the key.
@return
the value matching the given index.
@throws com::sun::star::lang::IndexOutOfBoundsException
if the specified index is greater than the number of
elements
*/
any getValueByIndex( [in] long nIndex )
raises( com::sun::star::lang::IndexOutOfBoundsException );
};
}; }; }; };
--%<------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
