home *** CD-ROM | disk | FTP | other *** search
- From: guido@cwi.nl (Guido van Rossum)
- Newsgroups: alt.sources
- Subject: STDWIN 0.9.5, Part 02/19
- Message-ID: <3066@charon.cwi.nl>
- Date: 4 Mar 91 11:57:33 GMT
-
- 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@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@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
-