guido@cwi.nl (Guido van Rossum) (03/04/91)
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