Skip to content

start:

Data Exchange in the Form Navigator
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:

  1. The target does not exist, i.e. the components were dropped onto empty space.

  2. The root entry is part of the source components – you can't move the root

  3. One of the source components

    1. is a child of the target component

    2. equals the target component

    3. is a form, and at the same time an ancestor of the target

    4. is a control, and the target is the root component

  4. 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:

  1. The target does not exist, i.e. the components were dropped onto empty space.

  2. 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.

4.3 More to come .....