![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to bitmap.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDTahoe / new / X / man / man1|
Return to bitmap.1 CVS log | Up to [CSRG BSD Unix] / 43BSDTahoe / new / X / man / man1 |
1.1 root 1: .TH BITMAP 1 "29 January 1986" "X Version 10"
2: .SH NAME
3: bitmap \- bitmap editor for X window system
4:
5: .SH SYNOPSIS
6: .B bitmap
7: filename [\fIdimensions\fP] [\fIhost\fP:\fIdisplay\fP] [=\fIgeometry\fP]
8:
9: .SH DESCRIPTION
10:
11: .I bitmap
12: lets you interactively create small bitmaps, or edit previously created
13: bitmaps. A bitmap is a small picture, represented as a rectangular
14: array of 0 and 1 bits. The X window system uses bitmaps to represent
15: cursors and icons, among other things.
16:
17: When you run
18: .I bitmap,
19: you are given a magnified version of the bitmap, with each
20: pixel blown up into a large square, like a piece of graph paper. You
21: can then use the mouse to set, clear, or invert individual pixels, and
22: can invoke commands to set, clear or invert larger rectangular areas of
23: the bitmap. Other commands allow you to move or copy rectangular areas
24: from one part of the bitmap to another, and to define a `hot spot'--a
25: special single point on the bitmap, which is useful when the bitmap is
26: used as an X cursor.
27:
28: The output of the
29: .I bitmap
30: program is a small program fragment. By #include'ing such a program
31: fragment in your C program, you can easily declare the size and contents
32: of cursors, icons, and other bitmaps that your program creates to deal
33: with the X window system.
34:
35: When
36: .I bitmap
37: starts, it first tries to read the specified file
38: (see FILE FORMAT). If the file already exists, it
39: creates a window containing a grid of the
40: appropriate dimensions.
41:
42: If the file does not exist,
43: .I bitmap
44: will create a window for a
45: bitmap of the size specified by
46: .I dimensions
47: , which should be two
48: numbers separated by the letter `x' (e.g. 7x9, 13x21). The first number
49: is the bitmap's width; the second is its height. The bitmap will start
50: out empty. If no dimensions are specified on the command line, a
51: 16x16 bitmap will be created. The absolute limit is 99x99; the practical
52: limit is somewhat lower, and depends on the size and resolution of your
53: display.
54:
55: .I bitmap
56: accepts two other optional command line arguments. You may specify a
57: display name in the form \fIhost\fP:\fIdisplay\fP (see \fIX(1)\fP).
58: And you may provide
59: a geometry specification. If you don't give a geometry specification,
60: .I bitmap
61: will ask you where you want to put the window when it starts up. See
62: .I X(1)
63: for a full explanation.
64:
65: The window that
66: .I bitmap
67: creates has four parts. The largest
68: section is the checkerboard grid, which is a magnified version of the
69: bitmap you are editing. At the upper left is a set of commands that you
70: can invoke with any mouse button. Below the commands is an "actual size"
71: picture of the bitmap you are editing; below that is an inverted
72: version of the same bitmap. Each time you change the grid, the same
73: change will occur in the actual-size bitmap and its inverse.
74:
75: If you use a window manager to make the
76: .I bitmap
77: window larger or smaller, the grid squares will automatically
78: get larger or smaller as well.
79:
80: .SH COMMANDS
81:
82: (Note for users of color displays: In all of the following,
83: ``white'' means the background color, and ``black'' means the
84: foreground color. You may specify a foreground and background
85: color in your \fI.Xdefaults\fP file; see the X DEFAULTS section below.)
86:
87: When the cursor is in the checkerboard region, each mouse button has
88: a different effect upon the single square that the cursor is over.
89:
90: The
91: .I left mouse button
92: turns a grid square black and sets the corresponding
93: bitmap bit to 1.
94:
95: The
96: .I right mouse button
97: turns a grid square white and sets the corresponding
98: bitmap bit to 0.
99:
100: The
101: .I middle mouse button
102: inverts a grid square, turning it white if it was
103: black, or black if it was white. It also inverts the corresponding bitmap
104: bit, setting it to 0 if it was 1, and to 1 if it was 0.
105:
106: You can also invoke more sophisticated commands by moving the mouse over
107: one of the command boxes at the upper right corner, and pressing any
108: mouse button.
109:
110: .PP
111: .TP 8
112: .I Clear All
113: turns all the grid squares white and
114: sets all bitmap bits to 0. This is irreversible, so invoke it with care.
115:
116: .PP
117: .TP 8
118: .I Set All
119: turns all the grid squares black and sets all bitmap bits to 1.
120: This is also irreversible.
121:
122: .PP
123: .TP 8
124: .I Invert All
125: inverts all the grid squares and bitmap bits, as if you had pressed
126: the middle mouse button over each square.
127:
128: .PP
129: .TP 8
130: .I Clear Area
131: clears a rectangular area of the grid, turning it white and setting the
132: corresponding bitmap bits to 0. After you click over this command, the
133: cursor turns into an `upper-left corner'. Press any mouse button over the
134: upper-left corner of the area you want to invert, and
135: .I hold the button down
136: while moving the mouse to the lower-right corner of the area you
137: want to invert, then let the button up.
138:
139: While you are holding down the button, the selected area will be
140: covered with X's, and the cursor will change to a `lower-right corner'.
141: If you now wish to abort the command without clearing an area, either press
142: another mouse button, move the cursor outside the grid, or move the
143: cursor to the left of or above the upper-left corner.
144:
145: .PP
146: .TP 8
147: .I Set Area
148: turns a rectangular area of the grid black and sets the corresponding
149: bitmap bits to 1. It works the same way as the
150: .I Clear Area
151: command.
152:
153: .PP
154: .TP 8
155: .I Invert Area
156: inverts a rectangular area of
157: the grid. It works the same way as the
158: .I Clear Area
159: command.
160:
161: .PP
162: .TP 8
163: .I Copy Area
164: copies a rectangular area from
165: one part of the grid to another. First, you select the rectangle to be
166: copied, in the manner described under
167: .I Clear Area
168: above. Then, the
169: cursor will change to an "upper-left corner". When you press a mouse
170: button, a destination rectangle will overlay the grid; moving the mouse
171: while holding down the button will move this destination rectangle. The
172: copy will occur when you let up the button. To cancel the copy, move
173: the mouse outside the grid and then let up the button.
174: .PP
175: .TP 8
176: .I Move Area
177: works identically to
178: .I Copy Area, except
179: that it clears the source rectangle after copying to the destination.
180:
181: .PP
182: .TP 8
183: .I Line
184: will draw a line between two points.
185:
186: .PP
187: .TP 8
188: .I Circle
189: will draw a circle specifying the center and a radius
190:
191: .PP
192: .TP 8
193: .I Filled Circle
194: will draw a filled circle given the center and radius of the circle.
195: .PP
196: .TP 8
197: .I Set Hotspot
198: designates a point on the bitmap as the "hot spot". If a program
199: is using your bitmap as a cursor, the hot spot indicates which point on
200: the bitmap is the "actual" location of the cursor. For instance, if
201: your cursor is an arrow, the hot spot should be the tip of the arrow; if
202: your cursor is a cross, the hot spot should be where the perpendicular
203: lines intersect.
204:
205: .PP
206: .TP 8
207: .I Clear Hotspot
208: removes any hot spot that was defined on this bitmap.
209:
210: .PP
211: .TP 8
212: .I Write Output
213: writes the current bitmap value to the
214: file specified in the original command line. If the file already
215: exists, the original file is first renamed to
216: .B filename~
217: (in the manner of \fIemacs(1)\fP and other text editors).
218:
219: If either the renaming or the writing cause an error (e.g.
220: ``Permission denied'), a Macintosh-style dialog window will appear, asking
221: if you want to write the file \fI/tmp/filename\fP instead. If you say yes,
222: all future ``Write Output'' commands will write to \fI/tmp/filename\fP as well.
223: See below for the format of the output file.
224:
225: .PP
226: .TP 8
227: .I Quit
228: exits the
229: .I bitmap
230: program. If you have edited
231: the bitmap and have not invoked
232: .I Write Output,
233: or you have edited it
234: since the last time you invoked
235: .I Write Output,
236: a Macintosh-style dialog
237: window will appear, asking if you want to save changes before quitting.
238: ``Yes'' does a ``Write Output'' before exiting; ``No'' just exits, losing
239: the edits; ``Cancel'' means you decided not to quit after all.
240:
241:
242: .SH FILE FORMAT
243:
244: \fIBitmap\fP reads and writes files in the following format,
245: which is suitable for #include'ing in a C program:
246: .nf
247: #define foo_width 9
248: #define foo_height 13
249: #define foo_x_hot 4
250: #define foo_y_hot 6
251: static short foo_bits[] = {
252: 0x0010, 0x0038, 0x007c, 0x0010,
253: 0x0010, 0x0010, 0x01ff, 0x0010,
254: 0x0010, 0x0010, 0x007c, 0x0038,
255: 0x0010};
256: .fi
257:
258: The variables ending with
259: .I _x_hot
260: and
261: .I _y_hot
262: are optional; they will be present only if a hot spot has been
263: defined for this bitmap. The other variables must be present.
264:
265: In place of ``foo'', the five variables will be prefixed
266: with a string derived from the name of the file that you specified
267: on the original command line by
268: (1) deleting the directory path (all characters up to and including
269: the last `/', if one is present)
270: (2) deleting the extension (the first `.', if one is present,
271: and all characters beyond it)
272:
273: For example, invoking
274: .I bitmap
275: with filename
276: .I /usr/include/bitmaps/cross.bitmap
277: will produce a file with variable
278: names
279: .I cross_width, cross_height,
280: and
281: .I cross_bits
282: (and
283: .I cross_x_hot
284: and
285: .I cross_y_hot
286: if a hot spot is defined).
287:
288: It's easy to define a bitmap or cursor in an X program by simply #include'ing
289: a bitmap file and referring to its variables. For instance, to use a cursor
290: defined in the files
291: .I this.cursor
292: and
293: .I this_mask.cursor,
294: one simply writes
295: .sp
296: .nf
297: #include "this.cursor"
298: #include "this_mask.cursor"
299: XCreateCursor (this_width, this_height, this_bits, this_mask_bits,
300: this_x_hot, this_y_hot, foreground, background, func);
301: .sp
302: .fi
303: where
304: .I foreground
305: and
306: .I background
307: are color values, and
308: .I func
309: is a display function (normally GXcopy).
310:
311: An X program can also read a bitmap file at runtime by using the function
312: .I XReadBitmapFile.
313:
314: .SH X DEFAULTS
315: .PP
316: .PP
317: .TP 8
318: .B Background
319: The window's background color. Bits which are 0 in the bitmap are
320: displayed in this color. This option is useful only on color
321: displays. Default: white.
322: .PP
323: .TP 8
324: .B Border
325: The border color. This option is useful only on color displays.
326: Default: black.
327: .PP
328: .TP 8
329: .B BorderWidth
330: The border width. Default: 3.
331: .PP
332: .TP 8
333: .B BodyFont
334: The text font. Default: vtsingle.
335: .PP
336: .TP 8
337: .B Foreground
338: The foreground color. Bits which are 1 in the bitmap are
339: displayed in this color. This option is useful only on color
340: displays. Default: black.
341: .PP
342: .TP 8
343: .B Highlight
344: The highlight color.
345: .I bitmap
346: uses this color to show the hot spot and to indicate rectangular areas
347: that will be affected by the
348: .I Move Area, Copy Area, Set Area, Clear Area,
349: and
350: .I Invert Area
351: commands. If a highlight color is not given, then
352: .I bitmap
353: will highlight by inverting. This option is useful only on color displays.
354:
355: .PP
356: .TP 8
357: .B Mouse
358: The mouse cursor's color. This option is useful only on color displays.
359: Default: black.
360:
361: .SH ENVIRONMENT
362: DISPLAY - the default host and display number.
363:
364: .SH SEE ALSO
365: X(1), Xlib Documentation.
366:
367:
368: .SH DIAGNOSTICS
369:
370: The following messages may be displayed in the C-shell that you invoked
371: .I bitmap
372: with. Any of these conditions aborts
373: .I bitmap
374: before it can create its window.
375:
376:
377: ``bitmap: could not connect to X server on \fIhost\fP:\fIdisplay\fP''
378:
379: Either the display given on the command line or the DISPLAY
380: environment variable has an invalid host name or display number, or
381: the host is down, or the host is unreachable, or the host is not
382: running an X server, or the host is refusing connections.
383:
384: ``bitmap: no file name specified''
385:
386: You invoked
387: .I bitmap
388: with no command line arguments. You must give a
389: file name as the first argument.
390:
391:
392: ``bitmap: could not open file \fIfilename\fP for reading -- \fImessage\fP''
393:
394: The specified file exists but cannot be read, for the reason given in
395: <message> (e.g., permission denied).
396:
397:
398: ``bitmap: invalid dimensions \fIstring\fP''
399: ``bitmap: dimensions must be positive''
400:
401: The second command line argument was not a valid dimension
402: specification.
403:
404:
405: ``bitmap: file \fIfilename\fP does not have a valid width dimension''
406: ``bitmap: file \fIfilename\fP does not have a valid height dimension''
407: ``bitmap: file \fIfilename\fP has an invalid \fIn\fPth array element''
408:
409: The input file is not in the correct format; the program gave up when
410: trying to read the specified data.
411:
412:
413: The following messages may be displayed in the C-shell after \fIbitmap\fP
414: creates its window:
415:
416: ``bitmap: Unrecognized variable \fIname\fP in file \fIfilename\fP''
417:
418: .I bitmap
419: encountered a variable ending in something other than
420: .I _x_hot, _y_hot, _width,
421: or
422: .I _height
423: while parsing the input file. It will ignore this variable and
424: continue parsing the file.
425:
426:
427: ``bitmap: XError: \fImessage\fP''
428: ``bitmap: XIOError''
429:
430: A protocol error occurred. Something is wrong with either the X server
431: or the X library which the program was compiled with. Possibly they are
432: incompatible. If the server is not on the local host, maybe the
433: connection broke.
434:
435:
436: .SH BUGS
437: Doesn't take enough command line options yet. Most options can be
438: specified only through .\fIXdefaults\fP.
439:
440: If you move the mouse too fast while holding a mouse button down,
441: some squares may be `missed'. This is caused by limitations in how
442: frequently the X server can sample the mouse location.
443:
444: There is no way to write to a file other than that specified on the
445: command line.
446:
447: There is no way to change the size of the bitmap once the program
448: is started.
449:
450: Edits are unrecoverably lost if you terminate the program with a ^C
451: or ^\ in the shell which invoked it, or if you kill it with the shell's
452: ``kill'' command.
453:
454: Dimensions greater than 99 are not read properly from the command
455: line or input file. Generally such dimensions would not be useful anyway,
456: since they would produce a window larger than most displays.
457:
458: .SH AUTHOR
459: Copyright (c) 1986 by Massachusetts Institute of Technology.
460: .br
461: Ron Newman, MIT Project Athena
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.