OPEN LOOK 3.0 1
OLPIXMAP(1) USER COMMANDS 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 (usu-
ally 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 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 con-
tent 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.
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.
OPEN LOOK 3.0 Last change: 7/12/90 1
OLPIXMAP(1) USER COMMANDS OLPIXMAP(1)
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 damp-
ing 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 actu-
ally manipulated.
OVERVIEW:
STARTUP BEHAVIOR
olpixmap comes up with a base window plus a pinned popup
window. The base window consists of a canvas pane display-
ing 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 draw-
ing process of) the current object. For the case of a sin-
gle pixel, clicking SELECT sets the chosen pixel to the
OPEN LOOK 3.0 Last change: 7/12/90 2
OLPIXMAP(1) USER COMMANDS OLPIXMAP(1)
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 rectan-
gle), 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 sys-
tem for selection of a pixmap file to open.
Save writes out the current pixmap file.
Detailed explanations of the open and save opera-
tions 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 sup-
ported.
The Zoom Out button is the inverse operation of the
Zoom In button. Selecting Zoom Out returns the pix-
map 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
area of the pixmap.
Move works in a similar fashion to Copy.
OPEN LOOK 3.0 Last change: 7/12/90 3
OLPIXMAP(1) USER COMMANDS OLPIXMAP(1)
The Roll function will horizontally or vertically
rotate 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.
Draw The Draw menu consists of an exclusive setting from
which the user can choose the current drawing func-
tion.
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 Rectan-
gles 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
OPEN LOOK 3.0 Last change: 7/12/90 4
OLPIXMAP(1) USER COMMANDS OLPIXMAP(1)
will be displayed in the window footer. olpixmap
supports reading of standard X11 bitmap format
files.
Browsing
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 magnifica-
tion pane of olpixmap. The file will then be opened
as usual.
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 mes-
sages 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 magnifica-
tion value. If the user has not zoomed in, no
operation is performed.
Fill Area
OPEN LOOK 3.0 Last change: 7/12/90 5
OLPIXMAP(1) USER COMMANDS OLPIXMAP(1)
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 rec-
tangular 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 to the background color.
Roll The Roll function will horizontally and/or verti-
cally 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
OPEN LOOK 3.0 Last change: 7/12/90 6
OLPIXMAP(1) USER COMMANDS OLPIXMAP(1)
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 bound-
ing 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.
Drawing Circles
Circles are drawn in an identical manner to ovals.
The constraint of a square bounding box is automati-
cally 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
OPEN LOOK 3.0 Last change: 7/12/90 7
OLPIXMAP(1) USER COMMANDS OLPIXMAP(1)
line style.
Drawing Squares
Squares are drawn in an identical manner to rectan-
gles. 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 con-
trols; 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 dimen-
sions 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''
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,
OPEN LOOK 3.0 Last change: 7/12/90 8
OLPIXMAP(1) USER COMMANDS OLPIXMAP(1)
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 mag-
nification 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 com-
mand 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). For exam-
ple, 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.0 systems will
produce a file with variable names cross_width,
cross_height, cross_ncolors, cross_chars_per_pixel,
cross_colors, and cross_pixels. It's easy to define a
OPEN LOOK 3.0 Last change: 7/12/90 9
OLPIXMAP(1) USER COMMANDS OLPIXMAP(1)
pixmap in an X program by simply #include'ing a pixmap file
and referring to its variables. For instance, to use a pix-
map 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), xsetroot(1), olfm(1)
COPYRIGHT
Copyright 1989, AT&T
OPEN LOOK 3.0 Last change: 7/12/90 10