OLPIXMAP(1) OPEN LOOK 4 OLPIXMAP(1)
NAME
olpixmap - pixmap editor
SYNOPSIS
olpixmap [-options...] [filename]
DESCRIPTION
The olpixmap editor is a software product that allows users (primarily
software developers) to create and edit pixmaps that may be used by other
X Window System applications. olpixmap is intended for use mainly by
software developers to create pixmaps for use in their applications, but
can also be useful to end users in creating custom background pixmaps for
their root window (see xsetroot(1), which has been modified to accept
pixmap files).
The olpixmap editor is an independent, self-contained component of the
OPEN LOOK product. It is meant as a complement to the bitmap program
provided by MIT as part of the X Window System.
As an interactive application, olpixmap reacts to user input (usually by
manipulating the mouse) to set pixels in a pixmap to specific colors.
Users have available to them convenient primitive operations for drawing
simple closed shapes and lines, as well as filling arbitrarily shaped
areas with a specified color.
The pixmap editor does not support mouseless operations within the pixmap
grid. The only mouseless operations supported are navigation between
controls and windows, and mnemonics and accelerators.
The output of olpixmap is a small C code fragment. By #include'ing such
a program fragment into an application, the user can easily declare the
size and content of icons, window backgrounds, and other pixmaps that an
application creates to deal with the X Window System.
The olpixmap editor writes pixmaps in the XPM (X PixMap) file format.
The XPM format is a convention for storing pixmaps on disk in a portable
(ASCII), device-independent (no depth or color limitations),
#include'able format, similar to MIT's standard X11 bitmap file format.
Applications wanting to read or write this format will need to link in
two source files to provide this support. These files (xpm.c and xpm.h)
are installed by olpixmap for such use, and can be found (typically) in
/usr/X/lib/tutorial/XPM on SVR3.2 machines and in
/usr/lib/X11/tutorial/XPM on SVR4.0 machines.
DEFINITIONS, ACRONYMS, AND ABBREVIATIONS
Pixmap A pixmap is a three dimensional array of bits. A pixmap is
normally thought of as a two dimensional array of pixels, where
each pixel can be a value from 0 to 2N-1, where N is the depth (z
axis) of the pixmap. A pixmap can also be thought of as a stack
of N bitmaps.
10/89 Page 1
OLPIXMAP(1) OPEN LOOK 4 OLPIXMAP(1)
Pixel A pixel is an N-bit value (at a single point), where N is the
number of bit planes (e.g., the depth of) used in a particular
pixmap.
Depth The depth of a pixmap is the number of bits per pixel it has.
Bitmap A bitmap is a pixmap of depth 1.
Press A press is the down transition of a mouse button or key.
Release A release is the up transition of a mouse button or key.
Click A click is a button press followed by a button release with no
intervening mouse motion (any mouse damping factor is taken into
account).
Dragging
Dragging refers to a button press followed by some amount of
mouse motion (greater than the mouse damping factor), terminated
by a button release.
Mouse Damping Factor
The mouse damping factor is the amount the mouse is allowed to
actually move in between a button press and a button release
while still considering the button press/release combination to
be a click.
Sweeping
Sweeping is mouse motion with a mouse button down; similar to
dragging.
Canvas The canvas is the area in which the pixmap is actually
manipulated.
OVERVIEW:
STARTUP BEHAVIOR
olpixmap comes up with a base window plus a pinned popup window. The
base window consists of a canvas pane displaying a magnified image of a
pixmap, in which each pixel is shown as a large square (as if on a piece
of graph paper), and a button control area. The popup shows the pixmap
at its actual size, with a single-pixel wide box outlining the portion of
the pixmap being magnified.
When olpixmap starts, it first tries to read the specified file. If the
file already exists, it creates a canvas pane containing a grid of the
appropriate dimensions. If the file does not exist, olpixmap will create
a pane for a pixmap of the default size, and the pixmap will start out
empty.
SELECT, ADJUST, and MENU
SELECT is used to start working with (i.e., start the drawing process of)
the current object. For the case of a single pixel, clicking SELECT sets
Page 2 10/89
OLPIXMAP(1) OPEN LOOK 4 OLPIXMAP(1)
the chosen pixel to the current color, while dragging SELECT sets all
pixels dragged through. In the case of lines or line segments, pressing
SELECT sets the initial endpoint; releasing SELECT sets the terminal
endpoint. For other objects (e.g., oval or rectangle), pressing SELECT
sets the center or corner of the bounding rectangle. Subsequent dragging
of SELECT changes the size of the bounding rectangle. The object is
drawn the appropriate size upon release of SELECT.
ADJUST currently has no function.
MENU is used to bring up a menu.
CONTROL LAYOUT
olpixmap has a canvas pane to display the magnified pixmap located to the
left of a control panel. The control panel has buttons and menu buttons
labeled File, View, Edit, Draw, Palette, and Properties. The
functionality associated with each button is listed under the appropriate
heading.
File Selecting File pops up a window with a text field and buttons for
opening and saving a pixmap.
Open reads in a fresh pixmap file.
Browse allows interactive traversal of the file system for
selection of a pixmap file to open.
Save writes out the current pixmap file.
Detailed explanations of the open and save operations can be
found in the sections labeled ``Reading Files In'', ``Browsing'',
and ``Writing Files Out''.
View Show Pixmap (the default button) allows the user to pop up a
window containing the actual size pixmap on which the user is
working. The pixmap in the popup window is updated in real time
with any operations the user performs. (This button is used to
re-popup this window if the one from start-up is unpinned.)
The Zoom In button is the second control. It allows the user to
zoom in to a higher magnification level on the current pixmap.
Successive zoom-ins are supported.
The Zoom Out button is the inverse operation of the Zoom In
button. Selecting Zoom Out returns the pixmap to the previous
level of magnification.
Edit The Fill button enables the user to fill a portion of the pixmap
to the current color.
Clear provides a quick way to clear out a specified rectangular
area of the pixmap.
The Copy button enables the user to copy selected areas of the
pixmap.
Move works in a similar fashion to Copy.
The Roll function horizontally or vertically rotates the pixmap,
with wrapping around at the edges.
Further details of the controls in the Edit menu can be found in
the appropriately labeled sections that follow.
10/89 Page 3
OLPIXMAP(1) OPEN LOOK 4 OLPIXMAP(1)
Draw The Draw menu consists of an exclusive setting from which the
user can choose the current drawing function.
Pixels enables the user to set arbitrary pixels.
Lines allows the user to draw lines by selecting two endpoints.
Segments is similar to Lines, letting the user draw connected
line segments. Each subsequent endpoint specified after the
first two draws a connecting line from the previous one.
Ovals enables the user to draw arbitrary ovals by sweeping the
bounding rectangle on the pixmap.
Circles is a constrained case of the general Ovals function.
Rectangles lets the user draw arbitrary rectangles by sweeping
the rectangle on the pixmap.
Squares is a constrained case of the general Rectangles function.
Further details of the controls in the Draw menu can be found in
the appropriately labeled sections that follow.
Palette Pressing the Palette menu button displays a submenu showing the
different drawing colors available. The current drawing color
can be changed by choosing a new entry from this menu.
Properties
The Properties button pops up a property window that allows the
user to choose the current line width, line style, grid
appearance, and pixmap dimensions.
Further details of the controls in the Properties property window
can be found in the appropriately labeled sections that follow.
COMMANDS
Reading Files In
Choosing Open from the File window initiates a read from the file
named in the text field. Any previous work is discarded and the
new pixmap file is read in, with the canvas being resized as
necessary. Any error messages related to reading the specified
file will be displayed in the window footer. olpixmap supports
reading of standard X11 bitmap format files.
Browsing
The Browse window is a pop-up window with its pushpin initially
unpinned. Choosing Browse from the File window will pop up a File
Manager window from which the user can traverse through the file
system and potentially choose a pixmap file to open. Double-
click SELECT on the icon of the desired pixmap file in order to
load it into the pixmap editor. The browse operation can be
cancelled if desired via a File Manager submenu.
Alternatively, the user can take advantage of the "drag and drop"
feature to open pixmap files shown in already-existing File
Manager windows. Using SELECT, drag the desired file from an
independent File Manager window, and drop it onto the
magnification pane of olpixmap. The file will then be opened as
usual.
Page 4 10/89
OLPIXMAP(1) OPEN LOOK 4 OLPIXMAP(1)
Writing Files Out
Choosing Save from the File window writes the current pixmap to
the file named in the text field (which by default is the last
one opened). If there is an existing file by that name, it will
be renamed with an appended tilda character. Any error messages
related to writing the specified file will be displayed in the
window footer.
Show Pixmap
Selecting the Show Pixmap button pops up a window that contains a
actual size representation of the pixmap currently being edited.
If the window is already popped up, then it will be raised to the
front. This pixmap is updated as the user works on the canvas.
Magnifying
Magnification is accomplished by the use of the Zoom In and Zoom
Out buttons. The Zoom In button increases the level of
magnification for the canvas pane (scrollbars are added if not
already present). The pixel representations are sized
accordingly. Any number of Zoom In operations may be performed
up to the point of having a single pixel fill the viewport.
Subsequent Zoom In requests are ignored. The Zoom In operations
are stacked; the Zoom Out button returns the canvas to the
previous magnification value. If the user has not zoomed in, no
operation is performed.
Fill Area
When Fill is chosen, the user is directed to select a point
within the area that s/he desires to fill. All pixels in that
area that are of the same color as the one chosen will be filled
to be the current color. Thus, the fill stops at the boundaries
of where the color is not the same as that of the chosen point.
Clear Area
Choosing Clear prompts the user to sweep out a rectangular area
to clear to the background color.
Copy Area
When Copy is chosen, the user is directed to sweep an area of the
canvas by dragging SELECT, indicating the area to be copied.
When SELECT is released, the user is instructed to specify, by
pressing SELECT, the location where the upper left corner of the
copied area is to begin. When SELECT is released, the area is
copied.
Move Area
When Move is chosen, the user is directed to sweep an area of the
canvas by dragging SELECT indicating the area to be moved. When
SELECT is released, the user is instructed to specify, by
pressing SELECT, the location where the upper left corner of the
swept area is to be moved. When SELECT is released, the area is
moved. Any pixel ``exposed'' by the move operation will be set
10/89 Page 5
OLPIXMAP(1) OPEN LOOK 4 OLPIXMAP(1)
to the background color.
Roll This function will horizontally and/or vertically rotate the
pixmap, with wrapping around at the edges. The user makes this
happen by choosing a point within the pixmap to make the new
upper-left corner of the pixmap. This point will first be rolled
horizontally to the left edge of the pixmap, with all pixel data
to its left wrapping around to the right edge of the pixmap, and
then the point is rolled vertically to the top edge of the
pixmap, with all pixel data above wrapping around to the bottom
edge of the pixmap. This function is useful when creating a
pixmap that needs to join with itself when tiled.
Drawing Raw Pixels
The user may set individual pixels by selecting the Pixels item
under the Draw menu button. When the user is drawing raw pixels,
SELECT sets the pixel pointed to by the mouse to the current
color.
Drawing Lines
To draw a collection of lines, the user would first select the
Lines button. The user would then be prompted to select the
initial endpoint by pressing SELECT over some pixel. A rubber
band line would appear anchored to the selected pixel, tracking
the pointer. When the user would release the button, the
terminal endpoint is selected and the line is drawn using the
current color, line width, and line style.
Drawing Connected Segments
Drawing connected line segments follows a similar interface to
drawing lines. The user selects the initial endpoint of the
first segment by pressing SELECT. A rubber band line tracks the
pointer until the user releases the button, causing the line to
be drawn in the current color using the current line width, and
line style. To draw another segment, the user again presses
SELECT. However, for this and all subsequent segments, the
initial endpoint is anchored at the terminal endpoint of the
previously drawn segment. When SELECT is pressed, a rubber band
line appears, anchored at the terminal endpoint of the previous
segment, tracking the pointer. When SELECT is released, the next
segment is drawn.
Drawing Ovals
Selecting Ovals prompts the user to sweep the bounding box for
the oval. When the user presses SELECT, a rubber banding
rectangle is drawn, centered about the pixel over which SELECT
was pressed. The appropriate corner (lower right, if the user
pulls down and to the right; upper left, if the user pulls up and
to the left, etc.) tracks the pointer until the user releases
SELECT. An oval is then drawn to the size specified by the
bounding rectangle, using the current color, line width, and line
style.
Page 6 10/89
OLPIXMAP(1) OPEN LOOK 4 OLPIXMAP(1)
Drawing Circles
Circles are drawn in an identical manner to ovals. The
constraint of a square bounding box is automatically imposed.
Drawing Rectangles
Selecting Rectangles prompts the user to sweep the bounding box
for the rectangle. When the user presses SELECT, a rubber
banding rectangle is drawn, centered about the pixel over which
SELECT was pressed. The appropriate corner tracks the pointer
until the user releases SELECT. A rectangle is then drawn to the
size specified by the rubber banding rectangle, using the current
color, line width, and line style.
Drawing Squares
Squares are drawn in an identical manner to rectangles. The
constraint of a square bounding box is automatically imposed.
Changing the Current Color
The color used for drawing operations may be changed using the
Palette submenu. This menu displays a box for each of the
available colors in the colormap. The menu can be pinned for
rapid access.
PROPERTIES
The Properties property sheet allows the user to set the values of
various parameters pertaining to the operation of olpixmap. New values
may be chosen by manipulating the controls; these values are then put
into effect by clicking SELECT on the ``Apply'' button. The user may
choose the ``Reset'' button at any time to return the controls to the
values currently in effect.
Line Width
The Line Width slider allows the user to change the width of
objects drawn (lines, ovals, rectangles, etc.). The slider
displays the current line width (zero by default). This value
may be changed by the user to any integer value.
Line Style
The Line Style item allows the user to select the line type.
Line type is selected by choosing one of the two exclusive
settings, ``Solid'' (the default) or ``Dashed.''
Grid Appearance
The Grid item is an exclusive setting that controls whether the
canvas grid will be shown; selecting ``Off'' inhibits the display
of the grid.
Pixmap Dimensions
The Pixmap Width and Height fields show the dimensions of the
pixmap currently being edited. Either or both of these values
may be dynamically changed by typing a valid integer value into
the appropriate fields (and subsequently selecting the ``Apply''
10/89 Page 7
OLPIXMAP(1) OPEN LOOK 4 OLPIXMAP(1)
button). Any error messages will be displayed in the window
footer.
The pixmap is resized to the size requested by the user, with any
pixel values being copied into the new pixmap. If the new pixmap
is larger than the old pixmap, the old pixmap will be copied
intact, starting at (0,0), with the remainder of the new pixmap
being unset. If the new pixmap is smaller, the old pixmap is
copied starting at (0,0) and clipped by the boundary of the new
pixmap. The magnification pane is sized appropriately.
FILE FORMAT
olpixmap reads and writes files in the following format (XPM), which is
suitable for #include'ing in a C program:
#define name_format 1
#define name_width 16
#define name_height 16
#define name_ncolors 4
#define name_chars_per_pixel 1
static char * name_colors[] = {
" " , "#FFFFFFFFFFFF",
"." , "SkyBlue",
"X" , "#000000",
"o" , "ForestGreen"
} ;
static char * name_pixels[] = {
"X..X X",
" X..X X",
" X..X X ",
" X..X X ",
" X..X X ",
" X..X X ",
" X..X X ",
" X.. X ",
" XX X ",
" X ooX ",
" X XooX ",
" X XooX ",
" X XooX ",
" X XooX ",
" X XooX ",
" X XooX"
} ;
The name portion of the shown variables will be derived from the name of
the file specified either on the original command line or in the File
window by deleting the directory path (all characters up to and including
the last `/', if one is present), and deleting the extension (the first
`.', if one is present, and all characters beyond it).
Page 8 10/89
OLPIXMAP(1) OPEN LOOK 4 OLPIXMAP(1)
For example, invoking olpixmap with the filename
/usr/X/include/X11/pixmaps/cross.xpm on SVR3.2 systems or
/usr/include/X11/pixmaps/cross.xpm on SVR4 systems will produce a file
with variable names cross_width, crossheight, cross_ncolors,
crosscharsperpixel, cross_colors, and crosspixels.
It's easy to define a pixmap in an X program by simply #include'ing a
pixmap file and referring to its variables. For instance, to use a
pixmap defined in the file cross.xpm, one simply writes:
#include "cross.xpm"
Pixmap cross = XCreatePixmapFromData(DISPLAY, DRAWABLE, COLORMAP,
cross_width, cross_height, DEPTH,
cross_ncolors, cross_chars_per_pixel,
cross_colors, cross_pixels);
Colors will be allocated from the supplied colormap as necessary, and the
pixmap cross (which will be created with the specified depth) could then
be used like any normal X pixmap.
An X program can also read a pixmap file at runtime by using the function
XReadPixmapFile().
SEE ALSO
bitmap(1)
10/89 Page 9