Difference between revisions of "Documentation/DevGuide/OfficeDev/Component/Models"

Latest revision as of 13:04, 9 August 2021

There is not an independent specification for a model service. The interface com.sun.star.frame.XModel is currently supported by Writer, Calc, Draw and Impress document components. In our context, we call objects supporting com.sun.star.frame.XModel, model objects. All Apache OpenOffice document components have the service com.sun.star.document.OfficeDocument in common. An OfficeDocument implements the following interfaces:

XModel

The interface com.sun.star.frame.XModel inherits from com.sun.star.lang.XComponent and introduces the following methods, which handle the model's resource description, manage its controllers and retrieves the current selection.

  string getURL ()
  sequence < com::sun::star::beans::PropertyValue > getArgs ()
  boolean attachResource ( [in] string aURL, 
                           [in] sequence < com::sun::star::beans::PropertyValue > aArgs )
 
  com::sun::star::frame::XController getCurrentController ()
  void setCurrentController (com::sun::star::frame::XController xController)
  void connectController (com::sun::star::frame::XController xController)
  void disconnectController (com::sun::star::frame::XController xController)
  void lockControllers ()
  void unlockControllers ()
  boolean hasControllersLocked ()
 
  com::sun::star::uno::XInterface getCurrentSelection ()

The method getURL() provides the URL where a document was loaded from or last stored using storeAsURL(). As long as a new document has not been saved, the URL is an empty string. The method getArgs() returns a sequence of property values that report the resource description according to com.sun.star.document.MediaDescriptor, specified on loading or saving with storeAsURL. The method attachResource() is used by the frame loader implementations to inform the model about its URL and MediaDescriptor.

The current or last active controller for a model is retrieved through getCurrentController(). The corresponding method setCurrentController() sets a different current controller at models where additional controllers are available. However, additional controllers can not be created at this time for Apache OpenOffice components using the component API. The method connectController() is used by frame loader implementations and provides the model with a new controller that has been created for it, without making it the current controller. The disconnectController() tells the model that a controller may no longer be used. Finally, the model holds back screen updates using lockControllers() and unlockControllers(). For each call to lockControllers(), there must be a call to unlockControllers() to remove the lock. The method hasControllersLocked() tells if the controllers are locked.

The currently selected object is retrieved by a call to getCurrentSelection(). This method is an alternative to getSelection() at the com.sun.star.view.XSelectionSupplier interface supported by controller services.

XModifiable

The interface com.sun.star.util.XModifiable traces the modified status of a document:

  void addModifyListener ( [in] com::sun::star::util::XModifyListener aListener)
  void removeModifyListener ( [in] com::sun::star::util::XModifyListener aListener)
  boolean isModified ()
  void setModified ( [in] boolean bModified)

XStorable

The interface com.sun.star.frame.XStorable stores a document under an arbitrary URL or its current location. Details about how to use this interface are discussed in the chapter Handling Documents.

XPrintable

The interface com.sun.star.view.XPrintable is used to set and get the printer and its settings, and dispatch print jobs. These methods and special printing features for the various document types are described in the chapters Printing Text Documents, Printing Spreadsheet Documents, Printing Drawing Documents and Printing Presentation Documents.

  sequence< com::sun::star::beans::PropertyValue > getPrinter ()
  void setPrinter ( [in] sequence< com::sun::star::beans::PropertyValue > aPrinter ) 
  void print ( [in] sequence< com::sun::star::beans::PropertyValue > xOptions )

XEventBroadcaster

For versions later than 641, the optional interface com.sun.star.document.XEventBroadcaster at office documents enables developers to add listeners for events related to office documents in general, or for events specific for the individual document type.See Document Events).

  void addEventListener ( [in] com::sun::star::document::XEventListener xListener)
  void removeEventListener ( [in] com::sun::star::document::XEventListener xListener)

The XEventListener must implement a single method, besides disposing():

  [oneway] void notifyEvent ( [in] com::sun::star::document::EventObject Event )

The struct com.sun.star.document.EventObject has a string member EventName, that assumes one of the values specified in com.sun.star.document.Events. These events are also on the Events tab of the Tools → Configure dialog.

The general events are the same events as those provided at the XEventBroadcaster interface of the desktop. While the model is only concerned about its own events, the desktop broadcasts the events for all the loaded documents.

XEventsSupplier

The optional interface com.sun.star.document.XEventsSupplier binds the execution of dispatch URLs to document events, thus providing a configurable event listener as a simplification for the more general event broadcaster or listener mechanism of the com.sun.star.document.XEventBroadcaster interface. This is done programmatically versus manually in Tools → Configure → Events.

XDocumentPropertiesSupplier

The optional interface com.sun.star.document.XDocumentPropertiesSupplier provides access to document information as described in section Document Info. Document information is presented in the File → Properties dialog in the GUI.

In OpenOffice.org versions before 3.0, use the interface com.sun.star.document.XDocumentInfoSupplier instead.

XViewDataSupplier

The optional com.sun.star.document.XViewDataSupplier interface sets and restores view data.

  com::sun::star::container::XIndexAccess getViewData ()
  void setViewData ( [in] com::sun::star::container::XIndexAccess aData)

The view data are a com.sun.star.container.XIndexAccess to sequences of com.sun.star.beans.PropertyValue structs. Each sequence represents the settings of a view to the model that supplies the view data.

Document Specific Features

Every service specification for real model objects provides more interfaces that constitute the actual model functionality For example, a text document service com.sun.star.text.TextDocument provides text related interfaces. Having received a reference to a model, developers query for these interfaces. The com.sun.star.lang.XServiceInfo interface of a model can be used to ask for supported services. The Apache OpenOffice document types support the following services:

Refer to the related chapters for additional information about the interfaces of the documents of Apache OpenOffice.