unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



bitmap(1X)							   bitmap(1X)
X11R6									X11R6



NAME

  bitmap, bmtoa, atobm - bitmap	editor and converter utilities for the X Win-
  dow System

SYNOPSIS

  bitmap [-options...] [filename] [basename]

  bmtoa	[-chars	...] [filename]

  atobm	[-chars	cc] [-name variable] [-xhot number] [-yhot number] [filename]

DESCRIPTION

  The bitmap program is	a rudimentary tool for creating	or editing rectangu-
  lar images made up of	1's and	0's.  Bitmaps are used in X for	defining
  clipping regions, cursor shapes, icon	shapes,	and tile and stipple pat-
  terns.

  The bmtoa and	atobm filters convert bitmap files (FILE FORMAT) to and	from
  ASCII	strings.  They are most	commonly used to quickly print out bitmaps
  and to generate versions for including in text.

COMMAND	LINE OPTIONS

  bitmap supports the standard X Toolkit command line arguments	(see X(1X)).
  The following	additional arguments are supported as well.

  -size	WIDTHxHEIGHT
      Specifies	size of	the grid in squares.

  -sw dimension
      Specifies	the width of squares in	pixels.

  -sh dimension
      Specifies	the height of squares in pixels.

  -gt dimension
      Grid tolerance.  If the square dimensions	fall below the specified
      value, grid will be automatically	turned off.

  -grid, +grid
      Turns on or off the grid lines.

  -axes, +axes
      Turns on or off the major	axes.

  -dashed, +dashed
      Turns on or off dashing for the frame and	grid lines.

  -stippled, +stippled
      Turns on or off stippling	of highlighted squares.

  -proportional, +proportional
      Turns proportional mode on or off.  If proportional mode is on, square
      width is equal to	square height.	If proportional	mode is	off, bitmap
      will use the smaller square dimension, if	they were initially
      different.

  -dashes filename
      Specifies	the bitmap to be used as a stipple for dashing.

  -stipple filename
      Specifies	the bitmap to be used as a stipple for highlighting.

  -hl color
      Specifies	the color used for highlighting.

  -fr color
      Specifies	the color used for the frame and grid lines.

  filename
      Specifies	the bitmap to be initially loaded into the program.  If	the
      file does	not exist, bitmap will assume it is a new file.

  basename
      Specifies	the basename to	be used	in the C code output file.  If it is
      different	than the basename in the working file, bitmap will change it
      when saving the file.

  Bmtoa	accepts	the following option:

  -chars cc
      This option specifies the	pair of	characters to use in the string	ver-
      sion of the bitmap.  The first character is used for 0 bits and the
      second character is used for 1 bits.  The	default	is to use dashes (-)
      for 0's and sharp	signs (#) for 1's.

  Atobm	accepts	the following options:

  -chars cc
      This option specifies the	pair of	characters to use when converting
      string bitmaps into arrays of numbers.  The first	character represents
      a	0 bit and the second character represents a 1 bit.  The	default	is to
      use dashes (-) for 0's and sharp signs (#) for 1's.

  -name	variable
      This option specifies the	variable name to be used when writing out the
      bitmap file.  The	default	is to use the basename of the filename com-
      mand line	argument or leave it blank if the standard input is read.

  -xhot	number
      This option specifies the	X coordinate of	the hotspot.  Only positive
      values are allowed.  By default, no hotspot information is included.

  -yhot	number
      This option specifies the	Y coordinate of	the hotspot.  Only positive
      values are allowed.  By default, no hotspot information is included.

USAGE

  bitmap displays grid in which	each square represents a single	bit in the
  picture being	edited.	 Actual	size of	the bitmap image, as it	would appear
  normally and inverted, can be	obtained by pressing Meta-I key.  You are
  free to move the image popup out of the way to continue editing.  Pressing
  the left mouse button	in the popup window or Meta-I again will remove	the
  real size bitmap image.

  If the bitmap	is to be used for defining a cursor, one of the	squares	in
  the images may be designated as the hot spot.	 This determines where the
  cursor is actually pointing.	For cursors with sharp tips (such as arrows
  or fingers), this is usually at the end of the tip; for symmetric cursors
  (such	as crosses or bullseyes), this is usually at the center.

  Bitmaps are stored as	small C	code fragments suitable	for including in
  applications.	 They provide an array of bits as well as symbolic constants
  giving the width, height, and	hot spot (if specified)	that may be used in
  creating cursors, icons, and tiles.

EDITING

  To edit a bitmap image simply	click on one of	the buttons with drawing com-
  mands	(Point,	Curve, Line, Rectangle,	and so forth.) and move	the pointer
  into the bitmap grid	window.	 Press one of the buttons on your mouse	and
  the appropriate action will take place.  You can either set, clear or
  invert the gird squares.  Setting a grid square corresponds to setting a
  bit in the bitmap image to 1.	 Clearing a grid square	corresponds to set-
  ting a bit in	the bitmap image to 0.	Inverting a grid square	corresponds
  to changing a	bit in the bitmap image	from 0 to 1 or 1 to 0, depending what
  its previous state was. The default behavior of mouse	buttons	is as speci-
  fied below.

  MouseButton1		  Set
  MouseButton2		  Invert
  MouseButton3		  Clear
  MouseButton4		  Clear
  MouseButton5		  Clear

  This default behavior	can be changed by setting the button function
  resources.  An example is provided below.

  bitmap*button1Function: Set
  bitmap*button2Function: Clear
  bitmap*button3Function: Invert
  and so forth.

  The button function applies to all drawing commands, including copying,
  moving and pasting, flood filling and	setting	the hot	spot.

DRAWING	COMMANDS

  Here is the list of drawing commands accessible through the buttons at the
  left side of the application's window.  Some commands	can be aborted by
  pressing A inside the	bitmap window, allowing	the user to select different
  guiding points where applicable.

  Clear
      This command clears all bits in the bitmap image.	 The grid squares
      will be set to the background color.  Pressing C inside the bitmap win-
      dow has the same effect.

  Set This command sets	all bits in the	bitmap image.  The grid	squares	will
      be set to	the foreground color.  Pressing	S inside the bitmap window
      has the same effect.

  Invert
      This command inverts all bits in the bitmap image.  The grid squares
      will be inverted appropriately.  Pressing	I inside the bitmap window
      has the same effect.

  Mark
      This command is used to mark an area of the grid by dragging out a rec-
      tangular shape in	the highlighting color.	 Once the area is marked, it
      can be operated on by a number of	commands (see Up, Down,	Left, Right,
      Rotate, Flip, Cut, and so	forth.)	 Only one marked area can be present
      at any time.  If you attempt to mark another area, the old mark will
      vanish.  The same	effect can be achieved by pressing Shift-MouseButton1
      and dragging out a rectangle in the grid window. Pressing	Shift-
      MouseButton2 will	mark the entire	grid area.

  Unmark
      This command will	cause the marked area to vanish.  The same effect can
      be achieved by pressing Shift-MouseButton3.

  Copy
      This command is used to copy an area of the grid from one	location to
      another.	If there is no marked grid area	displayed, Copy	behaves	just
      like Mark	described above.  Once there is	a marked grid area displayed
      in the highlighting color, this command has two alternative behaviors.
      If you click a mouse button inside the marked area, you will be able to
      drag the rectangle that represents the marked area to the	desired	loca-
      tion.  After you release the mouse button, the area will be copied.  If
      you click	outside	the marked area, Copy will assume that you wish	to
      mark a different region of the bitmap image, thus	it will	behave like
      Mark again.

  Move
      This command is used to move an area of the grid from one	location to
      another.	Its behavior resembles the behavior of Copy command, except
      that the marked area will	be moved instead of copied.

  Flip Horizontally
      This command will	flip the bitmap	image with respect to the horizontal
      axes. If a marked	area of	the grid is highlighted, it will operate only
      inside the marked	area.  Pressing	H inside the bitmap window has the
      same effect.

  Up  This command moves the bitmap image one pixel up.	If a marked area of
      the grid is highlighted, it will operate only inside the marked area.
      Pressing UpArrow inside the bitmap window	has the	same effect.

  Flip Vertically
      This command will	flip the bitmap	image with respect to the vertical
      axes. If a marked	area of	the grid is highlighted, it will operate only
      inside the marked	area.  Pressing	V inside the bitmap window has the
      same effect.

  Left
      This command moves the bitmap image one pixel to the left.  If a marked
      area of the grid is highlighted, it will operate only inside the marked
      area.  Pressing LeftArrow	inside the bitmap window has the same effect.

  Fold
      This command will	fold the bitmap	image so that the opposite corners
      become adjacent.	This is	useful when creating bitmap images for til-
      ing.  Pressing F inside the bitmap window	has the	same effect.

  Right
      This command moves the bitmap image one pixel to the right.  If a
      marked area of the grid is highlighted, it will operate only inside the
      marked area.  Pressing RightArrow	inside the bitmap window has the same
      effect.

  Rotate Left
      This command rotates the bitmap image 90 degrees to the left (counter
      clockwise.) If a marked area of the grid is highlighted, it will
      operate only inside the marked area.  Pressing L inside the bitmap win-
      dow has the same effect.

  Down
      This command moves the bitmap image one pixel down. If a marked area of
      the grid is highlighted, it will operate only inside the marked area.
      Pressing DownArrow inside	the bitmap window has the same effect.

  Rotate Right
      This command rotates the bitmap image 90 degrees to the right (clock-
      wise.) If	a marked area of the grid is highlighted, it will operate
      only inside the marked area.  Pressing R inside the bitmap window	has
      the same effect.

  Point
      This command will	change the grid	squares	underneath the mouse pointer
      if a mouse button	is being pressed down.	If you drag the	mouse button
      continuously, the	line may not be	continuous, depending on the speed of
      your system and frequency	of mouse motion	events.

  Curve
      This command will	change the grid	squares	underneath the mouse pointer
      if a mouse button	is being pressed down.	If you drag the	mouse button
      continuously, it will make sure that the line is continuous.  If your
      system is	slow or	bitmap receives	very few mouse motion events, it
      might behave quite strangely.

  Line
      This command will	change the gird	squares	in a line between two
      squares. Once you	press a	mouse button in	the grid window, bitmap	will
      highlight	the line from the square where the mouse button	was initially
      pressed to the square where the mouse pointer is located.	 By releasing
      the mouse	button you will	cause the change to take effect, and the
      highlighted line will disappear.

  Rectangle
      This command will	change the gird	squares	in a rectangle between two
      squares. Once you	press a	mouse button in	the grid window, bitmap	will
      highlight	the rectangle from the square where the	mouse button was ini-
      tially pressed to	the square where the mouse pointer is located.	By
      releasing	the mouse button you will cause	the change to take effect,
      and the highlighted rectangle will disappear.

  Filled Rectangle
      This command is identical	to Rectangle, except at	the end	the rectangle
      will be filled rather than outlined.

  Circle
      This command will	change the gird	squares	in a circle between two
      squares. Once you	press a	mouse button in	the grid window, bitmap	will
      highlight	the circle from	the square where the mouse button was ini-
      tially pressed to	the square where the mouse pointer is located.	By
      releasing	the mouse button you will cause	the change to take effect,
      and the highlighted circle will disappear.

  Filled Circle
      This command is identical	to Circle, except at the end the circle	will
      be filled	rather than outlined.

  Flood	Fill
      This command will	flood fill the connected area underneath the mouse
      pointer when you click on	the desired square.  Diagonally	adjacent
      squares are not considered to be connected.

  Set Hot Spot
      This command designates one square in the	grid as	the hot	spot if	this
      bitmap image is to be used for defining a	cursor.	 Pressing a mouse
      button in	the desired square will	cause a	diamond	shape to be
      displayed.

  Clear	Hot Spot
      This command removes any designated hot spot from	the bitmap image.

  Undo
      This command will	undo the last executed command.	 It has	depth one,
      that is, pressing	Undo after Undo	will undo itself.

FILE MENU

  The File menu	commands can be	accessed by pressing the File button and
  selecting the	appropriate menu entry,	or by pressing Ctrl key	with another
  key.	These commands deal with files and global bitmap parameters, such as
  size,	basename, filename and so forth.

  New This command will	clear the editing area and prompt for the name of the
      new file to be edited.  It will not load in the new file.

  Load
      This command is used to load a new bitmap	file into the bitmap editor.
      If the current image has not been	saved, user will be asked whether to
      save or ignore the changes.  The editor can edit only one	file at	a
      time.  If	you need interactive editing, run a number of editors and use
      cut and paste mechanism as described below.

  Insert
      This command is used to insert a bitmap file into	the image being
      currently	edited.	 After being prompted for the filename,	click inside
      the grid window and drag the outlined rectangle to the location where
      you want to insert the new file.

  Save
      This command will	save the bitmap	image.	It will	not prompt for the
      filename unless it is said to be <none>.	If you leave the filename
      undesignated or -, the output will be piped to stdout.

  Save As
      This command will	save the bitmap	image after prompting for a new
      filename.	 It should be used if you want to change the filename.

  Resize
      This command is used to resize the editing area to the new number	of
      pixels.  The size	should be entered in the WIDTHxHEIGHT format.  The
      information in the image being edited will not be	lost unless the	new
      size is smaller that the current image size. The editor was not
      designed to edit huge files.

  Rescale
      This command is used to rescale the editing area to the new width	and
      height.  The size	should be entered in the WIDTHxHEIGHT format.  It
      will not do antialiasing and information will be lost if you rescale to
      the smaller sizes.  Feel free to add you own algorithms for better res-
      caling.

  Filename
      This command is used to change the filename without changing the
      basename nor saving the file.  If	you specify - for a filename, the
      output will be piped to stdout.

  Basename
      This command is used to change the basename, if a	different one from
      the specified filename is	desired.

  Quit
      This command will	terminate the bitmap application.  If the file was
      not saved, user will be prompted and asked whether to save the image or
      not.  This command is preferred over killing the process.






EDIT MENU

  The Edit menu	commands can be	accessed by pressing the Edit button and
  selecting the	appropriate menu entry,	or by pressing Meta key	with another
  key.	These commands deal with editing facilities such as grid, axes,	zoom-
  ing, cut and paste, and so forth.

  Image
      This command will	display	the image being	edited and its inverse in its
      actual size in a separate	window.	 The window can	be moved away to con-
      tinue with editing.  Pressing the	left mouse button in the image window
      will cause it to disappear from the screen.

  Grid
      This command controls the	grid in	the editing area.  If the grid spac-
      ing is below the value specified by gridTolerance	resource (8 by
      default),	the grid will be automatically turned off.  It can be
      enforced by explicitly activating	this command.

  Dashed
      This command controls the	stipple	for drawing the	grid lines.  The
      stipple specified	by dashes resource can be turned on or off by
      activating this command.

  Axes
      This command controls the	highlighting of	the main axes of the image
      being edited.  The actual	lines are not part of the image.  They are
      provided to aid user when	constructing symmetrical images, or whenever
      having the main axes highlighted helps your editing.

  Stippled
      This command controls the	stippling of the highlighted areas of the
      bitmap image.  The stipple specified by stipple resource can be turned
      on or off	by activating this command.

  Proportional
      This command controls the	proportional mode.  If the proportional	mode
      is on, width and height of all image squares are forced to be equal,
      regardless of the	proportions of the bitmap window.

  Zoom
      This command controls the	zoom mode.  If there is	a marked area of the
      image already displayed, bitmap will automatically zoom into it.	Oth-
      erwise, user will	have to	highlight an area to be	edited in the zoom
      mode and bitmap will automatically switch	into it.  One can use all the
      editing commands and other utilities in the zoom mode.  When you zoom
      out, undo	command	will undo the whole zoom session.

  Cut This commands cuts the contents of the highlighted image area into the
      internal cut and paste buffer.

  Copy
      This command copies the contents of the highlighted image	area into the
      internal cut and paste buffer.

  Paste
      This command will	check if there are any other bitmap applications with
      a	highlighted image area,	or if there is something in the	internal cut
      and paste	buffer and copy	it to the image.  To place the copied image,
      click in the editing window and drag the outlined	image to the position
      where you	want to	place i, and then release the button.





CUT AND	PASTE

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

WIDGETS

  Below	is the widget structure	of the bitmap application.  Indentation	indi-
  cates	hierarchical structure.	 The widget class name is given	first, fol-
  lowed	by the widget instance name.  All widgets except the bitmap widget
  are from the standard	Athena widget set.

  Bitmap bitmap
	TransientShell image
	      Box box
		    Label normalImage
		    Label invertedImage
	TransientShell input
	      Dialog dialog
		    Command okay
		    Command cancel
	TransientShell error
	      Dialog dialog
		    Command abort
		    Command retry
	TransientShell qsave
	      Dialog dialog
		    Command yes
		    Command no
		    Command cancel
	Paned parent
	      Form formy
		    MenuButton fileButton
		    SimpleMenu fileMenu
			  SmeBSB  new
			  SmeBSB  load
			  SmeBSB  insert
			  SmeBSB  save
			  SmeBSB  saveAs
			  SmeBSB  resize
			  SmeBSB  rescale
			  SmeBSB  filename
			  SmeBSB  basename
			  SmeLine line
			  SmeBSB  quit
		    MenuButton editButton
		    SimpleMenu editMenu
			  SmeBSB  image
			  SmeBSB  grid
			  SmeBSB  dashed
			  SmeBSB  axes
			  SmeBSB  stippled
			  SmeBSB  proportional
			  SmeBSB  zoom
			  SmeLine line
			  SmeBSB  cut
			  SmeBSB  copy
			  SmeBSB  paste
		    Label status
	      Pane pane
		    Bitmap bitmap
		    Form form
			  Command clear
			  Command set
			  Command invert
			  Toggle  mark
			  Command unmark
			  Toggle  copy
			  Toggle  move
			  Command flipHoriz
			  Command up
			  Command flipVert
			  Command left
			  Command fold
			  Command right
			  Command rotateLeft
			  Command down
			  Command rotateRight
			  Toggle  point
			  Toggle  curve
			  Toggle  line
			  Toggle  rectangle
			  Toggle  filledRectangle
			  Toggle  circle
			  Toggle  filledCircle
			  Toggle  floodFill
			  Toggle  setHotSpot
			  Command clearHotSpot
			  Command undo

COLORS

  If you would like bitmap to be viewable in color, include the	following in
  the #ifdef COLOR section of the file you read	with xrdb:

       *customization:		       -color

  This will cause bitmap to pick up the	colors in the app-defaults color cus-
  tomization file:

  <&lt;XRoot>&gt;/lib/X11/app-defaults/Bitmap-color

  where	<&lt;XRoot>&gt;	refers to the root of the X11 install tree.









BITMAP WIDGET

  Bitmap widget	is a stand-alone widget	for editing raster images.  It is not
  designed to edit large images, although it may be used in that purpose as
  well.	 It can	be freely incorporated with other applications and used	as a
  standard editing tool.  The following	are the	resources provided by the
  bitmap widget.

  Bitmap Widget

  Header file	Bitmap.h
  Class		bitmapWidgetClass
  Class	Name	Bitmap
  Superclass	Bitmap

  All the Simple Widget	resources plus ...

  ______________________________________________________________________
  Name		    Class	      Type		Default	Value
  ______________________________________________________________________
  foreground	    Foreground	      Pixel

							XtDefaultFore-
							ground
  highlight	    Highlight	      Pixel

							XtDefaultFore-
							ground
  framing	    Framing	      Pixel

							XtDefaultFore-
							ground
  gridTolerance	    GridTolerance     Dimension		8
  size		    Size	      String		32x32
  dashed	    Dashed	      Boolean		True
  grid		    Grid	      Boolean		True
  stippled	    Stippled	      Boolean		True
  proportional	    Proportional      Boolean		True
  axes		    Axes	      Boolean		False
  squareWidth	    SquareWidth	      Dimension		16
  squareHeight	    SquareHeight      Dimension		16
  margin	    Margin	      Dimension		16
  xHot		    XHot	      Position		NotSet (-1)
  yHot		    YHot	      Position		NotSet (-1)
  button1Function   Button1Function   DrawingFunction	Set
  button2Function   Button2Function   DrawingFunction	Invert
  button3Function   Button3Function   DrawingFunction	Clear
  button4Function   Button4Function   DrawingFunction	Invert
  button5Function   Button5Function   DrawingFunction	Invert
  filename	    Filename	      String		None ()
  basename	    Basename	      String		None ()
  ______________________________________________________________________

AUTHOR

  Davor	Matic, MIT X Consortium