Return to bitmap.0 CVS log

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

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

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.