%***********************************************************************
%***********************************************************************
%***********************************************************************

\chapter {Command Windows}
\index{command window}\index{window}

This chapter covers the classes used to build windows and command
windows.

The classes covered in this chapter include:

\begin{description}
	\item[vCmdWindow] A class to show a window with various command panes.
	\item[vCommandPane] Used to define commands on a command bar.
	\item[vMenu] Used to define pull down menus.
	\item[vPane] Base class for various window panes.
	\item[vStatus] Used to define label fields on a status bar.
	\item[vWindow] A class to show a window on the display.
\end{description}

%------------------------------------------------------------------------

\Class{vCmdWindow}
\Indextt{vCmdWindow}

A class to show a window with various command panes.

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/vcmdwin.h>}
	\item [Class name:] vCmdWindow
 	\item [Hierarchy:] vBaseWindow \rta vWindow \rta vCmdWindow
	\item [Contains:] vDialog, vPane
\end{description}

\subsection* {Description}

The \code{vCmdWindow} class is derived from the \code{vWindow}
class. This class is intended as a class that serves as
a main control window containing various \code{vPane} objects
such as menu bars, canvases, and command bars. The main 
difference between the \code{vCmdWindow} class and the
\code{vWindow} class is how they are treated by the host
windowing system. You will normally derive your windows from
the \code{vCmdWindow} class.

\subsection* {Constructor} %------------------------------------

%............................................................
\Meth{vCmdWindow(char* title)}
\Indextt{vCmdWindow}

\Meth{vCmdWindow(char* title, int h, int w)}

These construct a \code{vCmdWindow} with a title and a size specified
in pixels. You can use \code{theApp->DefaultHeight()} and
\code{theApp->DefaultWidth()} in the call to the constructor to
create a ``standard'' size window. Note that the height and width are
of the canvas area, and not the entire window.

\subsection* {Inherited Methods} %------------------------------

See the section \code{vWindow} for details of the following methods.

\Meth{virtual void KeyIn(vKey key, unsigned int shift)}
\Indextt{KeyIn}
\Meth{virtual void MenuCommand(ItemVal itemId)}
\Indextt{MenuCommand}
\Meth{virtual void WindowCommand(ItemVal Id, ItemVal Val, CmdType Type)}
\Indextt{WindowCommand}

\Meth{virtual void AddPane(vPane* pane)}
\Indextt{AddPane}
\Meth{virtual void GetPosition(int\& left, int\& top, int\& width, int\& height)}
\Indextt{GetPosition}
\Meth{virtual int GetValue(ItemVal itemId)}
\Indextt{GetValue}
\Meth{virtual void RaiseWindow(void)}
\Indextt{RaiseWindow}
\Meth{virtual void ShowPane(vPane* wpane, int OnOrOff)}
\Indextt{ShowPane}
\Meth{virtual void SetValue(ItemVal itemId, int Val, ItemSetType what)}
\Indextt{SetValue}
\Meth{virtual void SetString(ItemVal itemId, char* title)}
\Indextt{SetString}
\Meth{virtual void SetTitle(char* title)}
\Indextt{SetTitle}

\Meth{virtual void CloseWin()}
\Indextt{CloseWin}

\subsection* {See Also}

vWindow

%------------------------------------------------------------------------

\Class{vCommandPane}
\Indextt{vCommandPane}

Used to define commands on a command bar.

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/vcmdpane.h>}
	\item [Class name:] vCommandPane
	\item [Used by:] vCmdWindow
\end{description}

\subsection* {Description}

A command pane is a horizontal bar in a command window that
holds \code{CommandObjects}.  You can use any of the
\code{CommandObjects}, although they all might not make sense
to use on a command bar (a List, for example, is a bit large for
the visual paradigm, but it would work). The layout
is left to right, so you don't need to fill in the RightOf
and Below fields. You can include Frames in a command bar,
and commands contained in that frame do use the RightOf
and Below attributes. 

You define the commands on a command bar using a
\code{CommandObject} array. You first create the command pane
with \code{myCmdPane = new vCommandPane(CommandBar)}, and
then add it to the window with \code{AddPane(myCmdPane)}.

You then handle the command objects in a command bar pretty much
like the same way as in a dialog. The main difference is that you
use the \code{vWindow} versions of \code{SetValue} and \code{WindowCommand}
instead of the corresponding methods of the \code{vDialog} class.
Other than the left to right ordering, things are pretty much the
same.

\subsection* {Example}

The discussion of \code{CommandObject} and \code{vDialog} contains
several examples of defining command objects.

See the section \code{vPane} for a general description of panes.

\subsection* {See Also}

vWindow, vStatus, CommandObject, vDialog, vPane

%------------------------------------------------------------------------
\Class{vMenu}
\Indextt{vMenu}

Used to define pull down menus.

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/v\_menu.h>}
	\item [Type name:] vMenu
\end{description}

\subsection* {Description}

The \code{vMenu} structure is used to define pulldown menus,
which includes the top level item on the menu bar, as well as the
items contained in the pulldown menu. These are passed to the
constructor of a \code{vCmdWindow} type object.

See the section \code{vPane} for a general description of panes.

\subsection* {Definition}

\footnotesize
\begin{verbatim}
typedef struct vMenu
  {
    char* label;       // The label on the menu
    ItemVal menuId;    // A User assigned unique id
    unsigned
     sensitive : 1,    // If item is sensitive or not
     checked : 1;      // If item is checked or not (*)
    char* keyLabel;    // Label for an accelerator key (*)
    vKey accel;        // Value of accelerator key
    vMenu* SubMenu;    // Ptr to a submenu 
    unsigned int kShift; // Shift state of accelerator
  } MenuItem;
\end{verbatim}
\normalfont\normalsize

Note that the items marked with an asterisk (\code{checked} 
and \code{keyLabel}) are not used when defining the top 
level menu bar items.

\subsection* {Structure Members}

\Param{char* label} The label on the menu.
See the description of the \code{vWindow} class for
information on setting the label of menu bar items.

For some platforms (Windows, but not Athena X),
\index{menu shortcut}
you can add a \& to indicate a shortcut for the command.
For example, specifying a label \code{\&File} allows
Windows users to pull down the \code{File} menu
by pressing \code{Alt-F}, and specifying a submenu label as
\code{\&New} allows the user to use \code{Alt-N} to select
the \code{New} command. The Athena version of \V\ strips
the \&, so you can (and probably should) denote shortcuts
for menu items even in Athena versions.

\Param{ItemVal MenuId} A user assigned unique id. This id is
\index{ItemVal}
passed to the \code{MenuCommand} (or \code{WindowCommand}) method
when a menu item is selected.  If a menu item with a submenu is
selected, \V\ will not return the id, but will cause the submenu
to be displayed.

It will be common practice to use the same id for menu items and
command objects defined on a command bar, and the same id value would then
be passed to \code{WindowCommand} for either the menu selection
or the equivalent button selection. Similarly, using the id to
set the item's sensitivity will change both the menu and the
button.

The values you use for your id in menus and controls should
be limited to being less than 30,000. The predefined
\V\ values are all above 30,000, and are reserved. \emph{
There is no enforcement of this policy.} It is up to you
to pick reasonable values.

If you want a separator line on a pulldown menu, you must use
the predefined value \code{M\_Line} for the \code{MenuId}.

\Param{int sensitive} Controls if item is initially sensitive or
not. Insensitive items are displayed grayed out. The predefined
symbols \code{notSens} and \code{isSens} can be used to define
the \code{MenuItem}. Note that \V\ uses the static definition of
the \code{MenuItem} to store the current sensitive state, and all
menus (or windows) sharing the same static definition will have
the same sensitive state. See the description of the \code{vWindow}
class for information on setting the sensitivity of menu bar
items.

\Param{int checked} The user can put a check mark in front of the
label of a menu item. This convention is often used to show a
given setting is in effect. Like the sensitive member, this
statically tracks the checked state. The predefined values
\code{isChk} and \code{notChk} can be used to specify this value.
This value is not used when defining the top level menu bar, and
you can use the predefined value \code{notUsed} for that case.
See the description of the \code{vWindow} class for information
on setting checked state of menu items.

\Param{char* keyLabel} Label for an accelerator key. The
predefined symbol \code{noKeyLbl} can be used to indicate there
is no \code{keyLabel}. This value is not used when defining the
top level menu bar, and you can use the predefined value \code{notUsed}
accelerator key.

\Param{vKey accel} This is the value of the keystroke that
is the accelerator for this menu item. When the user presses
this key, the \code{vWindow::MenuCommand} method will be
called just as though the user had used the mouse to select
the menu item. This value may be used in combination with the
\code{kShift} and \code{keyLabel} parameters. See the
explanation of \code{vWindow::KeyIn} for a complete
explanation of key codes.

Note that the Windows version really doesn't support
\code{Alt} key codes. The Windows system intercepts
Alt keys and tries to interpret them as menu accelerators.
Unfortunately, there is no simple way to override this
behavior, so Alt keys are essentially unsupported on Windows.
Using functions keys with combinations of Shift and Control
is supported, as are regular control keys.

\Param{MenuItem* SubMenu} Pointer to another \code{MenuItem}
definition of a submenu. \V\ will cause submenus to be shown
automatically when selected. The predefined symbol \code{noSub}
can be used to indicate there is no submenu.

\Param{unsigned int kShift} This is the shift value to
be used with the \code{accel} key definition. To use
\code{Ctrl-D} as the accelerator key, you would specify the
value for Control-D (easily specified as \code{'D'-'@'}) for
\code{accel}, and leave \code{kShift} set to zero. If you use a
Ctrl code, you must specify both the control code, and the
\code{VKM\_Ctrl} shift code. Note that this value is at the end
of the \code{vMenu} structure because of it was forgotten in
early implementations of \V. By placing it at the end, earlier
versions of \V code are compatible with no changes to the source.
Sigh, I didn't get this one right.

\subsection* {Example}

This example defines a menu bar with the items \emph{File} and
\emph{Edit}. The \code{MenuBar} definition would be passed to the
constructor of the appropriate \code{vCmdWindow} derived object.

\vspace{.1in}
\small

\includegraphics{fig/menubar.eps}

\normalfont\normalsize
\vspace{.1in}

Only the File submenu is shown here, and is an example of the
menu as it might be included in a standard File menu. Note that this
example menu includes items that can all be specified by using
standard predefined values (see \emph{Predefined ItemVals}). It
also includes an optionally defined \code{Debug} item. A
definition like this might be used for the \code{FileMenu} in
the \code{Menu} example. Note that \& is used to denote shortcuts
for menu items.

\footnotesize
\begin{verbatim}
static vMenu FileMenu[] =
  {
    {"&New", M_New, isSens,notChk,noKeyLbl,noKey,noSub},
    {"&Open", M_Open, isSens,notChk,noKeyLbl, noKey, noSub},
    {"&Save", M_Save, isSens,notChk,noKeyLbl,noKey,noSub},
    {"Save &As", M_SaveAs, isSens,notChk,noKeyLbl,noKey,noSub},
#ifdef vDEBUG
    {"-", M_Line, notSens,notChk,noKeyLbl,noKey,noSub},
    {"&Debug", M_SetDebug,isSens,notChk,noKeyLbl,noKey,noSub},
#endif
    {"-", M_Line, notSens,notChk,noKeyLbl,noKey,noSub},
    {"E&xit", M_Exit, isSens,notChk,noKeyLbl,noKey,noSub},
    {0}
  };

static vMenu EditMenu[] = {...};  // Define Edit pulldown

// Define menu bar, which includes the File and Edit pulldown
static vMenu MenuBar[] =
  {
    {"&File",M_File,isSens,notUsed,notUsed,noKey,&FileMenu[0]},
    {"&Edit",M_Edit,isSens,notUsed,notUsed,noKey,&EditMenu[0]},
    {0,0}                         // end of menubar
  };

  ...

  vMenuPane myMenuPane = new vMenuPane(MenuBar);  // construct pane
  AddPane(myMenuPane);
\end{verbatim}
\normalfont\normalsize

\subsection* {See Also}

vWindow, vPane

%------------------------------------------------------------------------

\Class{vPane}
\Indextt{vPane}

The \code{vPane} class serves as a base class for various pane
objects contained by the \code{vWindow} class. There are no
methods or services provided by the \code{vPane} class that
you need to use directly, but the class is used extensively by
\V\ internally.

There are four types of panes used by \V\ in a \code{vCmdWindow},
including menu panes, canvas panes, command panes and status
panes. To add a pane to a window, you will first define the
contents of the pane (menu, commands, status info) using static
arrays, then construct an instance of the pane with \code{new
vWhateverPane}. Then you add the instance to the window using
\code{AddPane}.

Note that the canvas panes are described in the \Sect{Drawing}
chapter. The commands used with a command pane are described
in the \Sect{Dialogs} chapter, while menus and status bars
are covered in \code{vMenu} and \code{vStatus} in this chapter. 

\subsection* {Canvas Pane}
\index{canvas pane}
\begin{description}
        \item [Header:] \code{<v/vcanvas.h>}
        \item [Class name:] vCanvasPane
	\item [Constructor:] \code{userCanvasPane()}
\end{description}

\subsection* {Command Pane}
\index{command pane}
\begin{description}
        \item [Header:] \code{<v/vcmdpane.h>}
        \item [Class name:] vCommandPane
	\item [Constructor:] \code{vCommandPane(CommandObject* cmdbar)}
\end{description}

\subsection* {Menu Pane}
\index{menu pane}
\begin{description}
        \item [Header:] \code{<v/vmenu.h>}
        \item [Class name:] vMenuPane
	\item [Constructor:] \code{vMenuPane(vMenu* menubar)}
\end{description}

\subsection* {Status Pane}
\index{status pane}
\begin{description}
        \item [Header:] \code{<v/vstatusp.h>}
        \item [Class name:] vStatusPane
	\item [Constructor:] \code{vStatusPane(vStatus* sbar)}
\end{description}

\subsection* {See Also}

CommandObject, vCanvasPane, vCmdWindow, vCommandPane, vMenu,
vStatus

%--------------------------------------------------------------------

\Class{vStatus}
\Indextt{vStatus}

Used to define label fields on a status bar.

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/v\_defs.h>}
	\item [Type name:] vStatus
	\item [Used by:] vWindow
\end{description}

\subsection* {Description}

The \code{vStatus} structure is used to define the top level
status bar included on a \code{vCmdWindow}, and the labels it
contains. The \code{vStatus} array is usually passed to the
\code{vStatusPane} constructor. See the section \code{vPane} for
a general description of panes.

\subsection* {Definition}

\footnotesize
\begin{verbatim}
typedef struct vStatus      // for status bars
  {
    char* label;            // text label
    ItemVal statId;         // id
    CmdAttribute attrs;     // attributes - CA_NoBorder
    unsigned sensitive : 1; // if button is sensitive or not
    int width;              // to specify width (0 for default)
  } vButton;
\end{verbatim}
\normalfont\normalsize

\subsection* {Structure Members}

\Param{char* label} Text of label field. See the description of
the \code{vWindow} class for information on changing the text of
a label.

\Param{ItemVal id} Id for the label. Use this value when changing
value with \code{SetString} or \code{SetValue}.

\Param{CmdAttribute attrs} The current implementation only uses
\index{CA\_NoBorder}
the \code{CA\_NoBorder} attribute. If \code{CA\_NoBorder} is
supplied, the label will be drawn on the command bar without a border
or box around it.  Not supplying \code{CA\_NoBorder} (e.g.,
\code{CA\_None}) will result in a label with a border or box
around it. In general, unbordered labels don't change, and
bordered labels are used to show changing status.

\Param{int sensitive} If label is sensitive or not. Use
predefined symbols \code{isSens} and \code{notSens} to specify
the initial state. On some implementations, the label will be
grayed if it is insensitive. The sensitivity can be changed
using \code{vWindow::SetValue} as described in the section
\code{vWindow}.

\Param{int width} This can be used to specify a fixed width for
a label. Normally, the label will be sized to fit the length of the
text. If you provide a non-zero width, then the label field will
remain constant size.

\subsection* {Example}

This shows a sample status bar with two fields. It is added
to a \code{vCmdWindow} using \code{AddPane}. The value of the
file name would be changed by calling    
\code{SetString(m\_curFile, filename)} somewhere in your program.

\vspace{.1in}
\small
\includegraphics{fig/statbar.eps}
\normalfont\normalsize

\footnotesize
\begin{verbatim}
static vStatus sbar[] =
  {
    {"Current file:", m_curMsg,CA_NoBorder,isSens,0},
    {" ", m_curFile,CA_None,isSens,100},
    {0,0,0,0,0}
  };
  ...
  vStatusPane myStatusPane = new vStatusPane(sbar); // construct
  AddPane(myStatusPane);
\end{verbatim}
\normalfont\normalsize

\subsection* {See Also}

vWindow, vPane

%--------------------------------------------------------------------

\Class{vWindow}
\Indextt{vWindow}

A class to show a window on the display.

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/vwindow.h>}
	\item [Class name:] vWindow
 	\item [Hierarchy:] vBaseWindow \rta vWindow
	\item [Contains:] vDialog, vPane
\end{description}

\subsection* {Description}

The \code{vWindow} class is an aggregate class that usually has
associated \code{vPane} objects -- window panes, in other
words. There several kinds of panes, including menu panes,
command bar panes, status panes, and drawing canvas panes. As you
would expect, classes derived from \code{vWindow} also include
panes.

The \code{vWindow} class will probably never be used by your
application - it serves primarily as a superclass for the
\code{vCmdWindow} class. This class may be more useful in
future versions of \V, but for now it is not really useful
by itself. You will typically derive your own class from
\code{vCmdWindow}, and override several of the methods
defined by \code{vWindow} and \code{vCmdWindow}.

Menus and commands in the panes send messages to the \code{Window\-Command}
and \code{Menu\-Command} methods when the user clicks on a command
or menu item contained in the window. The application program can
also change attributes of the various menu items and commands
associated with a window. Canvas panes are designed to handle
their own interaction with the user (mouse events, etc.).

\subsection* {Constructor} %------------------------------------

%............................................................
\Meth{vWindow()}
\Indextt{vWindow}
\Meth{vWindow(char* title)}
\Meth{vWindow(char* title, int h, int w)}
\Meth{vWindow(char* title, int h, int, WindowType wintype)}
\Param {title} Title to place in title bar.
\Param {h,w} The height and width of the window.
\Param {wintype} CMDWINDOW or WINDOW type for window.
\newline
\newline

The constructor for \code{vWindow} is normally called with a
name, size, and possibly a window type. The name will be
displayed in the window's title bar by default. The size is the
initial size of the window's \emph{canvas} work area in pixels.
The type may be \code{CMDWINDOW} or \code{WINDOW}. The constructor
for \code{vCmdWindow} invokes the proper \code{vWindow} constructor.

\subsection* {Methods to Override} %----------------------------

%............................................................
\Meth{virtual void KeyIn(vKey key, unsigned int shift)}
\Indextt{KeyIn}
\index{keyboard input}

\code{KeyIn} is invoked when a key is pressed while a window has
focus. The \code{key} value is the \code{vKey} value of the key
pressed, and \code{shift} indicates the shift state of the key.

Handling the keystroke is not necessarily trivial. Regular ASCII
characters in the range from a Space (0x40) up to a tilde (\tild)
are passed to \code{KeyIn} directly, and shift will be 0, even
for upper case letters. The current version of \V\ does not have
explicit support for international characters, so values between 0x80 and
0xFF are undefined, and correspond to whatever might be the local
convention for the character set.  (This will be one thing for
X and another for Windows - but you can count on the values
for each platform. Thus, you can use non-English characters
on each platform, even though they won't be the same values on X
and Windows. I would like a portable solution for this. If any
non-English users of \V have any ideas about this problem, I'd
like to hear. The choice seems to be between the standard
MS-DOS code page solution and the ANSI character set used
on X platforms. I'm not ready to support multibyte characters
for some time yet.) Values between 0xFF00 and 0xFFFF correspond to the
various function keys and keypad keys found on a typical
keyboard. The standard set by IBM PCs has determined what function keys
are supported by \V\@. The file \code{<v/vkeys.h>} has the
definitions for the key codes supported. 

Besides getting a keycode for the non-ASCII keys, \code{KeyIn}
also gives a shift code corresponding to the Control, Shift, and
Alt modifier keys. (These are defined as \code{VKM\_Ctrl},
\code{VKM\_Shift}, and \code{VKM\_Alt}.) Pressing the F4 key
would return the code for F4 (vk\_F4), while the keystroke Alt-F4
will return the code for the F4 key, and the shift code set to
\code{VKM\_Alt}\@. More than one bit of the shift code can be
set -- the shift values are really bit values. Control keys from
the normal character set (Ctrl-A, etc.) are passed as their true
control code, but \emph{not} the \code{VKM\_Ctrl} shift set.

In addition, you also need to check for the \code{VKM\_Alt}
modifier applied to regular Ascii keys.  The keystroke Alt-K will
be mapped to a \emph{lower case} Ascii 'k' with the \code{VKM\_Alt}
bit set in \code{shift}.  The top row keys (1,2, etc.) can also
be pressed with the  \code{VKM\_Ctrl} bit set in \code{shift},
and your program will need to deal with these.  It will quite
often be the case that your program simply ignores many of these
values.

\code{KeyIn} will also return a value when only a modifier key is
pressed. For example, pressing the Alt key returns a key value of
\code{vk\_Alt}. A macro defined in \code{<v/vkeys.h>}
called \code{vk\_IsModifer(x)} can be used to determine if a key
\code{x} is a modifier. Your program can usually ignore modifier
keys.

If you have defined any keystroke combinations to be accelerators
for menu commands, your program will never see those keystrokes
in \code{KeyIn}. Instead, they are intercepted by the system and
mapped to the appropriate command to pass to the \code{MenuCommand}
method.

Note that the keystrokes are not displayed by the system. It is
up to your program to handle keystrokes and to do something
useful with them.

You should call \code{vWindow::KeyIn} from your derived method
with any keystrokes you don't handle. The \code{vWindow::KeyIn}
method passes these unhandled keystrokes up to the \code{vApp::KeyIn}
method. Thus, you will have the choice of either handling
keystrokes in the window or in the app class.

%............................................................
\Meth{virtual void MenuCommand(ItemVal itemId)}
\Indextt{MenuCommand}
\index{menu commands}

\code{MenuCommand} is called when a menu command is selected.
This virtual function allows menu commands to be distinguished
from other commands in a window, although it is not usually
necessary to do so. The default method simply passes the menu
command along to the \code{WindowCommand} method, so you don't
need to override this method if you don't distinguish between
menu and command events.

%............................................................
\Meth{virtual void WindowCommand(ItemVal Id, ItemVal Val, CmdType Type)}
\Indextt{WindowCommand}
\index{window commands}

This method is invoked when a user activates a command object in
a command pane. The \code{Id} of the command object is passed in
in the \code{Id} field, and the value and type (e.g., C\_Button
or C\_CheckBox) of the command are passed in in the \code{Val}
and \code{Type} parameters. Note that command objects in a
command pane are really no different than the command objects in a
dialog. Most of the discussion for handling these commands is
covered in the sections on dialogs. See \code{vCommandPane} and 
\code{vDialog::DialogCommand} for more details about the values
passed to \code{WindowCommand}.

\code{WindowCommand} is also called by the default \code{MenuCommand}
in response to menu picks. The \code{Id} is the id of the item
that generated the call.

The default behavior of \code{WindowCommand} is to call the
\code{AppCommand} method. However, you will almost always
override the default \code{WindowCommand} method.

\Meth{virtual void WorkSlice()}

See \code{vApp::WorkSlice} for a description of this method.

\subsection* {Utility Methods} %--------------------------------

%............................................................
\Meth{virtual void AddPane(vPane* pane)}
\Indextt{AddPane}

This method is used to add the pane \code{pane} to a window.
Panes will be displayed in the order they are added. You can add
exactly one menu pane, plus canvas, command, and status panes.
You typically first create a given pane (e.g., \code{myPane = new
XPane(PaneDef))}, and then add the pane to the window with
\code{AddPane(myPane)}.

%............................................................
\Meth{void GetPosition(int\& left, int\& top, int\& width, int\& height)}
\Indextt{GetPosition}

Returns the position and size of \code{this} window. These values
reflect the actual position and size on the screen of the window.
On X, this is the whole \code{vCommandWindow} frame. On the
Windows MDI version, it is the size and position of just the
drawing canvas and its scroll bars. The intent of this method
is to allow you to find out where the active window is so
you can move a window, or position a dialog so that it
doesn't cover a window.
It is most useful when used in
conjunction with \code{SetDialogPosition}.

%............................................................
\Meth{virtual int GetValue(ItemVal itemId)}
\Indextt{GetValue}

This method is used to retrieve the value of a menu or command
object in a menu or command pane.  The \code{itemId} is the id of
the item as defined in the menu or command bar definition.
For menu items, this will return the menu checked state.
For other command objects, the value returned will be appropriate
as described in the \Sect{Dialog Commands} section.

%............................................................
\Meth{virtual void RaiseWindow(void)}
\Indextt{RaiseWindow}
\index{top window}\index{window focus}\index{focus}

This method will raise the window to top of all windows on the
display.  Raising a window is often a result of mouse actions of
the user, but this method allows a buried window to be moved to
the top under program control. You will need to track which
window instance you want raised, possibly through the \code{vAppWinInfo}
object.

%............................................................
\Meth{virtual void SetValue(ItemVal itemId, int Val,
ItemSetType what)}
\Indextt{SetValue}

This method is used to change the state of command window items.
The item with \code{itemId} is set to \code{Val} using the
\code{ItemSetType} parameter to control what is set. Not all
command items can use all types of settings. See \code{vWindow::GetValue}
and \code{vDialog::SetValue} for a more complete description.

If a menu item and a command item in the same window share the
same id, they will both be set to the same value (this usually
applies to sensitivity). Only the controls in the window that
sent this message are changed.

%............................................................
\Meth{virtual void SetValueAll(ItemVal itemId, int Val,
ItemSetType what)}
\Indextt{SetValueAll}

This method is similar to \code{SetValue}, except that
the control with the given \code{itemId} in \emph{ALL} currently
active windows is set. This is useful to keep control values
in different windows in sync.

%............................................................
\Meth{virtual void SetPosition(int left, int top)}
\Indextt{SetPosition}

Moves \code{this} window to the location \code{left} and
\code{top}. This function is of limited usefulness.
\code{SetDialogPosition} is more useful.

%............................................................
\Meth{virtual void SetString(ItemVal itemId, char* title)}
\Indextt{SetString}

This can be used to change the label on a command bar button,
status bar label, or menu item. The item identified by \code{itemId}
will have its label changed to \code{title}.

%............................................................
\Meth{virtual void SetStringAll(ItemVal itemId, char* title)}
\Indextt{SetStringAll}

This method is similar to \code{SetString}, except that
the string with the given \code{itemId} in \emph{ALL} currently
active windows is set. This is useful to keep control strings
in different windows in sync.

%............................................................
\Meth{virtual void SetTitle(char* title)}
\Indextt{SetTitle}

Set the name of the window shown on its title bar to \code{title}.

%............................................................
\Meth{virtual void ShowPane(vPane* wpane, int OnOrOff)}
\Indextt{ShowPane}

You can show or hide a command, status, or canvas pane with this
method. The pane must first be defined, created, and added
to the command window (which will show the pane). You can then
hide the pane later by calling this method with the pointer to
the pane and \code{OnOrOff} set to 0. A 1 will show the pane.
Note that in some environments (e.g., X), the window may show up
again in a different position in the window. For example, if you
had a command bar above a status bar, and then hide the command
bar, it will be placed under the status bar when you show it
again. This is a ``feature'' of X.

%............................................................
\Meth{virtual void ShowWindow(void)}
\Indextt{ShowWindow}

You \emph{must} call \code{ShowWindow()} after you have added all the
panes to the window. You usually call \code{ShowWindow()} in the
constructor to your \code{vCmdWindow} class after you have created
all the panes and have used \code{AddPane} to add them to the window.

\subsection* {Other Methods} %----------------------------------

%............................................................
\Meth{virtual void CloseWin()}
\Indextt{CloseWin}

This method is called by the \code{vApp::CloseAppWin} method
as part of closing down a window. The default \code{vWindow::CloseWin()}
method's behavior is to take care of some critical housekeeping
chores. You will normally never override this method. However, it
is remotely conceivable that there will be an occasion you need
to do something really low level after a window has been
destroyed by the host GUI environment. In that case, your method
\emph{must} call the immediate superclass \code{vWindow::CloseWin()}, and
then do whatever it has to do. Normally, you handle such details
in your class's \code{CloseAppWin} method.

\subsection* {See Also}

vCmdWindow