VIcon

Used to define V icons.

Synopsis

Header:

[vquickr.htm#vIcon <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 2²⁴ 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.

Constructor

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

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 fourth parameter specifies depth. The final parameter specifies the type of the icon, which by default is Normal. If you specify Transparent for 8 or 24 bit icons, then the lower left corner pixel will be used as a transparent color.

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 2⁸ or 256 colors) or 24 (for 2²⁴ 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 2²⁴ 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 one[#FootNote1 ¹] (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);
 
 

Transparent Icons

Beginning with V 1.21, V supports transparent 8 and 24 bit icons on MS-Windows. They should be added to OS/2 and X in the future. If you specify Transparent for the IconType in the vIcon constructor, then V will treat the icon as having a transparent background. The pixel in the lower left corner is used for the transparent color. Transparent icons make much nicer icon buttons.

See Also

C_Button, Dialog Commands, C_Icon and C_IconButton