+.TH BITMAP 1 "29 January 1986" "X Version 10"
+.SH NAME
+bitmap \- bitmap editor for X window system
+
+.SH SYNOPSIS
+.B bitmap
+filename [\fIdimensions\fP] [\fIhost\fP:\fIdisplay\fP] [=\fIgeometry\fP]
+
+.SH DESCRIPTION
+
+.I 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
+.I 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
+.I 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
+.I 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,
+.I bitmap
+will create a window for a
+bitmap of the size specified by
+.I 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 absolute limit is 99x99; the practical
+limit is somewhat lower, and depends on the size and resolution of your
+display.
+
+.I bitmap
+accepts two other optional command line arguments. You may specify a
+display name in the form \fIhost\fP:\fIdisplay\fP (see \fIX(1)\fP).
+And you may provide
+a geometry specification. If you don't give a geometry specification,
+.I bitmap
+will ask you where you want to put the window when it starts up. See
+.I X(1)
+for a full explanation.
+
+The window that
+.I 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
+.I bitmap
+window larger or smaller, the grid squares will automatically
+get larger or smaller as well.
+
+.SH 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 \fI.Xdefaults\fP 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
+.I left mouse button
+turns a grid square black and sets the corresponding
+bitmap bit to 1.
+
+The
+.I right mouse button
+turns a grid square white and sets the corresponding
+bitmap bit to 0.
+
+The
+.I 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.
+
+.PP
+.TP 8
+.I Clear All
+turns all the grid squares white and
+sets all bitmap bits to 0. This is irreversible, so invoke it with care.
+
+.PP
+.TP 8
+.I Set All
+turns all the grid squares black and sets all bitmap bits to 1.
+This is also irreversible.
+
+.PP
+.TP 8
+.I Invert All
+inverts all the grid squares and bitmap bits, as if you had pressed
+the middle mouse button over each square.
+
+.PP
+.TP 8
+.I 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
+.I 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.
+
+.PP
+.TP 8
+.I 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
+.I Clear Area
+command.
+
+.PP
+.TP 8
+.I Invert Area
+inverts a rectangular area of
+the grid. It works the same way as the
+.I Clear Area
+command.
+
+.PP
+.TP 8
+.I 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
+.I 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.
+.PP
+.TP 8
+.I Move Area
+works identically to
+.I Copy Area, except
+that it clears the source rectangle after copying to the destination.
+
+.PP
+.TP 8
+.I Line
+will draw a line between two points.
+
+.PP
+.TP 8
+.I Circle
+will draw a circle specifying the center and a radius
+
+.PP
+.TP 8
+.I Filled Circle
+will draw a filled circle given the center and radius of the circle.
+.PP
+.TP 8
+.I 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.
+
+.PP
+.TP 8
+.I Clear Hotspot
+removes any hot spot that was defined on this bitmap.
+
+.PP
+.TP 8
+.I 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
+.B filename~
+(in the manner of \fIemacs(1)\fP 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 \fI/tmp/filename\fP instead. If you say yes,
+all future ``Write Output'' commands will write to \fI/tmp/filename\fP as well.
+See below for the format of the output file.
+
+.PP
+.TP 8
+.I Quit
+exits the
+.I bitmap
+program. If you have edited
+the bitmap and have not invoked
+.I Write Output,
+or you have edited it
+since the last time you invoked
+.I 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.
+
+
+.SH FILE FORMAT
+
+\fIBitmap\fP reads and writes files in the following format,
+which is suitable for #include'ing in a C program:
+.nf
+#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};
+.fi
+
+The variables ending with
+.I _x_hot
+and
+.I _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
+.I bitmap
+with filename
+.I /usr/include/bitmaps/cross.bitmap
+will produce a file with variable
+names
+.I cross_width, cross_height,
+and
+.I cross_bits
+(and
+.I cross_x_hot
+and
+.I 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
+.I this.cursor
+and
+.I this_mask.cursor,
+one simply writes
+.sp
+.nf
+#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);
+.sp
+.fi
+where
+.I foreground
+and
+.I background
+are color values, and
+.I func
+is a display function (normally GXcopy).
+
+An X program can also read a bitmap file at runtime by using the function
+.I XReadBitmapFile.
+
+.SH X DEFAULTS
+.PP
+.PP
+.TP 8
+.B 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.
+.PP
+.TP 8
+.B Border
+The border color. This option is useful only on color displays.
+Default: black.
+.PP
+.TP 8
+.B BorderWidth
+The border width. Default: 3.
+.PP
+.TP 8
+.B BodyFont
+The text font. Default: vtsingle.
+.PP
+.TP 8
+.B 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.
+.PP
+.TP 8
+.B Highlight
+The highlight color.
+.I bitmap
+uses this color to show the hot spot and to indicate rectangular areas
+that will be affected by the
+.I Move Area, Copy Area, Set Area, Clear Area,
+and
+.I Invert Area
+commands. If a highlight color is not given, then
+.I bitmap
+will highlight by inverting. This option is useful only on color displays.
+
+.PP
+.TP 8
+.B Mouse
+The mouse cursor's color. This option is useful only on color displays.
+Default: black.
+
+.SH ENVIRONMENT
+ DISPLAY - the default host and display number.
+
+.SH SEE ALSO
+ X(1), Xlib Documentation.
+
+
+.SH DIAGNOSTICS
+
+The following messages may be displayed in the C-shell that you invoked
+.I bitmap
+with. Any of these conditions aborts
+.I bitmap
+before it can create its window.
+
+
+ ``bitmap: could not connect to X server on \fIhost\fP:\fIdisplay\fP''
+
+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
+.I bitmap
+with no command line arguments. You must give a
+file name as the first argument.
+
+
+ ``bitmap: could not open file \fIfilename\fP for reading -- \fImessage\fP''
+
+The specified file exists but cannot be read, for the reason given in
+<message> (e.g., permission denied).
+
+
+ ``bitmap: invalid dimensions \fIstring\fP''
+ ``bitmap: dimensions must be positive''
+
+The second command line argument was not a valid dimension
+specification.
+
+
+ ``bitmap: file \fIfilename\fP does not have a valid width dimension''
+ ``bitmap: file \fIfilename\fP does not have a valid height dimension''
+ ``bitmap: file \fIfilename\fP has an invalid \fIn\fPth 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 \fIbitmap\fP
+creates its window:
+
+ ``bitmap: Unrecognized variable \fIname\fP in file \fIfilename\fP''
+
+.I bitmap
+encountered a variable ending in something other than
+.I _x_hot, _y_hot, _width,
+or
+.I _height
+while parsing the input file. It will ignore this variable and
+continue parsing the file.
+
+
+ ``bitmap: XError: \fImessage\fP''
+ ``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.
+
+
+.SH BUGS
+ Doesn't take enough command line options yet. Most options can be
+specified only through .\fIXdefaults\fP.
+
+ 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.
+
+ 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.
+
+.SH AUTHOR
+Copyright (c) 1986 by Massachusetts Institute of Technology.
+.br
+ Ron Newman, MIT Project Athena
projects / unix-history / commitdiff