next up previous contents
Next: 7 Drawing Up: V Reference Manual Previous: 5 Command Windows

6 Dialogs

This chapter covers the classes used to build dialogs, and the various kinds of command objects that can be included in a dialog.

The classes and command objects covered in this chapter include:

CmdAttribute
A type describing attributes of various command objects.
CommandObject
Main type used to define commands to dialogs and command panes.
Commands
Command items used in building dialogs.
vIcon
Used to define V icons.
vDialog
Class to build a modeless dialog.
vModalDialog
Used to show modal dialogs.

6.1 CmdAttribute

   

A type describing attributes of various command objects.

Synopsis

Header:
<v/v_defs.h>
Type name:
CmdAttribute

Description

These attributes are used when defining command items. They are used to modify default behavior. These attributes are bit values, and some can be combined with an OR operation. Note that not all attributes can be used with all commands.

Attributes

CA_DefaultButton
Used with a C_Button to   indicate that this button will be the default button. The user can activate the default button by pressing the Enter key as well as using the mouse. It will most often be associated with the OK button.

CA_Hidden
Sometimes you may find it useful to have a       command object that is not displayed at first. By using the CA_Hidden attribute, the command object will not be displayed. The space it will require in the dialog or dialog pane will still be allocated, but the command will not be displayed. You can then unhide (or hide) the command using the SetValue method: SetValue(CmdID, TrueOrFalse, Hidden).

CA_Horizontal
Command will have horizontal orientation.   This attribute is used with Sliders and Progress Bars.

CA_Large
The object should be larger than usual. It can   be used with Lists, Progress Bars, Sliders, Text Ins, and Value Boxes.

CA_MainMsg
Used with a C_Label to indicate that   its string will be replaced with the message supplied to the ShowDialog method.

CA_NoBorder
Used for frames and status bar labels,   CA_NoBorder specifies that the object is to be displayed with no border.

CA_NoLabel
Used for progress bars to suppress display of   the value label.

CA_NoNotify
Used for combo boxes and lists. When   specified, the program will not be notified for each selection of a combo box item or a list item. When specified, the program is notified only when the combo box button is pressed, and must then use GetValue to retrieve the item selected in the combo box list. For lists, you will need another command button in the dialog to indicate list selection is done.

CA_NoSpace
Used for frames, this attribute causes the   command objects within the frame to be spaced together as tightly as possible. Normally, command objects have a space of several pixels between them when laid out in a dialog. The CA_NoSpace attribute is especially useful for producing a tightly spaced set of command buttons.

CA_None
No special attributes. Used as a symbolic filler when defining items, and is really zero.

CA_Percent
Used with progress bars to add a % to the   value label.

CA_Small
The object should be smaller than usual. It can   be used with Progress Bars and Text Ins. On Progress Bars, CA_Small means that the text value box will not be shown.

CA_Text
Used for Spinners to specify that a text list   of possible values has been supplied.

CA_Vertical
Command will have vertical orientation.   This attribute is used with Sliders and Progress Bars.

C.1 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
  } 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 chapter 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 codeItemVal 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 Section 6.1, CmdAttribute.

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.

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.

See Also

vWindow, Predefined ItemVals, CmdAttribute, Commands

6.3 Commands

 

This section describes how each of the command objects available in V is used to build dialogs.

Synopsis

Header:
<v/v_defs.h>
Type name:
CmdType

Description

V provides several different kinds of command items that are used in dialogs. The kind of command is specified in the cmdType field of the CommandObject structure when defining a dialog. This section describes current dialog commands available with V. They will be constructed by V to conform to the conventions of the host windowing system. Each command is named by the value used to define it in the CommandObject structure.

Commands

C_Blank

   

A Blank can help you control the layout of your dialogs. The Blank object will occupy the space it would take if it were a C_Label, but nothing will be displayed. This is especially useful for leaving space between other command objects, and getting nice layouts with RightOfs and Belows. You control the size of the Blank by providing a string with an appropriate number of blanks for the title field.

C_BoxedLabel

   

C_Button

   

C_CheckBox

   

C_ColorButton

   

C_ComboBox

   

Example

The following is a simple example of using a combo box in a modal dialog. This example does not process items as they are clicked, and does not show code that would likely be in an overridden DialogCommand method. The code interface to a list and a combo box is very similar - the interaction with the user is different. This example will initially fill the combo box label with the text of comboList[2].

enum { cbxId = 300 };
char* comboList[] =
  {
    "First 0",   // The first item in the list
     ...
    "Item N",    // The last item in the list
    0            // 0 terminates the list
  };
  ...
CommandObject ComboList[] =
  {
    {C_ComboBox, cbxId, 2, "A Combo Box", (void*)comboList,
       CA_NoNotify,isSens,NoFrame,0,0},
    {C_Button, M_OK, M_OK, " OK ", NoList,
       CA_DefaultButton, isSens, NoFrame, 0, ListId},
    {C_EndOfList,0,0,0,0,CA_None,0,0,0}
  };
    ...
    vModalDialog cd(this);    // create list dialog
    int cid, cval;
    ...
    cd.AddDialogCmds(comboList);   // Add commands to dialog
    cid = ld.ShowModalDialog("",cval);  // Wait for OK
    cval = ld.GetValue(cbxId);  // Retrieve the item selected


C_EndOfList

   

This is not really a command, but is used to denote end of the command list when defining a CommandObject structure.

C_Frame

   

C_Icon

   

C_IconButton

   

C_Label

C_ColorLabel

     

Select Options This places a label in a dialog. A label is defined in a CommandObject array. This is a typical definition:

 {C_Label, lblId,0,"Select Options",NoList,CA_None,isSens,NoFrame,0,0, 0,0}


While the value of a label can be changed with SetString(lblId, "New Label"), they are usually static items. If the label is defined with the CA_MainMsg attribute, then that label position will be used to fill the the message provided to the ShowDialog method.

A C_ColorLabel is a label that uses the List parameter of the CommandObject array to specify a vColor. You can specify the color and change the color in the same fashion as described in the C_ColorButton command.

C_List

   

Example

The following is a simple example of using a list box in a modal dialog. This example does not process items as they are clicked.

enum {lstId = 200 };
char* testList[] =
  {
    "First 0",   // The first item in the list
     ...
    "Item N",    // The last item in the list
    0            // 0 terminates the list
  };
  ...
CommandObject ListList[] =
  {
    {C_List, lstId, 0, "A List", (void*)testList,
       CA_NoNotify,isSens,NoFrame,0,0},
    {C_Button, M_OK, M_OK, " OK ", NoList,
       CA_DefaultButton, isSens, NoFrame, 0, lstId},
    {C_EndOfList,0,0,0,0,CA_None,0,0,0}
  };
    ...
    vModalDialog ld(this);    // create list dialog
    int lid, lval;
    ...
    ld.AddDialogCmds(ListList);   // Add commands to dialog
    ld.SetValue(lstId,8,Value);  // pre-select 8th item
    lid = ld.ShowModalDialog("",lval);  // Wait for OK
    lval = ld.GetValue(lstId);  // Retrieve the item selected


C_ProgressBar

   

Example

The following shows how to define a progress bar, and how to set its value.

enum{frm1 = 200, lbl1, pbrH, pbrV, ... };
  static CommandObject Cmds[] =
  {
    ...
    // Progress Bar in a frame
    {C_Frame, frm1, 0, "",NoList,CA_None,isSens,NoFrame, 0,0},
    {C_Label, lbl1, 0, "Progress",NoList,CA_None,isSens,frm1,0,0},
    {C_ProgressBar, pbrH, 50, "", NoList,
        CA_Horizontal,isSens,frm1, 0, lbl1},  // Horiz, with label

    {C_ProgressBar, pbrV, 50, "", NoList,  // Vertical, no value
      CA_Vertical | CA_Small, isSens,NoFrame, 0, frm1},
    ...
  };
  ...
  // Set the values of both bars to same
  SetValue(pbrH,retval,Value);    // The horizontal bar
  SetValue(pbrV,retval,Value);    // The vertical bar


C_RadioButton

   

Example

The following example of defining and using radio buttons was extracted from the sample file v/examp/mydialog.cpp. It starts with the button RB1 pushed.

enum {
    frmV1 = 200, rdb1, rdb2, rdb3, ...
...
  };
...
static CommandObject DefaultCmds[] =
  {
    {C_Frame, frmV1, 0,"Radios",NoList,CA_Vertical,isSens,NoFrame,0,0},
    {C_RadioButton, rdb1, 1, "KOB",  NoList,CA_None,isSens, fmV1,0,0},
    {C_RadioButton, rdb2, 0, "KOAT", NoList,CA_None, isSens,frmV1,0,0},
    {C_RadioButton, rdb3, 0, "KRQE", NoList,CA_None, isSens,frmV1,0,0},
    {C_Button, M_Cancel,M_Cancel,"Cancel",NoList,CA_None,
        isSens, NoFrame, 0, frmV1},
    {C_Button, M_OK, M_OK, " OK ", NoList, CA_DefaultButton, 
        isSens, NoFrame, M_Cancel, frmV1},
    {C_EndOfList,0,0,0,0,CA_None,0,0,0}
  };
...
void myDialog::DialogCommand(ItemVal Id, ItemVal Val, CmdType Ctype)
  {
    switch (Id)              // switch on command id
      {
        case rdb1:            // Radio Button KOB
            // do something useful - current state is in retval
            break;
        ...
        // cases for other radio buttons

      }
    // let the super class handle M_Cancel and M_OK
    vDialog::DialogCommand(id,retval,ctype);
  }


C_Slider

   

Example

The following example shows the definition line of a slider, and a code fragment from an overridden DialogCommand method to get the value of the dialog and update a C_Text item with the current value of the slider. The slider starts with a value of 50.

enum { frm1 = 80, sld1, txt1 };
CommandObject Commands[] =
  {
    ...
    {C_Frame, frm1, 0, "",NoList,CA_None,isSens,NoFrame,0,0},
    {C_Slider, sld1, 50, "",NoList,CA_Horizontal,isSens,frm1,0,0},
    {C_Text, txt1, 0, "", "50",CA_None,isSens, frm1, sld1, 0},
    ...
  };
  ...
void testDialog::DialogCommand(ItemVal id,
  ItemVal retval, CmdType ctype)
  { 
    ...
    switch (id)     // Which dialog command item?
      {
        ...
        case sld1:    // The slider
          {
            char buff[20];
            sprintf(buff,"%d",retval);  // To string
            SetString(txt1,buff);      // Show value
          }
        ...
      }
    ...
  }


C_Spinner

   

Example

This example shows how to setup the C_Spinner to select a value from a text list (when supplied with a list and the CA_Text attribute), from a range of integers (when supplied a range list), or from a starting value (when no list is provided). The definitions of the rest of the dialog are not included.

  static char* spinList[] =    // a list of colors
    {
      "Red","Green","Blue", 0
    };
  static int minMaxStep[3] =  // specify range of
    {                         // -10 to 10
      -10, 10, 2              // in steps of 2
    };
  enum { spnColor = 300, spnMinMax, spnInt, ... };
  CommandObject SpinDialog[] =
    {
      ...
      {C_Spinner,spnColor,0,"Vbox", // A text list.
        (void*)spinList,CA_Text,     // the list is CA_Text
        isSens,NoFrame, 0,0},
      {C_Spinner,spnMinMax,0,"Vbox", // a range -10 to 10
        (void*)minMaxStep,CA_None,  // by 2's starting at 0
        isSens,NoFrame, 0,0},
      {C_Spinner,spnInt,32,"Vbox",  // int values step by 1
        NoList,CA_None,             // starting at 32
        isSens,NoFrame, 0,0},
      ...
    };


C_Text

   

C_TextIn

   

Example

The following example demonstrates how to use a TextIn.

CommandObject textInList[] =
  {
    ...
    {C_TextIn, txiId,0,"",NoList,CA_None,isSens,NoFrame,0,0},
    ...
    {C_EndOfList,0,0,0,0,CA_None,0,0,0}
  };
 ...
    vModalDialog md(this);      /// make a dialog
    int ans, val;
    char text_buff[255];        // get text back to this buffer
 ...
    md.AddDialogCmds(textInList);  // add commands
    ans = md.ShowModalDialog("Enter text.", val);  // Show it
    text_buff[0] = 0;          // make an empty string
    (void) md.GetTextIn(txiId, text_buff, 254); // get the string
 ...


C_ToggleButton

   

C_ToggleFrame

     

C_ToggleIconButton

   

C.12 vIcon

    

Used to define V icons.

Synopsis

Header:
<v/v_icon.h>
Class name:
vIcon

Description

Icons may be used for simple graphical labels in dialogs, as well as for graphical command buttons in dialogs and command bars. See the sections vButton and Dialog Commands for descriptions of using icons.

Presently, V supports monochrome icons which allow an on or off state for each pixel, and color icons of either 256 or tex2html_wrap_inline10337 colors. The format of V monochrome icons is identical to the X bitmap format. This is a packed array of unsigned characters (or bytes), with each bit representing one pixel. The size of the icon is specified separately from the icon array. The V color icon format is internally defined, and allows easy conversion to various color file formats used by X and Windows.

Definition

    class vIcon     // an icon
      {
      public:             //---------------------------------------- public
        vIcon(unsigned char* ic, int h, int w, int d = 1);
        ~vIcon();
        int height;             // height in pixels
        int width;              // width in pixels
        int depth;              // bits per pixel (1,8, or 24)
        unsigned char* icon;    // ptr to icon array

      protected:        //--------------------------------------- protected
      private:          //--------------------------------------- private
      };


Constructor

vIcon(unsigned char* icon, int height, int width, int depth = 1)

 

The constructor for a vIcon has been designed to allow you to easily define an icon. The first parameter is a pointer to the static icon array. (Note: vIcon does not make a copy of the icon - it needs to be a static or persistent definition in your code.) The second and third parameters specify the height and width of the icon. The last parameter specifies depth.

Class Members

int height
This is the height in pixels of the icon.

int width
This is the width in pixels of the icon. A icon will thus require (height * width) pixels. These bits are packed into bytes, with 0's padding the final byte if needed.

int depth
For monochrome icons, this will be one. For color icons, the value is either 8 (for tex2html_wrap_inline10342 or 256 colors) or 24 (for tex2html_wrap_inline10344 colors).

unsigned char* icon
This is a pointer to the array of bytes that contain the icon. V basically uses the format defined by X (.XBM) bitmaps for monochrome bitmaps. It uses an internal format consisting of a color map followed by a one byte per pixel color icon description, or a three bytes per pixel color icon description.

Defining Icons

The easiest way to define an icon is to include the definition of it in your code (either directly or by an #include). You then provide the address of the icon data plus its height and width to the initializer of the vIcon object.

The V distribution includes a simple icon editor that can be used to create and edit icons in standard .vbm format, as well as several other formats. You can also generate monochrome icons is with the X bitmap utility. That program allows you to draw a bitmap, and then save the definition as C code. This code can be included directly in your code and used in the initialization of the vIcon object. If you follow the example, you should be able to modify and play with your icons very easily.

A simple converter that converts a Windows .bmp format file to a V .vbm V bitmap format is also included in the standard V distribution. There are many utilities that let you generate .bmp files on both Windows and X, so this tool easily lets you add color icons of arbitrary size. Chapter 9 has more details on bmp2vbm.

The standard V distribution also contains a directory (v/icons) with quite a few sample icons suitable for using in a command bar.

Once you have a .vbm file, the easiest way to add an icon to your program is to include code similar to this in your source:

#include "bruce.vbm"    // Picture of Bruce
  static vIcon bruceIcon(&bruce_bits[0], bruce_height,
                          bruce_width,8);


The following sections describe the format of the unsigned char* icon data for 1, 8, and 24 bit V icons.

1 Bit Icons

Icon definitions are packed into bytes. A bit value of 1 represents Black, a 0 is White. The bytes are arranged by rows, starting with the top row, with the bytes padded with leading zeros to come out to whole bytes. The bytes are scanned in ascending order (icon[0], icon[1], etc.). Within bytes, the bits are scanned from LSB to MSB. A 12 bit row with the pattern BBBWWBBWBWBW would be represented as unsigned char row[] = { 0x67, 0x05 };. This is the format produced by the X bitmap program.

8 Bit Icons

Eight bit icons support 256 colors. Each pixel of the icon is represented by one byte. Bytes are arranged in row order, starting with the top row. Each byte represents an index into a color map. The color map consists of RGB byte entries. While an 8 bit icon can only have 256 colors, it can map into tex2html_wrap_inline10348 possible colors. Thus, each 8 bit icon must also include the color map as part of its data. The very first byte of the icon data is the number of entries in the color map minus onegif (you don't have to define all 256 colors), followed by the color map RGB bytes, followed by the icon pixels. The following is a very simple example of an icon:

//vbm8
#define color_width 16
#define color_height 12
#define color_depth 8
static unsigned char color_bits[] = {
       2,       // 3 colors in color map (2 == 3-1)
       255,0,0, // byte value 0 maps to red
       0,255,0, // 1 -> green
       0,0,255, // 2 -> blue
       // Now, the pixels: an rgb "flag", 3 16x4 rows
       0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, // RRRRRRRRRRRRRRRR
       0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0, // RRRRRRRRRRBBBBBR
       0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0, // RRRRRRRRRRBBBBBR
       0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, // RRRRRRRRRRRRRRRR
       1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, // GGGGGGGGGGGGGGGG
       1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, // GGGGGGGGGGGGGGGG
       1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, // GGGGGGGGGGGGGGGG
       1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, // GGGGGGGGGGGGGGGG
       2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2, // BBBBBBBBBBBBBBBB
       2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2, // BBBBBBBBBBBBBBBB
       2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2, // BBBBBBBBBBBBBBBB
       2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2  // BBBBBBBBBBBBBBBB
     };

static vIcon colorIcon(&color_bits[0], color_height, color_width,
     color_depth);


24 Bit Icons

Twenty-four bit icons are arranged in rows, staring with the top row, of three bytes per pixel. Each 3 byte pixel value represents an RGB value. There is no color map, and the RGB pixel values start immediately in the unsigned char* icon data array. This is a simple example of a 24 bit icon.

//vbm24
#define c24_height 9
#define c24_width 6
#define c24_depth 24
    static unsigned char c24_bits[] = {
     255,0,0,255,0,0,255,0,0,255,0,0,0,255,0,0,255,0, //RRRRGG
     255,0,0,255,0,0,255,0,0,255,0,0,0,255,0,0,255,0, //RRRRGG
     255,0,0,255,0,0,255,0,0,255,0,0,255,0,0,255,0,0, //RRRRRR
     0,255,0,0,255,0,0,255,0,0,255,0,0,255,0,0,255,0, //GGGGGG
     0,255,0,0,255,0,0,255,0,0,255,0,0,255,0,0,255,0, //GGGGGG
     0,255,0,0,255,0,0,255,0,0,255,0,0,255,0,0,255,0, //GGGGGG
     0,0,255,0,0,255,0,0,255,0,0,255,0,0,255,0,0,255, //BBBBBB
     0,0,255,0,0,255,0,0,255,0,0,255,0,0,255,0,0,255, //BBBBBB
     0,0,255,0,0,255,0,0,255,0,0,255,0,0,255,0,0,255  //BBBBBB
    };
    static vIcon c24Icon(&c24_bits[0], c24_height, c24_width,
        c24_depth);


Example

This example uses the definition of the checked box used by the Athena checkbox dialog command.

// This code is generated by the V Icon Editor:
//vbm1
#define checkbox_width 12
#define checkbox_height 12
#define checkbox_depth 1
static unsigned char checkbox_bits[] = {
   0xff, 0x0f, 0x03, 0x0c, 0x05, 0x0a, 0x09, 0x09, 
   0x91, 0x08, 0x61,  0x08, 0x61, 0x08, 0x91, 0x08,
   0x09, 0x09, 0x05, 0x0a, 0x03, 0x0c, 0xff, 0x0f};

// This code uses the above definitions to define an icon
// in the initializer of checkIcon to vIcon.

static vIcon checkIcon(&checkbox_bits[0],
    checkbox_height, checkbox_width, checkbox_depth);


See Also

vButton, Dialog Commands C_Icon and C_IconButton

C.8 vDialog

 

Class to build a modeless dialog.

Synopsis

Header:
<v/vdialog.h>
Class name:
vDialog
Hierarchy:
(vBaseWindow,vCmdParent) -> vDialog
Contains:
CommandObject

Description

The vDialog class is used to build modeless dialogs. Since most dialogs will require a response to the commands they define, you will almost always derive your own subclass based on vDialog, and override the DialogCommand method to handle those commands. Note that vDialog is multiply derived from the vBaseWindow and the vCmdParent classes.

Constructor

vDialog(vBaseWindow* parent)

 

vDialog(vApp* parent)

vDialog(vBaseWindow* parent, int isModal = 0, char* title = "")

vDialog(vApp* parent, int isModal = 0, char* title = "")

A dialog is constructed by calling it with a pointer to a vBaseWindow or vApp, which is usually the 'this' of the object that creates the vDialog. The isModal parameter indicates if the dialog should be modal or modeless. You would usually use the default of 0. The modal flag is used by the derived vModalDialog class. The title parameter can be used to set a title for your dialog (see SetDialogTitle for information on titles). If you create a derived dialog class, you might provide a parent and a title in your constructor, and provide the 0 for the isModal flag in the call to the vDialog constructor.

The constructor builds an empty dialog. The AddDialogCmds method must be called in order to build a useful dialog, which you would usually do from within the constructor of your derived dialog class.

IMPORTANT! When you derive your own vDialog objects, you should write constructors for both the vBaseWindow* and vApp* versions. These two different constructors allow dialogs to be used both from windows directly, and from the vApp code as well. Normally, you would construct a dialog from a window. Occasionally, it will be useful to build a dialog from the vApp that applies to all windows, and not just the window that constructed it.

void vDialog::AddDialogCmds(CommandObject* cList)

 

This method is used to add a list of commands to a dialog. It is called after the dialog object has been created. You can usually do this in the constructor for your derived Dialog class. This method is passed an array of CommandObject structures.

void vDialog::SetDialogTitle(char* title)

 

This can be used to dynamically change the title of any object derived from a vDialog object. Note that the title will not always be displayed. This depends on the host system. For example, the user can set up their X window manager to not show decorations on transient windows, which is how dialogs are implemented on X. You should write your applications to provide a meaningful title as they are often helpful when displayed.

Example

This example shows the steps required to use a dialog object. Note that the example uses the vDialog class directly, and thus only uses the default behavior of responding to the OK button.

virtual void CancelDialog()

 

This method is used to cancel any action that took place in the dialog. The values of any items in the dialog are reset to their original values, and the This method is automatically invoked when the user selects a button with the value M_Cancel and the DialogCommand method invoked as appropriate to reset values of check boxes and so on. CancelDialog can also be invoked by the application code.

virtual void CloseDialog()

 

The CloseDialog is used to close the dialog. It can be called by user code, and is automatically invoked if the user selects the M_Done or M_OK buttons and the the user either doesn't override the DialogCommand or calls the default DialogCommand from any derived DialogCommand methods.

virtual void DialogCommand(ItemVal Id, ItemVal Val, CmdType Type)

 

This method is invoked when a user selects some command item of the dialog. The default DialogCommand method will normally be overridden by a user derived class. It is useful to call the default DialogCommand from the derived method for default handling of the M_Cancel and M_OK buttons.

The Id parameter is the value of the cmdId field of the CommandObject structure. The Val parameter is the retVal value, and the Type is the cmdType.

The user defined DialogCommand is where most of the work defined by the dialog is done. Typically the derived DialogCommand will have a switch statement with a case for each of the command cmdId values defined for items in the dialog.

void DialogDisplayed()

 

This method is called by the V runtime system after a dialog has actually been displayed on the screen. This method is especially useful to override to set values of dialog controls with SetValue and SetString.

It is important to understand that the dialog does not get displayed until ShowDialog or ShowModalDialog has been called. There is a very important practical limitation implied by this, especially for modal dialogs. The values of controls cannot be changed until the dialog has been displayed, even though the vDialog object may exist. Thus, you can't call SetValue or SetString until after you call ShowDialog for modeless dialogs, or ShowModalDialog for modal dialogs. Since ShowModalDialog does not return until the user has closed the dialog, you must override DialogDisplayed if you want to change the values of controls in a modal dialog dynamically.

For most applications, this is not a problem because the static definitions of controls in the CommandObject definition will be usually be what is needed. However, if you need to create a dialog that has those values changed at runtime, then the easiest way is to include the required SetValue and SetString calls inside the overridden DialogDisplayed.

void GetDialogPosition(int& left, int& top, int& width, int& height)

 

Returns the position and size of this dialog. These values reflect the actual position and size on the screen of the dialog. The intent of this method is to allow you to find out where a dialog is so position it so that it doesn't cover a window.

virtual int GetTextIn(ItemVal Id, char* str, int maxlen)

 

This method is called by the application to retrieve any text entered into any C_TextIn items included in the dialog box. It will usually be called after the dialog is closed. You call GetTextIn with the Id of the TextIn command, the address of a buffer (str), and the size of str in maxlen.

virtual int GetValue(ItemVal Id)

 

This method is called by the user code to retrieve values of command items, usually after the dialog is closed. The most typical use is to get the index of any item selected by the user in a C_List or C_ComboBox.

int IsDisplayed()

 

This returns true if the dialog object is currently displayed, and false if it isn't. Typically, it will make sense only to have a single displayed instance of any dialog, and your code will want to create only one instance of any dialog. Since modal dialogs allow the user to continue to interact with the parent window, you must prevent multiple calls to ShowDialog. One way would be to make the command that displays the dialog to be insensitive. IsDisplayed() is provided as an alternative method. You can check the IsDisplayed() status before calling ShowDialog.

virtual void SetDialogPosition(int left, int top)

 

Moves this dialog to the location left and top. This function can be used to move dialogs so they don't cover other windows.

virtual void SetValue(ItemVal Id, ItemVal val, ItemSetType type)

 

This method is used to change the state of dialog command items. The ItemSetType parameter is used to control what is set. Not all dialog command items can use all types of settings. The possibilities include:

Checked

 

The Checked type is used to change the checked status of check boxes. V will normally handle checkboxes, but if you implement a command such as Check All, you can use SetValue to change the check state according to ItemVal val.

Sensitive

 

The Sensitive type is used to change the sensitivity of a dialog command.

Value

 

The Value type is used primarily to preselect the item specified by ItemVal val in a list or combo box list.

ChangeList, ChangeListPtr

       

Lists, Combo Boxes, and Spinners use the itemList field of the defining CommandObject to specify an appropriate list. SetValue provides two ways to change the list values associated with these controls.

The key to using ChangeListPtr and ChangeList is an understanding of just how the controls use the list. When a list type control is instantiated, it keeps a private copy of the pointer to the original list as specified in the itemList field of the defining CommandObject.

So if you want to change the original list, then ChangeList is used. The original list may be longer or shorter, but it must be in the same place. Remember that a NULL entry marks the end of the list. So you could allocate a 100 item array, for example, and then reuse it to hold 0 to 100 items.

Call SetValue with type set to ChangeList. This will cause the list to be updated. Note that you must not change the itemList pointer used when you defined the list or combo box. The contents of the list can change, but the pointer must be the same. The val parameter is not used for ChangeList.

Sometimes, especially for regular list controls, a statically sized list just won't work. Using ChangeListPtr allows you to use dynamically created list, but with a small coding penalty. To use ChangeListPtr, you must first modify the contents of the itemList field of the original CommandObject definition to point the the new list. Then call SetValue with ChangeListPtr. Note that this will both update the pointer, and update the contents of the list. You don't need to call again with ChangeList.

The following illustrates using both types of list change:

  char* comboList[] = {
    "Bruce", "Katrina", "Risa", "Van", 0 };
  char* list1[] = {"1", "2", "3", 0};
  char* list2[] = {"A", "B", "C", "D", 0};

  // The definition of the dialog
  CommandObject ListExample[] = {
    {C_ComboBox,100,0,"",(void*)comboList,CA_None,isSens,0,0,0},
    {C_List,200,0,"",(void*)list1,CA_None,isSens,0,0,0},
    ...
    };
   ...

    // Change the contents of the combo list
    comboList[0] = "Wampler";  // Change Bruce to Wampler
    SetValue(200,0,ChangeList);
   ...
    // Change to a new list entirely for list
    // Note that we have to change ListExample[1], the
    // original definition of the list control.
    ListExample[1].itemList = (void*)list2;  // change to list2
    SetValue(100,0,ChangeListPtr);
   ...


Note that this example uses static definitions of lists. It is perfectly fine to use completely dynamic lists: you just have to dynamically fill in the appropriate itemList field of the defining CommandObject.

Please see the description of DialogDisplayed for an important discussion of setting dialog control values.

virtual void SetString(ItemVal Id, char* str)

 

This method is called to set the string values of dialog items. This can include the labels on check boxes and radio buttons and labels, as well as the text value of a Text item.

Please see the description of DialogDisplayed for an important discussion of setting dialog control values.

virtual void ShowDialog(char* message)

 

After the dialog has been defined, it must then be displayed by calling the ShowDialog method. If a C_Label was defined with a CA_MainMsg attribute, then the message provided to ShowDialog will be used for that label.

ShowDialog returns to the calling code as soon as the dialog is displayed. It is up to the DialogCommand method to then handle command input to the dialog, and to close the dialog when done.

Please see the description of DialogDisplayed for an important discussion of setting dialog control values.

Derived Methods

None.

Inherited Methods

None.

See Also

vModalDialog

C.14 vModalDialog

 

Used to show modal dialogs.

Synopsis

Header:
<v/vmodald.h>
Class name:
vModalDialog
Hierarchy:
(vBaseWindow,vCmdParent) -> vDialog -> vModalDialog
Contains:
CommandObject

Description

This class is an implementation of a modal dialog. This means that the dialog grabs control, and waits for the user to select an appropriate command from the dialog. You can use any of the methods defined by the vDialog class, as well as the new ShowModalDialog method.

Constructor

vModalDialog(vBaseWindow* parent, char* title)

 

vModalDialog(vApp* parent, char* title)

There are two versions of the constructor, one for constructing dialogs from windows, the other from the vApp object. See the description of the vDialog constructor for more details.

The default value for the title is an empty string, so you can declare instances of modal dialogs without the title string if you wish. The dialog title will always show in Windows, but in X is dependent on how the window manager treats decorations on transient windows.

New Methods

virtual ItemVal ShowModalDialog(char* message, ItemVal& retval)

 

This method displays the dialog, and does not return until the modal dialog is closed. It returns the id of the button that caused the return, and in retval, the value of the button causing the return as defined in the dialog declaration.

Please see the description of DialogDisplayed for an important discussion of setting dialog control values.

There are a couple of ways to close a modal dialog and make ShowModalDialog return, all controlled by the DialogCommand method. The default DialogCommand will close the modal dialog automatically when the user clicks the M_Cancel, M_Done, or M_OK buttons.

All command actions are still passed to the virtual DialogCommand method, which is usually overridden in the derived class. By first calling vModalDialog::DialogCommand to handle the default operation, and then checking for the other buttons that should close the dialog, you can also close the dialog by calling the CloseDialog method, which will cause the return.

The following code demonstrates this.

    void myModal::DialogCommand(ItemVal id, ItemVal val,
        CmdType ctype)
      {
        // Call the parent for default processing
        vModalDialog::DialogCommand(id,val,ctype);
        if (id == M_Yes || id == M_No) // These close, too.
            CloseDialog();
      }


Derived Methods

virtual void DialogCommand(ItemVal Id, ItemVal val, CmdType type)

 

Adds a little functionality for handling this modally.

Inherited Methods

vDialog(vBaseWindow* parent)

 

vDialog(vBaseWindow* parent, int modalflag)

vDialog(vApp* parent)

vDialog(vApp* parent, int modalflag)

void vDialog::AddDialogCmds(CommandObject* cList)

 

virtual void CancelDialog()

 

virtual void CloseDialog()

 

virtual int GetTextIn(ItemVal Id, char* str, int maxlen)

 

virtual int GetValue(ItemVal Id)

 

virtual void SetValue(ItemVal Id, ItemVal val, ItemSetType type)

 

virtual void SetString(ItemVal Id, char* str)

 

virtual void ShowDialog(char* message)

 

See Also

vDialog


next up previous contents
Next: 7 Drawing Up: V Reference Manual Previous: 5 Command Windows

root
Sun Mar 9 12:27:13 EST 1997