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