Difference between revisions of "Writer/Smart Tags"

From Apache OpenOffice Wiki
Jump to: navigation, search
(Added interface description for recognizers)
(Added interface description for action libraries)
Line 117: Line 117:
 
  | rowspan="1" style="width:15%" | '''Description'''
 
  | rowspan="1" style="width:15%" | '''Description'''
 
  | This method is used for initializing the recognizer component and is currently needed by Writer to use xml based smart tags (see example below). For your own smart tag components you can implement this method with an empty body.
 
  | This method is used for initializing the recognizer component and is currently needed by Writer to use xml based smart tags (see example below). For your own smart tag components you can implement this method with an empty body.
 +
|-
 +
| rowspan="1" style="width:15%" | '''Arguments'''
 +
| sequence<any> '''aArguments''': Initialization arguments
 +
|-
 +
| '''Return Value'''
 +
| None.
 +
|}
 +
 +
 +
==The Action Library Interface==
 +
 +
For a look at the action library interface definition go to this [http://go-ooo.org/lxr/source/api/offapi/com/sun/star/smarttags/XSmartTagAction.idl page].
 +
 +
 +
{| border=1 cellspacing=0 cellpadding=5 style="width:75%"
 +
! colspan="2" style="background:#ffdead;" | string getName()
 +
|-
 +
| rowspan="1" style="width:15%" | '''Arguments'''
 +
| None.
 +
|-
 +
| '''Return Value'''
 +
| Returns the name of the action library component.
 +
|}
 +
 +
 +
{| border=1 cellspacing=0 cellpadding=5 style="width:75%"
 +
! colspan="2" style="background:#ffdead;" | string getDescription()
 +
|-
 +
| rowspan="1" style="width:15%" | '''Arguments'''
 +
| None.
 +
|-
 +
| '''Return Value'''
 +
| Returns a textual description of the action library component.
 +
|}
 +
 +
 +
{| border=1 cellspacing=0 cellpadding=5 style="width:75%"
 +
! colspan="2" style="background:#ffdead;" | long getSmartTagCount()
 +
|-
 +
| rowspan="1" style="width:15%" | '''Arguments'''
 +
| None.
 +
|-
 +
| '''Return Value'''
 +
| The return value indicates how many smart tags are included in the action library component.
 +
|}
 +
 +
 +
{| border=1 cellspacing=0 cellpadding=5 style="width:75%"
 +
! colspan="2" style="background:#ffdead;" | string getSmartTagName()
 +
|-
 +
| rowspan="1" style="width:15%" | '''Arguments'''
 +
| sal_Int32 '''nSmartTagIndex''': Index of the wanted smart tag. Value needs to be between 0 and the number of smart tags available (exclusively).
 +
|-
 +
| '''Return Value'''
 +
| Returns the name of one specific smart tag in this action component. This name is needed to associate the actions of a smart tag with the corresponding recognizer.
 +
|}
 +
 +
 +
{| border=1 cellspacing=0 cellpadding=5 style="width:75%"
 +
! colspan="2" style="background:#ffdead;" | string getSmartTagCaption()
 +
|-
 +
| rowspan="2" style="width:15%" | '''Arguments'''
 +
| sal_Int32 '''nSmartTagIndex''': Index of the wanted smart tag. Value needs to be between 0 and the number of smart tags available (exclusively).
 +
|-
 +
| XController '''xController''': The reference to the controller of the current document.
 +
|-
 +
| '''Return Value'''
 +
| Returns the caption of one specific smart tag in this action component. The caption will be display by Openoffice.org Writer in the context menu.
 +
|}
 +
 +
 +
{| border=1 cellspacing=0 cellpadding=5 style="width:75%"
 +
! colspan="2" style="background:#ffdead;" | long getActionCount()
 +
|-
 +
| rowspan="2" style="width:15%" | '''Arguments'''
 +
| sal_Int32 '''nSmartTagIndex''': Index of the wanted smart tag. Value needs to be between 0 and the number of smart tags available (exclusively).
 +
|-
 +
| XController '''xController''': The reference to the controller of the current document.
 +
|-
 +
| '''Return Value'''
 +
| Returns the number of available actions of one specific smart tag in this action library.
 +
|}
 +
 +
 +
{| border=1 cellspacing=0 cellpadding=5 style="width:75%"
 +
! colspan="2" style="background:#ffdead;" | string getActionCaption()
 +
|-
 +
| rowspan="3" style="width:15%" | '''Arguments'''
 +
| sal_Int32 '''nSmartTagIndex''': Index of the wanted smart tag. Value needs to be between 0 and the number of smart tags available (exclusively).
 +
|-
 +
| sal_Int32 '''nActionIndex''': Index of the wanted action. Value needs to be between 0 and the number of actions available for the specified smart tag (nSmartTagIndex).
 +
|-
 +
| XController '''xController''': The reference to the controller of the current document.
 +
|-
 +
| '''Return Value'''
 +
| This function returns the caption of an action of one specific smart tag in this action library.
 +
|}
 +
 +
 +
{| border=1 cellspacing=0 cellpadding=5 style="width:75%"
 +
! colspan="2" style="background:#ffdead;" | void invokeAction()
 +
|-
 +
| rowspan="4" style="width:15%" | '''Arguments'''
 +
| sal_Int32 '''nSmartTagIndex''': Index of the wanted smart tag. Value needs to be between 0 and the number of smart tags available (exclusively).
 +
|-
 +
| sal_Int32 '''nActionIndex''': Index of the wanted action. Value needs to be between 0 and the number of actions available for the specified smart tag (nSmartTagIndex).
 +
|-
 +
| string aWord: Word that was recognized as actionable.
 +
|-
 +
| XController '''xController''': The reference to the controller of the current document.
 +
|-
 +
| '''Return Value'''
 +
| None.
 +
|}
 +
 +
 +
{| border=1 cellspacing=0 cellpadding=5 style="width:75%"
 +
! colspan="2" style="background:#ffdead;" | void initialize()
 +
|-
 +
| rowspan="1" style="width:15%" | '''Description'''
 +
| This method is used for initializing the action library component and is currently needed by Writer to use xml based smart tags (see example below). For your own smart tag components you can implement this method with an empty body.
 
  |-
 
  |-
 
  | rowspan="1" style="width:15%" | '''Arguments'''
 
  | rowspan="1" style="width:15%" | '''Arguments'''

Revision as of 10:44, 30 January 2007

Introduction

Smart Tags were introduced in Microsoft Office XP and allow to recognize words that have a special meaning to the user and futhermore allow to execute certain actions for a recognized word. Support for smart tags is included in the Openoffice 2.2 release as a new feature. In order to use this feature external UNO components (so-called smart tag libraries) have to be installed. This document explains how to write own smart tag libraries and how to integrate them into your Openoffice. The necessary interfaces for smart tag libraries currently have the status "unpublished" because there are still some minor enhancements planned. Nevertheless smart tag libraries are fully supported in Openoffice Writer 2.2. Just be aware that you have may have to modify the code of your components if you want to use them with the next release of Openoffice.org.

Basic functionality of Smart Tags

Basically smart tags UNO components consist of two parts:

  • A recognizer
  • An action library.

If a recognizer component is installed in openoffice its recognize() method will be invoked by Openoffice.org Writer for every word found in the opened document. The recognize method then decides if the word has some specific meaning and returns true or false. Recognized words will be underlined violet in Openoffice.org Writer. If the control key is pressed and the mouse is moved over a underlined word the mouse cursor changes to a hand. When you click on the word with the left mouse button (still holding the control key) a context menu is opened. This is where action libraries come into play. An action library provides actions for recognized words. The captions of available actions are displayed in the context menu. When you click on one entry in the context menu the invokeAction() method of the action library component is called. This method subsequently executes the appropriate action (a simple action might be opening some URL in the browser).

Here is a sceenshot of an example smart tag component which recognizes document property keywords like author, subject, title etc. There is only one action defined. This action inserts the value of the recognized document property into the text document.

Stag screenshot1.gif

The Services

For supporting external smart tag components two new service definitions have been added to offapi:

  • com.sun.star.smarttags.SmartTagRecognizer
  • com.sun.star.smarttags.SmartTagAction

The SmartTagRecognizer service exports the interface XSmartTagRecognizer. Accordingly the service SmartTagAction exports the interface XSmartTagAction.

The Interfaces

Recognizer and action components are collections of smart tags. This means a smart tag component can contain recognizers or actions for different topics, e.g. a smart tag for recognizing email addresses and another one for recognizing dates and times can be packed into one single recognizer component (accordingly actions for both the email and the date smart tag can be combined in one action component).

Next sections explain the interfaces of recognizer and action components in detail.

The Recognizer Interface

For a look at the recognizer interface definition go to this page.

This interface is comprised of 7 methods which have to be implemented by a recognizer component.


string getName()
Arguments None.
Return Value Retuns the name of the Regonizer component.


string getDescription()
Arguments None.
Return Value Returns a textual description of the recognizer component.


long getSmartTagCount()
Arguments None.
Return Value The return value indicates how many smart tags are included in the recognizer component.


string getSmartTagName()
Arguments sal_Int32 nSmartTagIndex: Index of the wanted smart tag. Value needs to be between 0 and the number of smart tags available (exclusively).
Return Value Returns the name of one specific smart tag in this recognizer. This name is needed to associate the recognizer part of a smart tag with the action part. Thus there mustn't be two recognizer components installed that include a recognizer withthe same name.


string getSmartTagCaption()
Arguments sal_Int32 nSmartTagIndex: Index of the wanted smart tag. Value needs to be between 0 and the number of smart tags available (exclusively).
XController xController: The reference to the controller of the current document.
Return Value Returns the caption of one specific smart tag in this recognizer. The caption will be display by Openoffice.org Writer in the context menu.


boolean Recognize()
Arguments OUString aWord: Word that shall be checked by smarttag.
sal_Int32 nSmartTagIndex: Index of the wanted smart tag. Value needs to be between 0 and the number of smart tags available (exclusively).
XController xController: The reference to the controller of the current document.
Return Value Returns true if the passed word has a special meaning to the smart tag. Otherwise false is returned.


void initialize()
Description This method is used for initializing the recognizer component and is currently needed by Writer to use xml based smart tags (see example below). For your own smart tag components you can implement this method with an empty body.
Arguments sequence<any> aArguments: Initialization arguments
Return Value None.


The Action Library Interface

For a look at the action library interface definition go to this page.


string getName()
Arguments None.
Return Value Returns the name of the action library component.


string getDescription()
Arguments None.
Return Value Returns a textual description of the action library component.


long getSmartTagCount()
Arguments None.
Return Value The return value indicates how many smart tags are included in the action library component.


string getSmartTagName()
Arguments sal_Int32 nSmartTagIndex: Index of the wanted smart tag. Value needs to be between 0 and the number of smart tags available (exclusively).
Return Value Returns the name of one specific smart tag in this action component. This name is needed to associate the actions of a smart tag with the corresponding recognizer.


string getSmartTagCaption()
Arguments sal_Int32 nSmartTagIndex: Index of the wanted smart tag. Value needs to be between 0 and the number of smart tags available (exclusively).
XController xController: The reference to the controller of the current document.
Return Value Returns the caption of one specific smart tag in this action component. The caption will be display by Openoffice.org Writer in the context menu.


long getActionCount()
Arguments sal_Int32 nSmartTagIndex: Index of the wanted smart tag. Value needs to be between 0 and the number of smart tags available (exclusively).
XController xController: The reference to the controller of the current document.
Return Value Returns the number of available actions of one specific smart tag in this action library.


string getActionCaption()
Arguments sal_Int32 nSmartTagIndex: Index of the wanted smart tag. Value needs to be between 0 and the number of smart tags available (exclusively).
sal_Int32 nActionIndex: Index of the wanted action. Value needs to be between 0 and the number of actions available for the specified smart tag (nSmartTagIndex).
XController xController: The reference to the controller of the current document.
Return Value This function returns the caption of an action of one specific smart tag in this action library.


void invokeAction()
Arguments sal_Int32 nSmartTagIndex: Index of the wanted smart tag. Value needs to be between 0 and the number of smart tags available (exclusively).
sal_Int32 nActionIndex: Index of the wanted action. Value needs to be between 0 and the number of actions available for the specified smart tag (nSmartTagIndex).
string aWord: Word that was recognized as actionable.
XController xController: The reference to the controller of the current document.
Return Value None.


void initialize()
Description This method is used for initializing the action library component and is currently needed by Writer to use xml based smart tags (see example below). For your own smart tag components you can implement this method with an empty body.
Arguments sequence<any> aArguments: Initialization arguments
Return Value None.
Retrieved from "https://wiki.openoffice.org/w/index.php?title=Writer/Smart_Tags&oldid=24088"
Personal tools