Defining a Service
The new-style UNOIDL services combine interfaces and properties to specify a certain functionality. In addition, old-style services can include other services. For these purposes, interface
, property
and service
declarations are used within service specifications. Usually, services are the basis for an object implementation, although there are old-style services in the OpenOffice.org API that only serve as a foundation for, or addition to, other services, but are not meant to be implemented by themselves.
We are ready to assemble our ImageShrink
service. Our service will read image files from a source directory and write shrunk versions of the found images to a destination directory. Our XImageShrink
interface offers the needed capabilities, together with the interface com.sun.star.document.XFilter that supports two methods:
boolean filter( [in] sequence< com::sun::star::beans::PropertyValue > aDescriptor) void cancel()
A new-style service can only encompass one interface, so we need to combine XImageShrink
and XFilter
in a single, multiple-inheritance interface:
#ifndef __org_openoffice_test_XImageShrinkFilter_idl__ #define __org_openoffice_test_XImageShrinkFilter_idl__ #include <com/sun/star/document/XFilter.idl> #include <org/openoffice/test/XImageShrink.idl> module org { module openoffice { module test { interface XImageShrinkFilter { interface XImageShrink; interface com::sun::star::document::XFilter; }; }; }; }; #endif
The ImageShrink
service specification is provided by the following code:
#ifndef __org_openoffice_test_ImageShrink_idl__ #define __org_openoffice_test_ImageShrink_idl__ #include <org/openoffice/test/XImageShrinkFilter.idl> module org { module openoffice { module test { service ImageShrink: XImageShrinkFilter; }; }; }; #endif
A new-style service is defined using the service
declaration. A new-style service opens with the keyword service
, followed by a service name, a colon, the name of the interface supported by the service, and, finally, a semicolon. The first letter of the service name should be upper-case.
service ServiceName: XInterface;
An old-style service is much more complex. It opens with the keyword service
, followed by a service name and the service body in braces, and, finally, a semicolon. The body of a service can reference interfaces and services using interface
and service
instructions, and it can identify properties supported by the service through [property]
instructions.
-
Interface
keywords followed by interface names in a service body indicates that the service supports these interfaces. By default, theinterface
forces the developer to implement this interface. To suggest an interface for a certain service, prepend an [optional] flag in front of the keywordinterface
. This weakens the specification to a permission. An optional interface can be implemented. Use one interface declaration for each supported interface or give a comma-separated list of interfaces to be exported by a service. You must terminate theinterface
instruction using a semicolon.
-
service
instructions in a service body include other services. The effect is that all interface and property definitions of the other services become part of the current service. A service reference can be optional using the[optional]
flag in front of theservice
keyword. Use one declaration per service or a comma-separated list for the services to reference. Theservice
declaration ends with a semicolon.
-
[property]
declaration s describe qualities of a service that can be reached from the outside under a particular name and type. As opposed to interface attributes, these qualities are not considered to be a structural part of a service. Refer to the section Properties in the chapter Professional UNO to determine when to use interface attributes and when to introduce properties in a service . Theproperty
keyword must be enclosed in square brackets, and continue with a known type and a property identifier. Just like a service and an interface, make a property non-mandatory writing[property, optional]
. Besides optional,there is a number of other flags to use with properties. The following table shows all flags that can be used with[property]
:
Property Flags | Description |
---|---|
optional
|
Property is non-mandatory. |
readonly
|
The value of the property cannot be changed using the setter methods for properties, such as setPropertyValue(string name) .
|
bound
|
Changes of values are broadcast to com.sun.star.beans.XPropertyChangeListeners registered with the component. |
constrained
|
The component must broadcast an event before a value changes, listeners can veto. |
maybeambiguous
|
The value cannot be determined in some cases, for example, in multiple selections. |
maybedefault
|
The value might come from a style or the application environment instead of from the object itself. |
maybevoid
|
The property type determines the range of possible values, but sometimes there may be situations where there is no information available. Instead of defining special values for each type denoting that there are no meaningful values, the UNO type void can be used. Its meaning is comparable to null in relational databases.
|
removable
|
The property is removable. If a property is made removable, you must check for the existence of a property using hasPropertyByName() at the interface com.sun.star.beans.XPropertySetInfo and consider providing the capability to add or remove properties using com.sun.star.beans.XPropertyContainer.
|
transient
|
The property will not be stored if the object is serialized (made persistent). |
- Several properties of the same type can be listed in one
property
declaration. Remember to add a semicolon at the end. Implement the interface com.sun.star.beans.XPropertySet when putting properties in your service, otherwise the properties specified will not work for others using the component.
The following UNOIDL snippet shows the service, the interfaces and the properties supported by the old-style service com.sun.star.text.TextDocument as defined in UNOIDL. Note the optional interfaces and the optional and read-only properties.
service TextDocument { service com::sun::star::document::OfficeDocument; interface com::sun::star::text::XTextDocument; interface com::sun::star::util::XSearchable; interface com::sun::star::util::XRefreshable; interface com::sun::star::util::XNumberFormatsSupplier; [optional] interface com::sun::star::text::XFootnotesSupplier; [optional] interface com::sun::star::text::XEndnotesSupplier; [optional] interface com::sun::star::util::XReplaceable; [optional] interface com::sun::star::text::XPagePrintable; [optional] interface com::sun::star::text::XReferenceMarksSupplier; [optional] interface com::sun::star::text::XLineNumberingSupplier; [optional] interface com::sun::star::text::XChapterNumberingSupplier; [optional] interface com::sun::star::beans::XPropertySet; [optional] interface com::sun::star::text::XTextGraphicObjectsSupplier; [optional] interface com::sun::star::text::XTextEmbeddedObjectsSupplier; [optional] interface com::sun::star::text::XTextTablesSupplier; [optional] interface com::sun::star::style::XStyleFamiliesSupplier; [optional, property] com::sun::star::lang::Locale CharLocale; [optional, property] string WordSeparator; [optional, readonly, property] long CharacterCount; [optional, readonly, property] long ParagraphCount; [optional, readonly, property] long WordCount; };
Content on this page is licensed under the Public Documentation License (PDL). |