+---------------------------------+
|              WTITLE             |
+---------------------------------+
WTITLE([<window name>])

-----------------------------------
Returns title assigned to a window.
Return value - Character
-----------------------------------

User-defined windows can be assigned a title that appears in the top
border of the window.  If you create a window with DEFINE WINDOW, you
can include a TITLE clause to create a title for the window.  FoxPro
system windows (Browse windows, the Command window, the ASCII chart, ...
) all have titles by default.

WTITLE() can be used to return the title for a window.  If a <window
name> is not included in WTITLE(), the title is returned for the
frontmost window.  If output is being directed to the desktop, the null
string is returned.

<window name>
        To return the title for a specific window, include the <window name> in
WTITLE().  If you include the name of a user-defined window (a window
created with DEFINE WINDOW), the title assigned to the window with the
TITLE clause is returned.

        When you issue BROWSE WINDOW to create a Browse window with the
characteristics of a user-defined window, the title of the user-defined
window is returned by WTITLE() if the Browse window does not have a
title.  If the Browse window does have a title, the title of the Browse
window is returned.


Window Names and Titles
-----------------------

Here is some information concerning the names assigned to user-defined
windows, System windows and Browse windows.

Names are assigned to windows in the following manner:

User-defined windows derive their names from the DEFINE WINDOW command.
Given the command DEFINE WINDOW <window name>, <window name> becomes the
name of the window.  There is a distinction between user-defined window
names and titles.  By default user-defined windows do not have titles.
If one is specified -- DEFINE WINDOW <window name> TITLE <expC> -- the
specified title will appear in the top border of the window but does not
become the name of the window.

Note that user-defined windows are the only windows to which output can
be directed and may only be created with the DEFINE WINDOW command.
User-defined windows do not include Browse windows, System windows,
editing windows, report windows, etc.

System windows derive their names from the title of the window. System
windows are part of the FoxPro interface.  Examples of System windows
include the Command window, the View window, the Trace window, the
Filer, the Help window, the Puzzle and so on.

CREATE or MODIFY COMMAND, REPORT, LABEL, and FILE windows derive their
names from the name of the file being created or modified.  The name of
the window will include the file extension if one exists.

Browse windows derive their names from the title of the window.  The
name (and title) of the Browse window is assigned in one of three ways.
By default the Browse window name is the database alias.  If BROWSE is
issued with the WINDOW clause, the Browse window name is the title of
the specified user-defined window (not the name of the user-defined
window).  If the specified user-defined window does not have a title,
the database alias is the name of the BROWSE window.  If a TITLE clause
is specified in the BROWSE command, the specified title is the name of
the Browse window.  If both the TITLE and WINDOW clause are specified,
the TITLE specified on the BROWSE command is the window's name.

Some additional notes on window names:

If you are unsure of the name assigned to a window, check the Window
popup.  All windows are listed at the bottom of the Window popup.

The current output window is denoted in the Window popup with a diamond.
If output is being directed to the screen and not to a user-defined
window, the diamond will be absent from the Window popup.

If you issue the command BROWSE WINDOW <window name>, two windows now
exist.  The Browse window takes on the attributes of the specified
user-defined window but is a separate window.  If a window is active
when you issue the BROWSE command and you do not specify a WINDOW
clause, the Browse window will take on the attributes of the active
window.  You can override this behavior by including the NORMAL clause
in the BROWSE command.

Window names that contain spaces can be specified in commands and
functions that accept window names (MOVE WINDOW, DEACTIVATE WINDOW,
WONTOP(), etc.) by specifying the part of the window name that begins
with the first non-space character and continuing until the first
non-space character is encountered.  User-defined window names cannot
contain spaces but Browse and System windows may.  The Browse window
with the name 'Invoice Entry' can be moved with the command MOVE WINDOW
invoice BY 1,1.

+---------------------------------+
|         Program Example         |
+---------------------------------+
CLOSE ALL
CLEAR WINDOWS
DEFINE WINDOW x FROM 2,2 TO 20,20 TITLE "User Window"

***   Send output to window X
ACTIVATE WINDOW x

***   WONTOP() returns 'X'
WAIT WINDOW "Window On Top " + WONTOP()

***   WOUTPUT() returns 'X'
WAIT WINDOW "Output Window "+ WOUTPUT()

USE GETFILE('DBF')
BROWSE WINDOW x NOWAIT  TITLE "Browse Window"
MOVE WINDOW browse BY 2,5

***   WONTOP() returns 'Browse Window' the Browse window name
WAIT WINDOW "Window On Top " + WONTOP()

***   WOUTPUT() returns 'X'
WAIT WINDOW "Output Window " + WOUTPUT()

***   Send output to the screen
ACTIVATE SCREEN

***   WONTOP() returns 'Browse Window'
WAIT WINDOW "Window On Top " + WONTOP()

***   WOUTPUT() Returns '' (output going to the screen)
WAIT WINDOW "Output Window " + WOUTPUT()

***   Close the Browse window
DEACTIVATE WINDOW browse
WAIT WINDOW "The Browse window is closed"

***   Release the user window X
CLEAR WINDOW
WAIT WINDOW "The user window is released from memory."
BROWSE NOWAIT

***   WONTOP() returns 'FILE' the Browse window name
***   is now the database alias

WAIT WINDOW "Window On Top "+ WONTOP()

***   WOUTPUT() Returns ''  (output going to the screen)
WAIT WINDOW "Output Window "+ WOUTPUT()
CLOSE ALL


-----------------------------------

See Also:  ACTIVATE WINDOW, BROWSE, DEFINE WINDOW, WEXIST(), WLAST(),
WONTOP(), WOUTPUT(), WREAD()

-----------------------------------