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