|
View:
New views
3 Messages
—
Rating Filter:
Alert me
|
|
|
Proposal: New Smart Tag APIHi,
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: interface-discuss-unsubscribe@... For additional commands, e-mail: interface-discuss-help@... |
|
|
|
|
|
|
| Free embeddable forum powered by Nabble | Forum Help |