Difference between revisions of "Drawing framework"
m (Introduction of glossary) |
(Added information about resources and configurations) |
||
| Line 12: | Line 12: | ||
The drawing framework can be seen as a resource management system, where the resources are panes, views, tool bars, commands (slots). Different types of resources are managed by individual resource controllers. The resource controllers are synchronized by the configuration controller. Its name comes from the configuration, which describes the set of active resources, i.e. the set of visible panes, views, and tooll bars. Synchronization means that activation or deactivation of resources of different types are made in a fashion that minimizes the overall time and reduces visual artifacts, i.e. flickering. The drawing framework is implemented on top of and abstracts from existing framework functionality provides mostly by the SFX2 and Framework projects. | The drawing framework can be seen as a resource management system, where the resources are panes, views, tool bars, commands (slots). Different types of resources are managed by individual resource controllers. The resource controllers are synchronized by the configuration controller. Its name comes from the configuration, which describes the set of active resources, i.e. the set of visible panes, views, and tooll bars. Synchronization means that activation or deactivation of resources of different types are made in a fashion that minimizes the overall time and reduces visual artifacts, i.e. flickering. The drawing framework is implemented on top of and abstracts from existing framework functionality provides mostly by the SFX2 and Framework projects. | ||
| + | There is a [[Drawing Framework Glossary|glossary]] for the drawing framework. | ||
==Current State== | ==Current State== | ||
The drawing framework is implemented in child work space components1 for panes and views. Tool bars and commands will be integrated soon. | The drawing framework is implemented in child work space components1 for panes and views. Tool bars and commands will be integrated soon. | ||
| + | |||
| + | TODO: Add proper links to the interfacs of the API when the components1 child work space is integrated. | ||
| + | |||
| + | |||
| + | |||
| + | ==Resources== | ||
| + | |||
| + | The set of resources handled by the drawing framework is | ||
| + | |||
| + | * Panes | ||
| + | |||
| + | * Views | ||
| + | |||
| + | * Tool Bars | ||
| + | |||
| + | * Command groups | ||
| + | |||
| + | While the first three need little explanation (the little explanation is done in the API documentation) the concept of [[Drawing Framework Glossary#Command Groups|command groups]] is not used (yet) anywhere else. A command group is a collection of commands realized by a module that implements at least the com::sun::star::frame::XDispatch interface and implements one or more commands (that to some are known as slots). One command group can, for example, implement the commands used by a tool bar, so that a package that provides a new tool bar has to provide at least the actual tool bar and one command group. | ||
| + | |||
| Line 75: | Line 95: | ||
# The synchronization layer uses the configuration controller to synchronize the requests from the application layer. It has no detailed knowledge about individual resources but controls the big picture. | # The synchronization layer uses the configuration controller to synchronize the requests from the application layer. It has no detailed knowledge about individual resources but controls the big picture. | ||
# The factories in the resource layer know '''how''' to activate or deactivate resources. | # The factories in the resource layer know '''how''' to activate or deactivate resources. | ||
| + | |||
| + | |||
| + | |||
| + | ==Configuration== | ||
| + | A configuration describes the set of active resources. The term ''active'' can mean different things for different types of resources. For panes, views, and tool bars it means that they are visible. For a command group it means that that group is ready to process incoming slot calls. | ||
| + | |||
| + | There are two important configurations, which ideally are identical. The current configuration describes the set of currently active resources. The requested configuration describes the set of resources that are requested to be active. Usually the two configurations differe only temporarily after a new request for the activation or deactivation of a resource has been made but not yet processed. Eventually the current configuration is updated to refelect the requested configuration. There may, however, circumstances, that do not allow a reource to be actived or (less likely) deactivated. One reason for this is that some resources are created asynchronously and become available only after a little time. | ||
| + | |||
| + | See the [[Drawing Framework Glossary#Configuration|configuration]] entry in the glossary for examples. | ||
| + | |||
| + | It is possible obtain a copy of the requested configuration and restore that later. This allows to undo temporary changes. | ||
| + | |||
| + | ===ResourceId=== | ||
| + | The configurations use URLs to identify resources. At the moment (cws components1) two URLs are used to specify a resource: the actual resource URL defines the type of the resource, and the optional URL of an anchor to which the resource may be bound. This scheme is realized by the css::drawing::framework::ResourceId interface. The use of two (or possibly more) URLs to describe one resource allows the unique description of each resource with the use of generic names for resource types. | ||
| + | |||
| + | Lets take the slide sorter as an example for this. In the left pane, the slide sorter bar is described by the ResourceId <pre>private:resource/floater/LeftImpressPane, private:/view/SlideSorter</pre>. The slide sorter view in the center pane id described by the ResourceId <pre>private:resource/floater/CenterPane, private:/view/SlideSorter</pre>. | ||
| + | |||
| + | Another advantage of the use of URLs is that a configuration can be unambiguously described by a set of ResourceIds. This allows easy storage of a configuration, i.e. when a slide show is started in place the current configuration is saved. When the slide show ends then the saved configuration is restored. The actual resource objects do not have to be referenced or even be kept alive. | ||
| + | |||
[[Category:Impress]] | [[Category:Impress]] | ||
| − | |||
Revision as of 17:05, 29 November 2006
Contents
Introduction
The drawing framework is a framework employed by the Impress and Draw applications for the synchronized activation and deactivation of resources. It design addresses the following goals
- ease of use
- flexibility
- extensibility
- abstraction from underlying frameworks
The drawing framework can be seen as a resource management system, where the resources are panes, views, tool bars, commands (slots). Different types of resources are managed by individual resource controllers. The resource controllers are synchronized by the configuration controller. Its name comes from the configuration, which describes the set of active resources, i.e. the set of visible panes, views, and tooll bars. Synchronization means that activation or deactivation of resources of different types are made in a fashion that minimizes the overall time and reduces visual artifacts, i.e. flickering. The drawing framework is implemented on top of and abstracts from existing framework functionality provides mostly by the SFX2 and Framework projects.
There is a glossary for the drawing framework.
Current State
The drawing framework is implemented in child work space components1 for panes and views. Tool bars and commands will be integrated soon.
TODO: Add proper links to the interfacs of the API when the components1 child work space is integrated.
Resources
The set of resources handled by the drawing framework is
- Panes
- Views
- Tool Bars
- Command groups
While the first three need little explanation (the little explanation is done in the API documentation) the concept of command groups is not used (yet) anywhere else. A command group is a collection of commands realized by a module that implements at least the com::sun::star::frame::XDispatch interface and implements one or more commands (that to some are known as slots). One command group can, for example, implement the commands used by a tool bar, so that a package that provides a new tool bar has to provide at least the actual tool bar and one command group.
Framework Design
The task of the drawing framework is to negotiate between resource providers on one side and the application that wants to show or hide a resource on the other side. The negotiation process is iterative: the activation of one resource may cause the activation request of other resources. For example, when the user switches the view in the center pane to the outline view, then the task pane is deactivated.
Two phase updates
The negation process is split into two phases, one for the actual negotiation of the requested changes and the other for updating the GUI to reflect these changes.
This is supported by the use of two configurations, the current configuration and the requested configuration. The current configuration contains the currently active resources while the requested configuration contains the resources which are requested to be active.
The actual negotiation phase is triggered by the initial request, for example the switch of the view in the center pane. In this phase only the the requested configuration is modified. The requested change is stored in the requested configurtion and then is broadcasted. Listeners may react by making further requests for the activation or deactivation of other resources. These are again broadcasted and may lead to even more requests. All requests are put into a queue which is processed until there are no more pending requests.
When all requests have been processed and the the requested configuration describes a new consistent state of the GUI then the second, the update phase is started. In this phase only the current configuration is modified.
That is, the requested configuration is not modified directly in this phase. The application can of course request the activation or deactivation of resources. Therefore, in the update phase a copy of the requested configuration is used which remains unchanged during the update.
The different resource controllers are asked to activate or deactivate resources so that eventually the current configuration looks like the requested configuration. Every activation and deactivation is broadcasted like the requests for the activations and deactivations where.
It is the task of the configuration controller to optimize the the update phase with respect to time and visual artifacts, flickering. It does that by acquiring the relevant locks and by calling the resource controllers in the right order.
Three layer design
The drawing framework is made up by a couple of controllers (not of the com::sun::star::frame::XController variety), factories, and modules that are located on three layers. The assignment to one of the layers depends on the knowledge about different aspects of the resource management:
- The application layer controls when to activate or deactivate a resource
- The synchronization layer uses the configuration controller to synchronize the requests from the application layer. It has no detailed knowledge about individual resources but controls the big picture.
- The factories in the resource layer know how to activate or deactivate resources.
Configuration
A configuration describes the set of active resources. The term active can mean different things for different types of resources. For panes, views, and tool bars it means that they are visible. For a command group it means that that group is ready to process incoming slot calls.
There are two important configurations, which ideally are identical. The current configuration describes the set of currently active resources. The requested configuration describes the set of resources that are requested to be active. Usually the two configurations differe only temporarily after a new request for the activation or deactivation of a resource has been made but not yet processed. Eventually the current configuration is updated to refelect the requested configuration. There may, however, circumstances, that do not allow a reource to be actived or (less likely) deactivated. One reason for this is that some resources are created asynchronously and become available only after a little time.
See the configuration entry in the glossary for examples.
It is possible obtain a copy of the requested configuration and restore that later. This allows to undo temporary changes.
ResourceId
The configurations use URLs to identify resources. At the moment (cws components1) two URLs are used to specify a resource: the actual resource URL defines the type of the resource, and the optional URL of an anchor to which the resource may be bound. This scheme is realized by the css::drawing::framework::ResourceId interface. The use of two (or possibly more) URLs to describe one resource allows the unique description of each resource with the use of generic names for resource types.
Lets take the slide sorter as an example for this. In the left pane, the slide sorter bar is described by the ResourceIdprivate:resource/floater/LeftImpressPane, private:/view/SlideSorter. The slide sorter view in the center pane id described by the ResourceId
private:resource/floater/CenterPane, private:/view/SlideSorter.
Another advantage of the use of URLs is that a configuration can be unambiguously described by a set of ResourceIds. This allows easy storage of a configuration, i.e. when a slide show is started in place the current configuration is saved. When the slide show ends then the saved configuration is restored. The actual resource objects do not have to be referenced or even be kept alive.
