NAME
bitmap, bmtoa, atobm − bitmap editor and conversion utilities.
SYNTAX
bitmap [options] [filename] [basename] bmtoa [options] [filename] atobm [options] [filename]
DESCRIPTION
bitmap allows you to create and edit small bitmaps that you can use as backgrounds, clipping regions, tile and stipple patterns, icons, and pointers. A bitmap is a grid of pixels, or picture elements, each of which is white, black, or, in the case of color displays, a color. See Chapter 7, Graphics Utilities, for instructions on using bitmap.
The bmtoa and atobm filters convert bitmap files to and from ASCII strings. They are most commonly used to print out bitmaps quickly and to generate versions for inclusion in text. Chapter 7 describes how to convert a font character to a bitmap using atobm.
The window that bitmap creates has three sections (see Figure 7-1 in Part One of this guide). The checkerboard grid is a magnified version of the bitmap you are editing. Each square represents a single bit in the picture being edited. Squares on the grid can be set, cleared, or inverted directly with the buttons on the pointer. Command buttons to perform higher-level operations, such as drawing lines and circles, are provided to the left of the grid. You can invoke these command buttons by clicking on them with the first pointer button. Across the top of the window is a menu bar that provides a File menu and an Edit menu.
You can display an actual size representation of the bitmap image (as it would appear both normally and inverted) by pressing the Meta-I key combination. You are free to move the image popup out of the way to continue editing. Clicking the first pointer button in the popup window or typing Meta-I again will remove the actual size bitmap image.
If the bitmap is to be used for defining a cursor, one of the squares in the image may be designated as the hot spot. This determines where the cursor is actually pointing. For cursors with sharp tips (such as arrows or fingers), this is usually at the end of the tip; for symmetric cursors (such as crosses or bullseyes), this is usually at the center.
Bitmaps are stored as small C code fragments suitable for including in applications. They provide an array of bits as well as symbolic constants giving the width, height, and hot spot (if specified) that may be used in creating cursors, icons, and tiles. A selection of commonly-used bitmaps is generally stored in /usr/include/X11/bitmaps on UNIX systems.
You give the size in pixels of the bitmap to be created (and consequently, the number of cells in the bitmap editing area) using the -size option. Existing bitmaps should be edited at their current size. The default size for new bitmaps is 16×16. (This is a little small—an icon such as the mailbox displayed by xbiff is 48×48 pixels.) See Chapter 7 for a discussion of bitmap window and image size issues.
When you run bitmap without a filename or with a new filename, the window will display a blank image area, suitable for you to begin editing. To edit a bitmap image, you can use one of the editing command buttons or use the pointer commands to change individual grid squares. (Chapter 7 describes both ways of editing; also see "Command Buttons for Drawing" and "Changing Grid Squares Using the Pointer" later in this reference page.)
OPTIONS: BITMAP
bitmap accepts all of the standard X Toolkit command-line options, which are listed on the X reference page. In addition, bitmap accepts the following application-specific options:
-axes, +axes
Turns the major axes on or off.
-dashed, +dashed
Turns dashing for the frame and grid lines on or off.
-dashes filename
Specifies the bitmap to be used as a stipple for dashing.
-fr color
Specifies the color used for the frame and grid lines.
-grid, +grid
Turns the grid lines on or off.
-gt pixels
Grid tolerance. If the square dimensions fall below the specified value, grid will be automatically turned off. The default is 8 (pixels square).
-hl color
Specifies the color to be used for highlighting.
-proportional, +proportional
Turns proportional mode on or off. If proportional mode is on, square width is equal to square height. If proportional mode is off, bitmap will use the smaller square dimension, if they were initially different.
-sh pixels
Specifies the height of squares in pixels.
-size WIDTHxHEIGHT
Specifies size of the grid in squares. WIDTHxHEIGHT are two numbers, separated by the letter "x", which specify the dimensions of the checkerboard grid within the bitmap window (e.g., 9×13). The first number is the grid’s width; the second number is its height. The default is 16×16.
-stipple filename
Specifies the bitmap to be used as a stipple for highlighting.
-stippled, +stippled
Turns stippling of highlighted squares on or off.
-sw pixels
Specifies the width of squares in pixels.
The bitmap editor also accepts the following arguments:
basename
Specifies the basename to be used in the C code output file. If it is different than the basename in the working file, bitmap will change the name of the file when saving.
filename
Specifies the bitmap to be initially loaded into the program. If the file does not exist, bitmap will assume it is a new file.
OPTIONS: BMTOA
The bmtoa (bitmap to array) conversion program accepts the following option:
-chars cc
Specifies the pair of characters to use in the string version of the bitmap. The first character is used for 0 bits and the second character is used for 1 bits. The default is to use dashes (−) for 0s and number signs (#) for 1s.
OPTIONS: ATOBM
The atobm (array to bitmap) conversion program accepts the following options:
-chars cc
Specifies the pair of characters to use when converting string bitmaps into arrays of numbers. The first character represents a 0 bit and the second character represents a 1 bit. The default is to use dashes (−) for 0s and number signs (#) for 1s.
-name variable
Specifies the variable name to be used when writing out the bitmap file. The default is to use the basename of the filename command-line argument or leave it blank if the standard input is read.
-xhot number
Specifies the X coordinate of the hot spot. Only positive values are allowed. By default, no hot spot information is included.
-yhot number
Specifies the Y coordinate of the hot spot. Only positive values are allowed. By default, no hot spot information is included.
RESOURCES
For a table of settable resources, see the section "Bitmap Widget Resources" later in this reference page. Appendix G, Athena Widget Resources, describes the resources that can be set for other widgets in the application. (See "Widget Hierarchy" later in this reference page.)
CHANGING GRID SQUARES USING THE POINTER
You can set, clear, or invert grid squares by pointing to them and clicking or dragging using one of the buttons as indicated below. Setting a grid square corresponds to setting a bit in the bitmap image to 1. Clearing a grid square corresponds to setting a bit in the bitmap image to 0. Inverting a grid square corresponds to changing a bit in the bitmap image from 0 to 1 or 1 to 0, depending upon its previous state. You can change multiple squares at once by holding the button down and dragging the cursor across them. The default behavior of pointer buttons is:
Button 1 (usually the left)
Sets one or more grid squares to the foreground color and sets the corresponding bits in the bitmap to 1.
Button 2 (usually the middle)
Inverts one or more grid squares. The corresponding bit or bits in the bitmap are inverted (1s become 0s and 0s become 1s).
Button 3 (usually the right)
Clears one or more grid squares (sets them to the background color) and sets the corresponding bits in the bitmap to 0.
For pointers with additional buttons, the fourth and fifth also clear the grid square(s).
This default behavior can be changed by setting the button function resources: bitmap∗button1Function: Set bitmap∗button2Function: Clear bitmap∗button3Function: Invert Note that the button function applies to all drawing commands, including copying, moving and pasting, flood filling and setting the hot spot.
COMMAND BUTTONS FOR DRAWING
bitmap provides 27 command buttons to assist you in drawing. The buttons are located to the left of the editing grid and their functions are summarized below. See Chapter 7 for more complete instructions. Note that most of the actions can also be performed using keyboard shortcuts (accelerators) while the pointer rests inside the editing grid or the surrounding whitespace.
ClearClears all bits in the bitmap image. Sets all of the grid squares to the background color. Typing c while the pointer rests inside the grid or the surrounding whitespace has the same effect.
SetSets all bits in the bitmap image. Sets all of the grid squares to the foreground color. Typing s has the same effect.
InvertInverts all bits in the bitmap image. The grid squares will be inverted appropriately. Typing i has the same effect.
MarkAllows you to mark an area of the grid by dragging out a rectangular shape in the highlighting color. Once the area is marked, you can perform a number of other operations on it. (See Up, Down, Left, Right, Rotate, Flip, Cut, etc.) 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 pressing the Shift key and the first pointer button simultaneously and then dragging to highlight a rectangle in the grid window. Press Shift and click the second pointer button to mark the entire grid area.
Unmark
Causes the marked area to vanish. You can perform the same action by pressing Shift and clicking the third pointer button.
CopyAllows you to copy an area of the grid from one location to another. If there is no marked grid area displayed, Copy first behaves just like Mark. Once there is a marked grid area displayed in the highlighting color, Copy has two alternative behaviors. If you press a pointer button inside the marked area, you can drag a rectangle representing the marked area to the desired location. When you release the pointer button, the area is copied. If you click outside the marked area, Copy will assume that you wish to mark a different region of the bitmap image and it will behave like Mark again.
MoveAllows you to move an area of the grid from one location to another. Its behavior resembles the behavior of Copy command, except that the marked area will be moved instead of copied.
Flip Horizontally
Flips the bitmap image with respect to the horizontal axes. If a marked area of the grid is highlighted, it will operate only inside the marked area. Pressing h has the same effect.
UpMoves the bitmap image one pixel up. If a marked area of the grid is highlighted, it will operate only inside the marked area. Pressing the up arrow key has the same effect.
Flip Vertically
Flips the bitmap image with respect to the vertical axes. If a marked area of the grid is highlighted, it will operate only inside the marked area. Pressing v has the same effect.
LeftMoves the bitmap image one pixel to the left. If a marked area of the grid is highlighted, it will operate only inside the marked area. Pressing the left arrow key has the same effect.
FoldFolds the bitmap image so that the opposite corners become adjacent. This is useful when creating bitmap images for tiling. Pressing f has the same effect.
RightMoves the bitmap image one pixel to the right. If a marked area of the grid is highlighted, it will operate only inside the marked area. Pressing the right arrow key has the same effect.
Rotate Left
Rotates the bitmap image 90 degrees to the left (counterclockwise.) If a marked area of the grid is highlighted, it will operate only inside the marked area. Pressing l has the same effect.
DownMoves the bitmap image one pixel down. If a marked area of the grid is highlighted, it will operate only inside the marked area. Pressing the down arrow has the same effect.
Rotate Right
Rotates the bitmap image 90 degrees to the right (clockwise). If a marked area of the grid is highlighted, it will operate only inside the marked area. Pressing r has the same effect.
PointChanges the grid squares underneath the pointer according to the guidelines explained in "Changing Grid Squares Using the Pointer." If you press a button and drag the pointer, the line may not be continuous depending on the speed of your system and frequency of pointer motion events.
CurveChanges the grid squares underneath the pointer according to the guidelines explained in "Changing Grid Squares Using the Pointer." The Curve command ensures that when you press a pointer button and drag, the line will be continuous. However,if your system is slow or bitmap receives very few pointer motion events, it might behave erratically.
LineAllows you to draw the straightest possible line between two grid squares. Once you press a pointer button in the grid window, bitmap will highlight the line from the square where the pointer button was initially pressed to the square where the pointer is located. When you release the pointer button, the highlighting will disappear and the actual line will be drawn.
Rectangle
Allows you to draw a rectangle. Once you press a pointer button in the grid window, bitmap will highlight the rectangle from the square where the pointer button was initially pressed to the square where the pointer is located. When you release the pointer button, the highlighting will disappear and the actual rectangle will be drawn.
Filled Rectangle
Performs the same function as Rectangle, except that the rectangle is filled (rather than outlined).
CircleAllows you to draw a circle. When you press a pointer button in the grid, that square becomes the center of the circle. You continue to hold the pointer button down and drag the pointer away from the center point to indicate a point on the circumference. An outline follows the pointer. When you release the pointer button, the highlighting will disappear and the actual circle will be drawn.
Filled Circle
Performs the same function as Circle, except that the circle is filled (rather than outlined).
Flood Fill
Fills any closed shape you click on. If a shape is open, you will "flood" a larger area than you intend. Diagonally adjacent squares are not considered to form a single shape.
Set Hot Spot
Designates one square in the grid as the hot spot if this bitmap image is to be used for defining a cursor. Pressing a pointer button in the desired square causes a diamond shape to be displayed.
Clear Hot Spot
Removes any designated hot spot from the bitmap image.
UndoUndoes the last executed command. You can only recover the last action performed; thus, pressing Undo after Undo will toggle the last action on and off.
FILE MENU
You can access the File menu commands by pressing the File button and selecting the appropriate menu entry or by pressing the Control key with another key. These commands deal with files and global bitmap parameters, such as size, basename, filename, etc. See Chapter 7 for more information.
NewClears the window so you can create a new image; prompts for a name for the new file. If you haven’t saved the current file, the changes will be lost.
LoadDynamically loads another bitmap file into the editing window; if you haven’t saved the current file, prompts you as to whether to save before loading the next file. The bitmap editor can edit only one file at a time. If you need interactive editing, run a number of editors and use cut and paste mechanism as described below.
InsertInserts a bitmap file into the image currently being edited. After being prompted for the filename, click inside the grid window and drag the outlined rectangle to the location where you want to insert the new file.
SaveSaves the bitmap image. It will not prompt for the filename unless it is said to be <none>. If you leave the filename undesignated or −, the output will be piped to standard output.
Save As
Saves the bitmap image after prompting for a new filename. Use this menu item if you want to change the filename.
ResizeChanges the dimensions of the editing grid to match dimensions you supply (widthxheight), without changing the size of the image. Thus, specifying a larger grid gives you more room to edit. Specifying a smaller grid may cause part of the current image to be truncated.
Rescale
Changes the dimensions of the grid to match dimensions you supply (widthxheight) and changes the image so that the proportions (the ratio of the image to the grid) remain the same. Thus, if you specify a grid twice the size of the current one, both the grid and the image will be doubled. Rescale will not do antialiasing and specifying a smaller grid may cause part of the current image to be truncated. Feel free to add your own algorithms for better rescaling.
Filename
Lets you change the filename of the current file without changing the basename or saving the file. If you specify − for a filename, the output will be piped to standard output.
Basename
Lets you change the basename of the current file if you want one different from the filename.
QuitTerminates the bitmap application. If changes have been made and not saved, a dialog box will ask whether to save before quitting. This command is preferable to killing the process.
EDIT MENU
The Edit menu commands can be accessed by pressing the Edit button and selecting the appropriate menu entry, or by pressing Meta key with another key. These commands deal with editing facilities such as the grid, axes, zooming, cut and paste, etc.
ImageDisplays a window showing what the bitmap being edited looks like at its actual size (both as it appears and in reverse video). You can move the window away to continue editing. Clicking the first pointer button on this window pops it down.
GridControls the grid in the editing area. If the grid spacing is below the value specified by the gridTolerance resource (8 by default), the grid will be automatically turned off. You can turn the grid on by selecting this menu item.
Dashed
Controls the stipple for drawing the grid lines. Select this menu item to toggle the stipple (specified by the dashes resource or the -dashes option).
AxesToggles diagonal axes. The axes simply assist in drawing; they are not part of the image. Off by default.
Stippled
Toggles a stipple pattern to be used for highlighting within the editing area. The stipple specified by the stipple resource can be turned on or off by activating this command.
Proportional
Toggles proportional mode which forces proportional grid squares, regardless of the dimensions of the bitmap window. On by default.
ZoomToggles zoom mode, which focuses in on a marked area of the image. (You can mark before or after selecting Zoom.) You can use all the editing commands and other utilities in the zoom mode. When you zoom out, Undo will undo the whole zoom session.
CutCuts the contents of any marked area into the internal (application local) cut and paste buffer. The marked area is deleted from the current image, but is available to be pasted from the buffer. (If this was the last area marked, it is also available to be pasted into other applications via a global buffer.)
CopyCopies the contents of any marked area into the internal (application local) cut and paste buffer. The marked area remains a part of the current image and is also available to be pasted from the buffer. (If this was the last area marked, it is also available to be pasted into other applications via a global buffer.)
PastePastes the contents of the global buffer (the marked area in any bitmap or xmag application); if the global buffer is empty, this item pastes a copy of the contents of the internal cut and paste buffer. To place the copied image, press and hold the first pointer button in the editing area, drag the outlined image to the position you want, and then release the button.
CUT AND PASTE
bitmap supports two cut and paste mechanisms: an internal cut and paste buffer and the global X selection cut and paste buffer. The internal cut and paste is used when executing Copy and Move drawing commands and also Cut and Copy commands from the Edit menu. The global X selection cut and paste is used whenever there is a highlighted area of a bitmap image displayed anywhere on the screen. To copy a part of image from another bitmap editor, simply highlight the desired area by using the Mark command or pressing the Shift key and dragging the area with the first pointer button. When the selected area becomes highlighted, any other applications (such as xterm, etc.) that use the PRIMARY selection will discard their selection values and unhighlight the appropriate information. Now, use the Paste command from the Edit menu or press Control and any pointer button to copy the selected part of image into another (or the same) bitmap application. If you attempt to do this without a visible highlighted image area, the bitmap will fall back to the internal cut and paste buffer and paste whatever is stored there at the moment.
WIDGET HIERARCHY
Below is the widget structure of the bitmap application. Indentation indicates hierarchical structure. The widget class name is given first, followed by the widget instance name. All widgets except the bitmap widget are from the standard Athena widget set. See Appendix G, Athena Widget Resources, for a list of resources that can be set. Bitmap bitmap TransientShell image Box box Label normalImage Label invertedImage TransientShell input Dialog dialog Command okay Command cancel TransientShell error Dialog dialog Command abort Command retry TransientShell qsave Dialog dialog Command yes Command no Command cancel 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 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 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
Bitmap Widget Resources
The Bitmap widget is a stand-alone widget for editing raster images. It is not designed to edit large images, although it may be used in that purpose as well. It can be freely incorporated with other applications and used as a standard editing tool.
Header fileBitmap.h
ClassbitmapWidgetClass
Class NameBitmap
SuperclassBitmap
The following are the resources provided by the Bitmap widget. All the Simple widget resources plus:
| Name | Class | Type | Default Value | ||||
| foreground | Foreground | Pixel | XtDefaultForeground | ||||
| highlight | Highlight | Pixel | XtDefaultForeground | ||||
| framing | Framing | Pixel | XtDefaultForeground | ||||
| gridTolerance | GridTolerance | Dimension | 8 | ||||
| size | Size | String | 32×32 | ||||
| dashed | Dashed | Boolean | True | ||||
| dashes | Dashes | Bitmap | unspecified | ||||
| grid | Grid | Boolean | True | ||||
| stipple | Stipple | Bitmap | unspecified | ||||
| 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 | ||||
Color
If you would like bitmap to be viewable in color, include the following in the #ifdef COLOR section of the file you read with xrdb: ∗customization: -color This line will cause bitmap to pick up the colors in the app-defaults color customization file, /usr/lib/X11/app-defaults/Bitmap-color. See Chapter 11, Setting Resources, for more information.
FILES
/usr/lib/X11/app-defaults/Bitmap
Specifies required resources.
/usr/lib/X11/app-defaults/Bitmap-color
Color customization file.
/usr/include/X11/bitmaps
On many systems, standard bitmaps can be found in this directory.
BUGS
bitmap should really be implemented with a scrollable editing area, so that the size of the application can be completely independent of the size of the bitmap being edited.
If you move the pointer too fast while holding a pointer button down, some squares may be missed. This is caused by limitations in how frequently the X server can sample the pointer location.
SEE ALSO
xmag; Chapter 7, Graphics Utilities.
AUTHOR
Release 5 bitmap by Davor Matic, MIT X Consortium; Previous releases of bitmap by Ron Newman, MIT Project Athena; bmtoa and atobm by Jim Fulton, MIT X Consortium.