Protocol Handler

From Apache OpenOffice Wiki
Jump to: navigation, search



The dispatch framework binds user interface controls, such as menu or toolbar items, to the functionality of Apache OpenOffice. Every function that is reachable in the user interface is described by a command URL and corresponding parameters.

The protocol handler mechanism is an API that enables programmers to add arbitrary URL schemas to the existing set of command URLs by writing additional protocol handlers for them. Such a protocol handler must be implemented as a UNO component and registered in the Apache OpenOffice configuration for the new URL schema.

Overview

To issue a command URL, the first step is to locate a dispatch object that is responsible for the URL. Start with the frame that contains the document for which the command is meant. Its interface method queryDispatch() is called with a URL and special search parameters to locate the correct target. This request is passed through the following instances:

disabling commands Checks if command is on the list of disabled commands, described in Disable Commands
interception Intercepts command and re-routes it, described in Dispatch Interception
targeting Determines target frame for command, described in Target Frame
controller Lets the controller of the frame try to handle the command, described in Processing Chain
protocol handler Determines if there is a custom handler for the command, described in this section
interpret as loadable content Loads content from file, described in URL Parameter. Generally contents are loaded into a frame by a com.sun.star.frame.FrameLoader , but if a content (e.g. a sound) needs no frame, a com.sun.star.frame.ContentHandler service is used, which needs no target frame for its operation.

The list shows that the protocol handler will only be used if the URL has not been called before. Because targeting has already been done, it is clear that the command will run in the located target frame environment, which is usually "_self".

Documentation note.png The target "_blank" cannot be used for a protocol handler. Since "_blank" leads to the creation of a new frame for a component, there would be no component yet for the protocol handler to work with.

A protocol handler decides by itself if it returns a valid dispatch object, that is, it is asked to agree with the given request by the dispatch framework. If a dispatch object is returned, the requester can use it to dispatch the URL by calling its dispatch() method.

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages