CommandObject


Used to define commands to dialogs and command panes.

Synopsis

Header:
<v/v_defs.h>
Type name:
CommandObject
Part of:
vDialog, vCommandPane

Description

This structure is used to define command items in dialogs and command panes. You will define a static array of CommandObject items. This array is then passed to the AddDialogCmds method of a dialog class such as vDialog or vModalDialog, or the constructor of a vCommandPane object, or more typically, a class derived from one of those.

Definition

typedef struct CommandObject
  {
    CmdType cmdType;    // what kind of item is this
    ItemVal cmdId;      // unique id for the item
    ItemVal retVal;     // initial value of object
    char* title;        // string
    void* itemList;     // used when cmd needs a list
    CmdAttribute attrs; // list of attributes
    int Sensitive;      // if item is sensitive or not
    ItemVal cFrame;     // Frame used for an item
    ItemVal cRightOf;   // Item placed left of this id
    ItemVal cBelow;     // Item placed below this one
    int size;           // Used for size information
    char* tip;          // ToolTip string
  } CommandObject;

Structure Members

CmdType cmdType
This value determines what kind of command item this is. The types of commands are explained in the section Commands.

ItemVal cmdId
This unique id for the command defined by the programmer. Each command item belonging to a dialog should have a unique id, and it is advisable to use some scheme to be sure the ids are unique. The V system does not do anything to check for duplicate ids, and the behavior is undefined for duplicate ids. The id for a command is passed to the DialogCommand method of the dialog, as well as being used for calls to the various SetX and GetX methods. There are many predefined values that can be used for ids as described in the section Standard V Values.

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. There is no enforcement of this policy. It is up to you to pick reasonable values.

The type ItemVal exists for historical reasons, and is equivalent to an int, and will remain so. Thus, the easiest way to assign and maintain unique ids for your controls is to use a C++ enum. As many as possible examples in this manual will use enums, but examples using the old style const ItemVal declarations may continue to exist. There is more discussion of assigning ids in the following example.

int retVal
The use of this value depends on the type of command. For buttons, for example, this value will be passed (along with the cmdId) to the DialogCommand method. The retVal is also used for the initial on/off state of check boxes and radio buttons. For some commands, retVal is unused. Note that the static storage provided in the declaration is not used to hold the value internally. You should use GetValue to retrieve the current value of a command object.

char* title
This is used for the label or text string used for command items.

void* itemList
This is used to pass values to commands that need lists or strings. The ListCmd is an example. Note the void * to allow arbitrary lists.

CmdAttribute attrs
Some command items use attributes to describe their behavior. These attributes are summarized in the CmdAttribute section.

int Sensitive
This is used to determine if an item is sensitive or not. Note that the static storage provided in the declaration is used by the V system to track the value, and should be changed by the SetValue method rather than directly. Thus dialogs sharing the same static declaration will all have the same value. This is usually desired behavior.

ItemVal cFrame
Command items may be placed within a frame. If this value is 0 (or better, the symbol NoFrame), the command will be placed in the main dialog area. If a value is supplied, then the command will be placed within the frame with the id cFrame.

ItemVal cRightOf, ItemVal cBelow
These are used to describe the placement of a command within a dialog. Ids of other commands in the same dialog are used to determine placement. The current command will be placed to the right of the command cRightOf, and below the command cBelow. The commands left and above don't necessarily have to be adjacent. By careful use of these values, you can design very attractive dialogs. You can control the width of command objects by padding the label with blanks. Thus, for example, you can design a dialog with all buttons the same size.

You can also use the CA_Hidden attribute to selectively hide command objects that occupy the same location in the dialog. Thus, you might have a button labeled Hide right of and below the same command object as another button labeled UnHide. By giving one of the two buttons the CA_Hidden attribute, only one will be displayed. Then you can use SetValue at runtime to switch which button is displayed in the same location. The bigger of the two command objects will control the spacing.

int size
The size parameter can be used for some command objects to specify size. For example, for labeled Button commands, the size specifies the minimum width in pixels of the button. It is also used in various other command objects as needed. A value of zero for size always means use the default size. Thus, you can take advantage of how C++ handles declarations and write CommandObject declarations that leave off the size values, which default to zero. Many of the examples in this reference do not specify these values.

char* tip
The tip parameter is used to specify an optional ToolTip string for use with a command object. If you provide a string here, that string will be automatically displayed after the user holds the mouse over that control. The exact delay before the tip is shown, and the format of the tip box is somewhat platform dependent, and all platforms might not support tool tips. (Currently, only OS/2 does not support tips.) Note that if you use a tip, you must be sure to include a value (usually 0) for the size parameter!

Example

The following example defines a simple dialog with a message label on the top row, a check box on the second row, two buttons in a horizontally organized frame on the third row, and an OK button on the bottom row. The ids in this example are defined using an enum. Remember that your ids must be less than 30,000, and using 0 is not a good idea. Thus, the enum in this example gives the ids values from 101 to 106. An alternative used in V code prior to release 1.13 was to provide const declarations to define meaningful symbolic values for the ids. Many examples of this type of id declaration will likely persist.

It also helps to use a consistent naming convention for ids. The quick reference appendix lists suggested prefixes for each control type under the CmdType section. For example, use an id of the form btnXXX for buttons. Predefined ids follow the form M_XXX.


enum {lbl1 = 101, frm1, btn1, btn2}
static CommandObject Sample[] =
  {
    {C_Label, lbl1, 0,"Sample",NoList,CA_MainMsg,isSens,NoFrame,0,0},
    {C_Frame, frm1, 0, "", NoList,CA_None,isSens,NoFrame,0,lbl1},
    {C_Button, btn1, 0, "Button 1", NoList, CA_None, isSens,frm1,0,0,0,
         "Tip for Button 1"},
    {C_Button, btn2, 0, "Button 2", NoList, CA_None, isSens,frm1,btn1,0,0,
         "Tip for Button 2"},
    {C_Button, M_OK, M_OK, " OK ", NoList, CA_DefaultButton, 
        isSens, NoFrame,0,frm1},
    {C_EndOfList,0,0,0,0,CA_None,0,0,0}
  };

See Also

vCmdWindow, Standard Values, CmdAttribute, Commands