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