Docking a Control

Docking a control changes the parent of the control and it may alter the alignment of the control to its parent.

To dock a docking control

1. Left-click the mouse on any part of the docking control.

2. Drag the control to a docking position (indicated by a single-line border on the dragging rectangle).

3. Release the mouse.

A docking rectangle is drawn in the approximate docking position that will result when the mouse is released. Holding down the Ctrl or Shift key ensures that a floating window will result. The Ctrl key causes the floating window to adopt its current horizontal size and the Shift key causes the floating window to adopt the smallest horizontal size possible.

The JadeDockBase control provides a drawGrip property that optionally displays a grip bar on dock controls to make it easier for the user to click on the control and possibly indicating to the user that the control can be dragged.

When a user drags a control around on the form, the process drills down through the windows under the mouse position to assess whether the windows are possible docking targets and whether that type of docking is allowed (for example, docking on the left of the window). This occurs even if non-eligible children cover the window.

If an eligible window is located, the queryDock event method is called for the docking control that is being dragged. That event passes the window with which docking is being requested and the type of docking. The queryDock event method must return whether the docking is accepted or rejected. If the method is not implemented, docking is accepted by default. The queryDock method allows you stricter control over what control can be actually docked where. The dragging rectangle is drawn in a way to indicate docking is possible only when the queryDock method returns true. The queryDock event method is called only once for each potential docking candidate and docking position combination during a dragging episode.

When a user drags a control and releases the mouse in a docking position, the following occurs.

1. The parent of the control is changed to the window that is accepting the docking.

2. The value of the alignContainer property of the control that is being docked is changed to the docking type.

3. If the control is the only visible child of a floating form, the floating form is destroyed.

4. If the control is the only visible child of a JadeDockContainer control, that container is hidden.

5. The position and size of the controls on the form are re-evaluated for the effects on their alignments caused by the removal of the control from the form.

   You can dock a JadeDockBar or JadeDockContainer control into any docking position (with one exception), regardless of the value of its alignContainer property. The docking control then adopts the new alignContainer property value implied by the docking mode. The exception is that a JadeDockBar control that has its alignContainer property set to AlignContainer_None cannot be docked AlignContainer_AllHorizontal or AlignContainer_AllVertical.

   A JadeDockBar control whose alignContainer property is set to AlignContainer_None is mostly useful as a toolbar sitting on a JadeDockContainer control as its parent and when docked somewhere else, it remains at its current size or the size derived from its children if the value of the alignChildren property is set to AlignChildren_Auto. Even when dragged and docked left, right, top, or bottom, it requires JadeDockContainer control as its parent. If it is not docked into a JadeDockContainer control, it clones its original JadeDockContainer parent or creates a new JadeDockContainer control if it did not have one.

   In addition, if the JadeDockBar control alignChildren property is not set to AlignChildren_Auto and the width of the control is greater that its height and the control is dragged to a left or right docking position (and it is not currently docked left or right), the values of width and height properties are exchanged when considering the docking position.

   Similarly, if the height of the control is greater than its width and the control is dragged to a top or bottom docking position (and it is not currently docked top or bottom), the values of width and height properties are exchanged when considering the docking position. This is necessary because the control does not know how to resize itself. For example, if the control were docked at the top and then dragged to the left position and these exchanges were not done, the control would retain its current width, stretch its height, and therefore probably use all of the space in its parent.

6. The docked event method of the JadeDockBar or JadeDockContainer control that is being docked is called on completion of the process, allowing any JADE logic adjustments that may be required.

Floating a docking control causes the form to re-evaluate the alignment of controls affected by the control being removed from the form. Floating a control does not cause the form size to be changed or a non-aligned control to be repositioned.

To handle the removal of the docking control from the form, you should place other controls on a Frame control that is aligned ‘all’ and that is a sibling of the docking control. For details, see the alignContainer property.

If the form is an MDI frame, the MDI client window that hosts the MDI child forms will be automatically repositioned and resized by default (unless Form::moveMdiClient has been called, in which case it is your responsibility).

The rules for displaying a resize bar to the right or on the bottom of JadeDockBar and JadeDockContainer controls when the value of the showResizeBar property is true are as follows.

• A resize bar is displayed on the right of the control if all of the controls that border the control on the right and that share the same parent know how to handle a user resize and they fill the entire right edge. The specific cases handled are:

  • The value of the alignContainer property is AlignContainer_AllVertical and there is another control with the same parent directly to its right (this could be a JadeDockBar, JadeDockContainer, or a Frame control) and whose alignContainer property is also set to AlignContainer_AllVertical.

  • The control is a JadeDockBar control, the value of the alignContainer property is AlignContainer_Left, the value of its alignChildren property is not set to AlignChildren_Auto (otherwise the control automatically resizes), and there is another JadeDockBar control with the same parent directly to its right with the value of the alignContainer property also set to AlignContainer_Left and its alignChildren property also not set to AlignChildren_Auto.

    A left-aligned JadeDockContainer control cannot do this, because it always resizes the control to the required minimum width.

  • The control is a JadeDockBar, the value of the alignContainer property is AlignContainer_Left, the value of its alignChildren property is not AlignChildren_Auto (otherwise the control automatically resizes), and all controls bordering the right edge with the same parent have the value of the alignContainer property set to AlignContainer_Top, AlignContainer_Bottom, AlignContainer_AllHorizontal, or AlignContainer_AllVertical and there is at least one AlignContainer_AllHorizontal or AlignContainer_AllVertical aligned control.

    A StatusLine control is aligned AlignContainer_Bottom by default.

• A resize bar is displayed on the bottom of the control for most cases if all of the controls bordering that control on the bottom edge and that share the same parent know how to handle a user resize and they fill the entire edge. The specific cases handled are:

  • The value of the alignContainer property is AlignContainer_AllHorizontal and there is another control with the same parent directly below the control (this could be a JadeDockBar, JadeDockContainer, or a Frame control) and whose alignContainer property is also set to AlignContainer_AllHorizontal.

  • The control is a JadeDockBar control, the value of the alignContainer property is AlignContainer_Top, the value of its alignChildren property is not set to AlignChildren_Auto (otherwise the control automatically resizes), and there is another JadeDockBar control with the same parent directly below it with the value of its alignContainer property also set to AlignContainer_Top and its alignChildren property also not set to AlignChildren_Auto.

    A top-aligned JadeDockContainer control cannot do this, because it always resizes the control to the required minimum height.

  • The control is a JadeDockBar, the value of the alignContainer property is AlignContainer_Top, the value of its alignChildren property is not AlignChildren_Auto (otherwise the control automatically resizes), and all of the controls bordering the bottom edge with the same parent with the values of the alignContainer property also set to AlignContainer_Left, AlignContainer_Right, AlignContainer_AllHorizontal, or AlignContainer_AllVertical and there is at least one AlignContainer_AllHorizontal or AlignContainer_AllVertical aligned control.

When using docked controls, you should be aware of the following points.

• A dock container must have visible children before it can be dragged.

• A dock control can be docked only in its original parent form. It cannot be docked into another form because the logic associated with the control has been compiled against the original form.

• A control can be moved from a floating window by changing its parent in your JADE code.

• A floating JadeDockContainer control is also a candidate for docking; that is, another docking control can be docked into the floating window if the floating dock control allows such a docking.

• Unless you set the appropriate values of the JadeDockContainer, Frame, or Form class allowDocking property for containers, a floated control does not have any suitable docking position available.

• A docking control that is aligned to its parent by using the alignContainer property will not scroll and it remains in place in its parent when the scroll bar of the parent is shifted. The control therefore remains visible and unchanged when the scroll bar of the parent is adjusted.

• Parent windows are evaluated as docking targets if their children are not valid targets, they do not have the appropriate allowDocking permission, or if the queryDock event method request of the child is rejected.