BeforeDock, AfterDock, Undock

Hacker’s Guide to Visual FoxPro
An irreverent look at how Visual FoxPro really works. Tells you the inside scoop on every command, function, property, event and method of Visual FoxPro.

BeforeDock, AfterDock, Undock

These events fire as part of the docking or undocking sequence of a toolbar. BeforeDock fires whenever the toolbar is docked or undocked. AfterDock fires when a toolbar is completely docked (except in one case—see below). Undock fires when a toolbar is undocked, but before it reappears. (And HickoryDickoryDock fires when the mouse runs up the clock.)

Usage

PROCEDURE BeforeDock
LPARAMETERS [ nIndex , ] nLocation

PROCEDURE AfterDock
[ LPARAMETERS nIndex ]

PROCEDURE Undock
[ LPARAMETERS nIndex ]

The nIndex parameter for all three is relevant only when the toolbar is contained in a control array. Then, it identifies the element of the array that fired the event.

The nLocation parameter to BeforeDock uses the same values as DockPosition (–1=undocked; 0–3=docked at top, left, right and bottom, respectively). It lets you know where the toolbar will be docked. This lets you do things like remove or resize controls that don’t dock well in that position. (For example, textual check boxes don’t dock well at the sides.) It would be very cool if you could even bail out of the docking here, but you can’t. Neither NoDefault nor Dock(–1) does anything in BeforeDock.

AfterDock is supposed to fire once the toolbar has settled into its new location. Most of the time, that's what happens. But in VFP 5, if you call Dock and pass the optional x and y coordinates to specify the exact docking position, AfterDock fires after the base bar has been laid down, but before the toolbar actually appears. In VFP 3, AfterDock always fires after the base bar has been laid down and before the controls appear. This bug is fixed in later versions.

In VFP 3, when a toolbar is moved from one docked location to another with the mouse, only BeforeDock and AfterDock fire; Undock does not. When you use Dock to move the toolbar from one docked position to another, BeforeDock fires, then Undock (for the old position), then BeforeDock and AfterDock fire. In VFP 5 and VFP 6, only BeforeDock and AfterDock fire, no matter which way you dock the toolbar. In VFP 7, the docking sequence has changed again. It is the same no matter which way you dock the toolbar, by mouse or by command, but now you get Undock, BeforeDock (with nLocation = –1), BeforeDock again (this time, with the new nLocation), and finally AfterDock. We thought we knew how this was supposed to work, but now we're confused again.

When you release a docked toolbar, Undock and BeforeDock fire after the toolbar's Destroy method. (In VFP 3, it's the other way around—BeforeDock, then Undock.) Our guess is that, for some internal reasons, FoxPro can't release a docked toolbar, so it has to undock it first. Because of this, you'll want to check for the existence of the contained objects before you start to manipulate them within these methods—otherwise, you'll end up with the dreaded "Unknown member" error.

Example

* Handle the case where a control doesn't fit for side docking.
* Making the control invisible solves the problem.

PROCEDURE BeforeDock
LPARAMETERS nLocation
IF INLIST(nLocation,1,2)
   * Dock to side, so remove check box
   This.chkMyCheck.Visible = .F.
ELSE
   * See if we need to put it back
   IF INLIST(This.DockPosition,1,2)
      This.chkMyCheck.Visible = .T.
   ENDIF
ENDIF