Return to bitmap.1 CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / new / X / man / man1

Annotation of 43BSDTahoe/new/X/man/man1/bitmap.1, revision 1.1

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.