Return to bitmap.1 CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / X / man

Annotation of 43BSD/contrib/X/man/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: 
        !           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.