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.
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;
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!
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