1BITMAP(1)                   General Commands Manual                  BITMAP(1)
2
3
4

NAME

6       bitmap,  bmtoa, atobm - bitmap editor and converter utilities for the X
7       Window System
8

SYNOPSIS

10       bitmap [ -options ... ] [ filename ] [ basename ]
11
12       bmtoa [ -chars ... ] [ filename ]
13
14       atobm [ -chars cc ] [ -name variable ] [ -xhot number ] [ -yhot  number
15       ] [ filename ]
16

DESCRIPTION

18       The  bitmap  program is a rudimentary tool for creating or editing rec‐
19       tangular images made up of 1's and 0's.  Bitmaps  are  used  in  X  for
20       defining  clipping  regions,  cursor  shapes, icon shapes, and tile and
21       stipple patterns.
22
23       The bmtoa and atobm filters convert bitmap files (FILE FORMAT)  to  and
24       from  ASCII  strings.  They are most commonly used to quickly print out
25       bitmaps and to generate versions for including in text.
26

COMMAND LINE OPTIONS

28       Bitmap supports the standard X  Toolkit  command  line  arguments  (see
29       X(7)).  The following additional arguments are supported as well.
30
31       -size WIDTHxHEIGHT
32           Specifies size of the grid in squares.
33
34       -sw dimension
35           Specifies the width of squares in pixels.
36
37       -sh dimension
38           Specifies the height of squares in pixels.
39
40       -gt dimension
41           Grid  tolerance.  If the square dimensions fall below the specified
42           value, grid will be automatically turned off.
43
44       -grid, +grid
45           Turns on or off the grid lines.
46
47       -axes, +axes
48           Turns on or off the major axes.
49
50       -dashed, +dashed
51           Turns on or off dashing for the frame and grid lines.
52
53       -stippled, +stippled
54           Turns on or off stippling of highlighted squares.
55
56       -proportional, +proportional
57           Turns proportional mode on or off.  If  proportional  mode  is  on,
58           square  width  is  equal to square height.  If proportional mode is
59           off, bitmap will use the smaller square  dimension,  if  they  were
60           initially different.
61
62       -dashes filename
63           Specifies the bitmap to be used as a stipple for dashing.
64
65       -stipple filename
66           Specifies the bitmap to be used as a stipple for highlighting.
67
68       -hl color
69           Specifies the color used for highlighting.
70
71       -fr color
72           Specifies the color used for the frame and grid lines.
73
74       filename
75           Specifies  the  bitmap to be initially loaded into the program.  If
76           the file does not exist, bitmap will assume it is a new file.
77
78       basename
79           Specifies the basename to be used in the C code output file.  If it
80           is  different  than  the  basename in the working file, bitmap will
81           change it when saving the file.
82
83       Bmtoa accepts the following option:
84
85       -chars cc
86           This option specifies the pair of characters to use in  the  string
87           version  of the bitmap.  The first character is used for 0 bits and
88           the second character is used for 1 bits.  The  default  is  to  use
89           dashes (-) for 0's and sharp signs (#) for 1's.
90
91       Atobm accepts the following options:
92
93       -chars cc
94           This option specifies the pair of characters to use when converting
95           string bitmaps into arrays of numbers.  The first character  repre‐
96           sents  a  0  bit  and the second character represents a 1 bit.  The
97           default is to use dashes (-) for 0's and sharp signs (#) for 1's.
98
99       -name variable
100           This option specifies the variable name to be used when writing out
101           the  bitmap  file.  The default is to use the basename of the file‐
102           name command line argument or leave it blank if the standard  input
103           is read.
104
105       -xhot number
106           This  option specifies the X coordinate of the hotspot.  Only posi‐
107           tive values are allowed.  By default,  no  hotspot  information  is
108           included.
109
110       -yhot number
111           This  option specifies the Y coordinate of the hotspot.  Only posi‐
112           tive values are allowed.  By default,  no  hotspot  information  is
113           included.
114

USAGE

116       Bitmap  displays  grid  in which each square represents a single bit in
117       the picture being edited.  Actual size of the bitmap image, as it would
118       appear  normally  and inverted, can be obtained by pressing Meta-I key.
119       You are free to move the image popup out of the way to  continue  edit‐
120       ing.   Pressing  the  left  mouse  button in the popup window or Meta-I
121       again will remove the real size bitmap image.
122
123       If the bitmap is to be used for defining a cursor, one of  the  squares
124       in the images may be designated as the hot spot.  This determines where
125       the cursor is actually pointing.  For cursors with sharp tips (such  as
126       arrows  or fingers), this is usually at the end of the tip; for symmet‐
127       ric cursors (such as crosses or bullseyes), this is usually at the cen‐
128       ter.
129
130       Bitmaps  are stored as small C code fragments suitable for including in
131       applications.  They provide an array of bits as well as  symbolic  con‐
132       stants  giving  the width, height, and hot spot (if specified) that may
133       be used in creating cursors, icons, and tiles.
134

EDITING

136       To edit a bitmap image simply click on one of the buttons with  drawing
137       commands  (Point,  Curve,  Line,  Rectangle, etc.) and move the pointer
138       into the bitmap grid window.  Press one of the buttons  on  your  mouse
139       and  the appropriate action will take place.  You can either set, clear
140       or invert the gird squares.  Setting a grid square corresponds to  set‐
141       ting  a  bit  in  the bitmap image to 1.  Clearing a grid square corre‐
142       sponds to setting a bit in the bitmap image to  0.   Inverting  a  grid
143       square corresponds to changing a bit in the bitmap image from 0 to 1 or
144       1 to 0, depending what its previous state was.  The default behavior of
145       mouse buttons is as specified below.
146
147                 MouseButton1        Set
148                 MouseButton2        Invert
149                 MouseButton3        Clear
150                 MouseButton4        Clear
151                 MouseButton5        Clear
152
153       This  default  behavior  can  be changed by setting the button function
154       resources.  An example is provided below.
155
156                 bitmap*button1Function: Set
157                 bitmap*button2Function: Clear
158                 bitmap*button3Function: Invert
159                 etc.
160
161       The button function applies to all drawing commands, including copying,
162       moving and pasting, flood filling and setting the hot spot.
163

DRAWING COMMANDS

165       Here  is the list of drawing commands accessible through the buttons at
166       the left side of  the  application's  window.   Some  commands  can  be
167       aborted  by  pressing  A inside the bitmap window, allowing the user to
168       select different guiding points where applicable.
169
170       Clear
171           This command clears all bits in the bitmap image.  The grid squares
172           will  be set to the background color.  Pressing C inside the bitmap
173           window has the same effect.
174
175       Set This command sets all bits in the bitmap image.  The  grid  squares
176           will  be set to the foreground color.  Pressing S inside the bitmap
177           window has the same effect.
178
179       Invert
180           This command inverts all  bits  in  the  bitmap  image.   The  grid
181           squares will be inverted appropriately.  Pressing I inside the bit‐
182           map window has the same effect.
183
184       Mark
185           This command is used to mark an area of the grid by dragging out  a
186           rectangular  shape  in  the  highlighting  color.  Once the area is
187           marked, it can be operated on by a  number  of  commands  (see  Up,
188           Down,  Left,  Right, Rotate, Flip, Cut, etc.)  Only one marked area
189           can be present at any time.  If you attempt to mark  another  area,
190           the  old  mark  will  vanish.   The  same effect can be achieved by
191           pressing Shift-MouseButton1 and dragging out  a  rectangle  in  the
192           grid window.  Pressing Shift-MouseButton2 will mark the entire grid
193           area.
194
195       Unmark
196           This command will cause the marked area to vanish.  The same effect
197           can be achieved by pressing Shift-MouseButton3.
198
199       Copy
200           This  command is used to copy an area of the grid from one location
201           to another.  If there  is  no  marked  grid  area  displayed,  Copy
202           behaves  just  like  Mark  described above.  Once there is a marked
203           grid area displayed in the highlighting color, this command has two
204           alternative  behaviors.   If  you  click  a mouse button inside the
205           marked area, you will be able to drag the rectangle that represents
206           the  marked  area  to  the desired location.  After you release the
207           mouse button, the area will be copied.  If you  click  outside  the
208           marked  area,  Copy  will  assume that you wish to mark a different
209           region of the bitmap image, thus it will behave like Mark again.
210
211       Move
212           This command is used to move an area of the grid from one  location
213           to  another.   Its behavior resembles the behavior of Copy command,
214           except that the marked area will be moved instead of copied.
215
216       Flip Horizontally
217           This command will flip the bitmap image with respect to  the  hori‐
218           zontal  axes.  If a marked area of the grid is highlighted, it will
219           operate only inside the marked area.  Pressing H inside the  bitmap
220           window has the same effect.
221
222       Up  This command moves the bitmap image one pixel up.  If a marked area
223           of the grid is highlighted, it will operate only inside the  marked
224           area.   Pressing  UpArrow  inside  the  bitmap  window has the same
225           effect.
226
227       Flip Vertically
228           This command will flip the bitmap image with respect to the  verti‐
229           cal  axes.   If  a  marked area of the grid is highlighted, it will
230           operate only inside the marked area.  Pressing V inside the  bitmap
231           window has the same effect.
232
233       Left
234           This  command  moves  the bitmap image one pixel to the left.  If a
235           marked area of the grid is highlighted, it will operate only inside
236           the  marked  area.  Pressing LeftArrow inside the bitmap window has
237           the same effect.
238
239       Fold
240           This command will fold the bitmap image so that the  opposite  cor‐
241           ners  become  adjacent.  This is useful when creating bitmap images
242           for tiling.  Pressing F inside  the  bitmap  window  has  the  same
243           effect.
244
245       Right
246           This  command  moves the bitmap image one pixel to the right.  If a
247           marked area of the grid is highlighted, it will operate only inside
248           the  marked area.  Pressing RightArrow inside the bitmap window has
249           the same effect.
250
251       Rotate Left
252           This command rotates the  bitmap  image  90  degrees  to  the  left
253           (counter  clockwise.)  If a marked area of the grid is highlighted,
254           it will operate only inside the marked area.  Pressing L inside the
255           bitmap window has the same effect.
256
257       Down
258           This  command  moves  the bitmap image one pixel down.  If a marked
259           area of the grid is highlighted, it will operate  only  inside  the
260           marked  area.   Pressing DownArrow inside the bitmap window has the
261           same effect.
262
263       Rotate Right
264           This command rotates the bitmap  image  90  degrees  to  the  right
265           (clockwise.)   If a marked area of the grid is highlighted, it will
266           operate only inside the marked area.  Pressing R inside the  bitmap
267           window has the same effect.
268
269       Point
270           This  command  will  change  the  grid squares underneath the mouse
271           pointer if a mouse button is being pressed down.  If you  drag  the
272           mouse  button continuously, the line may not be continuous, depend‐
273           ing on the speed of your  system  and  frequency  of  mouse  motion
274           events.
275
276       Curve
277           This  command  will  change  the  grid squares underneath the mouse
278           pointer if a mouse button is being pressed down.  If you  drag  the
279           mouse  button continuously, it will make sure that the line is con‐
280           tinuous.  If your system is slow or bitmap receives very few  mouse
281           motion events, it might behave quite strangely.
282
283       Line
284           This  command  will  change  the gird squares in a line between two
285           squares.  Once you press a mouse button in the grid window,  bitmap
286           will  highlight the line from the square where the mouse button was
287           initially pressed to the square where the mouse pointer is located.
288           By  releasing  the  mouse  button you will cause the change to take
289           effect, and the highlighted line will disappear.
290
291       Rectangle
292           This command will change the gird squares in  a  rectangle  between
293           two  squares.   Once  you  press a mouse button in the grid window,
294           bitmap will highlight the rectangle from the square where the mouse
295           button  was initially pressed to the square where the mouse pointer
296           is located.  By releasing the  mouse  button  you  will  cause  the
297           change  to  take  effect, and the highlighted rectangle will disap‐
298           pear.
299
300       Filled Rectangle
301           This command is identical to Rectangle, except at the end the  rec‐
302           tangle will be filled rather than outlined.
303
304       Circle
305           This  command  will change the gird squares in a circle between two
306           squares.  Once you press a mouse button in the grid window,  bitmap
307           will  highlight  the  circle from the square where the mouse button
308           was initially pressed to the square  where  the  mouse  pointer  is
309           located.   By  releasing the mouse button you will cause the change
310           to take effect, and the highlighted circle will disappear.
311
312       Filled Circle
313           This command is identical to Circle, except at the end  the  circle
314           will be filled rather than outlined.
315
316       Flood Fill
317           This  command  will  flood  fill  the connected area underneath the
318           mouse pointer when you click on  the  desired  square.   Diagonally
319           adjacent squares are not considered to be connected.
320
321       Set Hot Spot
322           This  command  designates one square in the grid as the hot spot if
323           this bitmap image is to be used for defining a cursor.  Pressing  a
324           mouse button in the desired square will cause a diamond shape to be
325           displayed.
326
327       Clear Hot Spot
328           This command removes any designated hot spot from the bitmap image.
329
330       Undo
331           This command will undo the last executed  command.   It  has  depth
332           one, that is, pressing Undo after Undo will undo itself.
333

FILE MENU

335       The  File menu commands can be accessed by pressing the File button and
336       selecting the appropriate menu entry, or  by  pressing  Ctrl  key  with
337       another  key.  These commands deal with files and global bitmap parame‐
338       ters, such as size, basename, filename etc.
339
340       New This command will clear the editing area and prompt for the name of
341           the new file to be edited.  It will not load in the new file.
342
343       Load
344           This command is used to load a new bitmap file into the bitmap edi‐
345           tor.  If the current image has not been saved, user will  be  asked
346           whether  to  save  or ignore the changes.  The editor can edit only
347           one file at a time.  If you need interactive editing, run a  number
348           of editors and use cut and paste mechanism as described below.
349
350       Insert
351           This  command  is used to insert a bitmap file into the image being
352           currently edited.  After being prompted  for  the  filename,  click
353           inside the grid window and drag the outlined rectangle to the loca‐
354           tion where you want to insert the new file.
355
356       Save
357           This command will save the bitmap image.  It will  not  prompt  for
358           the  filename  unless  it  is  said to be <none>.  If you leave the
359           filename undesignated or -, the output will be piped to stdout.
360
361       Save As
362           This command will save the bitmap image after prompting for  a  new
363           filename.  It should be used if you want to change the filename.
364
365       Resize
366           This  command  is used to resize the editing area to the new number
367           of pixels.  The size should be entered in the WIDTHxHEIGHT  format.
368           The  information  in the image being edited will not be lost unless
369           the new size is smaller that the current image  size.   The  editor
370           was not designed to edit huge files.
371
372       Rescale
373           This  command  is used to rescale the editing area to the new width
374           and height.  The size should be entered in the WIDTHxHEIGHT format.
375           It  will  not  do  antialiasing and information will be lost if you
376           rescale to the smaller sizes.  Feel free to add you own  algorithms
377           for better rescaling.
378
379       Filename
380           This  command  is  used to change the filename without changing the
381           basename nor saving the file.  If you specify - for a filename, the
382           output will be piped to stdout.
383
384       Basename
385           This  command  is  used  to change the basename, if a different one
386           from the specified filename is desired.
387
388       Quit
389           This command will terminate the bitmap application.   If  the  file
390           was  not saved, user will be prompted and asked whether to save the
391           image or not.  This command is preferred over killing the process.
392

EDIT MENU

394       The Edit menu commands can be accessed by pressing the Edit button  and
395       selecting  the  appropriate  menu  entry,  or by pressing Meta key with
396       another key.  These commands deal with editing facilities such as grid,
397       axes, zooming, cut and paste, etc.
398
399       Image
400           This command will display the image being edited and its inverse in
401           its actual size in a separate window.  The window can be moved away
402           to  continue  with  editing.  Pressing the left mouse button in the
403           image window will cause it to disappear from the screen.
404
405       Grid
406           This command controls the grid in the editing area.   If  the  grid
407           spacing  is  below the value specified by gridTolerance resource (8
408           by default), the grid will be automatically turned off.  It can  be
409           enforced by explicitly activating this command.
410
411       Dashed
412           This  command controls the stipple for drawing the grid lines.  The
413           stipple specified by dashes resource can be turned  on  or  off  by
414           activating this command.
415
416       Axes
417           This  command  controls  the  highlighting  of the main axes of the
418           image being edited.  The actual lines are not part  of  the  image.
419           They are provided to aid user when constructing symmetrical images,
420           or whenever having the main axes highlighted helps your editing.
421
422       Stippled
423           This command controls the stippling of the highlighted areas of the
424           bitmap  image.   The  stipple  specified by stipple resource can be
425           turned on or off by activating this command.
426
427       Proportional
428           This command controls the proportional mode.  If  the  proportional
429           mode  is on, width and height of all image squares are forced to be
430           equal, regardless of the proportions of the bitmap window.
431
432       Zoom
433           This command controls the zoom mode.  If there is a marked area  of
434           the  image  already  displayed, bitmap will automatically zoom into
435           it.  Otherwise, user will have to highlight an area to be edited in
436           the  zoom  mode  and bitmap will automatically switch into it.  One
437           can use all the editing commands and other utilities  in  the  zoom
438           mode.   When  you  zoom  out, undo command will undo the whole zoom
439           session.
440
441       Cut This commands cuts the contents of the highlighted image area  into
442           the internal cut and paste buffer.
443
444       Copy
445           This command copies the contents of the highlighted image area into
446           the internal cut and paste buffer.
447
448       Paste
449           This command will check if there are any other bitmap  applications
450           with  a  highlighted  image  area,  or if there is something in the
451           internal cut and paste buffer and copy it to the image.   To  place
452           the copied image, click in the editing window and drag the outlined
453           image to the position where you want to place i, and  then  release
454           the button.
455

CUT AND PASTE

457       Bitmap  supports  two  cut  and  paste mechanisms; the internal cut and
458       paste and the global X selection cut and paste.  The internal  cut  and
459       paste  is  used  when executing copy and move drawing commands and also
460       cut and copy commands from the edit menu.  The global X  selection  cut
461       and  paste  is  used  whenever  there is a highlighted area of a bitmap
462       image displayed anywhere on the screen.  To copy a part of  image  from
463       another  bitmap  editor  simply highlight the desired area by using the
464       Mark command or pressing the shift key and dragging the area  with  the
465       left  mouse  button.   When  the selected area becomes highlighted, any
466       other applications (such as xterm, etc.)  that  use  primary  selection
467       will  discard  their  selection  values and unhighlight the appropriate
468       information.  Now, use the Paste command for the Edit menu  or  control
469       mouse  button  to  copy the selected part of image into another (or the
470       same) bitmap application.  If you attempt to do this without a  visible
471       highlighted  image  area, the bitmap will fall back to the internal cut
472       and paste buffer and paste whatever was there stored at the moment.
473

WIDGETS

475       Below is the widget structure of the bitmap  application.   Indentation
476       indicates  hierarchical  structure.   The  widget  class  name is given
477       first, followed by the widget instance name.  All  widgets  except  the
478       bitmap widget are from the standard Athena widget set.
479
480            Bitmap bitmap
481                 TransientShell image
482                      Box box
483                           Label normalImage
484                           Label invertedImage
485                 TransientShell input
486                      Dialog dialog
487                           Command okay
488                           Command cancel
489                 TransientShell error
490                      Dialog dialog
491                           Command abort
492                           Command retry
493                 TransientShell qsave
494                      Dialog dialog
495                           Command yes
496                           Command no
497                           Command cancel
498                 Paned parent
499                      Form formy
500                           MenuButton fileButton
501                           SimpleMenu fileMenu
502                                SmeBSB  new
503                                SmeBSB  load
504                                SmeBSB  insert
505                                SmeBSB  save
506                                SmeBSB  saveAs
507                                SmeBSB  resize
508                                SmeBSB  rescale
509                                SmeBSB  filename
510                                SmeBSB  basename
511                                SmeLine line
512                                SmeBSB  quit
513                           MenuButton editButton
514                           SimpleMenu editMenu
515                                SmeBSB  image
516                                SmeBSB  grid
517                                SmeBSB  dashed
518                                SmeBSB  axes
519                                SmeBSB  stippled
520                                SmeBSB  proportional
521                                SmeBSB  zoom
522                                SmeLine line
523                                SmeBSB  cut
524                                SmeBSB  copy
525                                SmeBSB  paste
526                           Label status
527                      Pane pane
528                           Bitmap bitmap
529                           Form form
530                                Command clear
531                                Command set
532                                Command invert
533                                Toggle  mark
534                                Command unmark
535                                Toggle  copy
536                                Toggle  move
537                                Command flipHoriz
538                                Command up
539                                Command flipVert
540                                Command left
541                                Command fold
542                                Command right
543                                Command rotateLeft
544                                Command down
545                                Command rotateRight
546                                Toggle  point
547                                Toggle  curve
548                                Toggle  line
549                                Toggle  rectangle
550                                Toggle  filledRectangle
551                                Toggle  circle
552                                Toggle  filledCircle
553                                Toggle  floodFill
554                                Toggle  setHotSpot
555                                Command clearHotSpot
556                                Command undo
557

COLORS

559       If you would like bitmap to be viewable in color, include the following
560       in the #ifdef COLOR section of the file you read with xrdb:
561
562       *customization:                 -color
563
564       This will cause bitmap to pick up the colors in the app-defaults  color
565       customization file:
566
567           /usr/share/X11/app-defaults/Bitmap-color
568
569

BITMAP WIDGET

571       Bitmap widget is a stand-alone widget for editing raster images.  It is
572       not designed to edit large images, although it may be used in that pur‐
573       pose  as  well.   It can be freely incorporated with other applications
574       and used as a standard editing tool.  The following are  the  resources
575       provided by the bitmap widget.
576
577
578       Bitmap Widget
579
580       Header file     Bitmap.h
581       Class           bitmapWidgetClass
582       Class Name      Bitmap
583       Superclass      Bitmap
584
585       All the Simple Widget resources plus ...
586
587
588       Name              Class             Type              Default Value
589       foreground        Foreground        Pixel             XtDefaultForeground
590       highlight         Highlight         Pixel             XtDefaultForeground
591       framing           Framing           Pixel             XtDefaultForeground
592       gridTolerance     GridTolerance     Dimension         8
593       size              Size              String            32x32
594       dashed            Dashed            Boolean           True
595       grid              Grid              Boolean           True
596       stippled          Stippled          Boolean           True
597       proportional      Proportional      Boolean           True
598       axes              Axes              Boolean           False
599       squareWidth       SquareWidth       Dimension         16
600       squareHeight      SquareHeight      Dimension         16
601       margin            Margin            Dimension         16
602       xHot              XHot              Position          NotSet (-1)
603       yHot              YHot              Position          NotSet (-1)
604       button1Function   Button1Function   DrawingFunction   Set
605       button2Function   Button2Function   DrawingFunction   Invert
606       button3Function   Button3Function   DrawingFunction   Clear
607       button4Function   Button4Function   DrawingFunction   Invert
608
609       button5Function   Button5Function   DrawingFunction   Invert
610       filename          Filename          String            None ("")
611       basename          Basename          String            None ("")
612
613

AUTHOR

615       Davor Matic, MIT X Consortium
616
617
618
619X Version 11                     bitmap 1.0.8                        BITMAP(1)
Impressum