# 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