The vWindow class is an aggregate class that usually has
associated 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 vWindow also include
panes.
The vWindow class will probably never be used by your
application - it serves primarily as a superclass for the
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
vCmdWindow, and override several of the methods
defined by vWindow and vCmdWindow.
Menus and commands in the panes send messages to the WindowCommand
and MenuCommand 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.).
Constructor
vWindow()
vWindow(char* title)
vWindow(char* title, int h, int w)
vWindow(char* title, int h, int, WindowType wintype)
title Title to place in title bar.
h,w The height and width of the window.
wintype CMDWINDOW or WINDOW type for window.
The constructor for 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
canvas work area in pixels.
The type may be CMDWINDOW or WINDOW. The constructor
for vCmdWindow invokes the proper vWindow constructor.
Methods to Override
virtual void KeyIn(vKey key, unsigned int shift)
KeyIn is invoked when a key is pressed while a window has
focus. The key value is the vKey value of the key
pressed, and 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 (~ )
are passed to 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 <v/vkeys.h> has the
definitions for the key codes supported. See the key code
list.
Besides getting a keycode for the non-ASCII keys, KeyIn
also gives a shift code corresponding to the Control, Shift, and
Alt modifier keys. (These are defined as VKM_Ctrl,
VKM_Shift, and 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
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
not the VKM_Ctrl shift set.
In addition, you also need to check for the VKM_Alt
modifier applied to regular Ascii keys. The keystroke Alt-K will
be mapped to a
lower case Ascii 'k' with the VKM_Alt
bit set in shift. The top row keys (1,2, etc.) can also
be pressed with the VKM_Ctrl bit set in 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.
KeyIn will also return a value when only a modifier key is
pressed. For example, pressing the Alt key returns a key value of
vk_Alt. A macro defined in <v/vkeys.h>
called vk_IsModifer(x) can be used to determine if a key
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 KeyIn. Instead, they are intercepted by the system and
mapped to the appropriate command to pass to the 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 vWindow::KeyIn from your derived method
with any keystrokes you don't handle. The vWindow::KeyIn
method passes these unhandled keystrokes up to the vApp::KeyIn
method. Thus, you will have the choice of either handling
keystrokes in the window or in the app class.
virtual void MenuCommand(ItemVal itemId)
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 WindowCommand method, so you don't
need to override this method if you don't distinguish between
menu and command events.
virtual void UpdateView(vWindow* sender, int hint, void* pHint)
This is used to implement MVC. See the discussion of
MVC in the vApp class. UpdateView is called by
the derived vApp in response to the UpdateAllViews
message from some other view of the model.
The hints are passed to UpdateView to help define what action
the view needs to take. The originator window is
identified by sender. Generally, hint would have a value
set to an enum defined in your derived vApp class.
These values would hint about which kind of change is made so that only
appropriate actions is taken by the appropriate views. The pHint
is typically a pointer to the object representing the model.
This method is invoked when a user activates a command object in
a command pane. The Id of the command object is passed in
in the Id field, and the value and type (e.g., C_Button
or C_CheckBox) of the command are passed in in the Val
and 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 vCommandPane and
vDialog::DialogCommand for more details about the values
passed to WindowCommand.
WindowCommand is also called by the default MenuCommand
in response to menu picks. The Id is the id of the item
that generated the call.
The default behavior of WindowCommand is to call the
AppCommand method. However, you will almost always
override the default WindowCommand method.
virtual void WorkSlice()
See vApp::WorkSlice for a description of this method.
Utility Methods
virtual void AddPane(vPane* pane)
This method is used to add the pane 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., myPane = new
XPane(PaneDef)), and then add the pane to the window with
AddPane(myPane).
Returns the position and size of this window. These values
reflect the actual position and size on the screen of the window.
On X, this is the whole 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 SetDialogPosition.
virtual int GetValue(ItemVal itemId)
This method is used to retrieve the value of a menu or command
object in a menu or command pane. The 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
Dialog Commands section.
virtual void RaiseWindow(void)
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 vAppWinInfo
object.
virtual void SetValue(ItemVal itemId, int Val,
ItemSetType what)
This method is used to change the state of command window items.
The item with itemId is set to Val using the
ItemSetType parameter to control what is set. Not all
command items can use all types of settings. See vWindow::GetValue
and 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.
virtual void SetValueAll(ItemVal itemId, int Val,
ItemSetType what)
This method is similar to SetValue, except that
the control with the given itemId in
ALL currently
active windows is set. This is useful to keep control values
in different windows in sync.
virtual void SetPosition(int left, int top)
Moves this window to the location left and
top. This function is of limited usefulness.
SetDialogPosition is more useful.
This can be used to change the label on a command bar button,
status bar label, or menu item. The item identified by itemId
will have its label changed to title.
This method is similar to SetString, except that
the string with the given itemId in
ALL currently
active windows is set. This is useful to keep control strings
in different windows in sync.
virtual void SetTitle(char* title)
Set the name of the window shown on its title bar to title.
virtual void ShowPane(vPane* wpane, int OnOrOff)
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 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.
virtual void ShowWindow(void)
You
must call ShowWindow() after you have added all the
panes to the window. You usually call ShowWindow() in the
constructor to your vCmdWindow class after you have created
all the panes and have used AddPane to add them to the window.
Other Methods
virtual void CloseWin()
This method is called by the vApp::CloseAppWin method
as part of closing down a window. The default 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
must call the immediate superclass vWindow::CloseWin(), and
then do whatever it has to do. Normally, you handle such details
in your class's CloseAppWin method.