This chapter introduces the Bitmap Editor, used to create and modify bitmaps, icons, bitmap families, and icon families within a variety of resources.
Overview of Icons, Bitmaps, and Other Images
To work with icons and bitmaps, start Palm OS Resource Editor and open the resource file you want to edit, as described in "Opening a Resource Description File in Resource Editor".
You can either create a new bitmap, or edit an existing bitmap.
- To create a new bitmap, see"Creating New Bitmaps".
- To modify an existing bitmap, see "Modifying an Existing Bitmap".
To work with other raster images in your Palm OS application, see "Using the Bitmap Editor."
Creating New Bitmaps
- In the Files pane, select the resource description (XRD) file to which you want to add the bitmap.
- In the main menu bar, select Edit > New Resource. The New Resource dialog box appears.
- In the New Resource dialog box, select Bitmap and then click the New button.
- The name and number of the new bitmap appear in the Files pane, and the bitmap is displayed in the Bitmap Editor. For information on how to edit the bitmap, see "Modifying an Existing Bitmap".
Modifying an Existing Bitmap
- In the Files pane, select the bitmap resource you want to modify. When you select a bitmap resource, the bitmap's properties are displayed in the Properties pane.
- In the Files pane, double-click the bitmap resource to display it in the Bitmap Editor. The Bitmap Editor appears. For information on how to use the Bitmap Editor, see "Using the Bitmap Editor".
Using the Bitmap Editor
In the Bitmap Editor you can edit Palm OS bitmaps. A Palm OS bitmap is actually a family of bitmaps. A bitmap image family is a logical bitmap which is composed of a set of individual bitmap images at different bit-depths and densities. The Bitmap Editor provides a bitmap image family editor and a bitmap image editor.
The left side of the Bitmap Editor window displays the image family properties and all available bitmap images in the family. On the right side of the Bitmap Editor you can edit any bitmap image in the image family, and you can set element-specific properties for the bitmap. The Bitmap Editor window also contains a color palette.
Setting Image Family Properties
To change the image family's height and width, click the Set button in the Bitmap Editor. This displays a New Bitmap Size dialog where you can specify the new dimensions of the bitmaps in this image family. The width and height are expressed as values for the single-density image family members. Family members with other densities are scaled according to their density.
You can also specify whether or not to scale the images to the new size. If not, the image will be truncated in any dimension that is made smaller, and will have white filling any newly exposed areas.
Viewing Image Family Elements
The Bitmap Editor shows all the bitmap elements that are in the image family. Bitmap elements are uniquely identified by density and bit-depth.
The densities currently defined are 1X, 1.5X, and 2X. The bit-depths currently defined are 1-bit (black & white), 2-bit (4 grays), 4-bit (16 grays), 8-bit (Palm OS palette of 256 colors), and 16-bit (5-6-5 RGB).
The bitmaps in the image family are displayed as a list of thumbnail images, listed in order of increasing depth and then density, with each element labeled clearly. If there are more thumbnails than fit in the view area, a vertical scrollbar appears.
Thumbnails are shown in normalized scale. That is, the 1X and 2X thumbnails are shown at the same size, not with the 2X image being twice as large as the 1X. This way the "logical" value is being shown, making it easy to compare the actual device appearance of the bitmaps independent of the nominal density.
Selecting a thumbnail draws a selection rectangle around it and makes it active in the Bitmap Editor.
Adding and Deleting Image Family Elements
To add image elements to the image family, click the Add button in the Bitmap Editor. This displays a New Bitmap dialog listing all the possible image element types. You can select one or more image element types to create them. Element types that already exist in the bitmap family are indicated by being checked and disabled.
IMPORTANT: Resource Editor allows you to use the same external image file in more than one resource file. However, if you modify a property of the external image, you may inadvertently overwrite an existing bitmap used by another resource or resource file. As a result, you should generally make a copy of an external image file rather than reusing it in more than one resource file.
To delete image elements, you can use the mouse to select the elements you want to delete and then click the Delete button in the Bitmap Editor. Note that only the image family element from the resource is deleted; no external bitmap files are deleted.
You cannot delete all the image elements. If you try to delete the last element in a family, the Bitmap Editor will not allow it unless you first create a new element. This is necessary, as bitmap resources must contain at least one image element.
Importing Images
To define image elements, you select them and draw them in the Bitmap Editor, or else you import an image from a pre-existing file on disk. To import an image, click the Import button in the Bitmap Editor.
Note that saving a bitmap resource does not necessarily result in the edited imported image being saved in the file from which it came.
If the import image is a different size than the bitmap family member into which it is being stored, the Import Bitmap dialog appears, asking the user to resolve the difference. The Import Bitmap dialog allows the user to select one of four options:
- Scale new image: The new image is scaled from its original size to the size of the other bitmap family members.
- Truncate new image: The new image is truncated to fit the bounds implied by the other bitmap family members. If the new image is smaller than the existing members, it is enlarged and the newly exposed areas are filled with white.
- Scale existing images to new image size: The existing bitmap family members are made to conform to the new image's size, scaling them as appropriate.
- Truncate existing images to new image size: The existing bitmap family members are made to conform to the new image's size, truncating or expanding them as appropriate.
Using the Color Palette
The Bitmap Editor contains a Color Palette. The Color Palette changes based on the color format of the image being edited. For palette images (1-bit, 2-bit, 4-bit, and 8-bit) it displays a swatch of each of the colors available. For true color images (16-bit RGB) it displays a palette of 644 evenly distributed colors.
NOTE: If the XRD source file specifies that a bitmap uses a color table, then Resource Editor will attempt to use that color table. However, if the color table is missing, the color palette will be empty. You may see this problem if you have an existing application where the
hasColorTable
flag is set, but no color table exists.
In the top left corner of the Color Palette is a control that shows the currently selected foreground and background colors. Clicking on any of the available color swatches or on the color picker sets the foreground color. Right-clicking on any of the available color swatches or on the color picker sets the background color.
Using the Bitmap Editor Toolbar
The Bitmap Editor has a toolbar containing the following items:
- Rectangle Selection tool
- Color Selection tool
- Fill tool
- Magnification tool
- Pencil tool
- Brush tool
- Air Brush tool
- Line tool
- Rectangle tool
- Outlined Rectangle tool
- Filled Rectangle tool
- Rounded Rectangle tool
- Outlined Rounded Rectangle tool
- Filled Rounded Rectangle tool
- Ellipse tool
- Outlined Ellipse tool
- Filled Ellipse tool
When you click a tool in the toolbar to select it, the cursor changes to an appropriate cursor for the action that the tool performs.
Working with Other Formats—Graphic Families
Bitmaps and icons are not the only image formats available for use in Palm OS applications. Currently, you can add families of PNG images to your application in Palm OS Developer Suite.
- Create and edit PNG images using an appropriate graphics editor (not part of Palm OS Developer Suite).
- In Palm OS Developer Suite, create a graphic family resource. For more information, see "Creating a New Graphic Family Resource."
- Import the individual images into the graphic family resource copying the data or by reference an external file. For more information, see
Creating a New Graphic Family Resource
To create a new graphic family resource:
- In the Files pane, select the resource description (XRD) file to which you want to add the bitmap.
- In the main menu bar, select Edit > New Resource. The New Resource dialog box appears.
- In the New Resource dialog box, select Graphic Family and then click the New button.
- The number of the new graphic family resource appears in the Files pane, and a skeletal XML definition of a graphic family appears in the XML editor.
Complete the XML description for the graphic family as a whole. Then add an XML description for each of the images in the family. Follow the XML format described under "Graphic Family Resource" in Palm OS Resource File Formats.
NOTE: You add the images to the family by copying the binary data or by referencing an external file. For more information, see "Importing Images to a Graphic Family".
Importing Images to a Graphic Family
You can import images to a graphic family by copying the data into the XRD file or referencing an external file.
- Use the
GRAPHIC_FAMILY_DATA
element to copy the binary data of the image directly into the XRD file. Data must be in hexadecimal format. - Use the
GRAPHIC_FAMILY_EXTERNAL
element to reference an external image file.
For a complete description of the XML format, see the "Graphic Family Resource" section in Palm OS Resource File Formats.