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 (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 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.

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.

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 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 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 drawing process of) the current object. For the case of a single pixel, clicking SELECT sets the chosen pixel to the

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 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 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.

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

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 magnification 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 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

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 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 to the background color.

Roll The Roll 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

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 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.

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

OLPIXMAP(1)              USER COMMANDS                OLPIXMAP(1)
             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'' 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,

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 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). 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.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

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 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), xsetroot(1), olfm(1)

COPYRIGHT

Copyright 1989, AT&T