Return to bitmap.man CVS log

Up to [Research Unix] / researchv9 / X11 / src / X.V11R1 / clients / bitmap

Annotation of researchv9/X11/src/X.V11R1/clients/bitmap/bitmap.man, revision 1.1

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.