4.3BSD-UWisc/man/cat1/bitmap.1

BITMAP(1) UNIX Programmer's Manual BITMAP(1)

NAME
bitmap - bitmap editor for X window system

SYNOPSIS
bitmap filename [_d_i_m_e_n_s_i_o_n_s] [_h_o_s_t:_d_i_s_p_l_a_y] [=_g_e_o_m_e_t_r_y]

DESCRIPTION
_b_i_t_m_a_p 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 cursors and icons,
among other things.

When you run _b_i_t_m_a_p, you are given a magnified version of
the bitmap, with each pixel blown up into a large square,
like a piece of graph paper. You can then use the mouse to
set, clear, or invert individual pixels, and can invoke com-
mands to set, clear or invert larger rectangular areas of
the bitmap. Other commands allow you to move or copy rec-
tangular areas from one part of the bitmap to another, and
to define a `hot spot'--a special single point on the bit-
map, which is useful when the bitmap is used as an X cursor.

The output of the _b_i_t_m_a_p program is a small program frag-
ment. By #include'ing such a program fragment in your C
program, you can easily declare the size and contents of
cursors, icons, and other bitmaps that your program creates
to deal with the X window system.

When _b_i_t_m_a_p starts, it first tries to read the specified
file (see FILE FORMAT). If the file already exists, it
creates a window containing a grid of the appropriate dimen-
sions.

If the file does not exist, _b_i_t_m_a_p will create a window for
a bitmap of the size specified by _d_i_m_e_n_s_i_o_n_s , which should
be two numbers separated by the letter `x' (e.g. 7x9,
13x21). The first number is the bitmap's width; the second
is its height. The bitmap will start out empty. If no
dimensions are specified on the command line, a 16x16 bitmap
will be created. The absolute limit is 99x99; the practical
limit is somewhat lower, and depends on the size and resolu-
tion of your display.

_b_i_t_m_a_p accepts two other optional command line arguments.
You may specify a display name in the form _h_o_s_t:_d_i_s_p_l_a_y (see
_X(_1)). And you may provide a geometry specification. If
you don't give a geometry specification, _b_i_t_m_a_p will ask you
where you want to put the window when it starts up. See
_X(_1) for a full explanation.

Printed 1/10/87 29 January 1986 1

BITMAP(1) UNIX Programmer's Manual BITMAP(1)

The window that _b_i_t_m_a_p creates has four parts. The largest
section is the checkerboard grid, which is a magnified ver-
sion of the bitmap you are editing. At the upper left is a
set of commands that you can invoke with any mouse button.
Below the commands is an "actual size" picture of the bitmap
you are editing; below that is an inverted version of the
same bitmap. Each time you change the grid, the same change
will occur in the actual-size bitmap and its inverse.

If you use a window manager to make the _b_i_t_m_a_p window larger
or smaller, the grid squares will automatically get larger
or smaller as well.

COMMANDS
(Note for users of color displays: In all of the following,
``white'' means the background color, and ``black'' means
the foreground color. You may specify a foreground and
background color in your ._X_d_e_f_a_u_l_t_s file; see the X
DEFAULTS section below.)

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

The _l_e_f_t _m_o_u_s_e _b_u_t_t_o_n turns a grid square black and sets the
corresponding bitmap bit to 1.

The _r_i_g_h_t _m_o_u_s_e _b_u_t_t_o_n turns a grid square white and sets
the corresponding bitmap bit to 0.

The _m_i_d_d_l_e _m_o_u_s_e _b_u_t_t_o_n inverts a grid square, turning it
white if it was black, or black if it was white. It also
inverts the corresponding bitmap bit, setting it to 0 if it
was 1, and to 1 if it was 0.

You can also invoke more sophisticated commands by moving
the mouse over one of the command boxes at the upper right
corner, and pressing any mouse button.

_C_l_e_a_r _A_l_l
turns all the grid squares white and sets all bitmap
bits to 0. This is irreversible, so invoke it with
care.

_S_e_t _A_l_l turns all the grid squares black and sets all bitmap
bits to 1. This is also irreversible.

Printed 1/10/87 29 January 1986 2

BITMAP(1) UNIX Programmer's Manual BITMAP(1)

_I_n_v_e_r_t _A_l_l
inverts all the grid squares and bitmap bits, as if
you had pressed the middle mouse button over each
square.

_C_l_e_a_r _A_r_e_a
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 _h_o_l_d _t_h_e _b_u_t_t_o_n _d_o_w_n while mov-
ing the mouse to the lower-right corner of the area
you want to invert, then let the button up.

While you are holding down the button, the selected
area will be covered with X's, and the cursor will
change to a `lower-right corner'. If you now wish
to abort the command without clearing an area,
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.

_S_e_t _A_r_e_a
turns a rectangular area of the grid black and sets
the corresponding bitmap bits to 1. It works the
same way as the _C_l_e_a_r _A_r_e_a command.

_I_n_v_e_r_t _A_r_e_a
inverts a rectangular area of the grid. It works
the same way as the _C_l_e_a_r _A_r_e_a command.

_C_o_p_y _A_r_e_a
copies a rectangular area from one part of the grid
to another. First, you select the rectangle to be
copied, in the manner described under _C_l_e_a_r _A_r_e_a
above. Then, the cursor will change to an "upper-
left corner". When you press a mouse button, a des-
tination rectangle will overlay the grid; moving
the mouse while holding down the button will move
this destination rectangle. The copy will occur
when you let up the button. To cancel the copy,
move the mouse outside the grid and then let up the
button.

_M_o_v_e _A_r_e_a
works identically to _C_o_p_y _A_r_e_a, _e_x_c_e_p_t that it
clears the source rectangle after copying to the

Printed 1/10/87 29 January 1986 3

BITMAP(1) UNIX Programmer's Manual BITMAP(1)

destination.

_L_i_n_e will draw a line between two points.

_C_i_r_c_l_e will draw a circle specifying the center and a
radius

_F_i_l_l_e_d _C_i_r_c_l_e
will draw a filled circle given the center and
radius of the circle.

_S_e_t _H_o_t_s_p_o_t
designates a point on the bitmap as the "hot spot".
If a program is using your bitmap as a cursor, the
hot spot indicates which point on the bitmap is the
"actual" location of the cursor. For instance, if
your cursor is an arrow, the hot spot should be the
tip of the arrow; if your cursor is a cross, the
hot spot should be where the perpendicular lines
intersect.

_C_l_e_a_r _H_o_t_s_p_o_t
removes any hot spot that was defined on this bit-
map.

_W_r_i_t_e _O_u_t_p_u_t
writes the current bitmap value to the file speci-
fied in the original command line. If the file
already exists, the original file is first renamed
to filename~ (in the manner of _e_m_a_c_s(_1) and other
text editors).

If either the renaming or the writing cause an error
(e.g. ``Permission denied'), a Macintosh-style dia-
log window will appear, asking if you want to write
the file /_t_m_p/_f_i_l_e_n_a_m_e instead. If you say yes, all
future ``Write Output'' commands will write to
/_t_m_p/_f_i_l_e_n_a_m_e as well. See below for the format of
the output file.

_Q_u_i_t exits the _b_i_t_m_a_p program. If you have edited the
bitmap and have not invoked _W_r_i_t_e _O_u_t_p_u_t, or you
have edited it since the last time you invoked _W_r_i_t_e
_O_u_t_p_u_t, a Macintosh-style dialog window will appear,
asking if you want to save changes before quitting.
``Yes'' does a ``Write Output'' before exiting;

Printed 1/10/87 29 January 1986 4

BITMAP(1) UNIX Programmer's Manual BITMAP(1)

``No'' just exits, losing the edits; ``Cancel''
means you decided not to quit after all.

FILE FORMAT
_B_i_t_m_a_p reads and writes files in the following format, which
is suitable for #include'ing in a C program:
#define foo_width 9
#define foo_height 13
#define foo_x_hot 4
#define foo_y_hot 6
static short foo_bits[] = {
0x0010, 0x0038, 0x007c, 0x0010,
0x0010, 0x0010, 0x01ff, 0x0010,
0x0010, 0x0010, 0x007c, 0x0038,
0x0010};

The variables ending with __x__h_o_t and __y__h_o_t are optional;
they will be present only if a hot spot has been defined for
this bitmap. The other variables must be present.

In place of ``foo'', the five variables will be prefixed
with a string derived from the name of the file that you
specified on the original command line by
(1) deleting the directory path (all characters up to and
including the last `/', if one is present)
(2) deleting the extension (the first `.', if one is
present, and all characters beyond it)

For example, invoking _b_i_t_m_a_p with filename
/_u_s_r/_i_n_c_l_u_d_e/_b_i_t_m_a_p_s/_c_r_o_s_s._b_i_t_m_a_p will produce a file with
variable names _c_r_o_s_s__w_i_d_t_h, _c_r_o_s_s__h_e_i_g_h_t, and _c_r_o_s_s__b_i_t_s
(and _c_r_o_s_s__x__h_o_t and _c_r_o_s_s__y__h_o_t if a hot spot is defined).

It's easy to define a bitmap or cursor in an X program by
simply #include'ing a bitmap file and referring to its vari-
ables. For instance, to use a cursor defined in the files
_t_h_i_s._c_u_r_s_o_r and _t_h_i_s__m_a_s_k._c_u_r_s_o_r, one simply writes

#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);

where _f_o_r_e_g_r_o_u_n_d and _b_a_c_k_g_r_o_u_n_d are color values, and _f_u_n_c
is a display function (normally GXcopy).

An X program can also read a bitmap file at runtime by using
the function _X_R_e_a_d_B_i_t_m_a_p_F_i_l_e.

Printed 1/10/87 29 January 1986 5

BITMAP(1) UNIX Programmer's Manual BITMAP(1)

X DEFAULTS
Background
The window's background color. Bits which are 0 in
the bitmap are displayed in this color. This option
is useful only on color displays. Default: white.

Border The border color. This option is useful only on
color displays. Default: black.

BorderWidth
The border width. Default: 3.

BodyFont
The text font. Default: vtsingle.

Foreground
The foreground color. Bits which are 1 in the bit-
map are displayed in this color. This option is
useful only on color displays. Default: black.

Highlight
The highlight color. _b_i_t_m_a_p uses this color to show
the hot spot and to indicate rectangular areas that
will be affected by the _M_o_v_e _A_r_e_a, _C_o_p_y _A_r_e_a, _S_e_t
_A_r_e_a, and _I_n_v_e_r_t _A_r_e_a commands. If a highlight
color is not given, then _b_i_t_m_a_p will highlight by
inverting. This option is useful only on color
displays.

Mouse The mouse cursor's color. This option is useful
only on color displays. Default: black.

ENVIRONMENT
DISPLAY - the default host and display number.