Piper's Pit BBS/FTP: ibm 0020 - 0029/ibm0020-0029/ibm0028.tar/ibm0028/CSCAP321.ZIP/GRAPHICS.TXT

Text File | 1990-12-28 | 107.1 KB | 3,681 lines

                           C-scape and Graphics

        Copyright (c) 1990, Oakland Group, Inc.  All rights reserved.








SECTION1:  About this document

Part of C-scape's power is that it allows you to use graphics in your
applications.  This document takes a look at the various tools available for
using graphics.  It is organized as follows:

        Section 2    C-scape and graphics

                     This section offers a practical approach to the methods
                     that you can use to put graphics into your application.
                     Each part of this section is based on and explicates a
                     particular C-scape demo program (see below).

        Section 3    C-scape graphics theory

                     This section provides a theoretical explanation of C-scape
                     and its graphics components.  It is not required reading,
                     though you may find it useful, edifying, or even fun.

        Section 4    Function reference

                     This section is a reference for the functions mentioned in
                     this document and in the programs to which it refers.

For more basic information on C-scape, consult the C-scape User's Manual, the
C-scape Function Reference, and the file READ.ME (also on your distribution
media).

SECTION 2:  C-scape and graphics

C-scape sits on top of the Oakland Windowing Library (OWL), which itself has
two parts: the Window Manager and the Device Interface Group (DIG).  The Window
Manager creates, paints, manipulates, and destroys windows.  The DIG handles
all communications with the display hardware and operating system.

The Window Manager maintains all windows on the display and knows which parts
of each window are visible.  It uses a message passing scheme to handle
requests to paint, resize, and move windows.  For instance, when you want to
paint a window, you tell the Window Manager (by calling sed_Repaint).  The
Window Manager then sends a paint message to the window; this message tells the
window which of its parts are visible (and require painting).  The window
receives the message and paints the appropriate areas.  This message passing
approach allows the Window Manager to govern different types of windows with
the same message, since each type knows how to respond to the message.  Note
that every window has associated data that determines what it is currently
displaying because the Window Manager may send it a paint message at any time.
The data associated with a sed (the window type used by C-scape) is held in its
menu object.  The menu object consists of the text buffer, an array of fields,
and various state information.

When a window receives a paint message, it responds by drawing something, such
as a text string, to the display.  It does this with one of the standard DIG
commands.  The DIG is a collection of routines that perform specific interface
functions.  For example, one DIG routine plots a string to the display and
another scrolls a region on the display.  There exists one DIG for each display
mode.  disp_Init calls either the DIG you have specified or, if you so choose,
the best one available for your platform.

When you run a text mode C-scape program, disp_Init sets up the DIG to use
functions that communicate to the display in text mode.  In graphics mode, the
DIG is set up to emulate text mode with graphics commands, so that C-scape
still lays out text forms using character coordinates.  Note that C-scape
windows (seds) can only use fixed-width fonts and can only use one font at a
time.

The graphics mode DIG makes it possible to read and write bitmap images (or
pixmaps) to and from the display.  C-scape graphics programs use this ability
when they create windows containing bitmap images.

Note that the following applications use either grwins (GRaphics WINdows) or
pmwins (Pixel Map WINdows).  Both window classes can hold pixmaps.  A grwin is
designed for use in a dynamically changing situation; it automatically
allocates its own pixmap (ensuring that the window and its pixmap are the same
size) and can handle SAVE messages.  A pmwin is designed for more static
situations; it allocates its pixmap in a separate operation (pmap_Open) and
uses a "GRAB" message to read from the display and update its pixmap.

2.1  Drawing on top of the display and restoring

The easiest and simplest way of creating a graphical image on the display is to
draw directly to the display using a graphics library.  When you are finished,
you can remove the graphics by calling disp_Repaint.   disp_Repaint repaints
the entire C-scape display (all windows and the display background) and
obliterates the graphics image you have drawn.

With this approach, OWL knows nothing of the image you have created because it
exists outside of its windowing system.  While the graphical image is on the
display, you should not move or paint any C-scape windows, since the windows
will overwrite the image.

demodraw.c is an example which uses this method.  In brief, disp_Init
initializes OWL, the graphics library is initialized, and a clipping rectangle
is established for use with the graphics library routines; next, a C-scape sed
is created, painted, and run; then, a graphical image is drawn on top of the
C-scape window; finally, disp_Repaint restores the C-scape display, removing
the image.

2.2  Writing graphics to a background grwin window

Instead of drawing over your C-scape windows and losing the image when those
windows are repainted or moved, you can preserve the image by drawing on a
special C-scape window called the background window.

Because the background window is part of C-scape (and automatically managed by
OWL), you can place other windows on top of it and cover it.  When these
windows move or disappear, the graphical image becomes visible again.

Each application has one background window, which is the size of the entire
display.  This window has a buffer associated with it that is large enough to
store a display-size image.  When you run a C-scape program with a background
window, the contents of the display are saved in it before any C-scape output
is generated.  This allows you to save the images on the display before your
program starts and use them as a backdrop.  For a graphics applications, the
background window is a graphics window (grwin); in text mode applications, it
is a character map window (cmwin).  Under most circumstances, you don't need a
background window, in which case, you can set it to FNULL.

When you call disp_Init, use the function's second argument to create a
background window.  To create a grwin type:

   disp_Init(def_ModeGraphics, grwin_Class);


A grwin is a special version of a pixel map window (pmwin).  Like a pmwin, it
contains a pixmap in which it stores a graphical image.  Unlike a pmwin, it can
save its contents by processing a WINM_SAVE message.  Immediately before any
part of it is obscured, the grwin receives a WINM_SAVE message and saves its
area(s) that are to be covered.  When the obscuring window is moved or closed,
the grwin paints its pixmap to the display, thus restoring the image.

If you draw directly to an area of the display where a grwin is exposed, what
you have drawn will overwrite that portion of original pixmap image.  This does
not happen immediately, but when another window is placed on top of the grwin.
At that point, the save message is sent by the Window Manager and the grwin
updates its pixmap.  When you remove the other window, the new graphics image
of the grwin is automatically restored.

This method is simple and easy, but has two disadvantages.  Because a
background window is a display-size window, its pmap buffer must be large
enough to store an entire display of data.  This can use a great deal of
memory.  (See the table PC Graphics Modes under OWL, below.)  Also, you cannot
paint to those parts of the background window that are currently obscured, only
those parts that are visible.

Refer to demograf.c for an example that uses this technique.

2.3  win_Grab

The background grwin is convenient, but uses a great deal of memory.  If you
wish to use an image that is not the size of the entire display, you can use a
smaller window to hold it.  A smaller window means that the associated pixel
map (pmap) buffer occupies less memory.

Note that instead of a grwin, we use a pmwin.  Unlike a grwin, a pmwin does not
process the WINM_SAVE messages.  Instead of these, it uses the win_Grab
function, which you must call explicitly.  win_Grab copies the area of the
video display that corresponds to the window into the pmwin's pixmap.

To put a graphics into a pmwin, first, create the window with win_Open:

   pmwin_type graphwin;
   ocbox box;

   /* set up to open a window that is 21 characters wide and 11 tall */

   box.xmin = 0;
   box.ymin = 0;
   box.xmax = 20;
   box.ymax = 10;

   graphwin = win_Open(pmwin_Class, &box);

win_Open takes two arguments: a window class and an ocbox (Oakland Character
BOX).  An ocbox is a structure that holds the maximum and minimum row and
column values for the window you are opening.  Each of its elements is an
integer value; these values hold the absolute coordinates of the window's edges
on the display.

Having created the pmwin, put the graphics on the display in the area occupied
by the pmwin.  Before you draw to the screen, call disp_Cache, to remove the
mouse cursor from the display; otherwise, it will be part of the pmwin image.
Draw the image on the display.  Call win_Grab to save the image into the
pmwin's pixmap.  Finally, you can return the mouse cursor to the display with a
call to disp_Flush.

   /* hides mouse cursor */
   disp_Cache();

   /* ... draw image with graphic library routines over pmwin ... */

   /* capture into pmwin's pixmap what we drew */
   win_Grab(graphwin);

   /* restore mouse cursor */
   disp_Flush();


Remember, the pmwin must be completely unobscured when you draw the graphics
over it and grab it; the obscured parts of the window will not be grabbed.  The
size of a pmap is fixed by the size of the window when the window is opened.
If you resize the pmwin, its pmap will not change size to reflect the new
window size.

A pmwin can scroll through its pixmap or be resized to be smaller or larger
than the pixmap.  To scroll the window you should attach a border with scroll
bars such as bd_sidebar, bd_mouse or bd_mouse2.  If you make a window larger
than its pixmap, the extra area is filled with the background color of the
window.  You may set this attribute with win_SetAttr (the first argument is a
win_type; the second, a byte attribute).

Refer to demograb.c for a sample application that uses this technique.

2.4  Loading PCX file images

Every method we have discussed so far involves writing to the screen directly.
C-scape also allows you to use graphical images that are stored in and
retrieved from files; on the PC, C-scape supports the use of PCX files.  The
PCX file image format developed by Z-Soft Corporation is flexible and has
gained wide acceptance.

Files in other formats may be converted to PCX format by third party utilities,
which are often available on electronic bulletin boards and networks.  If you
need more information about the details of PCX file format and such utilities,
refer to the file pcxspec.txt on your C-scape disk 1 or contact Z-Soft:

   Z-Soft Corporation
   450 Franklin Road, Suite 100
   Marietta, Georgia  30067

   [phone] telephone
   [phone] fax


To display a PCX file, use a pmwin (pixel map window).  As OWL objects, pmwins
use win_ commands.  (Consult the demonstration program demopcx.c as a guide to
loading and displaying PCX file images.)

Before you can use a PCX file, you must initialize the PCX file interface by
calling pmap_IoInit:

     void pmap_IoInit()


Next, call ocolmap_Open.  This creates a color map that can hold the range of
colors that are necessary to create the image.  This routine takes an index, firstpix, and the
number of entries the color map will have, nentries.  It returns a color map
with the entries set to black (or NULL, if the range of the map is outside that
of the system hardware's default palette).

     ocolmap_type ocolmap_Open(firstpix, nentries)
        opixval         firstpix;
        unsigned        nentries;


To load a map from a PCX file opened in "rb" (read binary) mode, call
pmap_Load.  Note that win_Open does not allocate a pmap when it opens a pmwin.
pmap_Load reads the .pcx file, initializes your color map, allocates a pmap,
and loads the pmap with the PCX file image; it returns a pointer to the pmap it
has created.

     pmap_type pmap_Load(fp, crange)
        FILE            *fp;
        ocolmap_type    crange;


After you've loaded the pmap with pmap_Load, you can set the palette, if you so
please.  Having both loaded the pmap and set the palette, you can destroy
the color map:

     void ocolmap_Close(crange)
        ocolmap_type    crange;


After opening a pmap, attach the pmap to the pmap window with pmwin_SetPmap:

     void pmwin_SetPmap(win, pmap)
        win_type        win;
        pmap_type       pmap;


At this point, you can paint the window to the display with win_Employ.

You can refresh the display of a pmap window with win_Paint.  To paint the
border, a shadow, and the window, call bord_Paint.  In general, win_ routines
affect only the window; bord_ routines affect the window and border.  If the
pmwin is a bob, you must call sed_Repaint.

The pmap is the pmwin's associated data store that determine what is painted to
the display.  (seds are similar, in that the sed, menu, and field data
structures tell a sed what to paint.)

You can alter a pmwin's pmap by writing directly to the display and then
calling win_Grab.  For example, with the routines from a graphics library, you
draw to the video display in the area over a pmwin.  If you then call win_Paint
on the pmwin, the pmap will refresh itself and obliterate the changes to the
display; if you don't call win_Paint and, instead, call win_Grab, the image on
the display (where it falls within the exposed pmap) will be saved into the
window's pmap.  After grabbing, you may move the pmap window and repaint it.
The image you made by drawing over the pmap will then be a permanent part of
the pmap window appearance.

When you finish using a pmap, remove it with pmap_Close.  Set the pmwin's
pointer to the map to NULL with the following call:

     pmwin_SetPmap(win, NULL)


Next, destroy the pmwin with win_Close.  win_Close will not deallocate the
associated pmap.  You must call pmap_Close explicitly:

     boolean pmap_Close(pmap)
        pmap_type;


If you have a pmwin and need to get its pmap (to close it, for instance), call
pmwin_GetPmap:

     pmwin_GetPmap(win);

You can also save the pmap of a pmwin (or a grwin) to a file in PCX format by
calling pmap_Save.  This routine saves the pmap with its configuration of
pixels and planes.  Remember to open the file into which you
are saving the pmap in "wb" (write binary) mode.  You must also pass the
function an ocolmap, for storing the image's color range.

   boolean pmap_Save(fp, pmap, cmap)
       FILE *fp;
       pmap_type pmap;
       ocolmap_type cmap;

This function returns TRUE if it is successful.

2.5  Multiple device interfaces

Occasionally, you may want to run your application's data entry screen in text
mode and switch to graphics mode to show graphical images; for example, this
will make your application more efficient if your graphics hardware is very
slow.

To swap between text and graphics modes in a C-scape application, you need to
create two separate device interfaces.  Since only one device interface can be
current at one time, you must call disp_Init for one mode first, save the
current device interface with disp_GetCurrent, and then call disp_Init for the
other mode.  You then swap back and forth between the two device interfaces
with disp_SetCurrent.

Each device interface has its own Window Manager and set of windows.  A window
created under one device interface does not exist under the other device
interface.  If you wish to have a similar window under text and graphics modes,
you must create separate copies of the windows for each mode.

For example, you would begin by opening the text device interface:

    disp_Init(def_ModeText, FNULL);


Next, save a pointer to the text interface:

    VOID *textdisp;

    textdisp = disp_GetCurrent();


disp_GetCurrent shuts down the current interface without closing it.  You
should call it only when you are about to make another interface current.  This
means that you must immediately create the graphics mode interface:

    disp_Init(def_ModeGraphics, FNULL);


To change back to the text interface, save a pointer to the graphics mode
interface and make the text mode interface current again:

    VOID *grafdisp;

    grafdisp = disp_GetCurrent();

    disp_SetCurrent(textdisp);


We can now use C-scape in text mode.  If we want to put up windows in graphics
mode, we shut down the text interface and set the current device interface to
the graphics interface:

    textdisp = disp_GetCurrent();

    disp_SetCurrent(grafdisp);


You can also use this technique to drive two displays at once.  If your PC has
both a graphics and text display, the text interface will communicate with the
text display and the graphics interface will communicate with the graphics
display.

Note: This technique is not the best way to mix text and graphics.  Maintaining
two device interfaces requires more memory than running the whole application
in graphics mode.

See demoswap.c for an example of this type of application.

2.6  Compiling the demo programs

demograf.c, demograb.c, demopcx.c, and demoswap.c use window classes that
contain image maps of video data.  Because these programs need substantial
amounts of memory to store the image data, you must compile these in large
memory model or they will not run.  See the table below for more information
about memory use in the various graphics modes.

2.6.1 democlok.c:

democlok.c (for use with the Microsoft C and Borland Turbo C versions of
C-scape 3.2, only[--]their graphics libraries comprise part of the code)
displays a clock with hour, minute and sweep second hands.  The clock is
created using a userwin_Class window.   A userwin allows the application
programmer to control both painting the window and the window's response to
win_Go.  You can move, resize, and top the window; the clock image is scaled to
the window size.

You can only run democlok on a system capable of supporting graphics.  You must
have a graphics hardware capabilities and your run-time library must support
your particular graphics hardware.  For example, although C-scape supports the
Hercules card, Microsoft does not.  In this case democlok fails.  Note that on
some CGA systems you may have to run the DOS-supplied utility GRAFTABL.COM to
load the graphics character set.

The Turbo version of democlok looks for the Borland .BGI graphics driver files
in the \TC directory and the directory in which you run it.  You can change
this search path by changing the constant BGI_PATH in democlok or by setting
the environment variable "BGIPATH" on the DOS command line.  For example:

     set BGIPATH=c:\tc\bgi


2.6.2 demodraw.c:

demodraw.c (for use with the Microsoft C and Borland Turbo C versions only)
demonstrates a simple way drawing graphics over top of a C-scape window without
opening a graphics window.   It uses either the Microsoft or Turbo graphics
libraries to draw the graphic images.

You can only run demodraw on a system capable of supporting graphics.  You must
have graphics hardware capabilities and your run-time library must support your
particular graphics hardware.  Note that on some CGA systems you may have to
run the DOS-supplied utility graftabl.com to load the graphics character set.

The Turbo version of demodraw looks for the Borland .BGI graphics driver files
in the \TC directory and the directory in which you run it.  You can change
this search path by changing the constant BGI_PATH in demodraw.c or by setting
the environment variable "BGIPATH" on the DOS command line.  For example:

     set BGIPATH=c:\tc\bgi


2.6.3 demograf.c:

demograf.c (for use with the Microsoft C and Borland Turbo C versions of
C-scape 3.2, only) demonstrates how C-scape screens can be placed on top of
graphics images displayed in a system background window.  It uses either the
Microsoft or Turbo graphics libraries to draw the graphic images.

You can only run demograf on a system capable of supporting graphics.  You must
have a graphics hardware capabilities and your run-time library must support
your particular graphics hardware.  For example, although C-scape supports the
Hercules card, Microsoft does not.  In this case demograf would fail.  Note
that on some CGA systems you may have to run the DOS-supplied utility
GRAFTABL.COM to load the graphics character set.

The Turbo version of demograf looks for the Borland .BGI graphics driver files
in the \TC directory and the directory in which you run it.  You can change
this search path by changing the constant BGI_PATH in demograf.c or by setting
the environment variable "BGIPATH" on the DOS command line.  For example:

     set BGIPATH=c:\tc\bgi


2.6.4 demograb.c:

demograb.c (for use with the Microsoft C and Borland Turbo C versions of
C-scape 3.2, only) illustrates the use of the win_Grab function to update a
pmap window's PMAP from video display memory.  It uses either the Microsoft or
Borland Turbo C graphics libraries to draw to video display memory.

You can only run demograb on a system capable of supporting graphics.  You must
have a graphics hardware capabilities and your run-time library must support
your particular graphics hardware.  For example, although C-scape supports the
Hercules card, Microsoft does not.  In this case demograb would fail.  Note
that on some CGA systems you may have to run the DOS-supplied utility
GRAFTABL.COM to load the graphics character set.

The Turbo version of demograb looks for the Borland .BGI graphics driver files
in the \TC directory and the directory in which you run it.  You can change
this search path by changing the constant BGI_PATH in demograb.c or by setting
the environment variable "BGIPATH" on the DOS command line.  For example:

     set BGIPATH=c:\tc\bgi


2.6.5 demopcx.c:

demopcx.c demonstrates loading and displaying graphics images stored on disk
using the PCX file format.  This program uses: ABC.PCX, ART.PCX, FACE.PCX, and
GRAPH.PCX.

2.6.6 demoswap.c:

demoswap.c demonstrates changing from text mode to graphics and back.  It uses
disp_GetCurrent and disp_SetCurrent to maintain two device interfaces.

SECTION 3:  Background theory

C-scape allows you to write applications that run in either text or graphics
mode.   Graphics modes allow you to display graphical images and use
non-standard fonts and colors.  To change an application from text mode to
graphics mode, you need only have the disp_Init function initialize a graphics
display mode instead of a text mode.

To help you use graphics images with C-scape, this document provides an
introduction to the elements of graphics under C-scape along with a discussion
of various methods for using graphics images with C-scape.

C-scape currently supports graphics on the PC under DOS and on the Apollo.  We
will contact you to announce the addition of graphics functionality to our
other ports.

3.1  PC Graphics Modes under OWL

On a personal computer using MS-DOS, many graphics modes are available for use
as part of a C-scape application.  Each of these has its own characteristics in
terms of resolution, available colors, and memory use.  Below is a table
describing the various modes:




 Mode           Card        pixels    chars    font    colors    memory use

 pc_Mode4       CGA         320x200   40x25    8x8     4         16,000

 pc_Mode5       CGA         320x200   40x25    8x8     4         16,000

 pc_Mode6       CGA         640x200   80x25    8x8     2         16,000

 pc_ModeD       EGA         320x200   40x25    8x8     16        32,000

 pc_ModeE       EGA         640x200   80x25    8x8     16        64,000

 pc_ModeF       EGA         640x350   80x25    8x14    4         28,000

 pc_Mode10      EGA         640x350   80x25    8x14    16        112,000

 pc_Mode11      VGA         640x480   80x30    8x16    2         38,400

 pc_Mode12      VGA         640x480   80x30    8x16    16        153,600

 pc_Mode13      VGA         320x200   40x25    8x8     256       64,000

 pc_ModeCpq40   Plasma      640x400   80x25    8x16    2         32,000

 pc_ModeHerc    Hercules    720x350   90x25    8x14    2         31,500




In this chart, pixels denotes the display width and height in pixel units;
chars, the display width and height in character units (based on the default
font size); font, the default font character cell size (width x height);
colors, the number of available colors (2 is monochrome); and memory use, the
number of bytes of data needed to represent a full-display size image (this is
the size of the buffer allocated when you request a background window of
grwin_Class in the disp_Init).

3.2  def_ModeGraphics

When you initialize the display, you can select a particular graphics mode
(such as pc_Mode12 or pc_Mode13 on a PC) or you can allow def_ModeGraphics to
select the highest resolution graphics mode available:

On the PC, def_ModeGraphics selects modes in this order: pc_Mode12, pc_ModeF,
pc_Mode10, pc_Mode11, pc_ModeCpq40, pc_ModeHerc, pc_Mode6.  (Mode 12 has
highest priority; mode 6, lowest.)

3.3  High Resolution and non-standard video cards for the PC

On the PC, C-scape contains drivers for the standard CGA, EGA and VGA cards.
If you have a CGA, EGA or VGA card that is non-standard or a special
high-resolution video setup you may still be able to use C-scape with it
without having to write a driver yourself.

Metagraphics Software Corporation produces a sophisticated graphics library
called MetaWINDOW.  This libray includes drivers for a broad range of output
devices.  Oakland has a version of C-scape that will work with the MetaWINDOW
library to allow you to run on non-standard PC video hardware.  You may contact
Metagraphics for a list of display adapters they support:

   Metagraphics Software Corporation
   269 Mount Hermon Road
   P. O. Box 66779
   Scotts Valley, CA 95066

   [phone] telephone
   [phone] fax


Contact Oakland Group, Inc. for the price and availability of the MetaWINDOW
version of C-scape.

3.4  Additional graphics pages

C-scape does not use multiple graphics pages or Extended Memory Support.

3.5  Fonts

For PCs, OWL uses only one font of the default font size for a particular
display mode.  disp_Init uses a BIOS call to ascertain the default font table
on the video hardware card.  Thereafter, C-scape forgoes the BIOS and writes
directly to video memory when plotting text; this improves performance, as
direct video writes are faster than BIOS calls.

On VGA and EGA cards, C-scape allows you to use a non-standard font (if you
know how to program the card or have a utility to do so); if you change to a
new font from the default prior to disp_Init, C-scape will use the new font
when it calls disp_Init.  With the Hercules card, the fonts that C-scape uses
are hard coded into the assembler files and cannot be changed.

Although OWL uses whatever font is on the video card, it assumes that the
character cell size of the font is standard.  (See the table, above, for the
standard character cell sizes for the PC graphics modes supported by OWL.)  If
your card has a non-standard font, then you must inform OWL of the size of the
character cell.  After calling disp_Init, get a pointer to the display mode
font structure and use it to alter the height and width specifications that
will be used when plotting:

   ofont_type font;

   font = disp_GetDefFont();
   font->real.width = 8;       /* sets the character cell width of font */
   font->real.height = 16; /* sets the character cell height of font*/


There is no provision in OWL for proportional fonts; it assumes all character
cells of a font are of uniform size.  On PCs, OWL plots graphic text characters
on the nearest byte boundary.  On the more advanced platforms, the graphic
characters are not so constrained, but may be specified with pixel precision.

Platforms such as Apollo's Domain and Metagraphics support the simultaneous use
of multiple fonts.  Currently, however, OWL allows only one font per window.

3.6  Coordinate Systems

OWL uses coordinate systems to describe both individual windows and the
display.  This allows functions to refer to any position, by using an x and a y
coordinate.

The origin (0,0) of the display coordinate system is the upper-left corner of
the physical display.  The origin (0,0) of the window coordinate system is the
upper-left corner of the window.

3.6.1 Character vs. Pixel Coordinates

Because the window manager operates in both text and graphics modes, OWL uses
two different coordinate units: one based on characters and one based on
pixels.

Character coordinates measure the display in character-sized units.  For
example, a typical display might measure 25 characters tall and 80 characters
wide.

Pixel coordinates are based the number of pixels on the display, which depends
on the display's video adaptor and display mode.  A pixel is the smallest
addressable picture element.  For example, a graphics display might measure
320 pixels wide and 200 pixels tall.

Character coordinates are ints while pixel coordinates are opcoords.  opcoords
are an Oakland data type; they are signed integers.


 Character coordinate function arguments are used in the order (row, col); for
 pixel coordinates, the order is reversed: (x, y).


Internally, OWL converts everything to pixel coordinates, but its standard
external routines are based on character coordinates:

       win_SetPosition(win, row, col);


Pixel versions of commands are also available:

       win_SetPixPosition(win, x, y);


You can convert from character coordinates to pixel coordinates by multiplying
by the pixel height and width of a single character.  You can determine the
height and width of a character with win_GetFontHeight and
win_GetFontWidthWidth.  For x coordinates, use the font width; for y
coordinates, use the font height:

    pixel_xpos = win_GetFontWidth(win) * char_xpos;
    pixel_ypos = win_GetFontHeight(win) * char_ypos;


You can convert from pixel coordinates to character coordinates by dividing by
the pixel height and width of a single character.  You can determine the
height and width of a character with ofont_GetHeight and ofont_GetWidth.  For
x coordinates, use the font width; for y coordinates, use the font height:

    char_xpos = pix_xpos / win_GetFontWidth(win);
    char_ypos = pix_ypos / win_GetFontHeight(win);


If you convert between pixels and characters (in either direction) on a
text-based display, these functions still work, since a character is
considered to be 1 pixel wide and 1 pixel tall in text mode.  This is
consistent with the notion that a pixel is the smallest addressable element on
the display.

3.6.2 Coordinate Data Structures and Types

OWL provides several structures for describing points and screen regions in
both character and pixel coordinates.  The following structures exist: ocbox,
ocsize_struct, ocpos_struct, opbox, opsize_struct, opoint.

An ocbox (Oakland Character BOX) describes a rectangle in character
coordinates.  It contains the following elements:

    toprow     the top-most row of the rectangle.

    leftcol    the left-most column of the rectangle.

    botrow     the bottom-most row of the rectangle.

    rightcol   the right-most column of the rectangle.



It is defined as follows:

    typedef struct {
       int leftcol;
       int rightcol;
       int toprow;
       int botrow;
    } ocbox;


An opbox (Oakland Pixel BOX) describes a rectangle in pixel coordinates.  It
contains the following elements:

    xmin       the left-most edge of the rectangle.

    ymin       the top-most edge of the rectangle.

    xmax       the right-most edge of the rectangle.

    ymax       the bottom-most edge of the rectangle.



It is defined as follows:

    typedef struct {
       opcoord xmin;
       opcoord xmax;
       opcoord ymin;
       opcoord ymax;
    } opbox;


An ocsize_struct (Oakland Character SIZE structure) describes the size of a
rectangle in character coordinates.  It contains the two elements:

    height     the height of the rectangle in characters

    width      the width of the rectangle in character



It is defined as follows:

    typedef struct {
       int height;
       int width;
    } ocsize_struct;


An ocpos_struct (Oakland Character POSition structure) describes the position
of a point in character coordinates.  It contains the two elements:

    row        vertical position relative to the origin (display or window)

    col        horizontal position relative to the origin (display or window)



It is defined as follows:

    typedef struct {
       int row;
       int col;
    } ocpos_struct;


An opsize_struct (Oakland Pixel SIZE structure) describes the size of a
rectangle in pixel coordinates.  It contains the two elements:

    height     the height of the rectangle in pixels

    width      the width of the rectangle in pixels



The values of the height and width are odims, an Oakland data type.  An odim is
an unsigned int used for measuring (in pixels) dimensions of structures and
distances between coordinates.

The structure is defined as follows:

    typedef struct {
       odim height;
       odim width;
    } opsize_struct;


An opoint (Oakland POINT) describes the position of a point in pixel
coordinates.  It contains the two elements:

    x          the horizontal position of the point, relative to the origin

    y          the vertical position of the point, relative to the origin



These values are in opcoords, an Oakland data type.  An opcoord is an int used
for describing signed pixel coordinates.

The structure is defined as follows:

    typedef struct {
       opcoord x;
       opcoord y;
    } opoint;


There are functions for manipulating these structures:

    pixels            characters        function description

    opbox_GetWidth    ocbox_GetWidth    returns the width of the box.

    opbox_GetHeight   ocbox_GetHeight   returns the height of the box.

    opbox_copy        ocbox_copy        makes a copy of a box.

    opbox_trans       ocbox_trans       translates a box vertically and
                                        horizontally.

    opbox_equal       ocbox_equal       tests if two boxes are equal.

    opbox_set         ocbox_set         sets the positions of the corners of a
                                        box

    opoint_copy                         makes a copy of a point.

3.7  Painting



3.7.1 Paint data

A ptd_struct is a paint data structure.  The Window Manager passes it as the
indata argument to a window class function along with a paint message.  It
contains the following elements:

    win        The window that holds the area to be painted.

    relboxp    A pointer to an opbox that describes the rectangle to be
               painted.  The coordinates of the opbox are relative to the
               window.

    emsgdata   Extra message data used by the OWL to handle window scrolling.



Remember that the window manager only asks windows to paint areas of the
display in which they are visible.  This area may include the window's border.

A ptd is defined as follows:

    typedef struct _ptd {
       obj_type    win;
       opbox       *relboxp;
       VOID        *emsgdata;
    } ptd_struct;


The paint data structure describes a rectangular area of the display, occupied
by a window, that must be painted.  It is the responsibility of the window
class or the auxiliary function to paint only within this rectangle.

The function ptd_Clear clears a ptd rectangle to a specified color.  The
function ptd_SetInner copies and clips the ptd rectangle to exclude any of the
window's border area.  For more information, see the function reference at the
end of this document.

3.7.2 User painting

Once you have opened a window, you place it on the display by calling
win_Employ.  This function moves an an unemployed window to the top of the
employed list and paints it to the display.  You can then refresh the window by
calling win_Paint.

Both these functions cause the Window Manager to send a message to a window to
paint itself.  The principal difference between win_Employ and win_Paint is
that the latter has no effect on a window that is unemployed.

Other actions that affect the display, such as moving, resizing, or topping a
window are handled by the Window Manager.  The Window Manager keeps track of
which areas of which windows are visible on the display.  When you move a
window and obscured windows become exposed or visible ones obscured, the Window
Manager sends the appropriate messages to the windows involved.

Fully obscured windows are passed no paint messages.  Partially obscured
windows are painted in several steps.  For example, suppose there are two
employed windows, window1 and window2:


                                     b

      window1->      a


                                                             <- window2




When you call win_Paint on window2, it is completely painted with one call to
its class function.  window1, however, is obscured by window2.  When you call
win_Paint on it,  the Window Manager breaks the window up into two "tiles," a
and b, and sends two paint messages to the window class function, one for tile
a and the other for tile b.  This ensures that any activity within window1 will
not disturb window2.

When the Window Manager sends paint message to window's class function, it
passes a pointer to a ptd_struct (paint data structure) as the message indata
parameter.  A ptd_struct contains (1) a pointer, win, to the window being
painted and (2) a pointer, relboxp, to an opbox structure.  The opbox describes
the coordinates (relative to the window) of the rectangular region that the
window class function will paint.

There are 2 paint messages that may be sent:  one for painting the normal areas
of the object and one for painting the shadowed areas.

Every window object has a user paint flag. If the application programmer has
sets the user paint flag to TRUE with win_SetUserPaint, then the WINA_PAINT and
WINA_SHADOW messages are sent the the object's auxiliary function.  These
messages are sent after the window object has performed its default painting
and before the window border, if any, is painted.

All but one object class handles its own painting--the userwin_Class.   By
default, all objects except userwins have their user paint flags off; the
userwin's default setting is on.  Thus, it is entirely up to the userwin's
auxiliary function to paint the window (see the democlock example).

3.8  Attributes and colors

When you use C-scape's routines for color handling, you are actually
manipulating pairs of colors, since you are setting or getting a foreground
color and a background color simultaneously.  This pairing of a foreground
color and a background color is called an attribute, which uses a byte's worth
of space.  Each attribute is an index into a table called the attribute map,
which has a fixed size of 256 entries.  Each entry consists of a foreground
color and a background color.

The colors in the attribute map come from the hardware palette.  The number of
available colors and their particular hues depends upon the hardware.  (If
C-scape's color representation were to draw directly from the hardware palette,
then the color denotation for red on one system might correspond to blue on
another.)  The attribute map allows OWL to map C-scape colors (in the form of
attributes) to the actual colors provided by the hardware.

OWL keeps a list of the hardware colors that it uses.  This list is called an
ocolmap (Oakland Color MAP) and represents the hardware palette (or a portion
of it).  The ocolmap both represents the hardware palette and serves as a
working space for color map operations.  The number of colors in the map is
device dependent and limited by the number of available colors on the hardware.

Within the ocolmap, OWL denotes each color with an unsigned int, mapping each
color to a red, blue, and green (RGB) triplet.  A color is thus an index into a
table of RGB values.  The RGB values represent the relative levels of the red,
green and blue components that determine a color.

3.8.1 The attribute map

When you start an application, OWL creates an attribute map for each device
interface.  You read from and write to the attribute map with disp_GetMapEntry
and disp_SetMapEntry.  (Note: The interface to these functions is improperly
documented in the C-scape Function Reference.  The correct function interface
for each appears below.  opixval is currently typedef'd to be an unsigned int.)

To look up a value in an attribute map, use disp_GetMapEntry:

    void disp_GetMapEntry(byte attr, opixval *bg, opixval *fg);

This routine takes the value attr; it returns the background and foreground
colors in the variables bg and fg, respectively.  Note that bg and fg are
passed by reference.

To change a value in the attribute map, call disp_SetMapEntry:

    void disp_SetMapEntry(byte attr, opixval bg, opixval fg);

This routine sets the entry attr in the attribute map to background color bg
and foreground color fg.

disp_GetColors returns the number of colors available on a system.  You can use
disp_MapMono to adjust the attribute map for a monochrome system (if
disp_GetColors returns 2L).

    long disp_GetColors(void);

    void disp_MapMono(boolean mono);


If the display is monochrome, then disp_MapMono sets the map appropriately, by
making a set of calls to disp_SetMapEntry.

3.8.2 The ocolmap color map

A color map is an Oakland data structure used in operations involving the
system hardware palette of colors.  It represents a range of colors and their
associated RGB components.  You only want to use a color map when you wish to
manipulate colors on your hardware.

These are the elements of the color map:

    firstpix            The color index of the first color in the map.  The
                        firstpix color specifies the starting place in the
                        system hardware palette for the map's range of
                        colors.  Subsequent entries have contiguous and
                        sequential index values (the first color has the index
                        firstpix, the second, firstpix + 1, and so on).

    nentries            The number of colors represented in the map.

    rgbs[nentries -1]   An array of RGB (red-green-blue) triplets.  The first
                        value in the array is zero (in case firstpix has a
                        value greater than zero).  The triplet for the
                        firstpix color is rgbs[0]; the triplet for the last
                        color in the map is rgbs[nentries - 1].

                        The values of a triplet represent the relative levels
                        of the red, green, and blue components of a particular
                        color.

Each cell of the rgbs array is an orgb_struct structure, which has one member:
rgb.  rgb is a 3 celled array of bytes: the red component is rgb[ORED], the
green component is rgb[OGREEN], the blue component is rgb[OBLUE].  See the
functions below for retrieving and setting the RGB triplet of a color.

firstpix must be a value greater than or equal to zero and should be less than
the number of colors available on the system hardware palette.  For example, on
a PC with VGA video hardware with a palette of 16 colors, valid firstpix values
range from 0 to 15.  Likewise, firstpix + nentries should not exceed the
numbers of colors available in the hardware palette.  Again, assuming a VGA
with 16 colors, a color map with firstpix of 8 and nentries 7 would constitute
a valid range of colors.  This map could be used to represent the latter half
of the 16 color range.

While the attribute table has a fixed size (256 entries), the size of a color
map is effectively limited only by the size of the hardware palette.

You can get a copy of the current system palette with disp_GetColMap.  You can
alter the current system palette (change the hardware palette) with
disp_SetColMap.  You can get a pointer to the default system palette (i.e., the
initial values of the palette) with disp_GetDefColMapp.  If you wish to restore
an altered palette to the default, then call disp_SetColMapDefault.

If you are using color maps, there are some other functions that may be of use
to you.

The ocolmap_Open function allocates a colormap of nentries.  The first color in
the map has the index firstpix; the last color has the index (firstpix +
nentries - 1).  A pointer to the color map is returned.

    ocolmap_type ocolmap_Open(opixval firstpix, unsigned nentries);


The ocolmap_Close function frees the storage for the given colormap.

    void ocolmap_Close(ocolmap_type cmap);


The ocolmap_setpixrgb function sets the RGB values of a specific color ipix in
the given colormap cmap.  red, green, and blue are the RGB values,
respectively.  (In the current implementation olevel is type defined to be a
byte.)  ipix should be greater than or equal to the color map's firstpix and
less than nentries.

    void ocolmap_setpixrgb(ocolmap_type cmap, opixval ipix,
        olevel red, olevel green, olevel blue);


The ocolmap_entry function allows you to read the RGB triplet for a given
color.  colmap is the colormap from which you wish to read the colors.  opix is
the index of the color whose red green and blue values you wish to read.

    orgb_struct *ocolmap_entry(ocolmap_type colmap, opixval opix);

The RGB values are returned by a pointer to an orgb_struct, which has one
member: rgb.  rgb is a 3 celled array of bytes: the red component is rgb[ORED],
the green component is rgb[OGREEN], the blue component is rgb[OBLUE].  The
following functions return the red, green, and blue components of the RGB
triplet for the color ipix:

     olevel ocolmap_pixred(ocolmap_type cmap, opixval ipix);
     olevel ocolmap_pixgreen(ocolmap_type cmap, opixval ipix);
     olevel ocolmap_pixblue(ocolmap_type cmap, opixval ipix);

The function ocolmap_set copies the source color map scmap into the destination
map dcmap.  If the source is larger than the destination only the first portion
of the source equal to the size of the destination is copied.  If the source is
smaller than the destination map the latter portion of the destination map is
unaffected.  If either map is NULL or empty, nothing is copied.

    void ocolmap_set(ocolmap_type dcmap, ocolmap_type scmap);

The function ocolmap_samecolor compares two colors.  It returns TRUE if the RBG
values of scolor in the source map scmap is the same as those of dcolor in the
destination map dcmap; FALSE, otherwise.  dcmap and scmap may be the same map.

    boolean ocolmap_samecolor(ocolmap_type scmap, opixval scolor, ocolmap_type
        dcmap, opixval dcolor);

The ocolmap_getcolor function copies the RBG triplet of a single color scolor
in the source map scmap to that of the color dcolor in the destination map
dcmap.  dcmap and scmap may be the same map.  This routine returns TRUE if it
is able to copy the color; FALSE, otherwise (if the colors were out of range of
either map, for example).

    boolean ocolmap_getcolor(ocolmap_type scmap, opixval scolor, ocolmap_type
        dcmap, opixval dcolor);

3.9  All about pixel map windows

Pixel map windows (pmwins) are windows of the pmwin_Class.  A pixel map (pmap)
is a bit map image of video ram.

On the PC, each video mode requires a certain amount of storage (bits) for
representing a each pixel.  This is the "bits per pixel" count.  On a
monochrome system, you need only one bit per pixel, since it is either on or
off.  "On" may be represented as white, while "off" is black.  Systems with
grey scales or color require additional bits to represent intensity or
particular colors.

The storage method for a pixel's bitmap also affects how a pixel appears in
video memory.  The bits that represent a pixel are either stored contiguously
or arranged in multiple "planes."  Let's use, as an example, a color system
that 2 bits per pixel.  For contiguous storage, bits 1 and 2 of pixel 1 appear
contiguously in memory; they are then followed by bits 1 and 2 of the next
pixel (and so on).  For storage with multiple planes, bit 1 of pixel 1 is
followed by bit 1 of pixel 2, and so on, until bit 1 of the last pixel.  After
this chunk of memory,  the second plane starts; this holds bit 2 of pixel 1,
bit 2 of pixel 2, and so on.

OWL supports PCX file images for the following display modes:


 Mode           Card        bits per    nplanes     ncolors
                            pixel

 pc_Mode4       CGA         2           1           4

 pc_Mode5       CGA         2           1           4

 pc_Mode6       CGA         1           1           2

 pc_ModeD       EGA         1           4           16

 pc_ModeE       EGA         1           4           16

 pc_ModeF       EGA         1           2           4

 pc_Mode10      EGA         1           4           16

 pc_Mode11      VGA         1           1           2

 pc_Mode12      VGA         1           4           16

 pc_Mode13      VGA/MCGA    8           1           256

 pc_ModeCpq40   Plasma      1           1           2

 pc_ModeHerc    Hercules    1           1           2




Disparate sizes of pmap and file image

When you load a PCX file image with the pmap_Load function, the function tries
to allocate a pmap big enough to hold the image.  If the PCX file image
requires more than 64k bytes to buffer (the current size limit on a pmap), the
image is larger than the pmap and is cropped on the right and bottom.  If an
image is smaller than the pmap, pmap_Load pads the unused areas (the right and
bottom) with 0s.

Disparate sizes of pmwin and pmap

Having loaded an image, use pmwin_SetPmap to attach the pmap to the pmwin
window.  If the pmwin is smaller than the pmap, attach a mouse-sensitive border
with scroll bars (such as bd_mouse, bdmouse2, or bd_sidebar) to the window with
win_SetBorder; this will allow you to scroll through the image.  If the pmap is
smaller than the pmwin, the "bare" area around the image will have the window's
background attribute coloring it.

Using pmap_Open

If you wish, you can open a pmap by calling pmap_Open instead of pmap_Load.
However, this method requires you to find your own way of loading an image into
the pmap.  pmap_Open takes a pixel size specification and creates a pmap
window.  You are returned the window; or, NULL if it could not be opened.

     pmap_type pmap_Open(pixwidth, pixheight)
        odim        pixwidth;       /* this type is currently defined */
        odim        pixheight;      /* to be an unsigned int */


SECTION 4:  Functions

This section describes some common window functions of the OWL.  These
functions are listed here to help you work with grwins, pmwins, userwins and
cmwins, but you can also use them on seds and sleds.

This is because OWL and C-scape are written in an object oriented way.  Objects
like seds are of a sub-class derived from more basic super-class of objects.  A
sub-class of objects inherits the both the data and functionality of its
super-class.

Quite literally, data is inherited because the data structures for sub-class
include the data structure of its parent class as its first member.  For
instance, in the data structure of a sled, the sed data structure is the first
element, followed by sled-specific data.  In turn, the sed data structure's
first member is window data and then the sed_specific data; and so on.

The following diagram shows the relationships among some of the various Oakland
objects:


             common   <- object pointer           (lower level object)
            obj data

            bob data

            win data

             sedwin
              data

                                            (higher level, derived
            sledwin                                            object)
              data




The object pointer in the above diagram may be an obj_type, a bob_type, a
win_type, a sed_type or a sled_type.  They all point to the same root object in
memory.

Not only is it useful to visualize the inheritance of data this way, but that
of an object's functionality.  Just as the data structures of class objects are
nested, so are the object class functions.  Objects perform actions in response
to messages sent to the object's class function.  Derived classes process the
message and then forward it on to their parent class.  The beauty of this is
that objects are reusable, insular and have a uniform interface.

When the Window Manager asks an object to paint itself, it does not need to
worry about what kind of object it is or how the object carries out its task.
For example, to paint an window, it sends the object the WINM_PAINT message.
If the object is a sled, the sled performs its sled-specific task and then
passes the message on up to the sed level and so on.

Any place you would use a higher level object pointer (like sled_type) you
could use a lower level pointer (like sed_type, win_type, obj_type).  Functions
that operate on on lower-level objects can be used on higher-level derived
objects.  For instance, to name a sed you could use the function sed_SetName or
obj_SetName.

However, the converse is not true.  While win_ and obj_ functions are valid on
seds,  sed_ functions are not valid on windows or other objects.
sed_GetFieldNo is sed-specific; it does not work on a pmwin.  seds are windows
but windows are not necessarily seds.

Here is tree diagram that describes the relationship of the various classes:

    common

        border

            bd_1

            bd_2

            (... other borders)

        bob

            ufunc

            win

                userwin

                cmwin

                pmwin

                    grwin

                sed

                    sled

The table below lists some common sed operations that have window equivalents.
If just the OWL function name is given, then the function interface is the same
as the C-scape function.  If the interface is different or there is no one
function equivalent then the function prototype is given for each OWL function
involved.  In some cases, there is no simple OWL equivalent so a short line or
two of code is provided to show how to achieve the affect.

Note: You can use the following window functions on objects of sed_type; but
you cannot use sed functions on objects of win_type.

C-scape usage            OWL usage



sed_BorderExists         test the return value of this function:

                             (win_GetBorderFunc(win) != FNULL)

sed_BorderPrompt         use this code:

                             bord_SendMsg(win, BDM_PROMPT, (VOID *)title, NULL);

                             /*
                             win is of win_type
                             BDM_PROMPT is a pre-defined message
                             title is a character string
                             */

sed_Center               win_SetPosition(win, (disp_GetHeight() -
                             bord_GetHeight(win)) / 2, (disp_GetWidth() -
                             bord_GetWidth(win)) / 2);

sed_Close                win_Close

sed_CreateBob            win_CreateBob

sed_GetAncestor          bob_GetAncestor

sed_GetBordCorners       bord_GetTopRow
                         bord_GetLeftCol
                         bord_GetBotRow
                         bord_GetRightCol

sed_GetBorderColor       bord_GetAttr

sed_GetBorderHeight      bord_GetHeight

sed_GetBorderWidth       bord_GetWidth

sed_GetColors            win_GetAttr

sed_GetCorners           win_GetPosition

sed_GetHeight            win_GetHeight

sed_GetPosition          bord_GetTopRow
                         bord_GetLeftCol

sed_GetSize              win_GetHeight
                         win_GetWidth

sed_GetWidth             win_GetWidth

sed_Open                 win_Open

sed_Pop                  win_Unemploy

sed_Repaint              win_Employ, win_Paint

sed_RepaintBorder        bord_Paint

sed_SetBorder            win_SetBorder

sed_SetBorderColor       bord_SetAttr

sed_SetBorderFeature     bord_SetFeature

sed_SetBorderTitle       use this code:

                             bord_SendMsg(win, BDM_SETTITLE, (VOID *)title, NULL);

                             /*
                             win is of win_type
                             BDM_SETTITLE is a pre-defined message
                             title is a character string
                             */

sed_SetColors            win_SetAttr

sed_SetExplode           win_SetExplode

sed_SetHeight            win_SetSize

sed_SetMouse             win_SetMouse

sed_SetMouseCode         disp_SetMouseCode

sed_SetNextWin           win_SetNextWin

sed_SetPosition          win_SetPosition

                         (Note: win_GetPosition has a different interface)

sed_SetShadow            win_SetShadow

sed_SetShadowAttr        win_SetShadowAttr

sed_SetSize              win_SetSize

sed_SetWidth             win_SetSize

sed_Top                  win_Top

sedwin_ClassInit         win_ClassInit

                         (Note: If you are using sedwin_ClassInit then
                         this is redundant)


bord_GetAttr                                           Get a border's attribute


---------

Synopsis

byte bord_GetAttr(win)

   win_type win;              /* the window object */

Description

This routine gets the attribute of the border associated with window win.  The
attribute determines the foreground and background colors used to display the
border, its title, prompt, and any associated parts.  If there is no border
attached to win, then the attribute 0x00 is returned.

Return Value

A byte denoting the border attribute is returned.

Note

This routine is implemented as a macro.

See Also

bord_SetAttr



bord_GetBotRow - bord_GetTopRow            Get the position of a border's sides

---------

Synopsis

int bord_GetBotRow(win)

   win_type win;              the window object

int bord_GetLeftCol(win)

   win_type win;

int bord_GetRightCol(win)

   win_type win;

int bord_GetTopRow(win)

   win_type win;

Description

These functions are used to retrieve the position of the sides of a window's
border.  The position is specified in display relative character coordinates.

If the window has no border the position of the window's sides are returned.

Return Value

An integer is returned denoting the row or column position of the border's
side.



bord_GetHeight                                            Get a border's height

---------

Synopsis

int bord_GetHeight(border)

   win_type border;           the window which has the border

Description

This routine returns the height of win's border.  The width is specified in
character coordinates.  If the window has no border the height of the window is
returned.

Return Value

Returns the height of the border.

See Also

bord_GetWidth

Note

This routine is implemented as a macro.



bord_GetWidth                                              Get a border's width

---------

Synopsis

int bord_GetWidth(border)

   win_type border;           the window which has the border

Description

This routine returns the width of win's border.  The width is specified in
character coordinates.  If the window has no border the height of the window is
returned.

Return Value

Returns the width of the border.

See Also

bord_GetHeight

Note

This routine is implemented as a macro.



bord_Paint                                      Repaint a window and its border

---------

Synopsis

void bord_Paint(win)

   win_type win;              the window object

Description

This function causes all unobscured parts of a window, including its border to
be repainted on the display.  bord_Paint will no effect if the window has not
been employed first with win_Employ.

Return Value

There is no return value.

Note

This routine is implemented as a macro.

See Also

win_Paint



bord_SendMsg                                         Send a message to a border

---------

Synopsis

void bord_SendMsg(win, msg, indata, outdata)

   win_type win;              the window object
   int msg;                the message
   VOID *indata;              incoming data
   VOID *outdata;             outgoing data

Description

This function sends the msg message to the border associated with win.  indata
and outdata are used to pass information to and from the border.  Whether
indata and outdata are used and what type of information is passed is specific
to the message sent.

Return Value

There is no return value.

Note

This routine is implemented as a macro.



bord_SetAttr                             Set the attribute of a window's border

---------

Synopsis

void bord_SetAttr(win, attr)

   win_type win;              /* the window object */
   byte attr;                 /* the attribute of the border to set */

Description

This routine sets the window win's border attribute to attr.  The attribute
determines the foreground and background colors used to display the border, its
title, prompt, and any associated parts.  If the window has no border this
function does nothing.

Return Value

There is no return value.

Note

This routine is implemented as a macro.

See Also

bord_GetAttr



obj_DoAux                                    Call a object's auxiliary function

---------

Synopsis

int obj_DoAux(obj, msg, indata, outdata);

   obj_type sed;                    the object
   int msg;                         the auxiliary message
   VOID *indata;                    pointer to incoming data
   VOID *outdata;                   pointer to outgoing data

Description

This routine calls the object's auxiliary function.  msg is an integer
specifying an action for the auxiliary function to perform.  indata is a
pointer to incoming data to be used by the auxiliary function.  outdata is a
pointer to outgoing data returned by the auxiliary function.  obj_DoAux does
nothing if the object has no auxiliary function.

The auxiliary function provides the programmer with additional control over the
operations of an object.

You can use obj_DoAux to send your own custom messages to an auxiliary
function.  Use the AUX_USER macro to define your message values:

    #define APPLICATION_AUX_MSG        AUX_USER(1)

    /* ... */

    obj_DoAux(obj, APPLICATION_AUX_MSG, NULL, NULL);


Return Value

Returns the value returned by the auxiliary function upon its completion.

See Also

obj_SetAux



obj_Find                                                 Find an object by name

---------

Synopsis

obj_type obj_Find(name);

   char *name;                 the named object which you are seeking

Description

This function finds an object by name.

obj_Find returns a pointer to the named object, if found; NULL, otherwise.  You
can assign more that one object the same name but obj_Find returns a pointer to
only one of them.  If the name is not unique, it returns an object with the
specified name, but not necessarily any particular one.

Return Value

Returns a pointer to the named object, if found; NULL, otherwise.

Note



See Also

obj_SetName, obj_GetName



obj_SetAux                                  Attach an aux function to an object

---------

Synopsis

void obj_SetAux(obj, fun);

   obj_type obj;                    object
   aux_fptr fun;                    auxiliary function

Description

This routine attaches the auxiliary function fun to the given object.  If fun
is NULL the object will have no auxiliary function.

The auxiliary function provides the programmer with additional control over the
operations of an object.

You can use obj_DoAux to send your own custom messages to an auxiliary
function.

All auxiliary functions must have the same form:

int aux_Sample(obj, msg, indata, outdata)
   obj_type sed;
   int msg;
   VOID *indata;
   VOID *outdata;
{
   switch(msg) {
         /* ... */

   }

   return(1);
}

Return Value

There is no return value.

Note

This routine is implemented as a macro.

See Also

obj_DoAux



obj_GetName                                           Get the name of an object

---------

Synopsis

char *obj_GetName(obj);

   obj_type obj;                 the object

Description

This routine find the name of an object.

Return Value

Return a pointer to a null-terminated character arrary denoting the name of the
object, if found; NULL, if the object could not be found.

Note

See Also

obj_Find, obj_SetName



obj_SetName                                           Set the name of an object

---------

Synopsis

void obj_SetName(obj, name);

   obj_type obj;                 the object to name
   char *name;                   the name

Description

obj_SetName names a object.  Use NULL for name to remove an object's name.

Note: obj_SetName returns an integer denoting a handle for the name of the
object.  This handle is an entry in an internal system list and is not
otherwise needed by the C-scape user.

Return Value

Returns a handle to the name in the internal object name list.

Note

When you name objects, their names go into an internal symbol list.  This list
is not closed by disp_Close or obj_Close.  If you want to release the storage
that this list uses, call the function oak_Close after calling disp_Close.  In
most cases, you do not need to call oak_Close.  It has the following prototype:

    void oak_Close(void);


See Also

obj_Find, obj_GetName



ocbox_clippos                              Get the clipping position of a point

---------

Synopsis

unsigned ocbox_clippos(clipcboxp, rowp, colp);

   ocbox *clipcboxp;          the character box by which to clip
   int rowp;                  the point's row position
   int colp;                  the point's column position

Description

This routine returns a Sutherland-type clipcode that denotes where the point,
at location (rowp, colp), is in relation to the given character box clipcboxp.

A clipcode of 0 means the point is within the clipping box, i.e., is within or
on its boundaries.  Values other than 0 mean that the point is outside the
clipping box.  Further, if the clipcode is non-zero its value indicates to
which side(s) of the clipping box the point lies:


                  6               2               3

              (without,       (without,       (without,
             above-left)       above)       above-right)

                  4               0               1

              (without,       (within)        (without,
                left)                          right)

                 12               8               9

              (without,       (without,       (without,
             below-left)       below)       below-right)



Return Value

Returns an unsigned integer denoting the point's position relative to the
character box.

Note



See Also





ocbox_copy                                                 Copy a character box

---------

Synopsis

ocbox *ocbox_copy(dcboxp, scboxp);

   ocbox *dcboxp;             the destination box (copy)
   ocbox *scboxp;             the source box (original)

Description

This routine copies the contents of scboxp into dcboxp.  Both dcboxp and scboxp
point to boxes that are declared by the programmer prior to the call.  The
boxes are specified in character units.

Return Value

Returns a pointer to the copy of the character box, dcboxp.

Note

This routine is implemented as a macro.

See Also

opbox_copy



ocbox_equal                                         Compare two character boxes

---------

Synopsis

boolean ocbox_equal(cboxp1, cboxp2);

   ocbox *cboxp1;             pointer to box specified in character units
   ocbox *cboxp2;             pointer to box specified in character units

Description

This routine compares the two given boxes and determines if they are equal.
The box is given in character units.  The boxes are equal if the xmin, ymin,
xmax and ymax of the respective boxes are equal.

You may use ocbox_equal to determine whether two boxes coincide on the display
or whether they are simply of the same dimensions.

Return Value

Returns TRUE if cboxp1 and cboxp2 are equal; FALSE, otherwise.

Note



See Also





ocbox_GetHeight                               Get the height of a character box

---------

Synopsis

int ocbox_GetHeight(cboxp);

   ocbox *cboxp;              pointer to box specified in character units

Description

This routine returns the height of cboxp.  Both the box and its height are
specified in character units.

Return Value

Returns a integer value denoting the height of the character box.

Note

This routine is implemented as a macro.

See Also

ocbox_GetWidth, opbox_GetHeight, opbox_GetWidth



ocbox_GetWidth                                 Get the width of a character box

---------

Synopsis

int ocbox_GetWidth(cboxp);

   ocbox *cboxp;              pointer to box specified in character units

Description

This routine returns the width of cboxp.  Both the box and its width are
specified in character units.

Return Value

Returns an integer value denoting the width of the character box.

Note

This routine is implemented as a macro.

See Also

ocbox_GetHeight, opbox_GetWidth, opbox_GetHeight



ocbox_pixcoords                          Convert a pixel box to a character box

---------

Synopsis

void ocbox_pixcoords(cboxp, font, boxp);

   ocbox *cboxp;              the character box to convert
   ofont_type font;           the font to use in the conversion
   opbox *boxp;               the pixel box result

Description

This routine takes the character box pointed to by cboxp and supplies its pixel
box equivalent in boxp, given the font.  The font determines the character to
pixel ratio.

Both cboxp and boxp are pointers to boxes declared by the programmer prior to
the call.  The contents of the box to which boxp points will be altered to
contain the results of the conversion.

Return Value

There is no return value.

Note



See Also

win_GetFont, win_GetFontHeight, win_GetFontWidth, opcoord_GetXCol,
opcoord_GetYRow, opcoord_GridRound



ocbox_set                                                   Set a character box

---------

Synopsis

ocbox *ocbox_set(cboxp, toprow, leftcol, bottomrow, rightcol);

   ocbox *cboxp;              a pointer to the box to set
   int toprow;                the box position
   int leftcol;
   int bottomrow;
   int rightcol;

Description

This routine sets the character box cboxp with the given values toprow,
leftcol, bottomrow, and rightcol.  cboxp points to a character box declared by
the programmer prior to the call.  The box delimits a rectangular area by
defining the location of its four sides.

Return Value

Returns a pointer to the box that was set, cboxp.

Note

This routine is implemented as a macro.

See Also

opbox_set



ocbox_trans                                           Translate a character box

---------

Synopsis

ocboxp *ocbox_trans(cboxp, rowd, cold);

   ocbox *cboxp;              the character box to translate
   int rowd;                  the row displacement
   int cold;                  the column displacement

Description

This routine translates the character box cboxp by the displacements rowd and
cold.  The translation reflects a change in the box's position effected by the
addition of the the displacements to its current position.

Return Value

A pointer to a character box is returned - the same pointer passed in as cboxp.

Note

This routine is implemented as a macro.

See Also

opbox_trans



opbox_copy                                                     Copy a pixel box

---------

Synopsis

opbox *opbox_copy (dboxp, sboxp);

   opbox *dboxp;              the destination box (copy)
   opbox *sboxp;              the source box (original)

Description

This routine copies the contents of sboxp into dboxp.  Both sboxp and dcboxp
point to boxes that are declared by the programmer prior to the call.  The
boxes are specified in pixel units.

Return Value

Returns a pointer to the copy of the pixel box, dboxp.

Note

This routine is implemented as a macro.

See Also

ocbox_copy



opbox_GetHeight                                   Get the height of a pixel box

---------

Synopsis

opcoord opbox_GetHeight(boxp);

   oboxp *boxp;               pointer to a pixel box

Description

This routine returns the height of boxp.  Both the box and its height are
specified in pixel units.

Return Value

Returns an value denoting the height of the pixel box.

Note

This routine is implemented as a macro.

See Also

opbox_GetWidth, ocbox_GetHeight, ocbox_GetWidth



opbox_GetWidth                                     Get the width of a pixel box

---------

Synopsis

opcoord opbox_GetWidth(boxp)

   oboxp *boxp;               pointer to a pixel box

Description

This routine returns the width of boxp.  Both the box and its width are
specified in pixel units.

Return Value

Returns an value denoting the width of the pixel box.

Note

This routine is implemented as a macro.

See Also

opbox_GetHeight, ocbox_GetWidth, ocbox_GetHeight



opbox_set                                                       Set a pixel box

---------

Synopsis

opbox *opbox_set(boxp, xmin, ymin, xmax, ymax);

   opbox *boxp;               a  pointer to the box to set
   opcoord xmin;              the box position
   opcoord ymin;
   opcoord xmax;
   opcoord ymax;

Description

This routine sets the pixel box boxp with the given values xmin, ymin, xmax,
and ymax.  boxp points to a pixel box declared by the programmer prior to th
call.  The box delimits a rectangular area by defining the location of its four
sides.

Return Value

Returns a pointer to the box that was set, boxp.

Note

This routine is implemented as a macro.

See Also

ocbox_set



opbox_trans                                               Translate a pixel box

---------

Synopsis

opbox *opbox_trans(boxp, xdisp, ydisp);

   opboxp *boxp;              the pixel box to translate
   opcoord xdisp;             the x axis displacement
   opcoord ydisp;             the y axis displacement

Description

This routine translates the pixel box boxp by the displacements xdisp and
ydisp.  The translation reflects a change in the box's position effected by the
addition of the the displacements to its current position.

Return Value

A pointer to a pixel box is returned - the same pointer passed in as boxp.

Note

This routine is implemented as a macro.

See Also

ocbox_trans



opcoord_GetXCol                          Get character column for pixel x coord

---------

Synopsis

int opcoord_GetXCol(x, font);

   opcoord x;              the pixel x coordinate
   ofont_type font;        the reference font

Description

This routine gets the character column in which the pixel x coordinate lays.
That is, the pixel coordinate is rounded down to the nearest character
coordinate, given the font.

Return Value

Returns a value denoting a character column position.

Note



See Also

win_GetFont, win_GetFontHeight, win_GetFontWidth, opcoord_GetYRow,
ocbox_pixcoords



opcoord_GetYRow                             Get character row for pixel y coord

---------

Synopsis

int  opcoord_GetYRow(y, font);

   opcoord y;              the pixel y coordinate
   ofont_type font;        the reference font

Description

This routine gets the character row in which the pixel y coordinate lays.  That
is, the pixel coordinate is rounded down to the nearest character coordinate,
given the font.

Return Value

Returns a value denoting a character coordinate row position.

Note



See Also

win_GetFont, win_GetFontHeight, win_GetFontWidth, opcoord_GetXCol,
ocbox_pixcoords



opcoord_GridRound                        Rounds pixel position to text boundary

---------

Synopsis

void opcoord_GridRound(xp, yp, font)

   opcoord *xp;               the pixel x coordinate
   opcoord *yp;               the pixel y coordinate
   ofont_type font;           the reference font

Description

This routine rounds the pixel coordinates (*xp, *yp) down to the nearest
character coordinate, given the font.

Return Value

There is no return value.

Note



See Also

win_GetFont, win_GetFontHeight, win_GetFontWidth, opcoord_GetXCol,
opcoord_GetYRow, ocbox_pixcoords



ptd_Clear                                    Clear a paint rectangle to a color

---------

Synopsis

void ptd_Clear(ptd, color);

    ptd_struct *ptd;            paint data
    opixval color;              color to which to clear

Description

This function clears the rectangular area of the display described by the ptd
to the given color.

A ptd_struct contains the following elements:

    win        The window that holds the area to be painted.

    relboxp    A pointer to an opbox that describes the rectangle to be
               painted.  The coordinates of the opbox are relative to the
               window.

    emsgdata   Extra message data used by the OWL to handle window scrolling.



Return Value

There is no return value

Note

opixval is an Oakland data type denoting an index into the system (hardware)
color palette.  It is currently defined to be an unsigned integer.  The
resulting color is dependent on the palette.

See Also





ptd_SetInner                                  Clip a ptd to the window interior

---------

Synopsis

void ptd_SetInner(ptd, inptd, inboxp);

    ptd_struct *ptd;            paint data
    ptd_struct *inptd;          inner paint data return argument
    opbox *inboxp;              clipped box return argument

Description

This function clips away any of the border area included in the opbox of ptd to
within the ptd window's inner box.

This function copies ptd to inptd and sets inptd->relboxp to inboxp.  The
inboxp box is clipped the relbox of ptd and places the result in the inboxp
box.  inptd->relboxp points to inboxp.  The relbox of ptd is unaffected.

A ptd_struct contains the following elements:

    win        The window that holds the area to be painted.

    relboxp    A pointer to an opbox that describes the rectangle to be
               painted.  The coordinates of the opbox are relative to the
               window.

    emsgdata   Extra message data used by the OWL to handle window scrolling.



Return Value

Returns FALSE if the resulting relbox is empty; TRUE, otherwise.

Note

opixval is an Oakland data type denoting an index into the system (hardware)
color palette.  It is currently defined to be an unsigned integer.  The
resulting color is dependent on the palette.

See Also





win_ClassInit                             Initialize the window request handler

---------

Synopsis

void win_ClassInit();

Description

This routine initializes the request handler for the basic window class to
enable support for mouse functions.  The handler affects windows of win_Class,
and all borders.  It permits them to respond to mouse messages that pertain to
scrolling, re-sizing, and dragging.

You only need to call this routine if you want to use the mouse with basic
windows.  It is not necessary if you are not using the mouse--a null handler is
used by default.

Please note, if you have called sedwin_ClassInit for use with C-scape seds,
then you need not call this function.

Return Value

There is no return value.

See Also

hard_InitMouse



win_Close                                                        Close a window

---------

Synopsis

win_type win_Close(winclass);
   win_type win;                       the window object

Description

This routine closes the window and releases any storage it used.  The window
cannot be used after it has been closed.

If the window is employed, win_Close fires it and removes the window's image
from the display.

win_Close releases all the storage used by the objects attached to the window.

Return Value

There is no return value.

See Also

win_Open



win_CreateBob                                            Make a bob of a window

---------

Synopsis

bob_type win_Open(win, mode);
   win_type win;                       the window
   int mode;                       the dependence flag

Description

This routine creates a bob object from a window.

Bobs (basic objects provide a standard interface to a number of different
objects.  Bobs are create from objects, such as windows, that you can place
onto the display and activate.

The mode argument can have one of the following values BOB_DEPENDENT or
BOB_INDEPENDENT.

Bobs allow you to create complex screens consisting of various screen types
working in concert.  This allows you to nest windows (or seds) within seds.
Any C-scape field can contain a handle to a bob object.

Once you have created a bob from a window, you can use the bob_ functions to
control it.

Return Value

Returns the bob object created from the window or NULL if the bob object cannot
be created.

See Also

bob_Go, sed_GetFieldBob



win_Employ                                                      Employ a window

---------

Synopsis

boolean win_Employ(win);
   win_type win;                   the window object

Description

This routine places an unemployed window win at the top of the employed list
and paints it to the display.  The display area over which the window will be
placed is saved if there is a background grwin window.  If the window is
already employed it does nothing and returns TRUE.

If the window's user paint flag has been set, the window's auxiliary function
receives the WINA_PAINT and WINA_SHADOW messages.  These messages are sent to
the auxiliary function after the object class has performed its normal painting
action.

The only window class that performs no default painting is the userwin_Class.
For this window type, the auxiliary message must handle all painting.

Return Value

Returns TRUE if it is successful at employing the window and FALSE if the
window is NULL.

See Also

win_UnEmploy, win_Paint, win_SetUserPaint, win_IsUserPaint



win_GetAttr                                            Get a window's attribute

---------

Synopsis

byte win_GetAttr(win)

   win_type win;              the window object

Description

This routine gets the foreground/background color combination attribute
associated with the given window.

Return Value

Returns a byte value denoting the window's foreground/background attribute.

Note

This routine is implemented as a macro.



win_GetBox                                         Get a window's character box

---------

Synopsis

void win_GetBox(win, cboxp)

   win_type win;              the window object
   ocbox *cboxp;              pointer to box specified in character units

Description

This routine puts the character coordinates of the box occupied by the given
window in the character box pointed to by cboxp.  The coordinates are relative
to the window.

Return Value

There is no return value.

Note

This routine is implemented as a macro.

See Also

win_GetPixBox, win_GetPosition, win_GetPixPosition



win_GetData                               Get the window's generic data pointer

---------

Synopsis

VOID *win_GetData(win);

  win_type win;             the window object

Description

This routine returns the window's generic data pointer.  The generic data
pointer is a VOID * pointer that you can use for attaching program-specific
data to a window.

Return Value

Returns the generic data pointer of the window.  The generic data pointer is a
VOID * pointer.  Use a type cast to convert it to a different type if
necessary.

Note

This routine is implemented as a macro.

See Also

win_SetData



win_GetFont                                               Get the window's font

---------

Synopsis

ofont_type win_GetFont(win);

  win_type win;             the window object

Description

This routine gets a pointer to an ofont_struct describing the window's font.

Return Value

Returns an ofont_type corrsponding to the window's font.

Note

This routine is implemented as a macro.

See Also

win_GetFontHeight, win_GetFontWidth, ofont_GetHeight, ofont_GetWidth,



win_GetExplodeFptr                            Get the window's explode function

---------

Synopsis

exp_fptr win_GetExplodeFptr(win)
   win_type win;                   the window object

Description

This function retrieves a pointer to the explode function of a window.  If
there is no explode function it returns FNULL.

Return Value

Returns a pointer to the window's explode function; FNULL, if no explode
function exists.

Note

This routine is implemented as a macro.

See Also

win_SetExplode



win_GetFontHeight                                  Get the window's font height

---------

Synopsis

opcoord win_GetFontHeight(wint);

   win_type win;              the window object

Description

This routine gets the height of the window's font, in pixels.

Pixel coordinates are based the number of pixels on the display, which depends
on the display's video adaptor and display mode.  A pixel is the smallest
addressable picture element.  For example, a graphics display might measure
320 pixels wide and 200 pixels tall.  On a text based display, a character is
considered to be 1 pixel wide and 1 pixel tall.

Character coordinates are ints while pixel coordinates are opcoords.  opcoords
are an Oakland data type; they are signed integers.

Return Value

Returns of value denoting the height of the given font, in pixels.

Note

This routine is implemented as a macro.

See Also

win_GetFontWidth

win_GetFontWidth                                    Get the window's font width

---------

Synopsis

opcoord win_GetFontWidth(wint);

   win_type win;              the window object

Description

This routine gets the width of the window's font, in pixels.

Pixel coordinates are based the number of pixels on the display, which depends
on the display's video adaptor and display mode.  A pixel is the smallest
addressable picture element.  For example, a graphics display might measure
320 pixels wide and 200 pixels tall.  On a text based display, a character is
considered to be 1 pixel wide and 1 pixel tall.

Character coordinates are ints while pixel coordinates are opcoords.  opcoords
are an Oakland data type; they are signed integers.

Return Value

Returns of value denoting the width of the given font, in pixels.

Note

This routine is implemented as a macro.

See Also

win_GetFontHeight

win_GetHeight                                   Get a window's character height

---------

Synopsis

int win_GetHeight(win)

   win_type win;              the window object

Description

Gets the height of the given window, measured in character units.

Return Value

Returns an integer value denoting height in character units.

Note

This routine is implemented as a macro.

See Also

win_GetPixHeight, win_GetWidth, win_GetPixWidth



win_GetPixBox                                        Get the window's pixel box

---------

Synopsis

void win_GetPixBox(win, boxp)

   win_type win;              the window object
   opbox *boxp;               the pixel box we want

Description

This routine puts the coordinates of the window's upper left and lower right
corners in the given box.  The coordinates are relative to the window, i.e.,
the upper left corner is at (0,0) and are specified in pixel units.

Return Value

There is no return value.

Note

This routine is implemented as a macro.

See Also

win_GetBox, win_GetPosition, win_GetPixPosition



win_GetPixHeight                                    Get a window's pixel height

---------

Synopsis

opcoord win_GetPixHeight(win)

   win_type win;              the window object

Description

Gets the height of the given window, measured in pixel units.

Return Value

Returns an integer value denoting height in pixel units.

Note

This routine is implemented as a macro.

See Also

win_GetHeight, win_GetWidth, win_GetPixWidth



win_GetPixPosition                              Get a window's display position

---------

Synopsis

void win_GetPixPosition(win, opboxp)

   win_type win;              the window object
   opbox *opboxp;             pointer to a box specified in pixel units

Description

This routine puts the coordinates of the window's upper left and lower right
corners in the given box.  The coordinates are relative to the display and are
specified in pixel units.

Return Value

There is no return value.

Note



See Also

win_GetPosition, win_GetBox, win_GetPixBox



win_GetPixWidth                                      Get a window's pixel width

---------

Synopsis

opcoord win_GetPixWidth(win)

   win_type win;              the window object

Description

Gets the width of the given window, measured in pixel units.

Return Value

Returns an integer value denoting width in pixel units.

Note

This routine is implemented as a macro.

See Also

win_GetWidth, win_GetHeight, win_GetPixHeight



win_GetPosition                                 Get a window's display position

---------

Synopsis

void win_GetPosition(win, cboxp)

   win_type win;              the window object
   ocbox *cboxp;              pointer to box specified in character units

Description

This routine puts the coordinates of the window's upper left and lower right
corners in the given box.  The coordinates are relative to the display and are
specified in character units.

Return Value

There is no return value.

See Also

win_GetPixPosition, win_GetBox, win_GetPixBox



win_GetWidth                                     Get a window's character width

---------

Synopsis

int win_GetWidth(win)

   win_type win;              the window object

Description

Gets the width of the given window, measured in character units.

Return Value

Returns an integer value denoting width in character units.

Note

This routine is implemented as a macro.

See Also

win_GetPixWidth, win_GetHeight, win_GetPixHeight



win_GetXmax - win_GetYmin                                  Get the window edges

---------

Synopsis

opcoord win_GetXmax(win)

opcoord win_GetYmax(win)

opcoord win_GetXmin(win)

opcoord win_GetXmax(win)

   win_type win;              the window object

Description

These routines calculate the extent of a window exclusive of its associated
border, if any, and return a display-relative pixel coordinate for the
requested edge.

Return Value

Returns the coordinate of the appropriate edge of the window.  The coordinate
reference is relative to the display frame.

Note

This routine is implemented as a macro.

See Also





win_Go                                                           Go on a window

---------

Synopsis

int win_Go(win)

   win_type win;              the window object

Description

Transfers control the window's user interaction function and any windows to
which it may pass control.

seds and sleds have built-in user interaction functions.  Objects of all other
windows have no built-in function; they send the WINA_GO message to the
window's auxiliary function, if any, so that the auxiliary function may control
the interaction.

Return Value

Returns an integer value.  This value is determined by the window's go
function.  For seds, the return value is the sed baton.  For other windows, the
return value of the auxiliary function that processes the WINA_GO message is
the return value.

Note

This routine is implemented as a macro.

See Also





win_IsUserPaint                            Get the state of the user paint flag

---------

Synopsis

boolean void win_IsUserPaint(win);

    win_type win;               window

Description

This routine reports whether the window's user paint flag is set.  If the paint
flag is set, then the Window Manager window's sends the window's auxiliary
function WINA_PAINT and WINA_SHADOW messages.

Only userwins have their user paint flag set by default.  You can alter the
setting of the flag by calling win_SetUserPaint.

Return Value

Returns a TRUE if the the user paint is enabled; FALSE, otherwise.

Note

This routine is implemented as a macro.

See Also

win_SetUserPaint



win_Open                                                    Create a new window

---------

Synopsis

win_type win_Open(winclass, wcboxp);
   class_fptr winclass;                the window object class
   ocbox *wcboxp;                      starting size of the window

Description

This routine creates a window object of class winclass.  The starting size and
position (in character-based display coordinates) is specified by the ocbox
wcboxp.  The window is opened with the default system font.  The window is
placed in the unemployed window list.  You can employ the window and paint it
on the display with a call to win_Employ and destroy it with a call to
win_Close.

An ocbox is a structure with four members that describes a rectangular area:
leftcol, rightcol, botrow, toprow.  Each member is an int.

For windows of cmwin_Class and grwin_Class the ocbox determines the size the
window's associated cmap or pmap, respectively.  For those of pmwin_Class, the
ocbox determines only the starting size of the window.  A pmap for a pmwin is
allocated separately by pmap_Open; attached to the window with pmwin_SetPmap.

Return Value

Returns a pointer to the newly created window or NULL if unsuccessful.

Note

This routine is implemented as a macro.

See Also

win_Close, win_Employ, win_PixOpen



win_Paint                                                      Repaint a window

---------

Synopsis

void win_Paint(win);
   win_type win;              the window object

Description

This routine paints all unobscured portions of the given window, excluding its
border.  win_Paint will no effect if the window has not been employed first
with win_Employ.

If the window's user paint flag has been set, the window's auxiliary function
receives the WINA_PAINT and WINA_SHADOW messages.  These messages are sent to
the auxiliary function after the object class has performed its normal painting
action.

The only window class that performs no default painting is the userwin_Class.
For this window type, the auxiliary message must handle all painting.

Return Value

There is no return value.

Note

This routine is implemented as a macro.

See Also

bord_Paint, win_Employ, win_SetUserPaint, win_IsUserPaint



win_SetAttr                                           Sets a window's attribute

---------

Synopsis

void win_SetAttr(win, attr)

   win_type win;              the window object
   byte attr;                 the attribute

Description

This routine sets the attribute of the window win to the given attribute attr.
It subsequently paints all unobscured portions of the window.  Recall that the
attribute specifies a foreground/background color combination.

Return Value

There is no return value.

See Also

win_GetAttr



win_SetBorder                                       Attach a border to a window

---------

Synopsis

boolean win_SetBorder(win, border_func);

  win_type win;             the window object
  bd_fptr border_func;      the border function

Description

This routine creates a border from the given border function and sends an
"open" message to it.  Space is allocated for the border object.

Once a border has been attached to the window, the other window routines
automatically incorporate it into their actions.  The display routines
(win_Employ, bord_Paint) tell the border to paint itself.  The destructor
routines (win_Close) tell the border to destroy itself.  The size and
positioning functions compensate for the size of the border when doing their
calculations.

If a window already has a border, win_SetBorder destroys the old border and
replaces it with the new border.

Some standard border functions are bd_1, bd_2, bd_box, bd_null, bd_plain,
bd_std, and bd_title.

Return Value

Returns TRUE if successful.  If unable to create the border it returns FALSE.



win_SetData                               Set the window's generic data pointer

---------

Synopsis

void win_SetData(win, data);

  win_type win;             the window object
  VOID *data                the window data

Description

This routine sets the window's generic data pointer.  The generic data pointer
is a VOID * pointer that you can use for attaching program-specific data to a
window.  You should cast the address of your data to a (VOID *) when you call
this function.

Return Value

There is no return value.

Note

This routine is implemented as a macro.

See Also

win_GetData



win_SetExplode                           Attach an explode function to a window

---------

Synopsis

void win_SetExplode(win, explode);

  win_type win;             the win
  exp_fptr explode;         the explode function

Description

This routine attaches an explode function to a window.  The window manager
calls the explode function when the window is initially painted to the
display.  The explode function paints images to the display before the window
is painted and is used to create "special effects" when creating windows.

Some standard explode functions are exp_std and exp_BeamMeUp.

Return Value

There is no return value.

Note

This routine is implemented as a macro.



win_SetMouse                                 Attach a mouse handler to a window

---------

Synopsis

void win_SetMouse(win, handler)

   win_type win;                   the window object
   mouhandler_fptr handler;        the mouse handler to attach

Description

This routine attaches the mouse handler handler to window win.

Most of the mouse handlers provided by the library interact with seds.  The
winmou_Track handler is a generic track handler for windows of other classes,
such as grwins, cmwins, and userwins.

winmou_Track automatically communicates with the mouse handlers of other
windows (including seds) to pass control back and forth.  That is, if its
window is not the current window and the user moves the mouse from another
window into the winmou_Track window, winmou_Track accepts the offer to become
the current window.  Likewise, if it is the current window and the user moves
the mouse to another window, winmou_Track grants the request to become current
from another window.

To become current, a window must also have the capacity to respond to win_Go.
sed and sleds have this capacity intrinsically; it is part of their class
functions, sedwin_Class and sledwin_Class.  Windows of other classes (such as
cmwins, pmwins, and userwins) only gain this capacity when the window has an
auxiliary function that processes the message WINA_GO.

Once a window is current, calling kb_Read allows winmou_Track to process mouse
events for the window.  winmou_Track returns either MOU_THERE or MOU_CLICK from
kb_Read.

MOU_THERE means that a mouse event occurred in a another window and that window
has been granted control.  Your auxiliary function should return immediately.

MOU_CLICK means that the mouse was clicked in your window.  You can call
win_MouseCurEvent to get a mev_struct describing the event that occurred.
Then, you can call win_MouseDblClick, mev_IsButton1Down, mev_IsButton2Down,
mev_IsButton3Down to tell you whether the click was a double click or single
click and what button was used.  mev_GetX and mev_GetY tell of the x and y
pixel position of the event, in window coordinates.  mev_GetRow and mev_GetCol
tell of the character row and character column of the event, in window
coordinates.

Return Value

There is no return value.

Note

This routine is implemented as a macro.



win_SetNextWin                                   Pass control to another window

---------

Synopsis

void win_SetNextWin(currwin, nextwin);

   win_type currwin;                the current window
   win_type nextwin;                the next window

Description

Use this routine if you wish to pass control to another window without leaving
win_Go.

If you call win_SetNextWin with a handle to the next window, when you leave
your window, the window manager will pass control to the nextwin instead of
returning from win_Go.  If nextwin is NULL the window manager will not pass
control to another window and win_Go will simply return.

Typically this function is used by mouse handlers to pass control between
various windows when they are selected with the mouse.  The next window is
initially set to NULL.

Note that nextwin can be a C-scape sed because a sed is a type of window.

Return Value

There is no return value.

See Also

win_Go



win_SetPosition                               Set a window's character position

---------

Synopsis

void win_SetPosition(win, row, col)

   win_type win;              the window object
   int row;                the window display row position
   int col;                the window display column position

Description

This routine positions a window at the character coordinate position (col, row)
and, if the window is employed, repaints the window.  These coordinates are
relative to the display.

Return Value

There is no return value.

Note

This routine is implemented as a macro.

See Also

win_SetPixPosition, win_GetPosition, win_GetPixPosition



win_SetShadow                                        Set the window shadow size

---------

Synopsis

void win_SetShadow(win, shd);

   win_type win;                    win whose shadow to set
   int shd;                         size of shadow in characters

Description

This routine sets the size of the given window's shadow as specified by shd.
Note that shadow size is specified in character units.

A shadow is an extension to the window's border that paints a darkened strip
along the bottom and right edges of the window to give it a three dimensional
appearance.  The color of the strip is determined by the shadow attribute of
the window on which the shadow falls.

Return Value

There is no return value.

Note

This routine is implemented as a macro.

See Also

win_SetShadowAttr



win_SetShadowAttr                          Set the shadow attribute of a window

---------

Synopsis

void win_SetShadowAttr(win, attr);

   win_type win;                    the window
   byte attr;                       the shadow color attribute

Description

This routine sets the window's shadow attribute to the value given by attr.

The shadow attribute dictates how a shadow (from some other overlapping window
with a shadow border) will appear as it falls on this given window.  For
example, if you want black shadows to appear across your window use attribute
0x00.  Use a different attribute, such as 0x08, to create shadows that show the
contents of the window faintly within the shadow.

Return Value

There is no return value.

Note

This routine is implemented as a macro.

See Also

win_SetShadow



win_SetSize                                 Alter a window's display dimensions

---------

Synopsis

void win_SetSize(win, rows, cols)

   win_type win;              the window object
   int rows;                  the new window height in character rows
   int cols;                  the new window width in character columns

Description

This routine alters a window's dimensions on the display.  It saves any parts
of the display about to be obscured by expansion; exposes any parts about to be
unobscured by shrinking; and, paints the whole window in its new size.  It does
nothing if the window is NULL.

Return Value

There is no return value.

Note

This routine is implemented as a macro.  And, in this function the assumption
is made that borders do not need to be saved, and that the window contents need
to be saved before the border is shrunk to obscure them.

See Also

win_SetPixSize, win_GetSize, win_GetPixSize



win_SetUserPaint                                 Set a window's user paint flag

---------

Synopsis

void win_SetUserPaint(win, userpaint);

    win_type win;               window
    boolean userpaint;          auxiliary paint flag

Description

This routine sets or clears the user paint flag of a window.  If the paint flag
is set, then the Window Manager window's sends the window's auxiliary function
WINA_PAINT and WINA_SHADOW messages.

Only userwins have their user paint flag set by default.  You can test the
state of the flag by calling win_IsUserPaint.

Return Value

There is no return value.

Note

This routine is implemented as a macro.

See Also

win_IsUserPaint



win_Top                                Bring a window to the top of the display

---------

Synopsis

void win_Top(win)

   win_type win;              the window object

Description

This routine brings the specified window to the top of the display.

Return Value

There is no return value.

Note

This routine is implemented as a macro.



win_UnEmploy                                                      Fire a window

---------

Synopsis

boolean win_UnEmploy(win)

   win_type win;              the window object

Description

This routine moves a window from its place in the employed window list to the
unemployed list.  The window is removed from the display and the portions of
the display that were hidden by the window are repainted.  If the window is
already in the unemployed list, then this routine does nothing.

Return Value

There is no return value.

See Also

win_Employ