# vWindow

A class to show a window on the display.

### Synopsis

Header:
  `<v/vwindow.h>`
Class name:
  vWindow
Hierarchy:
  vBaseWindow ->vWindow
Contains:
  vDialog, vPane

### Description

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.

#### virtual void WindowCommand(ItemVal Id, ItemVal Val, CmdType Type)

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)`.

#### void GetPosition(int& left, int& top, int& width, int& height)

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.

ItemSetType values include Checked, Sensitive, Value, Hidden, ChangeList, ChangeListPtr, Red, Green, Blue, ChangeColor.

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.

#### virtual void SetString(ItemVal itemId, char* title)

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`.

#### virtual void SetStringAll(ItemVal itemId, char* 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.

### See Also

vCmdWindow