STDWIN 0.9.5, Part 02/19

[Guido van Rossum]

Archive-name: stdwin/part02

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#		"End of archive 2 (of 19)."
# Contents:  Doc/paper.ms Ports/mac/pstring.c
# Wrapped by guido at voorn.cwi.nl on Mon Mar  4 12:37:23 1991
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'Doc/paper.ms' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'Doc/paper.ms'\"
else
echo shar: Extracting \"'Doc/paper.ms'\" \(51068 characters\)
sed "s/^X//" >'Doc/paper.ms' <<'END_OF_FILE'
X.\" Typeset using refer -e -n | (di)troff -ms.
X.\" You may have to change the CW (Constant Width) macro define below
X.\" if you aren't typesetting on a PostScript printer.
X.\" Your best bet is to change ".ft C" by ".ft I" and "\fC" by "\fI".
X.\" Each occurs exactly once in the macro definition.
X.de CW
X.if t .if "\\$1"" .ft C
X.if t .if !"\\$1"" \fC\\$1\fP\\$2
X.if n .B "\\$1" "\\$2"
X..
X.TL
X.nr PD 0
X.nr PI 2n
X.ft H
X.ps 14
XSTDWIN \- A Standard Window System Interface
X.ps
X.ft
X.AU
X.ft H
XGuido van Rossum
X.ft
X.AI
X.ft HO
X.ps 8
X.vs 10
XCenter for Mathematics and Computer Science
XP.O. Box 4079, 1009 AB Amsterdam, The Netherlands
XE-mail: guido at cwi.nl or mcvax!guido
X.vs
X.ps
X.ft
X.AB
X.LP
XSTDWIN is an interface layer placed between an application written in C
Xand arbitrary window system, making the use of windows both easier and
Xmore portable.
XFor applications using STDWIN
Xfor their window management requirements, adaptation to a
Xdifferent window system is as easy as linking with an appropriate
Xversion of the STDWIN library.
XSo far, STDWIN libraries are available
Xfor the Apple Macintosh,
Xfor the Whitechapel MG-1 (running Oriel),
Xfor MIT's X Window System version 11,
Xfor the Atari ST,
Xand (subsets) for alphanumeric terminals on
X.UX
Xand MS-DOS.
X.FS
X.ft H
X.sp
XReport CS-R8817
X.br
XCentre for Mathematics and Computer Science
X.br
XP.O. Box 4079, 1009 AB Amsterdam, The Netherlands
X.ft
X.FE
XNew implementations are easily written.
X.PP
XLike STDIO, C's Standard I/O library, STDWIN's aim is to give
Xa simple interface, high-level functionality, and portability.
XIt does not attempt to allow access to all possible features of window
Xmanagement systems; rather, it provides the programmer with a
Xmodel which allows easy construction of that part of the program which
Xis concerned with window management.
X.PP
XSTDWIN's high-level operations include automatic window positioning
Xand resizing, scrolling, menus, keyboard shortcuts, and multiple-click
Xdetection.
X.sp
X.ps 8
X.vs 10
X.ft HO
X1980 Mathematics Subject Classification:
X.ft
X.ft H
X68B20.
X.ft
X.br
X.ft HO
X1982 CR Categories:
X.ft
X.ft H
XD.2.2, I.3.4, I.3.6.
X.ft
X.br
X.ft HO
XKey Words & Phrases:
X.ft
X.ft H
Xwindow systems, user interfaces, portability.
X.ft
X.br
X.ft HO
XNote:
X.ft
X.ft H
XThis paper has been submitted for publication elsewhere.
X.ft
X.vs
X.ps
X.AE
X.LP
X.NH
XIntroduction
X.LP
XFirst, some history.
XSTDWIN's conception was motivated by the desire to add a more modern
Xuser interface (i.e., one using windows and a mouse)
Xto the programming environment for the language ABC,
Xdeveloped here at CWI.
X.[
X%A Leo Geurts, Lambert Meertens, Steven Pemberton
X%T The ABC Programmer's Handbook
X%I CWI
X%C Amsterdam
X%D to be published in 1988
X.]
XThe ABC programming environment, consisting of a syntax-directed editor,
Xan interpreter and a source file manager, is a large body of C
Xcode which, through careful isolation of system-dependent modules, has
Xproven to be quite portable, both to different versions of
X.UX
Xand to non-\c
X.UX
Xsystems such as MS-DOS and the Apple Macintosh.
XNaturally, we did not want to lose its portability by tying
Xit closely to one particular window system.
X.PP
XOnly after having looked closely at a few existing window systems, we
Xbecame fully aware of the problems.
XMost window systems offer a large range of facilities, apparently
Xintended to enable programmers to create beautiful user interfaces,
Xbut often resulting in total chaos.
X.[
X%A Mike O'Dell
X%B EUUG Conference Proceedings, September 1987, Dublin, Ireland
X%T What They Don't Tell You About Window Systems
X.]
XOne of the problems appears to be the low level of most window system
Xinterfaces.
XFor example, on the Apple Macintosh, all tools are provided to
Xwork with scroll bars (bit-scrolling operations, routines to draw scroll
Xbars, routines to detect user interaction with a scroll bar), but the
Xamount of code needed to glue these together and create a scrollable
Xview on a document is horrendous.
X.[
X%T Inside Macintosh
X%A Apple Computer
X%I Addison-Wesley
X%C Reading, Mass.
X%D 1985
X.]
XSimilarly, again on the Macintosh, double-clicking the mouse button is
Xa frequent form of user input, but there is no library routine available
Xto detects double-clicks, leading to much code duplication and
Xgratuitous differences between programs.*
X.FS
X* In all fairness it should be said that the Macintosh is still miles
Xahead of most of its competitors, simply because there are at least
Xstandards for many aspects of the interaction between application
Xand user, such as the placement of scroll bars, the use of double clicks
Xor the shape of the mouse cursor.
X.FE
X.PP
XWith these considerations in mind, we set out to design a `generic'
Xwindow system interface.
X.sp
X.IP \(bu
XThe interface should be general enough to suit the needs of many
Xdifferent programs.
XThus, it should be reasonably rich in functionality, e.g., provide both
Xtextual and graphical output, handle keyboard, mouse and menu-based
Xinput, support multiple windows, etc.
X.IP \(bu
XIt should be simple to use.
XIncluding one header file and calling a
Xsmall number of routines (with not too many parameters!) should suffice
Xfor the creation of a full-function window and the definition of its
Xcontents.
XAs much as possible, the programmer should only be bothered with issues
Xthat matter from the program's point of view.
XIn other words, the interface should be `high level'.
X.IP \(bu
XAnd most of all, it should be realistically portable; each potential
Xfeature should be weighed in the light of its implementability using
Xdifferent systems, including several popular micros.
X.sp
X.LP
XThe requirement of portability is necessarily both good and bad.
XIt is bad because it can sometimes make an elegant solution unfeasible,
Ximposing seemingly random restrictions.
XBut it is good because it makes the design stick to reality, and limits
Xit to the `essence' of window systems, rather than allowing the
Xdesigners to invent yet another incompatible paradigm.
XAnd sometimes the `helicopter view' gained from looking at
Xsolutions chosen by vastly different window systems for a particular
Xproblem has shown the way to an entirely new view, simplifying it by
Xgeneralization.
X.sp
X.LP
XA large part of the paper is devoted to a detailed description of
XSTDWIN's functionality from a programmer's point of view.
XFirst the `core' of the package is described, explaining the basic
Xoutput and input facilities;
Xthen some extra facilities are briefly discussed.
XInterspersed are comments on the rationale for particular solutions,
Xsome hints on the implementation, and warnings about non-portable uses.
XAt the end the paper returns to the more philosophical issues:
Xexperiences, future developments, food for thought.
X.NH
XDescription
X.LP
X.NH 2
XHeader file
X.LP
XApplications wishing to use STDWIN must place a line saying
X.CW "#include <stdwin.h>"
Xnear the top of their source file(s).
XAll user-visible external names defined in this header file start with
X.CW w
Xor
X.CW W .
Xexternal names used internally by implementations begin with
X.CW _w
Xor
X.CW _W .
X.NH 2
XInitialization and clean-up
X.LP
XBefore starting to use STDWIN, the initialization routine
X.CW "winit()"
Xmust be called.
XBefore exiting, the application should call
X.CW "wdone()"
Xto perform any necessary clean-up operations.
X.PP
XThese calls can't be repeated; after
X.CW "wdone()"
Xhas been called the application cannot call
X.CW "winit()"
Xagain and `return to life'.
X.NH 2
XCreating and destroying windows
X.LP
XA new window is created by calling
X.CW "wopen(title, drawproc)" .
X.I Title
Xis a string identifying the window to the user; it is usually displayed
Xby STDWIN in the window's border, e.g., in a title bar.
X.I Drawproc
Xis the address of the window's draw procedure (see next section), or
XNULL if the window is not to have a draw procedure.
XSTDWIN windows look like windows in the usual style of the underlying
Xwindow system, usually with a title bar, scroll bars etc.
XPosition, size and other characteristics of the new window are
Xdetermined by STDWIN (but see below).
X.PP
X.CW "Wopen"
Xreturns a
X.I "window pointer" ,
Xof type
X.CW "WINDOW *" ,
Xto be used to identify the window in subsequent operations.
XIf creation of the window failed, a NULL pointer is returned.
X.PP
XSTDWIN allows an application to have multiple windows open simultaneously.
XImplementations usually impose a limit on the number of open
Xwindows; when this limit is reached,
X.CW "wopen"
Xreturns NULL, and the application should try to close other windows
X(or prompt the end user to close them).
X.PP
XA window is deleted permanently by calling
X.CW "wclose(win)" .
XWindows can be deleted only by the application.
XThe end user can send a request to the application to close a window,
Xbut the application may ignore the request or postpone its execution.
X.PP
XThere is no explicit way to iconize
Xa window (i.e., to temporarily close it, leaving an icon in its place).
XOn systems where window iconization is built into the window system,
XSTDWIN may support it silently; all the application notices is that no
Xinput is received for iconized windows.
X.NH 3
XChanging defaults
X.LP
XWhen a window is opened STDWIN determines
Xa default size and position for it.
XUsually this is convenient for the application (which needn't
Xhave its own algorithm for placing multiple windows, for example),
Xbut sometimes finer control is desirable.
XTherefore, a number of default-setting routines are provided:
X.LP
X.CW "wsetdefwinsize(width, height)"
X.IP
XChanges the default window size.
XThis sets the net size, excluding borders, scroll bars etc.
X.LP
X.CW "wsetdefwinpos(h, v)"
X.IP
XChanges the default window position.
XThis default is usually not a constant but a dynamically computed value.
XThe next opened window will be placed at
X.I "(h, v)" ;
Xthe position of windows opened after that may be a more complicated
Xfunction of
X.I h
Xand
X.I v .
X.LP
XThese routines may be called at any time; they affect only windows
Xopened after their call.
XA negative or zero parameter restores the default for that
Xdimension.
XOther values are clipped or rounded to reasonable and implementable
Xvalues; these routines are best seen as giving hints to STDWIN, which
Xmay be ignored by some implementations.
X.NH 2
XThe output model
X.LP
XA STDWIN window is a view on a possibly much larger area,
Xa rectangle referred to as its
X.I document ,
Xin which the application draws its output.
XThe document's size is chosen by the application, and can be changed at
Xany time by calling
X.CW "wsetdocsize(win, width, height)" .
XIt is not limited by window or screen size, nor indeed by available
Xmemory; the entire document's contents are not stored directly.
XThe end user has the freedom to `pan' the window over the document's
Xsurface, using scroll bars or a similar mechanism.
XWhen a particular part of the document is to be visible in the window,
XSTDWIN asks the application to repaint that area.
XIt is not forbidden to draw outside the document, but the end
Xuser normally can't pan outside the document (unless the window is
Xlarger than the document).
X.PP
XThere are two mechanisms for repainting: a low-level mechanism using
XDRAW events, and a higher-level mechanism using a
X.I "draw procedure" .
X.PP
XDRAW events are merged with the general event stream (see below); when
Xno other events are in the event queue, STDWIN looks to see if
Xthere is any window needing a repaint, and if so, it passes a DRAW event
Xfor that window to the application.
XA DRAW event includes as additional information the rectangle
Xthat is to be repainted.
XThe application should react by erasing and repainting that rectangle
X(or a larger part of the document).
X.PP
XNormally, however, windows have an associated
X.I "draw procedure" .
XThis is a procedure (defined by the application) which knows how to draw
Xthe entire document, or any sub-rectangle of it.
XWhen STDWIN is about to generate a DRAW event for a window with a draw
Xprocedure, it prepares the window for drawing, erases the rectangle
Xthat needs repainting, and calls the draw procedure with the window and
Xthe rectangle as parameters.
XThe advantage of this mechanism over DRAW events is the possibility for
Xcertain STDWIN implementations to clip the output to a smaller,
Xnon-rectangular area that really needs a repaint; also somewhat simpler
Xevent decoding logic for the application.
X.PP
XUsually, the end user controls which part of the document is visible in
Xthe window (by manipulating the scroll bars).
XHowever, there are times when an application wants to display a particular
Xpart of the document, e.g. to show the effect of a search operation.
XIt can then call
X.CW "wshow(win, <rectangle>)"
Xto indicate that the given rectangle should be visible, if at all
Xpossible.
XSTDWIN will check whether this is already the case, and if not, move
Xthe window with respect to the document to make it visible.
XThere is also a lower-level call,
X.CW "wsetorigin(win, <point>)"
Xwhich makes the given point in the document the top left corner of the
Xwindow.
X.PP
XWhen the application wants to change part of the document, it can
Xdirectly paint the changes (after preparing for drawing in that
Xparticular window).
XHowever, it is often more appropriate to delay the actual painting until
Xafter other input has been processed.
XIt is possible to tell STDWIN that a particular area of the document
Xneeds repainting by calling
X.CW "wchange(win, <rectangle>)" .
XAt the appropriate time, a DRAW event for this rectangle (possibly
Xmerged with other areas that need repainting) will be generated, or the
Xwindow's draw procedure will be called.
X.PP
XWhen the repaint area is non-rectangular (e.g., it is the union of
Xseveral rectangles), the application is asked to repaint the smallest
Xrectangle that encloses the repaint area.
XThis may occasionally cause more repainting than absolutely necessary,
Xresulting in extra delays; since the repainting is limited to the window
Xsize, however, the costs won't be excessive in most cases.
XThe choice was made here for a simple interface to the draw procedure,
Xavoiding dynamic data structures.
XFor the needs of the highest-demanding applications, an enquiry routine
Xreturning the exact repaint area may have to be be added
X(or a function telling
Xwhether a particular rectangle intersects the repaint area).
X.NH 2
XDrawing in a document
X.NH 3
XThe coordinate system
X.LP
XSTDWIN provides a single coordinate system per window.
XCoordinates are integers, with the X axis pointing right and the Y axis
Xpointing down.
XIn order to avoid confusion with other conventions, the axes
Xare never called X and Y axis but h and v axis.
XH coordinates are always listed first.
XThe origin (0, 0) is the top left corner of the document.
XUnit size equals pixel size on the screen; thus, documents inherit the
Xscreen's aspect ratio.
XPixels on different machines can vastly differ in size; e.g.,
Xon alphanumerical terminals,
Xpixel size might well equal character cell size.
XTherefore, applications should scale their drawings accordingly.
XSTDWIN provides enquiry functions to tell the physical size of a pixel.
XAn alternative approach, suitable for applications that display mostly
Xtext, is to scale the drawing accordingly to the dimensions of
Xcharacters drawn on the screen.
XText measuring functions are available for this purpose (see below).
X.NH 3
XPreparation for drawing
X.LP
XSince a picture is usually built out of a large number of calls to
Xprimitive drawing operations, it would be annoying to have to specify
Xa window parameter on each call.
XSTDWIN requires the application to say in which window it wants to
Xdraw before using any drawing primitives, by calling
X.CW "wbegin\%draw\%ing(win)" .
XAfter the drawing is done, the application should call
X.CW "wend\%draw\%ing(win)" ,
Xtelling STDWIN to flush the output to the screen.
X.PP
XIn a draw procedure these calls are unnecessary; there, all drawing
Xoperations apply to the given window, and output is flushed when the
Xdraw procedure returns.
X.NH 3
XGraphical primitives
X.LP
XSTDWIN currently provides a small set of graphical primitives.
XThis set will be extended when the need arises.
XAll primitives except
X.CW werase
Xand
X.CW winvert
Xdraw in OR mode, i.e., they only add black pixels to the drawing
Xand never erase pixels.
XNote that points are actually given as two integer parameters, h and v;
Xrectangles are given as four integer parameters:
Xleft, top, right and bottom.
XRectangles always refer to the area enclosed by infinitely thin
Xboundary lines; e.g., the rectangle (0, 0, 1, 1) encloses a 1 by 1
Xsquare whose top left corner is the origin (0, 0).
X.PP
XFunctions currently defined are:
X.LP
X.CW "wdrawline(<point1>, <point2>)"
X.IP
XDraws a line from point1 to point2.
X.LP
X.CW "wdrawbox(<rectangle>)"
X.IP
XDraws a box (i.e., a rectangle) inside the given rectangle.
X.LP
X.CW "wdrawcircle(<point>, radius)"
X.IP
XDraws a circle with the specified radius around the given point as
Xcenter.
X.LP
X.CW "wpaint(<rectangle>)"
X.IP
XPaints the area inside the given rectangle black.
X.LP
X.CW "werase(<rectangle>)"
X.IP
XErases the area inside the given rectangle.
X.LP
X.CW "winvert(<rectangle>)"
X.IP
XInverts the pixels in the given rectangle.
X.LP
X.CW "wshade(<rectangle>, percentage)"
X.IP
XAdds a shading pattern to the given rectangle, approximately making the
Xgiven percentage of all pixels black.
XThus, a percentage of 0 has no effect;
Xa percentage of 50 sets every other pixel;
Xa percentage of 100 is equivalent to
X.CW "wpaint(<rectangle)" .
XThe exact shading pattern used is implementation-dependent, as are the
Xvalues to which percentages are rounded.
X.NH 3
XText drawing primitives
X.LP
XSTDWIN supports the drawing of characters in a font which may be
Xproportionally spaced, depending on the implementation.
XThe exact shape and size of the characters are implementation-dependent.
XSTDWIN does not use the notion of a `base line' on which characters are
Xdrawn; rather, when a character or string is to be drawn, the top left
Xcorner of the box around it is given.
XAll boxes have the same height, and a width appropriate for the
Xcharacter, so characters drawn in adjacent boxes `look right'.
XThis approach has the advantage that the application needn't be
Xconcerned with such font parameters as base line, ascent, descent and
Xleading; it can simply start drawing characters at (0, 0) and they
Xwill come out `right'.
X(This advantage for simplistic applications may turn into a disadvantage
Xfor programs wishing precise control over the placement of characters.
XIn that case, additional enquiry functions will have to be defined
Xto remedy this situation.)
X.PP
XThe call
X.CW "wdrawchar(<point>, character)"
Xdraws the given character with its top left corner at the given point.
XIt returns the h coordinate of the right edge of the box in which the
Xcharacter is drawn; this is the `natural' h coordinate for a character
Xto be drawn next to it.
X.PP
XThe call
X.CW "wdrawtext(<point>, string, length)"
Xdraws the characters of the given string starting with the top left
Xcorner at the given point.
X.I Length
Xindicates the number of characters in the string;
Xif negative, the string ends with a NUL character.
X.CW Wdrawtext
Xreturns the h coordinate of the right edge of the box in which the
Xlast character is drawn.
XNote that no special interpretation is given to characters like
X.CW \&'\en'
Xor
X.CW \&'\et' ;
Xthey may be displayed as spaces or funny graphics.
X.NH 3
XText measuring primitives
X.LP
XThe dimensions of characters drawn by the above functions depend on the
Xfont used.
XFuture versions may implement font and size changes under application
Xcontrol; currently these are fixed by the implementation.
XFor applications that want to know in advance how big the strings they
Xare drawing will be, there are functions to measure text dimensions.
XUnlike the drawing primitives,
Xthe text measuring primitives and the style-changing primitives
Xdescribed in the next section can be called anywhere.
X.PP
XThe following text-measuring functions are defined:
X.LP
X.CW "wlineheight()"
X.IP
XGives the vertical height of the boxes in which characters are drawn.
XThis is the same for all characters, and the value delivered gives a
X`natural-looking' line spacing when lines are drawn at v coordinates
Xwith increments of this value.
X.LP
X.CW "wcharwidth(character)"
X.IP
XComputes the width of the box in which the given character will be drawn.
X.LP
X.CW "wtextwidth(string, length)"
X.IP
XComputes the width of the box in which the string will be drawn.
X.I Length
Xindicates the number of characters in the string;
Xif negative, the string ends with a NUL character.
X.LP
X.CW "wtextbreak(string, length, width)"
X.IP
XComputes the number of characters from the string that will fit in a box
Xof the given width (in pixels).
X.I Length
Xis interpreted as above.
X.NH 3
XText style
X.LP
XFuture versions of STDWIN will have to worry about mixing fonts,
Xtype sizes and text styles.
XCurrently applications have no control over the font and size used, and
Xcan only control one aspect of text style;
Xdifferent window systems differ so much
Xin their support of font names, font scaling, style combinations and so
Xon, that it seemed wise to avoid these issues in the
Xfirst version (however, some implementations have a way to influence
Xthe font, size or style used at initialization time).
XThe only calls currently available are those to change between normal,
Xblack on white characters and inverse, white on black characters; this
Xis needed to display the focus in the text-editing package (see below).
X.PP
XThe call
X.CW "wsetinverse()"
Xsets the text style to inverse characters; the call
X.CW "wsetplain()"
Xreverts the text style back to normal.
XThe text style is a global attribute, so draw procedures that change it
Xshould reset it to normal before leaving.
X.NH 3
XScrolling
X.LP
XApplications like text editors often have a need for deleting a
Xhorizontal or vertical slice from their document; e.g., after a text
Xeditor has deleted a couple of lines, the remaining lines must be moved
Xup in the document.
XAlthough it is theoretically possible to do this by calling
X.CW "wchange"
Xfor the remaining part of the document (assuming the draw procedure
Xknows that the v coordinates of the affected lines have changed),
Xthis often involves a lot of drawing which could have been avoided by
Xapplying a `bit copy' operation as available in many systems,
Xcombined with only a little bit of redrawing
X(e.g., for lines `scrolled in' from below the window border).
X.PP
XThe call
X.CW "wscroll(win, <rectangle>, dh, dv)"
Xis provided to help in situation.
XIt should be called outside the drawing procedure,
Xwhere the call to
X.CW wchange
Xwould otherwise be placed.
XIf the particular STDWIN implementation supports the requested type of
Xbit scroll operation, it will scroll the bits inside the given
Xrectangle by an amount of
X.I dh
Xto the right and by
X.I dv
Xdownward.
X(Negative values mean scrolling to the left or upward, respectively.)
XNo bits outside the given rectangle are affected or used:
Xbits `scrolled out' of the rectangle will simply be thrown away; for
Xthe area that is to be `scrolled in' from outside the rectangle,
X.CW wchange
Xis called internally.
XIf the particular form of bit scrolling required isn't supported,
Xthe entire call is equivalent to
X.CW "wchange(win, <rectangle>)" ,
Xrelying on the normal repaint mechanism to update the window.
X.NH 2
XThe input model
X.LP
XInteractive input is presented to the application in the form of
X.I events .
XExamples of events are `a character has been typed' or `the mouse button
Xhas been pressed'.
XSome other information generated asynchronously by STDWIN is also passed
Xin the form of events.
X.PP
XEvents are queued internally; the routine
X.CW "wgetevent"
Xgets the next event from the queue and passes it to the application.
XIf the queue is empty, it waits until an event arrives first.
X(Certain events, like DRAW events, are not really queued but constructed
Xon the fly when the queue is empty.)
X.PP
XSome applications don't want to wait when no event is ready, but do want
Xto process events that are already queued.
XFor such cases there is the alternative routine
X.CW "wpollevent"
Xwhich acts like
X.CW "wgetevent"
Xwhen an event is available from the queue, but returns immediately with
Xa dummy NULL event when the queue is empty.
X.PP
XAn event always applies to a particular window.
XThis means that an application which has no window open is blind and deaf.
XWhen an application calls
X.CW "wgetevent"
Xin this state, it is terminated.
XTherefore, applications should make sure to always open a window before
Xcalling
X.CW wgetevent .
X.PP
XSTDWIN implementations may limit the size of the event queue; when the
Xqueue is filled up events may get lost without notification.
X(There is no way to prevent this, since the problem usually occurs in
Xthe underlying operating system.)
X.NH 2
XEvents
X.LP
XEvents are typically read in a `main event loop', which might look
Xsomething like this:
X.DS
X.CW
Xint stop= 0;
Xwhile (!stop) {
X    EVENT e;
X    wgetevent(&e);
X    switch (e.type) {
X        ...
X    }
X}
X.R
X.DE
XThe variable
X.CW e
Xis called the
X.I "event record" .
XThe information placed in the event record depends on the event type.
XFor all event types, the type is available as
X.CW "e.type" ,
Xand the window to which the event applies as
X.CW "e.window" ;
Xadditional information is listed with the individual event descriptions.
XThis additional information is stored in a
Xunion named
X.CW e.u ,
Xe.g.,
X.CW e.u.character
Xfor character input events.
X.PP
XFor clarity, events are always referred to by their `informal' names in this
Xpaper, e.g., MOUSE DOWN.
XThe actual constants defined by STDWIN are derived from the informal
Xname by prepending
X.CW WE_
Xand replacing spaces by underscores, yielding, e.g.,
X.CW WE_MOUSE_DOWN .
X.PP
XEvents can be classified as mouse events, other user input events and
XSTDWIN-generated events.
X.NH 3
XMouse events
X.LP
XMouse events are generated when the user presses a mouse button inside
Xthe visible part of a document displayed in a window.
XThere are separate event types for a press of a button, moves while
Xa button is held down, and a release of a button.
XThe position of the mouse cursor at the time the event was generated is
Xreported in (\c
X.CW e.u.where.h ,
X.CW e.u.where.v ).
XThe button number
X(1, 2 or 3 on a three-button mouse; always 1 on a one-button mouse)
Xis reported in
X.CW e.u.where.button .
X.PP
XMouse events allows easy detection of
X.I "multiple clicks" ,
Xto which many applications want to assign a special meaning.
XSuccessive presses on a mouse button are considered to be part of a
Xclick sequence if they are `close together' in space and time.
XWhen a mouse button is pressed, STDWIN checks whether it is close enough
Xto the previous press to be considered a continuation of the same click
Xsequence, and if so, notes the number of the current click in
X.CW e.u.where.click .
XA click that is unrelated to previous clicks has click number 1;
Xa following related click has click number 2, the next one has number
X3, and so on, until the mouse is moved too far away or the user waits
Xtoo long, in which case the click number is reset to 1 at the next
Xmouse event.
XThis way of reporting multiple clicks requires no delay to see whether a
Xclick is part of a multiple-click sequence; mouse events are reported as
Xsoon as they happen.
X.PP
XNot all STDWIN implementations run on machines whose mouse has more than
Xone button; it is therefore unwise to write an application which can
Xperform certain operations only through buttons 2 or 3.
XIf multiple buttons are held down simultaneously, only events for the
Xbutton pressed first are generated.
X.PP
XThe mouse event types are
XMOUSE DOWN
Xfor a button press,
XMOUSE MOVE
Xfor a move of the mouse cursor while a button is still depressed, and
XMOUSE UP for a button release.
XThe click number for MOUSE MOVE events is always zero.
XIn order to prevent filling up the event queue, multiple MOUSE MOVE
Xevents may be collapsed to a single event, giving only the last mouse
Xposition.
XWhen the user moves the mouse outside the window with a button held
Xdown, the mouse remains associated with the window, and its position is
Xreported relative to the origin of the window's document.
XThe click number for a MOUSE UP event is the same as that of the
Xcorresponding MOUSE DOWN event if the mouse wasn't moved too far from
Xits original position, or zero if it was moved further (and in this case
Xthis event is the end of its click sequence).
X.NH 3
XOther user input events
X.IP CHAR
X.br
XThe user has typed a character at the keyboard.
XIts ASCII value is reported in
X.CW e.u.character .
XNote that some special keys (like RETURN, TAB, BACKSPACE) do not send
XCHAR events but COMMAND events.
X.IP COMMAND
X.br
X.RS
XThis event is sent for special keys on the keyboard, and for certain
Xspecial actions recognized by STDWIN.
XSome keys do not generate CHAR events but COMMAND events, because they
Xdo not send the same ASCII code on all keyboards (e.g., Enter), or
Xbecause there are no standard ASCII codes for them (e.g., arrows and
Xfunction keys).
XA code telling which special command was meant is reported in
X.CW e.u.command .
XPossible values represent the following keys and standard actions:
XCANCEL, TAB, RETURN, BACKSPACE, LEFT, RIGHT, UP, DOWN and CLOSE; this
Xlist may be extended in the future.
XThe constants are actually called
X.CW WC_CANCEL
Xetc.
X.PP
XCLOSE is to be interpreted as a request to close the window; the key
Xor other action that generates it is system-dependent.
XThe application should close the window, possibly after verifying that
Xany changes the user has made to the file displayed in the window have
Xbeen saved, in which case it may ignore the request,
Xor put up a dialogue box asking what should be done to the file.
X.RE
X.IP MENU
X.br
X.RS
XA menu item was selected.
XThe menu id and item number of the selected item are reported in
X.CW e.u.m.id
Xand
X.CW e.u.m.item ;
Xmenu items are numbered starting at 0
X(see below for the definition of menus).
X.PP
XThe interaction technique used to select menu items is not defined by
XSTDWIN; a suitable technique is chosen by each implementation, e.g.
Xpop-up, push-down or permanently present menus.
XKeyboard shortcuts are usually also available.
XThe application cannot distinguish between the various ways of selecting
Xa particular menu item; all it sees is which item is selected.
X.RE
X.NH 3
XSTDWIN-generated events
X.IP NULL
X.br
XNothing happened.
XThis is a dummy event reported only by
X.CW "wpollevent"
Xwhen the event queue is empty.
X.IP ACTIVATE
X.br
XA window has been `activated'.
XThis is usually caused by the end user selecting an inactive window with
Xthe mouse.
XOnly one window can be active at any time.
XThis usually means that all subsequent keyboard input applies to
Xthe active window; some applications want to change the highlighting of
Xselected objects in a document when its window is active.
X(Highlighting of the window's title, etc. is done
Xautomatically by STDWIN.)
XAfter a window is opened, the first event applying to it is
Xusually an ACTIVATE event (because windows are opened in an unactivated
Xstate).
XApplications needn't monitor ACTIVATE events if all they want
Xis determining to which window keyboard input applies; the relevant
Xwindow is reported with each event in
X.CW e.window .
X.IP DEACTIVATE
X.br
XA window has been `deactivated'.
XThis usually occurs just before another window is activated.
XIn many implementations of STDWIN it is possible for the user to
Xactivate a window not belonging to the current application; in this case
Xthe current application receives only a DEACTIVATE event until one of
Xits windows is reactivated.
XNote that closing a window does not generate a DEACTIVATE event for it,
Xsince the window has already disappeared by the time the application can
Xcall
X.CW "wgetevent" .
X.IP SIZE
X.br
X.RS
XA window's size has changed.
XThis is usually done by the user explicitly resizing the window;
Xin some (`tiling') STDWIN implementations it can also be caused by
Xopening or closing other windows.
X.PP
XSome applications want to format their documents to fit exactly in the
Xwindow.
XSIZE events make it possible for such applications to monitor window
Xsize changes.
XThe new window size is not reported in the event record; the application
Xcan use the enquiry function
X.CW wgetwinzize
Xfor this purpose (see below).
X.PP
XNote that window moves don't generate events
X(except possibly DRAW events).
X.RE
X.IP DRAW
X.br
XThis event is reported only for windows without an associated draw
Xprocedure.
XIt means that part of the window needs to be repainted.
XThe smallest rectangle enclosing the area to be repainted is reported in
X.CW e.u.area ,
Xa struct with four fields
X.CW left ,
X.CW top ,
X.CW right
Xand
X.CW bottom .
X.IP TIMER
X.br
XThe window's alarm timer has gone off.
XFor each window, an alarm may be set with the call
X.CW "wsettimer(win, dsecs)" .
XThe alarm will go off, causing a TIMER event,
Xaproximately
X.I dsecs/10
Xseconds in the future (\c
X.I dsecs
Xmeaning deciseconds).
XOnly one alarm per window is maintained; a new call overrides the
Xpreviously set alarm.
XA value of 0 cancels the alarm.
XTimer values may be rounded up to whole seconds by some implementations.
XThe maximum timer value that is guaranteed to be supported is
X32000 dsecs.
X.NH 2
XPushing events back
X.LP
XOccasionally, an application may want to postpone processing of an event
Xtill later.
XE.g., a subroutine may be getting events in a loop until it
Xreceives an event which shouldn't be handled locally but in the main
Xevent loop.
XThe routine
X.CW "wungetevent(&eventrecord)"
Xallows an event to be pushed back onto the event queue; the next
Xcall to
X.CW wgetevent
Xor
X.CW wpollevent
Xwill report the event just pushed back.
XOnly a single event can be pushed back (some implementations save the
Xpushed back event in a separate buffer).
XIt is possible to modify the event before pushing it back, or to
Xsynthesize events entirely.
X.NH 2
XGetting and setting the active window
X.LP
XA pointer to the active window is returned by the function
X.CW "wactive()" .
XThe application can also make a different window active by calling
X.CW "wsetactive(win)" .
XThis call does not take effect immediately; some time in the future, a
XDEACTIVATE event for the currently active window and an ACTIVATE event
Xfor the newly activated will be received.
X.NH 2
XMenus
X.LP
XMost window systems provide a simple way to set up and manipulate menus,
Xin their simplest form lists of text strings which can be selected by
Xthe user by clicking on a string with the mouse.
XMenus may `pop up' when a particular mouse button is pressed in a
Xparticular screen area, or be `pulled down' from a `menu bar', etc.
XSTDWIN provides a consistent, simple way for the application to
Xinterface with standard menus, or with menus defined entirely by the
XSTDWIN library (if the window system provides no usable menus).
X.PP
XA
X.I menu
Xcontains a number of
X.I items ,
Xnumbered starting at 0.
XA menu has a
X.I title ,
Xa text string displayed to identify the menu to the user, and a
X.I "menu id" ,
Xa small positive integer identifying the menu to the application.
XEach item contains a text string, an optional
X.I "check mark"
X(which may be set by the application to indicate whether an option
Xcontrolled by a menu item is active), and can be
X.I enabled
Xor
X.I disabled .
XOnly enabled items are selectable.
XWhen the user selects an enabled item, a MENU event is queued containing
Xthe menu id and item number in the event record.
XBecause of the way events are queued, it is possible to receive MENU
Xevents for disabled menu items
X(if the selection was made before the menu item was disabled);
Xapplications should be prepared to receive spurious menu selection events.
X.PP
XA menu is created by a call to
X.CW "wmenucreate(id, title)" ;
Xthis returns a
X.I "menu pointer"
Xwhich must be used for all further manipulations with the menu.
X.I Id
Xis the menu id, which should be in the range [1..255].
XMenu ids should be unique within an application.
X.PP
XInitially, a menu contains no items.
XItems are added by calling
X.CW "wmenuadditem(mp, text, shortcut)" .
XThe new item's number equals the number of items in the menu before this
Xcall; it is returned as the function value.
X.I Mp
Xis the menu pointer;
X.I text
Xis the item text.
XThe item is initially enabled and unchecked.
X.I Shortcut
Xis a character used to construct a `keyboard shortcut' for the
Xmenu item; \-1 means the item is not to have a shortcut.
X(The interpretation of keyboard shortcuts is implementation-dependent.
XIn a typical STDWIN implementation,
Xa menu item with shortcut `X' might be selected by typing ESC-X
Xor Meta-X (but not Control-X).
XAll printable characters are acceptable as shortcuts,
Xbut on some systems lower case and upper case are indistinguishable.)
XAdding an item with an empty string as text adds a disabled
X`separator' item.
X.PP
XThe text of an existing menu item can be changed by calling
X.CW "wmenusetitem(mp, number, text)" .
XItems can be enabled or disabled by calling
X.CW "wmenuenable(mp, number, flag)" .
XThe check mark for an item can be set or cleared by calling
X.CW "wmenucheck(mp, number, flag)" .
X.PP
XA menu can be deleted by calling
X.CW "wmenudelete(mp)" .
XNote that individual menu items, once added, cannot be removed, nor can
Xnew items be inserted in the middle.
XThis is due to restrictions in many window systems' menu interfaces;
Xusually menus are sufficiently static that it doesn't matter.
X.PP
XFor a menu's items to be selectable, the menu must be attached to a
Xwindow and the window must be activated.
XNormally, STDWIN automatically attaches all menus to all windows, so all
Xmenus become selectable as soon as the first window is activated.
XTo change this behaviour, the call
X.CW "wmenusetdeflocal(TRUE)"
Xcauses subsequently created menus to be `local', requiring
Xexplicit attachment and detachment.
XThe call
X.CW "wmenuattach(win, mp)"
Xattaches the menu
X.I mp
Xto the window
X.I win .
XThe call
X.CW "wmenudetach(win, mp)"
Xreverses this effect.
XA menu may be attached to multiple windows; multiple menus may be
Xattached to a window.
XAfter calling
X.CW "wmenusetdeflocal(FALSE)" ,
Xfuture menus will be `global' again, i.e., automatically attached to all
X(existing and new) windows.
X.NH
XAdditional facilities
X.LP
X.NH 2
XEnquiry functions
X.LP
XSome enquiry functions are available to interrogate the system state.
X.LP
X.CW "wgetscrsize(&width, &height)"
X.IP
XReturns the screen size measured in pixels into the integer variables
Xwhose addresses are passed.
X.LP
X.CW "wgetscrmm(&mmwidth, &mmheight)"
X.IP
XReturns the approximate screen size measured in millimeters.
XBy combining this information with the outcome of
X.CW wgetscrsize ,
Xpixel size and aspect ratio can conveniently be computed.
XIn some (most?) implementations, the numbers returned may be
Xapproximations or guesses.
X.LP
X.CW "wgetwinsize(win, &width, &height)"
X.IP
XReturns the size of the drawable area of a window, measured in pixels.
X(Due to the presence of borders, a maximally-sized window is usually
Xsmaller than the screen.)
X.NH 2
XThe text caret
X.LP
XIn documents that deal with text it is often useful to have some form of
X`text cursor', indicating the position where characters typed at the
Xkeyboard will be inserted.
XThe call
X.CW "wsetcaret(win, h, v)"
Xcauses a `caret' to appear just to the left of the character
Xposition (\c
X.I h ,
X.I v )
Xin the document.
XThe caret appears immediately before any character that
Xwould be drawn by
X.CW "wdrawtext(h, v, ...)" .
XThe caret has a system-defined shape; it is often a blinking vertical
Xbar.
X.PP
XEach window has its own caret; the caret in the active window may be
Xthe only one that is visible, or it may blink while the carets in other
Xwindows are static.
XAt any time a window has at most one caret; the old caret is removed
Xwhen a new one is specified.
XThe caret can be removed altogether with the call
X.CW "wnocaret(win)" .
X.NH 2
XDialogue tools
X.LP
XA
X.I "dialogue box"
Xis a `mini-window' containing a simple message or question,
Xand requiring
Xthe user to respond, e.g. by pressing a key or clicking the mouse in a
Xparticular area.
XAs long as the dialogue box is present, the application is blocked.
XAfter answering the question or acknowledging the message, the dialogue
Xbox disappears and normal interaction with the application continues.
XDialogue boxes may be presented even when no windows are open yet.
XThe following calls put up dialogue boxes and wait for a response:
X.sp
X.LP
X.CW "wmessage(string)"
X.IP
XDisplays a message and waits until the user acknowledges it.
XThe precise form of acknowledgement required
Xis implementation-dependent;
Xit could be pressing the Return key or clicking an `OK button' with the
Xmouse.
X.LP
X.CW "waskstr(question, replybuf, buflength)"
X.IP
XDisplays a question and waits until the user has finished typing a
Xreply.
XThe initial contents of the reply buffer are used as a default reply.
XThe function normally returns TRUE; if the user aborts the dialogue
X(e.g., by pressing the CANCEL button) it returns FALSE.
X.LP
X.CW "waskync(question, dflt)"
X.IP
XDisplays a question which gives the user the possibility to answer with
XYes, No or Cancel only.
XThe return value is 1 (Yes), 0 (No) or -1 (Cancel).
X.I Dflt
Xis the suggested (default) return value.
X.LP
X.CW "waskfile(prompt, replybuf, buflength, new)"
X.IP
XDisplays a dialogue box asking for a file name.
X.I Replybuf
Xinitially contains a default or suggested file name.
XThe boolean parameter
X.I new
Xspecifies whether a new (not yet existing) or old (existing) file is
Xrequired.
XWhen a new file is asked for, the user may specify an existing file,
Xbut in this case explicit permission is asked to overwrite it.
XThe function returns TRUE, or FALSE if the user aborts the dialogue.
XThe file name is returned in a form acceptable to the STDIO function
X.CW fopen .
XSTDWIN implementations may provide additional support, e.g. file name
Xcompletion or file system browsing; the fact that some systems provide
Xelaborate standard file-selection dialogues (which is highly appreciated
Xby the end users) was a strong motivation to include this function in
XSTDWIN.
X.LP
X.CW "wperror(string)"
X.IP
XDisplays an error message similar to that printed by the standard C
Xfunction
X.I perror (3),
Xand waits for an acknowledgement as for
X.CW wmessage .
X.sp
X.LP
XIt should be noted that
X.CW "waskstr"
Xis the most general of the above functions; in theory, versions of the
Xothers can be implemented with the help of
X.CW "waskstr"
Xand other existing tools.
X.NH 2
XThe text-editing package
X.LP
XThe
X.I text-editing
Xpackage is a set of routines implemented entirely `on top of' STDWIN,
Xwithout using any implementation-dependent functions or data structures.
XThe availability of this package
Xis important because it provides a standard way to tackle the
Xnon-trivial problem of editing multi-line text blocks.
XIt is clearly influenced by the TextEdit routines available in the Apple
XMacintosh's ROM Toolbox (but contains only original code).
X.PP
XThe text-editing package displays a paragraph of text in a rectangle of
Xa given width, breaking the lines at spaces between words as necessary.
XIt gives the application complete control over what happens to the text,
Xbut provides an easy way to handle user input intended to edit it.
X.PP
XThe call
X.CW "tecreate(win, <rectangle>)"
Xreturns a pointer to a text-editing block at the specified position in
Xthe given window's document.
X(A text-editing block is not a portion of the document but a data
Xstructure.)
XAny number of text-editing blocks may be created, although usually at
Xmost one block per window should be editable at any time.
X.PP
XInitially, the block contains no text.
XThe call
X.CW "tesettext(tp, string)"
Xsets the text to be edited, replacing any existing text in the block.
XThe call
X.CW "tegettext(tp)"
Xreturns a pointer to the text string (which remains valid only until the
Xnext call to a text-editing routine).
X.PP
XThe text block is not automatically drawn.
XWhen a text-editing routine changes the edited text (or other aspects of
Xits appearance), it calls
X.CW wchange
Xfor the appropriate area of the window; the window's draw procedure
Xshould call
X.CW "tedraw(tp)"
Xfor each block which overlaps the repaint area.
X.PP
XBesides the edited string, a text-editing block contains a
X.I focus ,
Xindicating which text is selected
Xfor deletion or at which position new text will be inserted.
XThe focus can be set by the application with the call
X.CW "tesetfocus(tp, first, last)" ,
Xtelling that the characters in the range [first..last-1] are selected,
Xor, if first equals last, that the text insertion point is at that
Xposition (characters are counted starting at 0).
XIf the focus is an insert position, the window's caret is set at that
Xposition in the document.
XText can be inserted at the focus (replacing its previous contents) by
Xcalling
X.CW "tereplace(tp, string)" ;
Xspecifying an empty string deletes any text in the focus.
X.PP
XThe simplest way to let the user edit the text in a text-editing block
Xis to call
X.CW "teevent(tp, &event\%record)"
Xfor each event.
XThis call returns TRUE if the event is applicable to the text-editing
Xblock (e.g., it is a CHAR event, or a mouse click within the block's
Xbounding rectangle), and in that case the event is processed by the
Xtext-editing package (e.g., a character is inserted, or the focus is
Xmoved to the point where the mouse was clicked).
XIf the event is not applicable to the particular block, the function
Xdoes nothing and returns FALSE; in this case the application should
Xfurther decide what to do to the event.
XOf course, the application is free to decide whether to offer an event
Xto a text-editing block at all; e.g., it might have a different
Xinterpretation for the Return key (for which the text-editing package
Xinserts a new-line character in the text string).
X.PP
XThere are more text-editing calls, e.g. to move a text-editing block to
Xa new position, to enquire about the focus, to perform individual
Xediting operations, to ask for the height of the rectangle minimally
Xneeded to display the text entirely, etc.
X.PP
XThe following call displays a text string in exactly the same way as
Xthe text-editing package would do (breaking it into lines at the same
Xplaces, etc.), but without creating a text-editing block, and thus
Xwithout a focus:
X.CW "wdrawpar(<point>, string, width)" .
XIt returns the v coordinate of the bottom of the text paragraph.
XTo compute the height of a text paragraph thus drawn without actually
Xdrawing it, one can call
X.CW "wparheight(string, width)" .
X.NH
XA complete example
X.LP
XThe program below is a complete STDWIN application.
XIt is presented here to give a feel for the use of some of the routines
Xdescribed above.
XThe program displays a window in which a text-edit block is placed;
Xall events recognized by the text-edit package are handled correctly,
Xand so are several ways of quitting.
XOther events are ignored.
X.if t .sp .5v
X.DS L
X.CW
X#include <stdwin.h>
X
XTEXTEDIT *tp; /* Global so drawproc can reference it */
X
Xvoid drawproc(w, left, top, right, bottom)
X    WINDOW *w;
X    int left, top, right, bottom;
X{
X    tedraw(tp);
X}
X.R
X.DE
X.DS L
X.CW
Xmain()
X{
X    MENU *m;
X    WINDOW *w;
X    int stop;
X    int width, height;
X.R
X.DE
X.DS L
X.CW
X    winit();
X    
X    m= wmenucreate(1, "Sample");
X    wmenuadditem(m, "Quit", 'Q'); /* Item 0 */
X    
X    w= wopen("Sample window", drawproc);
X    wgetwinsize(w, &width, &height);
X    tp= tecreate(w, 0, 0, width, height);
X.R
X.DE
X.DS L
X.CW
X    stop= 0;
X    while (!stop) {
X        EVENT e;
X        wgetevent(&e);
X        if (teevent(tp, &e))
X            wsetdocsize(w, width, tegetbottom(tp));
X        else {
X            switch (e.type) {
X            case WE_COMMAND:
X                if (e.u.command == WC_CLOSE || e.u.command == WC_CANCEL)
X                    stop= 1;
X                break;
X            case WE_MENU:
X                if (e.u.m.id == 1 && e.u.m.item == 0) /* Quit */
X                    stop= 1;
X                break;
X            }
X        }
X    }
X.R
X.DE
X.DS L
X.CW
X    wclose(w);
X    wdone();
X    exit(0);
X}
X.R
X.DE
X.if t .sp -.5v
X.NH
XExperiences
X.LP
XFive distinct STDWIN implementations have been created so far:
Xfor the Apple Macintosh,
Xfor the Whitechapel MG-1,
Xfor X version 11,
Xfor the Atari ST,
Xand a subset for alphanumeric displays
X(which runs both under Unix and MS-DOS).
X.PP
XOnce a STDWIN version for a target system is available,
Xapplication portability is high.
XMost portability problems that crop up
X(besides the usual problems like word size, byte order,
Xdata alignment or following NULL pointers)
Xhave to do with differences in other parts of the operating system
Xinterface, e.g. use of the file system.
XOne portability problem encountered with the STDWIN interface was that
Xsome programs developed for alphanumeric terminals expected a
Xfixed-width font; in general most problems were caused by insufficiently
Xprecise specification of STDWIN.
X.PP
XThe time needed to create a STDWIN version for a particular target
Xsystem is moderate.
XAn experienced C programmer who did not know anything about STDWIN or
Xthe Atari ST in advance
Xcreated a working Atari ST version in two months.
XSo far, each version has been created more or less from scratch
X(except for the common parts like the textedit package).
XWe have now gained enough experience with different target systems to be
Xable to create an intermediate layer containing code which remains more
Xor less constant between target systems.
X.NH
XFuture developments
X.LP
XTo date, the applications that use STDWIN have been mostly text-based.
XUndoubtedly, this has influenced the direction of development of drawing
Xfacilities in STDWIN.
XIt is sufficiently easy to add graphical primitives to an
Ximplementation, though, that we expect to add several as demand grows,
Xe.g., bitblt, clipping, line styles, filling.
XThe existing facilities set a sort of standard for the form of future
Xones.
XThe requirement that they be implementable on top of a large variety of
Xwindow systems will ensure that only more or less generally accepted
Xprimitives will be included in STDWIN; a useful sort of conservatism for
Xa package that wants to enhance application portability.
X.PP
XBesides the need to add more drawing primitives, there are several areas
Xwhere STDWIN requires, and will probably get, extensions: fonts, sizes
Xand styles; the mouse cursor; drawing in off-screen bitmaps (not
Xassociated with a window); error handling (which is currently virtually
Xabsent); event queue manipulations and an `event mask'; `clipboard' or
X`cut buffer' operations.
X.PP
XA development in a different direction, independent of the addition of
Xgraphical primitives, may be the addition of more toolboxes built on
Xtop of the exiting facilities, like the text editing package.
XTools are needed
Xto manipulate higher-order graphical objects,
Xto implement specific interaction techniques,
Xto provide `canned applications' like text-editing windows,
Xetc.
X.PP
XA third, potentially very useful, extension would be the addition of
Xdrawable
X`borders' to the window that aren't scrolled together with the document.
XIn such borders, interaction tools could be placed like palettes and
Xbuttons, or rulers around the document.
XThe design of such an extension should be the topic of further research,
Xin order to achieve the largest possible generality.
X.\" Filter troff input through refer -e -n
X.[
X$LIST$
X.]
END_OF_FILE
if test 51068 -ne `wc -c <'Doc/paper.ms'`; then
    echo shar: \"'Doc/paper.ms'\" unpacked with wrong size!
fi
# end of 'Doc/paper.ms'
fi
if test -f 'Ports/mac/pstring.c' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'Ports/mac/pstring.c'\"
else
echo shar: Extracting \"'Ports/mac/pstring.c'\" \(497 characters\)
sed "s/^X//" >'Ports/mac/pstring.c' <<'END_OF_FILE'
X/* Function to convert a C string to a Pascal string.
X   The conversion is not in-line, but returns a pointer to a static buffer.
X   This is needed when calling some toolbox routines.
X   MPW does the conversion in the glue.
X*/
X
X#include "macwin.h"
X
X#ifndef CLEVERGLUE
X
Xchar *
XPSTRING(src)
X	register char *src;
X{
X	static char buf[256];
X	register char *dst;
X	
X	dst = &buf[1];
X	while ((*dst++ = *src++) != '\0' && dst < &buf[256])
X		;
X	buf[0] = dst - &buf[1];
X	return buf;
X}
X
X#endif /* CLEVERGLUE */
END_OF_FILE
if test 497 -ne `wc -c <'Ports/mac/pstring.c'`; then
    echo shar: \"'Ports/mac/pstring.c'\" unpacked with wrong size!
fi
# end of 'Ports/mac/pstring.c'
fi
echo shar: End of archive 2 \(of 19\).
cp /dev/null ark2isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 ; do
    if test ! -f ark${I}isdone ; then
	MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 19 archives.
    rm -f ark[1-9]isdone ark[1-9][0-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0