Name

bitmap − X Window System bitmap editor

Syntax

bitmap [ options ] file dimensions

Arguments

dimensionsSpecifies the size of the bitmap grid contained in the displayed window.  If the size is not specified, bitmap creates a 16x16 bitmap grid.  The dimensions argument has the format widthxheight:

widthSpecifies the width of the bitmap. 

heightSpecifies the height of the bitmap. 

When an existing file is specified, its bitmap grid dimensions are used. 

Description

The bitmap program lets you interactively create small bitmaps or edit previously created bitmaps.  A bitmap is a small picture, represented as a rectangular array of 0 and 1 bits.  The X Window System uses bitmaps to represent, for example, cursors and icons. 

When it starts, the bitmap program first tries to read the specified file (see FILE FORMAT).  If the file already exists, the bitmap program creates a window containing a grid that displays the previously created bitmap. 

If the file does not exist, the bitmap program creates a window containing an empty grid.  The size of this grid is specified by the dimensions argument. 

When displayed, the bitmap window has four parts.  The largest section is the checkerboard grid.  This grid is a magnified version of the bitmap you are editing. 

You can then use the mouse or commands displayed in the upper right corner of the window to set, clear, or invert individual pixels. 

Subsequent commands allow you to move or copy rectangular areas from one part of the bitmap to another and to define a special single point (hot spot) on the bitmap that is useful when the bitmap is used as an X cursor.  They also let you draw lines, circles, and filled circles. 

Below the listed commands is an actual-size picture of the bitmap you are editing and an inverted version of the same bitmap.  Each time you change the grid, the same change occurs in the actual-size bitmap and its inverse. 

The output of the bitmap program is a small program fragment.  By including such a program fragment in your C program, you can declare the size and contents of cursors, icons, and other bitmaps that your program creates. 

Options

−bg colorSpecifies the color of the window’s background (color displays only).  The default is white. 

−d dispnameSpecifies the screen on which bitmap displays its window.  If the display option is not specified, bitmap uses the display screen specified by your DISPLAY environment variable.  The display option has the format hostname:number.  Using two colons (::) instead of one (:) indicates that DECnet is to be used for transport.  The default is :0.  For more information, see X(.).

−display dispnameThis option is the same as the −d option. 

−fg colorSpecifies the foreground color. 

−fn fontSpecifies the font used for the foreground. 

−geometrySpecifies the width, length, and location of the bitmap window.  If the geometry option is not specified, bitmap uses default values.  The geometry option has the format =[width][xlength][x][y].  For more information about the screen coordinate system, see X(.).

When creating a large bitmap, specify the geometry option to ensure that the bitmap is not displayed offscreen. 

−helpDisplays a brief description of valid options and arguments. 

−hl colorSpecifies the color used for highlighting. 

−ms colorSpecifies the mouse pointer color. 

−nodashedIndicates that grid lines in the work area should be drawn using solid lines. 

Commands

The following refers to the background color as “white” and the foreground color as “black.”

When the cursor is in the checkerboard region, each mouse button has a different effect on the single square that the cursor is over:

Left Turns the grid square to black and sets the corresponding bitmap bit to 1. 

Right Turns the grid square to white and sets the corresponding bitmap bit to 0. 

Middle Inverts a grid square and sets the bitmap bit to 0 if it was 1 and to 1 if it was 0. 

You can also invoke other commands by moving the mouse over one of the command boxes at the upper right corner and pressing any mouse button.  These commands are:

Clear All Turns all the grid squares white and sets all bitmap bits to 0.  This is irreversible. 

Set All Turns all the grid squares black and sets all bitmap bits to 1.  This is irreversible. 

Invert All Inverts all the grid squares and bitmap bits. 

Clear Area Clears a rectangular area of the grid, turning it white and setting the corresponding bitmap bits to 0. After you click on this command, the cursor turns into an “upper left corner.” Press any mouse button over the upper left corner of the area you want to invert and hold the button down.  Then, move the mouse to the lower right corner of the area you want to invert and release the button.  While the button is held down, the selected area is covered with Xs and the cursor changes to a “lower right corner.”
 
To abort the command, either press another mouse button, move the cursor outside the grid, or move the cursor to the left of or above the upper left corner.

Set Area Turns a rectangular area of the grid black and sets the corresponding bitmap bits to 1.  Specify the area as with the Clear Area command. 

Invert Area Inverts a rectangular area of the grid.  Specify the area as with the Clear Area command. 

Copy Area Copies a rectangular area from one part of the grid to another.  To copy an area, first specify the area as with the Clear Area command.  When the cursor changes to an “upper left corner,” press and hold a mouse button.  When you press and hold a button, the destination rectangle overlays the grid.  Next, while holding down the button, move the destination rectangle by moving the mouse.  Finally, release the button.  When the button is released, the area is copied.  To abort the command, move the mouse outside the grid and release the button. 

Move Area Works identically to the Copy Area command.  However, the Move Area command clears the source rectangle after copying to the destination. 

Flood Fill Inverts a closed area of the grid.  You must specify a solid area before invoking this command or bitmap will invert the entire grid. 

Overlay Area This command works identically to the Copy Area command.  However, the Overlay Area command does not remove the bitmap pattern that exists in the area to which the destination rectangle is copied. 

Line Draws a line between two points.  To specify the coordinates of the two points, click any mouse button successively on any two squares.  Doing this designates the line end points.  When the second endpoint is selected, bitmap draws the line. 

Circle Draws a circle.  To specify the center of the circle, first click any mouse button.  Then, click the same mouse button some distance from the center to determine the radius.  When the radius endpoint is selected, bitmap draws the circle. 

Filled Circle Draws a filled circle.  Specify the center and radius as with the Circle command. 

Set Hotspot Designates a point on the bitmap as the hot spot.  If a program is using your bitmap as a cursor, the hot spot indicates the point on the bitmap that represents the actual location of the cursor.  For example, if the cursor is an arrow, the hot spot should be the tip of the arrow. 

Clear Hotspot Removes any hot spot that was defined on the bitmap. 

Write Output Writes the current bitmap value to the file specified in the original command line.  If the file already exists, the original file is first renamed to filename~.  If either the renaming or the writing procedure causes an error, bitmap displays a Dialog window.  The Dialog window asks if you want to write the file to /tmp/filename instead.  If you say yes, the Write Output command will write to /tmp/filename.  In addition, all future executions of this command will write to this file as well. 

Quit Exits the bitmap program.  If you have edited the bitmap and have not invoked Write Output, or you have edited it since the last time you invoked Write Output, bitmap displays a Dialog window.  The Dialog window asks if you want to save changes before quitting.  To save the changes, select the Yes command button.  To exit the bitmap program and not save the changes, select the No command button.  To abort the command, select the Cancel command button. 

File Format

The bitmap command reads and writes files in the following format:

#define filename_width 9
#define filename_height 13
#define filename_x_hot 4
#define filename_y_hot 6
static short filename_bits[] = {
   0x10, 0x00, 0x38, 0x00, 0x7c, 0x00, 0x10, 0x00, 0x10, 0x00, 0x10, 0x00
   0xff, 0x01, 0x10, 0x00, 0x10, 0x00, 0x10, 0x00, 0x7c, 0x00, 0x38, 0x00
   0x10, 0x00};

 
The variables ending with _x_hot and _y_hot are optional.  These variables are present only if a hot spot has been defined for the bitmap.  The other variables must be present. 

In place of filename, the five variables are prefixed with a string derived from the name of the file specified on the original command line.  The replacement string does not include the directory path (all characters up to and including the last slash (/), if one is present) or the extension (the first period (.), if one is present, and all characters beyond it). 

For example, invoking bitmap with the file name /usr/include/bitmaps/cross.bitmap produces a file with variable names cross_width, cross_height, and cross_bits (and cross_x_hot and cross_y_hot, if a hot spot is defined). 

To define a bitmap or cursor in an X program, include a bitmap file and refer to its variables.  For example, to use a cursor defined in the files this.cursor and this_mask.cursor, use the following:

#include "this.cursor"
#include "this_mask.cursor"
Pixmap source = XCreateBitmapFromData (display, drawable, this_bits,
this_width, this_height);
Pixmap mask = XCreateBitmapFromData (display, drawable, this_mask_bits,
this_mask_width, this_mask_height);
Cursor cursor = XCreatePixmapCursor (display, source, mask, foreground,
background, this_x_hot, this_y_hot);

In this example, foreground and background are color values. 

An X program can also read a bitmap file at run time by using the function XReadBitmapFile. 

The bits are in XYBitmap format, with bitmap_unit = bitmap_pad = 8, and byte_order = bitmap_bit_order = LSBFirst (least significant bit and byte are leftmost). 

For backward compatibility with X10, bitmap can also read in a file where the "bits" array is declared as "static short foo_bits[ ]" and consists of an array of 16-bit hexadecimal constants.  This is interpreted as a XYBitmap with bitmap_unit = bitmap_pad = 16, byte_order = bitmap_bit_order =LSBFirst.  If you modify the bitmap after reading in such a file, bitmap will always write the file back out in standard X11 format. 

Restrictions

Most options can be specified only through the .Xdefaults file. 

If you move the mouse too fast while holding a mouse button down, some squares may be missed.  This is caused by how frequently the X Server can sample the mouse location. 

There is no way to write to a file other than the one specified on the command line. 

There is no way to change the size of the bitmap once the program is started. 

Edits are unrecoverably lost if you terminate the program with a CTRL/C or a circumflex (^) in the shell that invoked it, or if you kill it with the shell’s kill command. 

Although larger bitmaps are possible, the largest suggested bitmap dimensions are 180x180. 

X Defaults

The bitmap application reads the .Xdefaults file during startup and uses the appropriate resource specification to customize the appearance or characteristics of its displayed bitmap window.  The format for a specification in the .Xdefaults file is: [name.*]resource:  value

nameSpecifies the application name or, in the case of X Toolkit-based applications, the name string that restricts the resource assignment to that application or to a component of an application.  If this argument is not specified, the resource assignment is globally available to all X applications. 

resourceSpecifies the X resource. 

valueSpecifies the value that is to be assigned to the resource. 

For bitmap, the available name is bitmap. 

For bitmap, the available resources are:

Background Specifies the background color of the window.  Bits that are 0 in the bitmap are displayed in this color.  This option is useful only on color displays.  The default is white. 

BorderColor Specifies the border color of the window.  This option is useful only on color displays.  The default is black. 

BorderWidth Specifies the border width of the window in pixels.  The default is 2. 

BodyFont Specifies the text font displayed in the window.  The default is "variable". 

Foreground Specifies the foreground color of the window.  Bits that are 1 in the bitmap are displayed in this color.  This option is useful only on color displays.  The default is black. 

Highlight Specifies the highlight color.  The bitmap command uses this color to show the hot spot and to indicate rectangular areas that will be affected by the Move Area, Copy Area, Set Area, and Invert Area commands.  If a highlight color is not given, bitmap highlights by inverting.  This option is useful only on color displays. 

Mouse Specifies the color of the mouse cursor.  This option is useful only on color displays.  The default is black. 

Geometry Specifies the size and location of the bitmap window. 

Dimensions Specifies the default width and length used for new bitmaps. 

Diagnostics

The following messages may be displayed in the C shell with which you invoked bitmap.  Any of these conditions aborts bitmap before it can create its window. 

bitmap: could not connect to X Server on host:display

Either the display given on the command line or the DISPLAY environment variable has an invalid host name or display number, or the host is down, unreachable, not running an X Server, or refusing connections. 

bitmap: no file name specified

You invoked bitmap with no command line arguments.  You must give a file name as the first argument. 

bitmap: could not open file filename for reading -- message

The specified file exists but cannot be read, for the reason given in the message (for example, permission denied). 

bitmap: invalid dimensions string
bitmap: dimensions must be positive

The second command line argument is not a valid dimension specification. 

bitmap: file filename does not have a valid width dimension
bitmap: file filename does not have a valid height dimension
bitmap: file filename has an invalid nth array element

The input file is not in the correct format;  the program gave up when trying to read the specified data. 

The following messages may be displayed in the C shell after bitmap creates its window:

bitmap: Unrecognized variable name in file filename

While parsing the input file, the bitmap program encountered a variable ending in something other than _x_hot, _y_hot, _width, or _height.  It will ignore this variable and continue parsing the file. 

bitmap: XError: message
bitmap: XIOError

XError indicates that a protocol error occurred.  Something is wrong with either the X Server or the X library that the program was compiled with.  The message may indicate that they are incompatible.  XIOError usually indicates that the connection broke.  The connection may be interrupted if the X Server is not on the local host. 

See Also

X(1X)

Commands