![[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] / 43BSD / contrib / X / man|
Return to bitmap.1 CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / X / man |
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:
175: .PP
176: .TP 8
177: .I Move Area
178: works identically to
179: .I Copy Area, except
180: that it clears the source rectangle after copying to the destination.
181:
182: .PP
183: .TP 8
184: .I Set Hotspot
185: designates a point on the bitmap as the "hot spot". If a program
186: is using your bitmap as a cursor, the hot spot indicates which point on
187: the bitmap is the "actual" location of the cursor. For instance, if
188: your cursor is an arrow, the hot spot should be the tip of the arrow; if
189: your cursor is a cross, the hot spot should be where the perpendicular
190: lines intersect.
191:
192: .PP
193: .TP 8
194: .I Clear Hotspot
195: removes any hot spot that was defined on this bitmap.
196:
197: .PP
198: .TP 8
199: .I Write Output
200: writes the current bitmap value to the
201: file specified in the original command line. If the file already
202: exists, the original file is first renamed to
203: .B filename~
204: (in the manner of \fIemacs(1)\fP and other text editors).
205:
206: If either the renaming or the writing cause an error (e.g.
207: ``Permission denied'), a Macintosh-style dialog window will appear, asking
208: if you want to write the file \fI/tmp/filename\fP instead. If you say yes,
209: all future ``Write Output'' commands will write to \fI/tmp/filename\fP as well.
210: See below for the format of the output file.
211:
212: .PP
213: .TP 8
214: .I Quit
215: exits the
216: .I bitmap
217: program. If you have edited
218: the bitmap and have not invoked
219: .I Write Output,
220: or you have edited it
221: since the last time you invoked
222: .I Write Output,
223: a Macintosh-style dialog
224: window will appear, asking if you want to save changes before quitting.
225: ``Yes'' does a ``Write Output'' before exiting; ``No'' just exits, losing
226: the edits; ``Cancel'' means you decided not to quit after all.
227:
228:
229: .SH FILE FORMAT
230:
231: \fIBitmap\fP reads and writes files in the following format,
232: which is suitable for #include'ing in a C program:
233: .nf
234: #define foo_width 9
235: #define foo_height 13
236: #define foo_x_hot 4
237: #define foo_y_hot 6
238: static short foo_bits[] = {
239: 0x0010, 0x0038, 0x007c, 0x0010,
240: 0x0010, 0x0010, 0x01ff, 0x0010,
241: 0x0010, 0x0010, 0x007c, 0x0038,
242: 0x0010};
243: .fi
244:
245: The variables ending with
246: .I _x_hot
247: and
248: .I _y_hot
249: are optional; they will be present only if a hot spot has been
250: defined for this bitmap. The other variables must be present.
251:
252: In place of ``foo'', the five variables will be prefixed
253: with a string derived from the name of the file that you specified
254: on the original command line by
255: (1) deleting the directory path (all characters up to and including
256: the last `/', if one is present)
257: (2) deleting the extension (the first `.', if one is present,
258: and all characters beyond it)
259:
260: For example, invoking
261: .I bitmap
262: with filename
263: .I /usr/include/bitmaps/cross.bitmap
264: will produce a file with variable
265: names
266: .I cross_width, cross_height,
267: and
268: .I cross_bits
269: (and
270: .I cross_x_hot
271: and
272: .I cross_y_hot
273: if a hot spot is defined).
274:
275: It's easy to define a bitmap or cursor in an X program by simply #include'ing
276: a bitmap file and referring to its variables. For instance, to use a cursor
277: defined in the files
278: .I this.cursor
279: and
280: .I this_mask.cursor,
281: one simply writes
282: .sp
283: .nf
284: #include "this.cursor"
285: #include "this_mask.cursor"
286: XCreateCursor (this_width, this_height, this_bits, this_mask_bits,
287: this_x_hot, this_y_hot, foreground, background, func);
288: .sp
289: .fi
290: where
291: .I foreground
292: and
293: .I background
294: are color values, and
295: .I func
296: is a display function (normally GXcopy).
297:
298: An X program can also read a bitmap file at runtime by using the function
299: .I XReadBitmapFile.
300:
301: .SH X DEFAULTS
302: .PP
303: .PP
304: .TP 8
305: .B Background
306: The window's background color. Bits which are 0 in the bitmap are
307: displayed in this color. This option is useful only on color
308: displays. Default: white.
309: .PP
310: .TP 8
311: .B Border
312: The border color. This option is useful only on color displays.
313: Default: black.
314: .PP
315: .TP 8
316: .B BorderWidth
317: The border width. Default: 3.
318: .PP
319: .TP 8
320: .B BodyFont
321: The text font. Default: vtsingle.
322: .PP
323: .TP 8
324: .B Foreground
325: The foreground color. Bits which are 1 in the bitmap are
326: displayed in this color. This option is useful only on color
327: displays. Default: black.
328: .PP
329: .TP 8
330: .B Highlight
331: The highlight color.
332: .I bitmap
333: uses this color to show the hot spot and to indicate rectangular areas
334: that will be affected by the
335: .I Move Area, Copy Area, Set Area, Clear Area,
336: and
337: .I Invert Area
338: commands. If a highlight color is not given, then
339: .I bitmap
340: will highlight by inverting. This option is useful only on color displays.
341:
342: .PP
343: .TP 8
344: .B Mouse
345: The mouse cursor's color. This option is useful only on color displays.
346: Default: black.
347:
348: .SH ENVIRONMENT
349: DISPLAY - the default host and display number.
350:
351: .SH SEE ALSO
352: X(1), Xlib Documentation.
353:
354:
355: .SH DIAGNOSTICS
356:
357: The following messages may be displayed in the C-shell that you invoked
358: .I bitmap
359: with. Any of these conditions aborts
360: .I bitmap
361: before it can create its window.
362:
363:
364: ``bitmap: could not connect to X server on \fIhost\fP:\fIdisplay\fP''
365:
366: Either the display given on the command line or the DISPLAY
367: environment variable has an invalid host name or display number, or
368: the host is down, or the host is unreachable, or the host is not
369: running an X server, or the host is refusing connections.
370:
371: ``bitmap: no file name specified''
372:
373: You invoked
374: .I bitmap
375: with no command line arguments. You must give a
376: file name as the first argument.
377:
378:
379: ``bitmap: could not open file \fIfilename\fP for reading -- \fImessage\fP''
380:
381: The specified file exists but cannot be read, for the reason given in
382: <message> (e.g., permission denied).
383:
384:
385: ``bitmap: invalid dimensions \fIstring\fP''
386: ``bitmap: dimensions must be positive''
387:
388: The second command line argument was not a valid dimension
389: specification.
390:
391:
392: ``bitmap: file \fIfilename\fP does not have a valid width dimension''
393: ``bitmap: file \fIfilename\fP does not have a valid height dimension''
394: ``bitmap: file \fIfilename\fP has an invalid \fIn\fPth array element''
395:
396: The input file is not in the correct format; the program gave up when
397: trying to read the specified data.
398:
399:
400: The following messages may be displayed in the C-shell after \fIbitmap\fP
401: creates its window:
402:
403: ``bitmap: Unrecognized variable \fIname\fP in file \fIfilename\fP''
404:
405: .I bitmap
406: encountered a variable ending in something other than
407: .I _x_hot, _y_hot, _width,
408: or
409: .I _height
410: while parsing the input file. It will ignore this variable and
411: continue parsing the file.
412:
413:
414: ``bitmap: XError: \fImessage\fP''
415: ``bitmap: XIOError''
416:
417: A protocol error occurred. Something is wrong with either the X server
418: or the X library which the program was compiled with. Possibly they are
419: incompatible. If the server is not on the local host, maybe the
420: connection broke.
421:
422:
423: .SH BUGS
424: Doesn't take enough command line options yet. Most options can be
425: specified only through .\fIXdefaults\fP.
426:
427: If you move the mouse too fast while holding a mouse button down,
428: some squares may be `missed'. This is caused by limitations in how
429: frequently the X server can sample the mouse location.
430:
431: There is no way to write to a file other than that specified on the
432: command line.
433:
434: There is no way to change the size of the bitmap once the program
435: is started.
436:
437: Edits are unrecoverably lost if you terminate the program with a ^C
438: or ^\ in the shell which invoked it, or if you kill it with the shell's
439: ``kill'' command.
440:
441: Dimensions greater than 99 are not read properly from the command
442: line or input file. Generally such dimensions would not be useful anyway,
443: since they would produce a window larger than most displays.
444:
445: .SH AUTHOR
446: Copyright (c) 1986 by Massachusetts Institute of Technology.
447: .br
448: Ron Newman, MIT Project Athena
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.