Share via

ADOCKSTATE( ) Function

  • Article

Retrieves the dock state of any dockable Integrated Development Environment (IDE) windows or toolbars.

ADOCKSTATE( ArrayName [, 1 | 2 ] )

Parameters

  • ArrayName
    Specifies an array to populate with the dock state of a dockable window. The array contains the following information.
    Element Description
    1 Name of the IDE window or toolbar
    2 Dock state:

    1 - Docked

    0 - Undocked
    3 Dock position. For values, see DOCK WINDOW Command.
    4 Docked window, or name of the window to which the specified window is docked if tab or link-docked. This element does not apply to toolbars.
  • 1
    Return only IDE windows.
  • 2
    Return only toolbars.

Return Values

Numeric data type. ADOCKSTATE( ) returns the number of rows populated or 0 if none found.

Remarks

The array populated can contain both system and user-defined toolbars.

For toolbars or windows docked to the Visual FoxPro desktop, the fourth array element contains the desktop name, which you can retrieve using the _VFPCaption property.

Note   If a toolbar appears between the Visual FoxPro desktop and a window docked to the Visual FoxPro desktop, the fourth element contains the name of the toolbar.

If a window or toolbar is not docked, the fourth element contains an empty string.

The first element in each row for a user-defined toolbar contains the Caption property value for that toolbar.

For tab-docked windows, the leftmost window is the anchor window and contains details about how the entire container is docked. Visual FoxPro traverses the windows from left to right.

For link-docked windows, the upper left window in a link-docked container contains details about how the entire container is docked. The following rules determine docking order:

  • Visual FoxPro traverses the link-docked container beginning with upper leftmost window.
  • Visual FoxPro continues traversing windows from top to bottom followed by from left to right. A link-docked container might consist of multiple inner containers. Thus, the ordering of windows in the ADOCKSTATE( ) array might appear different.
  • The position contained in the third element of the array is relative to the window referenced in first element of the array.
  • Visual FoxPro traverses all link-docked windows first and tab-docked windows second. Essentially, Visual FoxPro makes two passes through a linked container. The first pass is for link-docked windows, and the second is for the tab-docked windows. Visual FoxPro includes only the leftmost tab-docked window in the first pass for link-docked windows.
  • Visual FoxPro traverses a tab-docked container from left to right.

If the third element in the array is set to -1 (not docked), the container is not docked. If the container is docked to the desktop, the third element in the array contains the position in which the container is docked to the Visual FoxPro desktop as referenced in the fourth element of the array.

For example, the following code creates an array, opens and docks several windows, and produces an array as shown:

CLEAR ALL
PUBLIC aa
DIMENSION aa[1]
ACTIVATE WINDOW Command 
ACTIVATE WINDOW Trace 
ACTIVATE WINDOW Document 
ACTIVATE WINDOW Properties 
ACTIVATE WINDOW Watch 
ACTIVATE WINDOW Locals 
SET
DOCK WINDOW View POSITION -1
DOCK WINDOW Command POSITION -1 
DOCK WINDOW Trace POSITION -1
DOCK WINDOW Document POSITION -1
DOCK WINDOW Properties POSITION -1
DOCK WINDOW Watch POSITION -1
DOCK WINDOW Command POSITION 1 WINDOW View
DOCK WINDOW Trace POSITION 1 WINDOW Command
DOCK WINDOW Document POSITION 3 WINDOW View
DOCK WINDOW Properties POSITION 3 WINDOW Trace
DOCK WINDOW Watch POSITION 4 WINDOW Command
DOCK WINDOW Locals POSITION 3 WINDOW Command
ADOCKSTATE(aa,1)

The resulting array appears as follows:

Row First element Second element Third element Fourth element
1 Trace 1 -1  
2 Properties 1 3 Trace
3 Watch 1 2 Trace
4 Locals 1 3 Watch
5 View 1 2 Watch
6 Document View 1 3 View
7 Command 1 4 Watch

Visual FoxPro displays docking information for debugger windows in the debugger. If a window is undocked, Visual FoxPro shows the name, dock state (0) and position (-1). If a window is docked, Visual FoxPro shows only the name, dock state (1), position, and window ("Visual FoxPro Debugger").

Historically in prior versions of Visual FoxPro, the Data Session window has always been referred to as the View window. Additionally, language used to control this window, such as HIDE WINDOW, ACTIVATE WINDOW, WONTOP( ), also refers to this window as the View window. Visual FoxPro continues to refer to the View window for the ADOCKSTATE( ) function.

Example

The following example shows the return results of ADOCKSTATE( ) when no toolbars or windows have been previously docked, for example, after deleting the FoxUser resource files or when Visual FoxPro is newly installed. Make sure the Command window is open.

CLEAR
dockNum = ADOCKSTATE(dockState)
? dockNum   && Returns 2 because Standard toolbar also exists.
? dockState(1)  && Outputs "COMMAND".
? dockState(4)  && Outputs an empty string because the Command    
                && window is not docked.
? dockState(5)  && Outputs "Standard". 
? dockState(8)  && Outputs "Microsoft Visual FoxPro" because the 
                && Standard toolbar is docked to the Microsoft  
                && Visual FoxPro desktop.

The following example shows how to use the DOCK WINDOW command to dock the Command window to the Visual FoxPro desktop window and use ADOCKSTATE( ) to obtain the dock state of the Command window. First, make sure the Command window is open. After docking the Command window, you can see that the Standard toolbar and Command windows are docked to the Microsoft Visual FoxPro desktop window. The position of the toolbars or windows in the array returned by ADOCKSTATE( ) can vary depending on the order in which the toolbars or windows are docked.

CLEAR
DOCK WINDOW Command POSITION 0
dockNum = ADOCKSTATE(dockState)
? dockNum   && Returns 2 because Standard toolbar also exists.
? dockState(1)  && Outputs "Standard". 
? dockState(4)  && Outputs "Microsoft Visual FoxPro".
? dockState(5)  && Outputs "COMMAND". 
? dockState(8)  && Outputs "Microsoft Visual FoxPro".

See Also

Functions | Caption Property | DOCK WINDOW Command | Docked Property | Docking Windows