bitmap(1X)
NAME
bitmap − X Window System bitmap editor
SYNTAX
bitmap filename [ dimensions ] [ display ] [ geometry ]
ARGUMENTS
dimensionsSpecifies the size of the bitmap grid contained in the displayed window. If not specified, bitmap creates a 16x16 bitmap grid. The dimensions argument has the format widthxlength.
widthSpecifies the width of the bitmap.
lengthSpecifies the length of the bitmap.
When an existing file is specified, its bitmap grid dimensions are used.
displaySpecifies the display screen on which bitmap is to display its window. If the display argument is not specified, bitmap uses the display screen specified by your DISPLAY environment variable. The display argument has the format hostname:number.
hostnameSpecifies the name of the host machine on which the display is connected. You can specify the name local to use shared memory, the name unix to use UNIX IPC, or the name of your host machine to use TCP.
numberSpecifies the number of the display on that host machine.
geometrySpecifies the width, length, and location of the bitmap window. If the geometry argument is not specified, bitmap uses mouse input. For further information, see DESCRIPTION.
The geometry argument has the format =[width][xlength][x][y]
widthSpecifies the number of pixels for the window’s horizontal dimension.
lengthSpecifies the number of pixels for the window’s vertical dimension.
xSpecifies the x screen coordinate (pixel value) for the starting corner of the window.
ySpecifies the y screen coordinate (pixel value) for the starting corner of the window.
Depending on which corner of the screen each is relative to, both the x and y coordinates must be preceded by a plus (+) or a minus (−). For more information about the screen coordinate system, see X(.).
When creating a large bitmap, specify the geometry argument in order to ensure that the bitmap is not displayed offscreen.
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 edited bitmap.
The size of the window can be specified by the geometry argument. If the geometry argument is not specified, however, position and size the bitmap window by pressing one of the following mouse buttons:
LeftPositions the upper left corner of the window at the mouse pointer and sizes the window with a default width and length.
MiddlePositions the starting point of the window at the mouse pointer and sizes the window to a width and length determined by mouse movement.
RightPositions the window at a default screen location and sizes the window with a default width and length.
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.
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.
COMMANDS
When using a color display, 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 upon 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 over 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 X’s 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.
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 or if your cursor is a cross, the hot spot should be where the perpendicular lines intersect.
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[] = {
0x0010, 0x0038, 0x007c, 0x0010,
0x0010, 0x0010, 0x01ff, 0x0010,
0x0010, 0x0010, 0x007c, 0x0038,
0x0010};
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 filename /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"
XCreateCursor (this_width, this_height, this_bits, this_mask_bits,
this_x_hot, this_y_hot, foreground, background, func);
In this example, foreground and background are color values and func is a display function (normally GXcopy).
An X program can also read a bitmap file at runtime by using the function XReadBitmapFile.
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 caret (^) in the shell which 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
Like most X-based applications, bitmap reads the .Xdefaults file during start-up 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 which are 0 in the bitmap are displayed in this color. This option is useful only on color displays. The default is white.
Border 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 3.
BodyFont Specifies the text font displayed in the window. The default is vtsingle.
Foreground Specifies the foreground color of the window. Bits which 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.
DIAGNOSTICS
The following messages may be displayed in the C-shell that you invoked bitmap with. 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 <message> (for example, permission denied).
bitmap: invalid dimensions string
bitmap: dimensions must be positive
The second command line argument was 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
A protocol error occurred. Something is wrong with either the X Server or the X library that the program was compiled with. Possibly they are incompatible. If the X Server is not on the local host, perhaps the connection broke.