Functional specification
This document describes the data exchange functionality in the form navigator. This is the small floater which can be switched on when designing a form document, and visualizes the logical structure of the form components (forms, sub forms, control models).
Data exchange means Drag and Drop functionality as well as Clipboard activities.
Table of Contents
1 Acceptance Rules
When doing a copy or move operation, given a set of
source components (e.g. the drag source) and a target component (the
drop target), the operation is rejected according to the rules below. If
and only neither of the rules applies, the operation is accepted.
In general and by default, the source can be an arbitrary mixture of
hidden controls, "normal" controls, and forms, while the destination can
be any valid entry in the form navigator.
1.1 Actions for different Component
Allowed actions differ for the different types of components: (hidden/non-hidden controls, and forms). Additionally, there is a difference if the data exchange is in-place (within the same navigator instance) or if it crosses document boundaries.
The following table shows the acceptance matrix under these aspects.
control \ action |
copy, in-place |
move, in-place |
copy, crossing |
move, crossing |
---|---|---|---|---|
hidden control |
+ |
+ |
+ |
- |
non-hidden control |
- |
+ |
- |
- |
forms |
- |
+ |
- |
- |
If the source of a data exchange operation contains a mixed set of different types, the weakest rules determine the result. Means if you mix for instance a hidden control with a form, then the acceptance rules for the form apply.
There are additional rules which may restrict the operation even further, they are explained in the next paragraphs.
1.2 Move
In addition to the rules from chapter 1.1, a move operation is rejected if one of the following points applies:
-
The target does not exist, i.e. the components were dropped onto empty space.
-
The root entry is part of the source components � you can't move the root
-
One of the source components
-
is a child of the target component
-
equals the target component
-
is a form, and at the same time an ancestor of the target
-
is a control, and the target is the root component
-
-
The target component is a control
1.3 Copy
In addition to the rules from chapter 1.1, a copy operation is rejected if and only if one of the following points applies:
-
The target does not exist, i.e. the components were dropped onto empty space.
-
The target component is no form
2 Functionality
2.1 Drag and Drop
2.1.1 Activation
as usual: Select an arbitrary set of entries in the navigator, and start dragging them.
2.1.2 Mode selection
The default mode is "move", i.e. if you do a DnD
operation without any modifier keys, a move will be triggered.
You can use the usual platform-dependent (e.g. on Windows: Ctrl)
modifier key(s) to force copying
2.2 Clipboard
2.2.1 Activation
as usual: Select an arbitrary set of entries in the navigator, open the context menu (no matter if by mouse or keyboard), and choose "Copy" or "Cut" therein. Alternatively, press the usual, platform-dependent keyboard shortcuts (e.g. on Windows: Ctrl-C for copy, Ctrl-X for cut).
The Paste aka Insert functionality is reachable when via context menu and usual shortcut, too. It is not available if no entry is selected, if more than one entry is selected, or if the selected entry does not fullfill the acceptance rules from chapter 1.
2.2.2 Cutting Entries
If you started a cut, the entries in question will get a brighter icon, indicating that they are to be moved once the move operation is finished. This means they are not removed from the model when you do the cut, but only when you do the paste from the clipboard.
3 Clipboard formats
This chapter is for completeness. It describes the internal clipboard formats used.
The following formats are used for transfering data within one or more instances of the form navigator.
3.1 Hidden controls
-
format name: application/x-openoffice;windows_formatname="svxform.HiddenControlModelsExchange"
-
content: a Sequence< XPropertySet >, denoting the models of the hidden controls to transfer
3.2 Control paths
-
format name: application/x-openoffice;windows_formatname="svxform.ControlPathExchange"
-
content: Sequence< Any >, 2 elements
-
first element: Reference< XNameContainer > which represents the collections of all forms
-
second element: Sequence< Sequence< int > >: Every element describes a "path� to a control model, relative to the container in the container above.
E.g., if the sequence is "( ( 0, 2 ), (1, 3, 2) )", then two elements with the paths "(0, 2)" and "(1, 3, 2)" are described. Means the first element is the third (2!) children of the first (0!) children of the container, and the second element is the third children of the forth children of the second children of the container.
-
3.3 Tree list entries
-
format name: application/x-openoffice;windows_formatname="svxform.FieldNameExchange"
- content: Virtually nothing :). This is not really transfered via
the usual exchange mechanisms, it is just a shortcut for instances
where the drag source is the same as the drop target; in this case the
latter does not need to rebuild all the internal information from the
persistent format 2.
In particular, this means the format does not supply data, it acts as placeholder only.
4 Test cases
4.1 Hidden controls
-
Create a form containing a hidden control. Create a new sub form below the first form.
-
Try to DnD this control to itself, to it's parent, to the sub form, to a free place in the navigator. Check that moving is allowed (and works) on the sub form, and nowhere else.
-
Try the same actions with the first modifier key (Ctrl). This should be a copy operation, thus it should be allowed (and work) on the forms, but nowhere else.
-
-
Create a second document, and a form therein
-
Try to DnD the hidden control from the first document to the form in the second document. Only copying to a form should work.
-
4.2 Non-Hidden Controls
-
Create a form with some controls (except than hidden controls)
-
mark an arbitrary set of controls, and try to DnD them in the navigator. Should be refused all times: Movement is not allowed (as the only existent form is the parent of the controls), and copy is not allowed in general for non-hidden controls.
-