BITMAP(1X10) COMMAND REFERENCE BITMAP(1X10)
NAME
bitmap - bitmap editor for X window system
For 4310, 4320, and 4330 series UTek products only.
Public domain software distributed by M.I.T. Project Athena.
Provided by Tektronix as is, without express or implied
warranty.
Not supported by Tektronix.
SYNOPSIS
bitmap filename [dimensions] [host:display] [=geometry]
DESCRIPTION
The program bitmap 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 bitmap, 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
commands to set, clear or invert larger rectangular areas of
the bitmap. Other commands allow you to move or copy
rectangular areas from one part of the bitmap to another,
and to define a `hot spot'--a special single point on the
bitmap, which is useful when the bitmap is used as an X
cursor.
The output of the bitmap program is a small program
fragment. 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 bitmap 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
dimensions. If the file does not exist, bitmap will create
a window for a bitmap of the size specified by dimensions ,
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 viewable limit is 414 x 278;
the practical limit is somewhat lower, and depends on the
size and resolution of your display. The program bitmap
accepts two other optional command line arguments. You may
specify a display name in the form host:display (see
X Version 10 29 January 1986 1
BITMAP(1X10) COMMAND REFERENCE BITMAP(1X10)
X(1x10)). And you may provide a geometry specification. If
you don't give a geometry specification, bitmap will ask you
where you want to put the window when it starts up. See
X(1x10) for a full explanation. The window that bitmap
creates has four parts. The largest section is the
checkerboard grid, which is a magnified version 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 bitmap 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 .Xdefaults 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 left mouse button turns a grid
square black and sets the corresponding bitmap bit to 1.
The right mouse button turns a grid square white and sets
the corresponding bitmap bit to 0.
The middle mouse button 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.
Clear All
turns all the grid squares white and sets all bitmap
bits to 0. This is irreversible, so invoke it with
care.
Set All turns all the grid squares black and sets all bitmap
bits to 1. This is also irreversible.
X Version 10 29 January 1986 2
BITMAP(1X10) COMMAND REFERENCE BITMAP(1X10)
Invert All
inverts all the grid squares and bitmap bits, as if
you had pressed the middle mouse button over each
square.
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 while
moving 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.
Set Area
turns a rectangular area of the grid black and sets
the corresponding bitmap bits to 1. It works the
same way as the Clear Area command.
Invert Area
inverts a rectangular area of the grid. It works
the same way as the Clear Area command.
Copy Area
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 Clear Area
above. Then, the cursor will change to an "upper-
left corner". When you press a mouse button, a
destination 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.
Move Area
works identically to Copy Area, except that it
X Version 10 29 January 1986 3
BITMAP(1X10) COMMAND REFERENCE BITMAP(1X10)
clears the source rectangle after copying to the
destination.
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 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.
Clear Hotspot
removes any hot spot that was defined on this
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~ (in the manner of emacs(1) and other
text editors).
If either the renaming or the writing cause an error
(e.g. ``Permission denied'), a Macintosh-style
dialog window will appear, asking if you want to
write the file /tmp/filename instead. If you say
yes, all future ``Write Output'' commands will write
to /tmp/filename as well. See below for the format
of the output file.
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, a Macintosh-style dialog window will appear,
asking if you want to save changes before quitting.
``Yes'' does a ``Write Output'' before exiting;
``No'' just exits, losing the edits; ``Cancel''
means you decided not to quit after all.
FILE FORMAT
Bitmap 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
X Version 10 29 January 1986 4
BITMAP(1X10) COMMAND REFERENCE BITMAP(1X10)
static short foo_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;
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 bitmap with filename
/usr/include/bitmaps/cross.bitmap will produce 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).
It's easy to define a bitmap or cursor in an X program by
simply #include'ing a bitmap file and referring to its
variables. For instance, to use a cursor defined in the
files this.cursor and this_mask.cursor, 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 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.
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.
X Version 10 29 January 1986 5
BITMAP(1X10) COMMAND REFERENCE BITMAP(1X10)
BodyFont
The text font. Default: vtsingle.
Foreground
The foreground color. Bits which are 1 in the
bitmap are displayed in this color. This option is
useful only on color displays. Default: black.
Highlight
The highlight color. bitmap 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, then bitmap 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.
SEE ALSO
X(1x10), Xlib Documentation.
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, or the host is unreachable, or
the host is not running an X server, or the host is 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
X Version 10 29 January 1986 6
BITMAP(1X10) COMMAND REFERENCE BITMAP(1X10)
given in <message> (e.g., 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''
bitmap encountered a variable ending in something other than
_x_hot, _y_hot, _width, or _height while parsing the input
file. 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 which the program was compiled
with. Possibly they are incompatible. If the server is not
on the local host, maybe the connection broke.
CAVEATS
Doesn't take enough command line options yet. Most options
can be specified only through .Xdefaults. If you move the
mouse too fast while holding a mouse button down, some
squares may be `missed'. This is caused by limitations in
how frequently the X server can sample the mouse location.
There is no way to write to a file other than that specified
on the command line.
X Version 10 29 January 1986 7
BITMAP(1X10) COMMAND REFERENCE BITMAP(1X10)
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 ^C or ^ in the shell which invoked it, or if you kill
it with the shell's ``kill'' command.
Dimensions greater than 99 are not read properly from the
command line or input file. Generally such dimensions would
not be useful anyway, since they would produce a window
larger than most displays.
X Version 10 29 January 1986 8
%%index%%
na:360,337;
sy:697,269;
de:966,16593;
di:17673,3069;
ca:20742,1537;
se:17559,114;
%%index%%000000000115