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:
h
ttp://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: interface-discuss-unsubscribeopenoffice.org
For additional commands, e-mail: interface-discuss-helpopenoffice.org
|