BITMAPS_BEGIN – BITMAPS_END
[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]
The BITMAPS_BEGIN – BITMAPS_END section is used to make custom icons available to the commands that are defined in the BUTTONS_BEGIN – BUTTONS_END section.
Note
The Visual Studio SDK also provides a set of standard icons. These icons are always available to commands and do not have to be defined in the BITMAPS_BEGIN – BITMAPS_END section.
For more information about how to use icons with commands, see BUTTONS_BEGIN – BUTTONS_END.
The Bitmap Entry
An entry in the BITMAPS_BEGIN – BITMAPS_END section specifies a bitmap resource followed by one or more indexes to that bitmap for each icon. Index references are separated by commas and the whole entry ends with a semicolon. The following shows this syntax: Bitmap ID, Icon Index, Icon Index, Icon Index;
These fields are defined in the following table. They must appear in the entry in the order shown. The last Icon Index field must be followed by a semicolon. For more information, see "The Bitmap Entry Fields" in this topic.
Field |
Description |
|---|---|
Bitmap ID |
A GUID:ID pair that identifies the bitmap. The ID is a resource ID for the bitmap. |
Icon Index |
An index that starts at 1 and specifies an icon in the bitmap. All icons are the same 16-pixel width. One or more index values can be specified for a single bitmap. Only when an icon is explicitly given in the bitmap entry can it be used in a command entry. |
Bitmaps Example
The following code example shows the BITMAPS_BEGIN – BITMAPS_END section from the File Explorer sample. Entries in this example are indented for readability. In an actual entry, all fields should be on a single line. For more information, see CMDS_SECTION – CMDS_END.
BITMAPS_BEGIN
guidEUGrp:IDB_CMDBAR,
bmpidFileSysTool, bmpidFolderView, bmpidShortcutView,
bmpidRefresh, bmpidOpenFile, bmpidPreviewFile, bmpidAddShortcut,
bmpidDeleteShortcut, bmpidExplorer, bmpidMSDOS, bmpidCommand;
BITMAPS_END
The Bitmap Entry Fields
Every entry in the BITMAPS_BEGIN – BITMAPS_END section must contain at least two fields, but multiple Icon Index fields are possible. A comma separates all fields in an entry and a semicolon indicates the end of the entry. The fields, in order, are as follows.
Bitmap ID
The Bitmap ID identifies a resource that contains an array of bitmaps. The Bitmap ID is always a GUID:ID pair in which the ID is the resource ID of the bitmap in the resource file of the VSPackage.
Each bitmap resource must have a unique Bitmap ID. A bitmap entry can share the GUID with another bitmap entry, but each entry must have a unique resource ID. The GUID is typically the command-set GUID of the VSPackage, but it may be a GUID that is specifically created for each bitmap.
If you create a bitmap, its resource ID must be defined in the resource file that creates the satellite DLL or managed package. For more information, see "Creating Custom Bitmap Icons" in this topic.
The bitmap files that are included in Visual Studio, Microsoft Office, or Windows can be used as a bitmap resource. For example, Office icons are referenced by using the GUID guidOfficeIcon, as defined in Vsshlids.h. Vsshlids.h is located in Visual Studio SDK installation path\VisualStudioIntegration\common\inc\.
The Bitmap ID field in the example is as follows.
guidEUGrp:IDB_CMDBARIn this example, the resource (.rc) file of the VSPackage must contain a bitmap resource that has the resource ID IDB_CMDBAR.
Icon Index
The Icon Index field specifies which bitmap in the bitmap resource will be used. The Icon Index is a value of 1 to n, where 1 represents the first image in the bitmap.
The BUTTONS_BEGIN – BUTTONS_END section uses the Icon Index and the GUID of the Bitmap ID field to define a command Icon ID:GUID:Icon Index. The indexes can be the actual numeric value of the index or a macro that has been assigned to the index number. We suggest that you use the latter convention because it is more readable. For example, in the File Explorer sample, the Icon Index, bmpidFileSysTool, is defined as follows in the Pkgcmdid.h header file that is included in the sample .ctc file.
#define bmpidFileSysTool 1The first three values in the Icon Index field in the example are as follows.
bmpidFileSysTool, bmpidFolderView, bmpidShortcutViewA command that uses the bmpidFolderView bitmap could be defined as follows.
guidEUCmd:cmdidFolderView, guidEUGrp:IDG_FOLDERPANE_VIEW, 0x0010, guidEUGrp:bmpidFolderView, BUTTON, 0, "Folders";
Creating Custom Bitmap Icons
The Visual Studio SDK lets you create custom icons by using the resource file of a project, as follows:
Each bitmap resource must have a unique resource ID that is defined in an .rc file.
A GUID can be defined for each bitmap resource, or you can use command-set GUID of the VSPackage.
This GUID:Resource ID pair is used to identify the bitmap in the BITMAPS_BEGIN - BITMAPS_END section. Define this GUID in either your Command Table Configuration (.Ctc) Files or in a .h header file that is included in your .ctc file.
Each icon in the bitmap resource should be 16 pixels wide and 16 pixels high, and the background color should be set to Magenta, as defined by RGB(255,0,255.) (For 32-bit images, use the alpha channel to specify transparency.)
Each icon that is created is assigned an Icon Index, starting with 1.
The first icon in this bitmap can be specified as GuidMyBmp:1.
For command icons that appear on menus and toolbars, the high-color format must be 32-bit ARGB where transparency is supplied by the alpha channel. For tool window icons, the high-color format is 24-bit (RGB), and the transparent color is supplied in code and is usually RGB(255, 0, 255).
For better readability, use the #define directive in a header file to provide a human-readable name for each Icon Index. For example, in the File Explorer sample, bmpidFileSysTool is defined in the Pkgcmdid.h header file that is included in the sample .ctc file:
#define bmpidFileSysTool 1