ADOCKSTATE( ) Function

  • Article

Retrieves the dock state of any dockable form, Integrated Development Environment (IDE) window, or toolbar. For forms only, you can use the GetDockState Method. ADOCKSTATE( ) is available in the run time.

ADOCKSTATE( ArrayName [, nType | nExtended])

Parameters

  • ArrayName
    Specifies an array with one or more rows containing the dock state of dockable items.

    Note

    Both system and user-defined toolbars can appear in the array. A form appears in the array only if the form's Dockable property is set to a value greater than 0.

    The following table illustrates the information that the array contains.

    Element Description

    1

    Name of the form, IDE window, or toolbar.

    For user-defined toolbars, the first element contains the Caption property value for that toolbar.

    2

    Dock state:

    1 - Docked

    0 - Undocked

    3

    Dock position.

    For form and toolbar values, see DockPosition Property. For windows, see DOCK Command.

    4

    Target object that specified object is docked with.

    This element does not apply to toolbars unless they are docked to the main Visual FoxPro window. For toolbars or windows docked to the main Visual FoxPro window, the fourth element contains the main Visual FoxPro window name, which you can retrieve using the _VFP Caption property. If a window or toolbar is not docked, the fourth element contains an empty string.

    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.

    5

    Object reference to docking form or toolbar.

    Applies only when docking user-defined forms or toolbars; otherwise, this element contains an empty string (IDE window).

    6

    Object reference to the target object if it is a user-defined form. If the target object is the main Visual FoxPro window, this element contains an object reference to the _SCREEN system variable. Otherwise, this element contains an empty string (IDE window).

  • nType
    Specifies one or more items for which you want ADOCKSTATE( ) to return dock state information.

    The following table lists the values for nType.

    nType Description

    0

    Return all or no windows. (Default)

    1

    Return only IDE windows.

    2

    Return only toolbars.

    3

    Return only user-defined forms.

  • nExtended
    Specifies the number of elements to return in the array.

    The following table lists the values for nExtended.

    nExtended Description

    0

    Return a four-element array for windows and toolbars.

    1

    Return a six-element array for forms.

Return Value

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

Remarks

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 traverses windows from top to bottom, 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. 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,1)  && Outputs "COMMAND".
? dockState(1,4)  && Outputs an empty string because the Command    
                && window is not docked.
? dockState(2,1)  && Outputs "Standard". 
? dockState(2,4)  && 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 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,1)  && Outputs "Standard". 
? dockState(1,4)  && Outputs "Microsoft Visual FoxPro".
? dockState(2,1)  && Outputs "COMMAND". 
? dockState(2,4)  && Outputs "Microsoft Visual FoxPro".

See Also

Tasks

How to: Dock Forms
How to: Dock Toolbars
How to: Dock Windows

Reference

Caption Property (Visual FoxPro)
DockPosition Property
DOCK Command
Docked Property

Other Resources

Functions