Celestin Apprentice 2/Apprentice-Release2.iso/Source Code/C/Libraries/stdwin/Doc/WHATSNEW

Text File | 1991-06-07 | 10.4 KB | 285 lines | [TEXT/????]

What's New in STDWIN 0.9.6
==========================

This release is a temporary measure, needed primarily to support the
upcoming release 0.9.2 of the Python programming language.  It is
still lacking complete and up-to-date documentation.

For those who are familiar with STDWIN 0.9.5, here is a summary of the
main changes in version 0.9.6 (of course, a number of bugs were also
fixed).


Overview of the changes
-----------------------

- Initialization is now separated in argument processing and actual
  initialization.
- Scroll bars can be turned off with an option at window creation time.
- More inquiry functions, e.g., document size, window position.
- Filled and XOR mode drawing of circles and elliptical arcs.
- Polygon drawing (filled, outline and XOR).
- Color drawing.
- Modifier keys (control, shift, meta etc.) are passed in mouse events.
- Closing a window is now indicated by a separate event, WE_CLOSE.
- New event type WE_KEY reports non-ASCII keys and keys with modifiers.

The new calls are documented the following sections.


New Initialization Calls
------------------------

Some window systems (like X11) have a standard set of command line
options that support overriding defaults by the end user.  The new
function wargs() parses the command line options and saves them for
later use by winit() and wopen().

void wargs(int *p_argc, char ***p_argv);

This function should be called before winit(), as early as possible
during the execution of main(), passing it the addresses of main's
arguments argc and argv.  It may modify argc and argv to reflect the
extraction of recognized options.

The application's argument parser does not have to worry about
conflicting options, as long as it uses the getopt() interface to
parse its own options.  On the Mac, this function initializes argc and
argv from the program arguments passed by the Finder; if the
application is called from the Finder's Print menu entry, the first
argument will be the string "-p".

If the application decides not to call winit() after it has called
wargs(), it need not call wdone() before exiting.  If wargs() has not
been called when winit() is called, system-defined defaults are
assumed.  On X11, resources can still be specified for such
applications; the program name is assumed to be "stdwin" and its class
"Stdwin", unless the RESOURCE_NAME environment variable is set.

void winitargs(int *p_argc, char ***p_argv);

This is equivalent to a call to wargs(p_argc, p_argv) followed by a
call to winit().


Scroll Bars Made Optional
-------------------------

It is now possible to specify whether a window should have scroll
bars.  This must be specified before the window is created and cannot
be changed once it is created.  By default, windows will have a
vertical scroll bar but no horizontal scroll bar.

void wsetdefscrollbars(int need_hbar, int need_vbar);

Specifies which scroll bars will be present on subsequently created
windows.  If need_hbar is nonzero, new windows will be created with
horizontal scroll bars; if need_vbar is nonzero, new windows will be
created with vertical scroll bars.

void wgetdefscrollbars(int *need_hbar_return, *need_vbar_return);

Returns the current status of the scroll bar creation flags set by
wsetdefscrollbars() through its arguments.

Note that even if they are present, scroll bars are only activated
when the document size in their direction is set to a value larger
than the window size.


More Inquiry Functions
----------------------

void wgetdefwinsize(int *width_return, int *height_return);

Return the default initial size for new windows, as set by
wsetdefwinsize().  Zero or negative values mean that a
system-dependent default method is used to find an initial size for
the window, e.g., interactive sizing.

void wgetdefwinpos(int *h_return, int *v_return);

Return the default initial position for new windows, as set by
wsetdefwinpos().  Zero or negative values mean that a system-dependent
default method is used to find an initial position for the window,
e.g., interactive placement.

void wgetwinpos(WINDOW *win, int *h_return, int *v_return);

Return the current window position on the screen.  Together with
wgetwinsize() this can be used to save a window's geometry and
recreate it in the same state at a later time.


Color Drawing
-------------

It is now possible to draw images in multiple colors, if the display
hardware allows this.  The model uses the notion of current foreground
and background colors.  Because different color hardware operates very
differently, the number of different colors and the way they are
selected is left unspecified by STDWIN.

A type COLOR is defined, which is some kind of (long) integer
representing a color value; suitable values can be extracted by name
from an external color database.  Applications that know on which
hardware they run may cheat, as the values of type COLOR will be
indexes into the color table or directly encode RGB value, but this
obviously restricts the application's portability.

Applications can only assume the presence of colors named white and
black; on monochrome displays, these are all there is.  Otherwise,
some standard colors are supposed to be available everywhere: gray25
(dark grey), gray50 (middle gray), gray75 (light gray), red, green,
blue, yellow, magenta, cyan.  There are also some pseudo color names
that may be assigned defaults by the end user: foreground, background,
primary, secondary, selection, hilight.  Some monochrome
implementations (especially the Mac) attempt to simulate a few gray
levels with fill patterns, but only as foreground color.  On X11,
color names are looked up in the server's color database; the notation
#RGB, #RRGGBB (etc.) is also recognized.

Each window has default foreground and background colors, which are in
effect immediately after wbegindrawing() and initially in draw
procedures.  These default colors are specified by calling
wsetfgcolor() and wsetbgcolor() outside drawing mode before creating a
window.  These colors may also be used to draw a window's
ornamentation such as scroll bars and menus; before a draw procedure
is called, the update area is cleared to the window's default
background color.

Two drawing functions are unsafe when color is used: winvert() and
wxorline().  For all affected pixels, these are guaranteed to
correctly swap the current foreground and background colors, but other
colors are swapped with arbitrary colors, giving an undefined effect.
Inverting the pixels once more (with the same foreground and
background colors in effect!) will return them to their original
colors, however.

Swapping the foreground and background colors has the effect of
drawing in inverse video; HOWEVER, this is not supported by the
termcap (alphanumeric) version of STDWIN, which bluntly ignores all
color requests.

typedef ... COLOR;

This type represents a color value.  It is one of C's integral types,
so it is possible (and useful!) to declare variables of type COLOR.

COLOR wfetchcolor(char *colorname);

Look the color name up in the external database of color definitions
and return a color value for it, if possible.  If the color is not
found in the database or no more color values are available (this
happens easily on systems with small color tables), the color value
for the default foreground is returned.

void wsetfgcolor(COLOR color);

Set the current foreground color.  In drawing mode, set the foreground
color used for drawing; outside drawing mode, set the default
foreground color for windows created subsequently.

void wsetbgcolor(COLOR color);

Set the current background color.  Similar to wsetfgcolor().

COLOR wgetfgcolor();

Return the current foreground color, as set by wsetfgcolor() or from a
system-defined default.

COLOR wgetbgcolor().

Return the current background color.  Similar to wgetfgcolor().


Filled and Xor'ed Circles and Arcs
----------------------------------

void wfillcircle(int h, int v, int radius);

Fills a circle with given center and radius.

void wxorcircle(int h, int v, int radius);

Inverts a circle with given center and radius.

void wfillelarc(int h, int v, int hrad, int vrad, int angle1, int angle2);

Fills a segment of an elliptical arc defined by the parameters as for
wdrawelarc.

void wxorelarc(int h, int v, int hrad, int vrad, int angle1, int  angle2);

Inverts an elliptical arc defined by the parameters as for wdrawelarc.


Polygons
--------

There is a way to draw arbitrary polygon shapes.

typedef struct { short h, v; } POINT;

This type is used to pass an array of points to the polygon routines.
Coordinates are specified as shorts so certain STDWIN versions
(especially the X11 version) can pass arrays of coordinates to routines
of the underlying window system without copying them.

void wdrawpoly(int n, POINT points[]);

Draws n-1 line segments given by n points: from points[0] to points[1],
from points[1] to points[2], etc., and finally from points[n-2] to
points[n-1].

void wfillpoly(int n, POINT points[]);

Fills polygon defined by n points.  If points[n-1] does not equal
points[0], an additional line segment closing the polygon shape from
points[n-1] to points[0] is implied.  The polygon may intersect itself.

void wxorpoly(int n, POINT points[]);

Inverts a filled polygon.  The polygon is defined as for wfillpoly().


Modifier Keys in Mouse Events
-----------------------------

The u.where.mask member of the EVENT structure now has a different
meaning.  It reports the modifier keys that were pressed at the time
the event was generated.  The following constants define bit masks for
various modifier keys:

#define WM_SHIFT    (1 << 0)
#define WM_LOCK        (1 << 1)
#define WM_CONTROL    (1 << 2)
#define WM_META        (1 << 3)
#define WM_OPTION    (1 << 4)
#define WM_NUM        (1 << 5)

On the Mac, WM_META corresponds to the Command modifier.  In X11,
WM_META is really "Modifier 3", commonly bound to the Meta or Alt key;
WM_OPTION and WM_NUM are not normally reported in X11 so their use is
not portable.


The WE_CLOSE Event
------------------

To simplify event decoding somewhat, a user's close request is now
reported as an event (WE_CLOSE) rather than a subcode (WC_CLOSE) of
the WE_COMMAND event.  All WE_COMMAND subcodes now report special
keys.


The WE_KEY Event
----------------

If a key is pressed together with the Meta key that is not a menu
shortcut, it is reported as a WE_KEY event.  This event uses the union
member u.key which has members code and mask.  The member u.key.code
specifies the ASCII code of the key; u.key.mask specifies the
modifiers that were pressed with the key.