.TH bitmap "" "" "X Utility"
.PC "Bit map editor"
\fBbitmap [\fI\-options\^\fB] [\fIfilename\^\fB] [\fIbasename\^\fB]\fR
.PP
.HS
.SH Options:
.IC \fB\-axes\fR
Turn the major axes off.
.IC \fB+axes\fR
Turn the major axes on.
.IC \fIbasename\fR
Specify the base name to use in the output file of C code
.IC \fB\-dashed\fR
Turn off dashing for the frame and grid lines
.IC \fB+dashed\fR
Turn on dashing for the frame and grid lines
.IC "\fB\-dashes\fI filename\fR"
Specify the bit map to be used as a stipple for dashing
.IC \fIfilename\fR
Specify the bit map to be initially loaded into the program
.IC "\fB\-fr\fI color\fR"
Specify the color used for the frame and grid lines
.IC "\fB\-grid\fR"
Turn the grid off
.IC "\fB+grid\fR"
Turn the grid on
.IC "\fB\-gt \fIdimension\fR"
Grid tolerance:
if the square dimensions fall below the specified value,
\fBbitmap\fR
automatically turns the grid off
.IC "\fB\-hl\fI color\fR"
Specify the color used for highlighting
.IC \fB\-proportional\fR
Turn off proportional mode
.IC \fB+proportional\fR
Turn on proportional mode
.IC "\fB\-sh \fIdimension\fR"
Specify the height of squares in pixels
.IC "\fB\-size \fIwidth\(muheight\fR"
Specify size of the grid in squares
.IC "\fB\-stipple\fI filename\fR"
Specify the bit map to be used as a stipple for highlighting
.IC \fB\-stippled\fR
Turn off stippling of highlighted squares
.IC \fB+stippled \fR
Turn on stippling of highlighted squares
.IC "\fB\-sw \fIdimension\fR"
Specify the width of squares in pixels
.HE
.II "image, bit-mapped^edit"
.II "bit-mapped image"
.II "edit bit-mapped image"
.B bitmap
is a rudimentary tool for creating or editing
rectangular images made up of 1's and 0's.
X uses bit-maps to define clipping regions,
cursor shapes, icon shapes, and tile and stipple patterns.
.SH "Using bitmap"
.B bitmap
displays a grid, each square of which represents one
pixel in the picture being edited.
To see the bit-mapped image in its actual size, as it appears both
normally and inverted, press
.BR <ctrl-I> .
You can drag the popped-up image out of the way to continue editing.
To remove the bit-mapped image,
either move the mouse cursor into the pop-up window and press
the left mouse button, or press
.B <ctrl-I>
again.
.PP
If you wish to use the bit-mapped image to define a mouse cursor,
you can designate one of the squares in the image as the ``hot spot'' \(em
that is, the point in the cursor that determines exactly where the cursor
is pointing.
For cursors with sharp points (e.g., an arrow or finger),
the hot spot is usually at the tip;
for symmetric cursors (such as a cross or bull's-eye), it usually is
at the center.
.PP
.B bitmap
stores a bit-map as a fragment of C code that is suitable for loading in
applications.
The C code gives an array of bits as well as symbolic
constants that give the width, height, and hot spot (if specified) that
can be used to create cursors, icons, and tiles.
For examples of the output of
.BR bitmap ,
see the Lexicon entry for
.BR bmtoa .
.SH Editing
To edit a bit-mapped image, simply click on one of the buttons with drawing
commands and move the mouse cursor into the bit-map grid window.
When you press one of the buttons on your mouse,
.B bitmap
performs the appropriate action.
You can set, clear, or invert a grid square.
Setting a square corresponds to setting a bit in the bit-mapped image to one;
clearing a square corresponds to setting a bit to zero.
Inverting a grid square corresponds to changing a bit from zero to
one or one to zero.
The following gives the default behavior of the mouse buttons:
.DS
.ta 0.5i 3.5i
	MouseButton1 (left mouse button):	Set
	MouseButton2 (center mouse button):	Invert
	MouseButton3 (right mouse button):	Clear
.DE
.PP
This default behavior can be changed by setting the mouse buttons' function
resources.
The following example inverts the default behavior of the center and right
mouse buttons:
.DM
	bitmap*button1Function: Set
	bitmap*button2Function: Clear
	bitmap*button3Function: Invert
.DE
.PP
The button function applies to all drawing commands, including copying,
moving, and pasting, flood filling, and setting the hot spot.
.SH "Drawing Commands"
The following lists the buttons on the left side of
.BR bitmap 's
window.
Each accessing a drawing command.
You can abort some commands by pressing `A' inside the bit-map window:
.IP \fK(Circle)\fR 0.75i
Change the grid squares in a circle between two squares.
Once you press a mouse button in the grid window,
.B bitmap
highlights the circle from the square where the mouse button was initially
pressed to the square where the mouse cursor is located.
Releasing the mouse button causes the change to take effect, and the
highlighted circle disappears.
.IP \fK(Clear)\fR
Clear all bits in the bit-mapped image.
The grid squares are set to the background color.
Pressing `C' inside the window has the same effect.
.IP "\fK(Clear_Hot_Spot)\fR"
Remove any designated hot spot from the bit-mapped image.
.IP \fK(Copy)\fR
Copy an area of the grid from one location to another.
If no marked grid area is displayed,
This command behaves like
.BR Mark ,
described below.
.IP
Once a marked grid area is displayed in the highlighting color,
this command has two alternative behaviors.
If you click a mouse button inside the marked
area, you can drag the rectangle that represents the
marked area to the desired location.
After you release the mouse button, the area is copied.
If you click outside the marked area,
.B Copy
assumes that you wish to mark a different region of
the bit-map image; thus, it again behaves like
.BR Mark .
.IP \fK(Curve)\fR
Change the grid squares underneath the mouse cursor if
a mouse button is being pressed down.
If you drag the mouse continuously,
.B bitmap
ensures that the line is continuous.
If your system is slow or
.B bitmap
receives very few mouse motion events, it might behave quite strangely.
.IP \fK(Down)\fR
Moves the bit-map image one pixel down.
If a marked area of the grid is highlighted, it operates only
within the marked area.
Pressing \*(DA inside the window has the same effect.
.IP "\fK(Filled_Circle)\fR"
This command is identical to
.BR Circle ,
except that the circle is filled rather than outlined.
.IP "\fK(Filled_Rectangle)\fR"
Identical to
.BR Rectangle ,
except at the end the rectangle is filled rather than outlined.
.IP "\fK(Flip_Horizontally)\fR"
Flip the bit-map image along the horizontal axis.
If a marked area of the grid is highlighted,
this command operates only within the marked area.
Pressing `F' inside the window has the same effect.
.IP "\fK(Flip_Vertically)\fR"
Flip the bit-mapped image along the vertical axis.
If a marked area of the grid is highlighted, this command operates
only within the marked area.
Pressing `V' inside the window has the same effect.
.IP "\fK(Flood_Fill)\fR"
Flood-fill the connected area beneath the mouse
cursor when you click on the desired square.
Diagonally adjacent squares are not considered to be connected.
.IP \fK(Fold)\fR
Fold the bit-mapped image so that the opposite corners become adjacent.
This is useful when creating bit-mapped images for tiling.
Pressing `F' inside the window has the same effect.
.IP \fK(Invert)\fR
Invert all bits in the bit-mapped image.
The grid squares are inverted appropriately.
Pressing `I' inside the window has the same effect.
.IP \fK(Left)\fR
Moves the bit-mapped image one pixel to the left.
If a marked area of the grid is highlighted, it operates only
within the marked area.
Pressing \*(LA inside the window has the same effect.
.IP \fK(Line)\fR
Change the grid squares in a line between two squares.
When you press a mouse button in the grid window,
.B bitmap
highlights the line from the square where the mouse button was initially
pressed to the square where the mouse cursor is located.
Releasing the mouse button causes the change to take effect,
and the highlighted line disappears.
.IP \fK(Mark)\fR
Mark an area of the grid by dragging out a rectangular shape
in the highlighting color.
Once the area is marked, it can be operated on by commands
.BR Up ,
.BR Down ,
.BR Left ,
.BR Right ,
.BR Rotate ,
.BR Flip ,
or
.BR Cut .
Only one marked area can be present at any time.
If you attempt to mark another area, the old mark will vanish.
The same effect can be achieved by simultaneously pressing
.B <shift>
and the left mouse button,
and dragging out a rectangle in the grid window.
Simultaneously pressing
.B <shift>
and the middle mouse button marks the entire grid area.
.IP \fK(Move)\fR
Move an area of the grid from one location to another.
Its behavior resembles the behavior of the command
.BR Copy ,
except that the marked area is moved instead of copied.
.IP \fK(Point)\fR
Change the grid squares underneath the mouse cursor if
a mouse button is being pressed down.
If you drag the mouse continuously, the line may not be continuous,
depending on the speed of your system and frequency of mouse-motion events.
.IP \fK(Rectangle)\fR
Change the grid squares in a rectangle between two squares.
When you press a mouse button in the grid window,
.B bitmap
highlights the rectangle from the square where the mouse button was initially
pressed to the square where the mouse cursor is located.
Releasing the mouse button causes the change to take effect,
and the highlighted rectangle disappears.
.IP \fK(Right)\fR
Moves the bit-mapped image one pixel to the right.
If a marked area of the grid is highlighted, it will operate only
within the marked area.
Pressing \*(RA inside the window has the same effect.
.IP "\fK(Rotate_Left)\fR"
Rotate the bit-map image 90\(de to the left (counter-clockwise).
If a marked area of the grid is highlighted, it will operate only
within the marked area.
Pressing `L' inside the window has the same effect.
.IP "\fK(Rotate_Right)\fR"
Rotate the bit-mapped image 90\(de to the right (clockwise).
If a marked area of the grid is highlighted, it operates only 
within the marked area.
Pressing `R' inside the window has the same effect.
.IP \fK(Set)\fR
Set all bits in the bit-mapped image.
The grid squares are set to the foreground color.
Pressing `S' inside the window has the same effect.
.IP "\fK(Set_Hot_Spot)\fR"
Designate one square in the grid as the hot spot.
Pressing a mouse button in the desired square displays a diamond shape.
.IP \fK(Undo)\fR
Undo the last executed command.
It has depth one \(em that is, pressing
.B Undo
after
.B Undo
will undo itself.
.IP \fK(Unmark)\fR
Erase the marked area.
The same effect can be achieved by simultaneously pressing
.B <shift>
and the right mouse button.
.IP \fK(Up)\fR
Move up the bit-mapped image by one pixel.
If a marked area of the grid is highlighted, this command operates only
within the marked area.
Pressing \*(UA inside the window has the
same effect.
.SH "File Menu"
To access the File Menu's commands, click the
.K File
button and select the appropriate menu entry, or press
.B <ctrl>
key with another key.
These commands deal with files, and with global parameters of the bit map
(e.g., size, basename, and file name):
.IP \fK(Basename)\fR 0.75i
Change the base name, if you want one other than the specified file name.
.IP \fK(Filename)\fR
Change the file name without changing the base name
or saving the file.
If you specify `\-' for a file name,
.B bitmap
writes its output to the standard output.
.IP \fK(Insert)\fR
Insert a bit-map image into the image being currently edited.
After
.B bitmap
has prompted you for the name of the file that holds the bit-mapped image
to insert,
click inside the grid window and drag the outlined rectangle to the
point where you wish to insert the newly loaded image.
.IP \fK(Load)\fR
Load a new bit-mapped image into the editor.
If you have not yet saved the current image,
.B bitmap
asked you whether to save the changes.
The editor can edit only one file at a time.
If you need interactive editing, run a number of editors and
use the cut-and-paste mechanism, as described below.
.IP \fK(New)\fR
Clear the editing area and prompt for the name of the new file to edit.
It will not load in the new file.
.IP \fK(Quit)\fR
Terminate
.BR bitmap .
If the file was not saved,
.B bitmap
prompts you to ask whether to save the image.
This command is preferred over killing the process.
.IP \fK(Rescale)\fR
Rescale the editing area to the new width and height.
Enter the size in the format
\fIwidth\(muheight\fR.
This commands does not do antialiasing,
and information is lost if you rescale to the smaller sizes.
.IP \fK(Resize)\fR
Resize the editing area to the new number of pixels.
Enter the size in the format \fIwidth\(muheight\fR.
The information in the image being edited will not be lost unless the new
size is smaller that the current image size.
NB, the editor was not designed to edit huge files.
.IP \fK(Save)\fR
Save the bit-map image.
It does not prompt for the file name unless it is said to be
.BR <none> .
If you leave the file name undesignated or `\-',
.B bitmap
writes the image to the standard output.
.IP "\fK(Save_As)\fR"
Save the bit-mapped image after prompting for a new file name.
It should be used if you want to change the file name.
.SH "Edit Menu"
To access the Edit Menu's commands,
press the
.K Edit
button and select the appropriate menu entry, or press
.B <esc>
with another key.
These commands deal with editing facilities, such as
grid, axes, zooming, and cut and paste:
.IP \fK(Axes)\fR 0.75i
Highlight the main axes of the image being edited.
These lines are not part of the image, but are
provided to help you keep your images symmetrical.
.IP \fK(Copy)\fR
Copy the contents of the highlighted image area into the
internal cut-and-paste buffer. 
.IP \fK(Cut)\fR
Cut the highlighted image area into the internal cut-and-paste buffer.  
.IP \fK(Dashed)\fR
Control the stipple for drawing the grid lines.
The stipple specified by the resource
.B dashes
can be turned on or off by activating this  command.
.IP \fK(Grid)\fR
Control the grid in the editing area.
.II gridTolerance
If the grid spacing is less than that specified by the resource
.B gridTolerance
(default, eight),
.B bitmap
automatically turn the grid off.
.IP \fK(Image)\fR
Open a separate window and
display therein the image being edited and its inverse in their actual size.
You can move the new window.
To erase the new window, move the mouse cursor into it
and press the left mouse button.
.IP \fK(Paste)\fR
Copy into the current image either
the highlighted area from another image or the contents of 
.BR bitmap 's
internal cut-and-paste buffer.
To place the copied image,
click in the editing window, drag the outlined image to the position
where you want to place it, then release the button.
.IP \fK(Proportional)\fR
Toggle proportional mode.
If proportional mode is on,
.B bitmap
forces all squares to have the same width and height,
regardless of the proportions of the bit-map window.
.IP \fK(Stippled)\fR
Toggle stippling of the highlighted areas of the bit-mapped image.
The stipple is specified by resource
.BR stipple .
.IP \fK(Zoom)\fR
Toggle zoom mode.
If an area of the image is highlighted,
.B bitmap
automatically zooms into it.
Otherwise,
.B bitmap
lets you highlight an area to be edited in the zoom mode;
.B bitmap
then automatically switches into it.
You can use all the editing commands and other utilities in the zoom mode.
When you zoom out, the command
.B undo
undoes the entire zoom session.
.SH "Cut and Paste"
.B bitmap
supports two cut-and-paste mechanisms:
the internal cut-and-paste, and the global X selection cut-and-paste.
.PP
.B bitmap
uses the internal cut-and-paste feature
when it executes the drawing commands
.B copy
and
.BR move ,
and when it executes the commands
.B cut
and
.B copy
on its
.B Edit
menu.
It uses the global X selection cut-and-paste
whenever any area of a bit-mapped image is highlighted.
.PP
To copy part of an image from another bit-map editor,
simply use the command
.B Mark
to highlight the desired area, or pressing the
.B <shift>
key and drag the area with the left mouse button.
When X highlights the selected area, any other application (such as
.BR xterm )
that use the primary selection
will discard its selection values and unhighlight the appropriate information.
To drop the cut portion of an image into the image you are now editing, use the
.B Paste
command from the
.B Edit
menu, or press the mouse's control button.
.PP
If you attempt to do this without a visible
highlighted image area,
.B bitmap
reads its internal cut-and-paste buffer
and pastes whatever is stored there at the moment.
.SH Widgets
Below is the widget structure of the
.B bitmap
application.
Indentation indicates hierarchical structure.
The widget class name is given first, followed by the widget instance name.
All widgets except the
.B bitmap
widget are from the standard Athena widget set.  
.DM
	Bitmap bitmap
		TransientShell image
			Box box
				Label normalImage
				Label invertedImage
.DE
.DM
		TransientShell input
			Dialog dialog
				Command okay
				Command cancel
.DE
.DM
		TransientShell error
			Dialog dialog
				Command abort
				Command retry
.DE
.DM
		TransientShell qsave
			Dialog dialog
				Command yes
				Command no
				Command cancel
.DE
.DM
		Paned parent
			Form formy
				MenuButton fileButton
				SimpleMenu fileMenu
					SmeBSB  new
					SmeBSB  load
					SmeBSB  insert
					SmeBSB  save
					SmeBSB  saveAs
					SmeBSB  resize
					SmeBSB  rescale
					SmeBSB  filename
					SmeBSB  basename
					SmeLine line
					SmeBSB  quit
.DE
.DM
				MenuButton editButton
				SimpleMenu editMenu
					SmeBSB  image
					SmeBSB  grid
					SmeBSB  dashed
					SmeBSB  axes
					SmeBSB  stippled
					SmeBSB  proportional
					SmeBSB  zoom
					SmeLine line
					SmeBSB  cut
					SmeBSB  copy
					SmeBSB  paste
				Label status
.DE
.DM
			Pane pane
				Bitmap bitmap
				Form form
					Command clear
					Command set
					Command invert
					Toggle  mark
					Command unmark
					Toggle  copy
					Toggle  move
					Command flipHoriz
					Command up
					Command flipVert
					Command left
					Command fold
					Command right
					Command rotateLeft
					Command down
					Command rotateRight
					Toggle  point
					Toggle  curve
					Toggle  line
					Toggle  rectangle
					Toggle  filledRectangle
					Toggle  circle
					Toggle  filledCircle
					Toggle  floodFill
					Toggle  setHotSpot
					Command clearHotSpot
					Command undo
.DE
.SH Colors
If you want
.B bitmap
to be viewable in color, include the following in the
.B "#ifdef COLOR"
section of the file you read with
.BR xrdb :
.DM
	*customization: \-color
.DE
.PP
This tells
.B bitmap
to pick up the colors in the color-customization file
.BR /usr/X11/lib/app-defaults/Bitmap-color .
.SH "Command-line Options"
.B bitmap
recognizes the following command-line arguments:
.IP \fB\-axes\fR 0.75i
Turn the major axes off.
.IP \fB+axes\fR
Turn the major axes on.
.IP \fIbasename\fR
Specify the base name to use in the output file of C code.
If it differs from the base name in the working file,
.B bitmap
changes it when saving the file.
.IP "\fB\-dashed \fB[\fIfilename\^\fB]\fR"
Turn off dashing for the frame and grid lines.
.I filename
names the bit-map to use as a stipple.
.IP \fB+dashed\fR
Turn on dashing for the frame and grid lines.
.IP \fIfilename\fR
Name the bit-map to be initially loaded into the program.
If
.I filename
does not exist,
.B bitmap
assumes it is a new file.
.IP "\fB\-fr\fI color\fR"
Use
.I color
for the frame and grid lines.
For a list of colors that X recognizes, see file
.BR /usr/X11/lib/rgb.txt .
.IP "\fB\-grid\fR"
Turn the grid off.
.IP "\fB+grid\fR"
Turn the grid on.
.IP "\fB\-gt \fIdimension\fR"
Set grid tolerance.
If the square dimensions fall below
.IR dimension ,
.B bitmap
automatically turns the grid off.
.IP "\fB\-hl\fI color\fR"
Use
.I color
for highlighting.
.IP \fB\-proportional\fR
Turn off proportional mode.
If proportional mode is on, square width equals square height.
If proportional mode is off and the square's dimensions differ,
.B bitmap
uses the smaller dimension.
.IP \fB+proportional\fR
Turn on proportional mode.
.IP "\fB\-sh \fIpixels\fR"
Set the height of squares, in
.IR pixels .
.IP "\fB\-size \fIwidth\(muheight\fR"
Set the size of the grid in squares.
.IP "\fB\-stipple\fI filename\fR"
Set the bit-map to be used as a stipple for highlighting.
.IP \fB\-stippled\fR
Turn off stippling of highlighted squares.
.IP \fB+stippled\fR
Turn on stippling of highlighted squares.
.IP "\fB\-sw \fIpixels\fR"
Set the width of squares, in
.IR pixels .
.SH "Bitmap Widget"
.II "widget^bitmap"
The widget
.B bitmap
is a stand-alone widget for editing raster images.
It is not designed to edit large images, although you can use it for that
purpose as well.
You can incorporate it with other
applications and use it as a standard editing tool.
The following are the resources provided by the widget
.BR bitmap :
.DM
.ta 0.5i 2.0i
	Bitmap Widget
.sp \n(pDu
	Header file Bitmap.h
	Class	bitmapWidgetClass
	Class Name	Bitmap
	Superclass	Bitmap
.DE
.PP
This widget uses all of the simple-widget resources, plus the following:
.sp \n(pDu
.nf
.ft L
.ta 1.6i 3.2i 4.8i
\fIName	Class	Type	Default Value\fP
foreground	Foreground	Pixel	XtDefaultForeground
highlight	Highlight	Pixel	XtDefaultForeground
framing	Framing	Pixel	XtDefaultForeground
gridTolerance	GridTolerance	Dimension	8
size	Size	String	32x32
dashed	Dashed	Boolean	True
grid	Grid	Boolean	True
stippled	Stippled	Boolean	True
proportional	Proportional	Boolean	True
axes	Axes	Boolean	False
squareWidth	SquareWidth	Dimension	16
squareHeight	SquareHeight	Dimension	16
margin	Margin	Dimension	16
xHot	XHot	Position	NotSet (\-1)
yHot	YHot	Position	NotSet (\-1)
button1Function	Button1Function	DrawingFunction	Set
button2Function	Button2Function	DrawingFunction	Invert
button3Function	Button3Function	DrawingFunction	Clear
button4Function	Button4Function	DrawingFunction	Invert
button5Function	Button5Function	DrawingFunction	Invert
filename	Filename	String	None ("")
basename	Basename	String	None ("")
.SH "See Also"
.B
atobm,
bmtoa,
editres,
X utilities
.R
.SH Notes
The default screen for
.B bitmap
is extremely large.
With its default resource file, it may not entirely fit onto a 640\(mu480
screen.
.PP
.II "Matic, Davor"
.B bitmap
was written by Davor Matic of the X Consortium.
