Functional SpecificationVista: SDD Display Window PackageSeptember 24, 1980IntroductionVista, sometimes called "the New Window Package", replaces current SDD windows implementations andis a supported "development software" package. It is used by the Tools Environment & Debugger andwill be the package of choice for private system developments, such as the Desktop Prototype.OverviewHardware and Operating SystemVista runs on Altos and Dolphins. The external interface presented to the client is the same on the twomachines. Configurations supported:Narrow Altos running Mesa Wide Altos running Mesa (two banks only)XMesa Altos running MesaDolphins running Mesa (Alto display only)Dolphins running PilotThe Window TreeVista creates a tree of windows.There is one root window (at level "zero") which is always equated to the visible bitmap and whichsupplies the background grey.Any window may have child windows contained within it.î ï\wpôžîmïWÈð!î%þïTqôXî¶ïI-rî¶ïDqô‰ð:ôŠsqî¶ïBIô˜ ô™ðTî¶ï@~ôð]î¶ï9 rî¶ï2tî¶ï.”qôðXôî¶ï,Éôð$î¬ï*+î¬ï'ð(î¬ï$îî¬ï"Pð)î¬ï²î¶ï«tî¶ï9quqî¶ïÇô¾u qð9ô¿î¶ïüôî¶ïŠð6ÿ¦¶CAVõ{2Child windows "obscure" their parent -- that is they are "above" their parent in the apparent "stack" ofwindows visible on the screen.Sibling windows may overlap: the eldest sibling -- the one which appears first in the list -- is the sibling"on top" of the stack.Vista contains routines for creating and destroying windows, for arranging them, and for displaying datawithin them.A comparison with the current Tools Environment: The first level of the window tree contains what, arenow called windows. The lower levels of the window tree contain what are now called subwindows.There is no longer any distinction between windows and subwindows. In the following discussion, allsymbols come from the interface Window unless otherwise qualified.OrganizationVista is organized as a collection of procedures. It is passive, responding only to calls from the client'sprogram. It creates no processes. It allocates almost no storage. There is a discussion about starting theworld, and Vista's interface to the bitmap in a section on UserTerminal at the end of this document.WindowsWindows occupy [possibly overlapping] rectangular regions of the virtual bitmap. A window's locationand size are defined in terms of its parent's location; the root window is always at bitmap location [0,0]even though its box.place may not be [0,0]. The box.place of rootWindow is the screen place ofthe bitmap origin.Windows "overlap" other windows and may be manipulated even when they are "under" other windows.Windows are contained within their parents rectangular regions: if they are of a size and position thatthey would "stick out" of their parent, their display is "trimmed off" at their parent's edge.Storage AllocationMost storage allocation is provided by the client. On window creation, the client provides a handle toobject storage space that he has obtained. This lets Vista be independent of and not fight with theclient's allocation strategies.All Vista object handles are of the form POINTER TO Object. Note: all Vista objects must be in the MDS.Often a client wishes to associate some private data with each window instance. The client can easily dothis by providing Vista with storage blocks larger than SIZE [Object].ÿîN°ïfñqî¶ïbôð4ô‘ð4î¶ï`Sôî¶ï\áôˆðeô‰î¶ï[ôî¶ïW¥ô”ô•ðMî¶ïUÚôî¶ïRhô…ð5ô†ð2î¶ïPžô¶ð(ô·ð8î¶ïNÓô©ôªðNî¶ïMôvqî¶ïFtî¶ïBqô›ð5ôœð7î¶ï@Åô‡ôˆðYî¶ï>úô±ð-ô²ð7î¶ï7ótî¶ï4qô¤ð<ô¥ð)î¶ï2¶ô—ðTô˜î¶ï0ìô™vqvqv q ôšî¶ï/!ôî¶ï+¯ô…ô†ðOî¶ï)äô§ðNô¨î¶ï(ôð^î¶ï!tî¶ï¡qô ð#ô¡ðDî¶ïÖô»ô¼ðPî¶ïôî¶ïšô§ð)w qvqs qsô¨î¶ï(qô‹ðiî¶ï]ôð8wqvq´¶BVõâ3Window PaintingVista provides a variety of procedures which enable the client to display data in a window by whiteningand blackening the bits in the window. These procedures include:Character and string paint proceduresBlacken/whiten/grey box proceduresCopy-this-array-of-bits proceduresBrush-and-trajectory paint procedures which allow graphics curves to be easily drawn (not ininitial release).Every window object contains a client-supplied repaint procedure which, on demand, will repaint all orpart of the window. This procedure is invoked, for example, when a window which was obscured by anoverlapping window suddenly becomes more visible.ScrollingRecall that areas that "stick out" of a window's parent are trimmed for display purposes. Arbitraryscrolling can be implemented quite simply by imbedding a window (the one that paints the data to bescrolled) within another window (the "frame") and then just altering the position (y coordinate forvertical scrolling) of the former within the latter: routines are provided which will perform theappropriate BITBLTs to minimize the area to be painted.Invalid AreasWithin a window as shown on the bitmap, sections of bits may become incorrect due to "externalcircumstances" -- e.g. because a window that was hiding them was just deleted. Vista accumulates theseinvalid areas and then calls the client's repaint procedure to fix them up. The client can indicate to Vistawhether to keep extensive (and expensive) information about the exact areas that are invalid, or to keepbriefer "bounding" information: the client will make this choice depending on how clever his repaintprocedure is at repainting small sub-regions of the window.Normally, when the client is called to paint the invalid area(s), there are no bits in the area that are blackbut should be white (the window package has possibly cleared the area to insure this) so the repaintprocedure can use "or" functions when repainting. If the client knows that his repaint procedure alwayssets all of the bits in the area(s), he indicates this in the window object: this may save Vista fromperforming unnecessary clearings.Features Not PresentVista is exclusively a windows and bitmap package. It has nothing to do with the keyboard and themouse.îN°ïfªqî¶ïa×tôî¶ï^eqô’ð>ô“ð)î¶ï\›ôðAî¬ïYüð%î¬ïW^ð"î¬ïTÀð"î¬ïR"ôÀðDôÁî¬ïPWôî¶ïLåô¥ð.ô¦uqð&î¶ïKô‹ð&ôŒð=î¶ïIPôð1î¶ïBItî¶ï>×qô¾ô¿ðGî¶ï=ô ð)ô¡ð:î¶ï;AôÒð_ôÓî¶ï9wôþôÿðKî¶ï7¬ôxsqð$î¶ï0¥tî¶ï-3qôÏðMôÐî¶ï+iô’ðOô“î¶ï)žô‰ð*uqôŠî¶ï'Óô“ðKô”î¶ï& ô§ð:ô¨ð+î¶ï$>ôð;î¶ï ÌôðVô‚î¶ïô´ôµðLî¶ï7ôŒð2ôð6î¶ïlôÇôÈð]î¶ï¢ôð!î¶ï›tî¶ï)qô²ðZô³î¶ï ^ÿÖ¶ AZôå4Vista provides no scrollbars or menus. Scrollbars can be built by the client with windows and menus canbe built by the client with "bitmap under" windows.AcceleratorsSince all window movement is done via explicit call [unlike the current Tools implementation, where theWindowObject and SubwindowObject can be directly manipulated by the client], Vista can maintainaccelerator information within windows such as totally visible and totally invisible bits.Definitions FilesVista follows the Pilot naming conventions for definitions files. There are seven definitions files in thepackage:Window contains all of the normal windows functions.WindowFont contains the font object and handle and the font related routines, which areexactly Initialize, CharWidth, and FontHeight.WindowOps contains private interfaces used by the implementation.WindowCookie contains interfaces which will be used by Vista to support "cookie cutter"style iconic movement. This is not supported in the first release, and "cookies" wil not beextensively discussed in this specification.UserTerminal and UserTerminalOps contain functions for manipulating and polling thehardware that Vista will run upon. See the last section of this document for a discussion of theiruse.Event provides the capability of having procedures called upon certain events happening to theenvironment. See the Tajo Functional Specification for information regarding it. It is includedin the Alto version of Vista since the implementation of UserTerminal depends upon it.The Window ObjectRecord DefinitionÿîN°ïfñqî¶ïbô‚ð?ôƒð)î¶ï`Sôð3î¶ïYLtî¶ïUÚqôŒð?ôð(î¶ïTôÈðRôÉî¶ïREôð/uquqî¶ïGÌrôiî¶ïC†qôôžðMî¶ïA¼î¬ï=vvqôð.î¬ï90v qô½ð2ô¾î¬ï7fôv qvqv qî¬ï3 vqð9î¬ï.ÚvqôºðDô»î¬ï-ôÆð\î¬ï+Eôð,î¬ï'vqô·vqô¸ð+î¬ï%5ô„ð'ô…ð<î¬ï#jî¬ï%vqôˆ ô‰ðPî¬ïZô–ðUô—î¬ïôØôÙvqî¶ïˆrôiî¶ï tôÿ¶ 2A]Ù¼5Place: TYPE = UserTerminal.Coordinate;Dims: TYPE = RECORD [w, h: INTEGER];Box: TYPE = RECORD [place: Place, dims: Dims];LinkedBox: TYPE = RECORD [boxes: Boxes, box: Box];Boxes: TYPE = POINTER TO LinkedBox;BoxesCount: TYPE = {none, one, many};Handle: TYPE = POINTER TO Object;Object: TYPE = RECORD [-- "Minus Land" is the possibly-allocated space before the location-- that the WindowHandle points to. It is like a backwards variant space.-- Booleans in the record body indicate whether the optional things are really-- present. If present, they are in the order shown, away from the window:-- cookie: MinusLandCookieCutter, "cookie cutter" location .. NIL for none-- under: MinusLandBitmapUnder, "bitmap under" location .. NIL for noneparent: Handle _ NIL,-- its parentsibling: Handle _ NIL,-- the sibling chainchild: Handle _ NIL,-- first childbox: Box _ [[0,0],[0,0]],-- parent relative location and sizedisplay: PROCEDURE [Handle] _ NIL,invalidBoxes: Boxes _ NIL,cookieCutterVariant: BOOLEAN _ FALSE,-- Is a "cookie cutter" in minus land?cookie: BOOLEAN _ FALSE,-- Is window a "cookie" now?underVariant: BOOLEAN _ FALSE,-- Is a "bitmap under" location in minus land?underNow: BOOLEAN _ FALSE,-- Is there a current active "bitmap under"?underSomewhat: BOOLEAN _ FALSE,-- Is bitmapunder incorrect for invisibles?boxesCount: BoxesCount _ one,-- How many boxes to compute invalid forclearingNotRequired: BOOLEAN _ FALSE,-- does display proc totally replace?invalidNow: PRIVATE BOOLEAN _ FALSE,-- Is some part of window currently invalid?totallyInvisible: PRIVATE BOOLEAN _ FALSE,-- Is window's area totally obscured?totallyVisible: PRIVATE BOOLEAN _ FALSE,-- Is window's area totally visible?obscuredBySibling: PRIVATE BOOLEAN _ TRUE,-- Does a sibling obscure me?obscuredByUncle: PRIVATE BOOLEAN _ TRUE,-- Does an ancestor's sibling obscure me?sticksOut: PRIVATE BOOLEAN _ TRUE-- Does it stick out past an ancestor? -- ];-- records to define the MinusLand components so "SIZE" works --MinusLandCookieCutter: TYPE = MACHINE DEPENDENT RECORD [LONG POINTER];MinusLandBitmapUnder: TYPE = MACHINE DEPENDENT RECORD [pointer: LONG POINTER, -- to WordsForBitmapUnder [window] wordsunderChanged: PROCEDURE [Handle, Box], -- ^ called when bitmap under changes if # NIL --mouseTransformer: PROCEDURE [Handle, Place] RETURNS [Handle, Place] ]; -- ^ called to convert a mouse position if # NIL --Client-Data Associated with a WindowSince the client handles all the storage allocation, it is simple for him to reserve private space associatedwith a window object for his private context. All he has to do is to allocate more than SIZE [Object]storage for the window.In Mesa, the convenient thing for the client to do is to declare a record type which includes both theÿîN°ïfñqî¬ïbyôXwyî¬ï`šwywywyî¬ï_wywyî¬ï]’ wywyî¬ïZóôwyw y î¬ïY)wyî¬ïUwyw yî¶ïQ¸ôXwywyî¶ïP4zð0{zî¶ïN°ðJî¶ïM,ðNî¶ïK¨ð6{zî¶ïJ#ðKî¶ïHŸðHîïGywyî-ÀzîïE—ywyî-ÀzîïDywyî-Àz îïByî-Àzð$îïAywyîï?‡wyîï>wywyî-Àzð&îï<ywywyî-Àzîï:ûy wywyî-Àzð.îï9wy wywyî-Àzð,îï7óywywyî-Àzð+îï6oyî-Àzð(îï4ëywywyî-Àzð%îï3gywôFyî-ÀzôXð*îï1ãywôFyî-ÀzôXð#îï0_ywôFyî-ÀzôXð"îï.ÚywôFywyî-ÀzôXîï-VywôFywyî-ÀzôXð'îï+Òy wôFywî-ÀzôXð'yî¶ï(Êzð@î¶ï'FywywôFyôXwôFyî¶ï%|ôwyîï#±wyzð)îï!æy wyîï zð2îïQywywyîï‡zð4î¶ïtð$î¶ï qô’ð:ô“ð3î¶ïCôžð?ôŸwsqvqî¶ïxôî¶ïô¦ð@ô§ð& È¶ ¿A]L6Object and his own data:MyWindowObject: TYPE = MACHINE DEPENDENT RECORD [ window: Window.Object, context: MyContext ];MyWindowHandle: TYPE = POINTER TO MyWindowObject;Then, given a Vista Handle, he can simply reference his data viamine: MyWindowHandle _ LOOPHOLE [windowHandle];something: MyContext _ mine.context;"Minus Land"There are optional fields within the Object. This is to minimize storage requirements. If the client isutilizing the optional features associated with these fields, he needs to allocate an appropriate amount ofstorage and supply a Handle that points to the correct place within the allocated block.Example: if the client wants a "bitmap under" to be maintained by Vista, he can set the bitmapUnder boolean in the Objectand supply, as the object's storage pointer, something likeStorage.Node [ SIZE[Object] + SIZE[MinusLandBitmapUnder] ] + SIZE[MinusLandBitmapUnder]The "Cookie" Window [not supported in initial release]Vista allows a window to appear to be of irregular shape. This is implemented by defining a normalrectangular window and then arranging things so that part of the background "below" the window"shows through" it.The implementation is arranged so that a user who does not utilize cookies is not burdened with theimplementation cost.To define a cookie, the user defines a window with a MinusLandCookieCutter. TheMinusLandCookieCutter points to a block of memory which is a bitmap that defines where thecookie-window is to be transparent. This "cookie cutter" bitmap mask contains ones where the cookie isopaque and zeros where the cookie is transparent. The "words per line" of the cookie cutter bitmap is(window.box.dims.w+15)/16. The cookie cutter may be redefined with this procedure:WindowCookie.SetCookieCutter: PROCEDURE [Handle, LONG POINTER]Before actually inserting any cookie windows into the window tree, the client must give the windowpackage some working space to manipulate cookies and cookie cutters:WindowCookie.SetCookieWorkingSpaces: PROCEDURE [CARDINAL, LONG POINTER, LONGPOINTER]îN°ïfñqî¶ïbvqôî¬ï^‰ywywyî¬ï\›î¬ïZî¬ïX¿wyw yî¶ïUMqvqð&î¬ïQ¸yvyî¬ïOÊð$î¶ïHÃtî¶ïEQqô–ð%vqð4ô— î¶ïC†ô’ðUô“î¶ïA¼ôvqð=î¶ï>msô‰ðkôŠxî¶ï<ésôð;î¬ï9šwôFð<î¬ï7óî¶ï1tôð7î¶ï-zqôªô«ðKî¶ï+¯ôÒðWôÓî¶ï)äôî¶ï&sô°ô±ðNî¶ï$¨ôî¶ï!6ôLôMð,vqî¶ïkvqôÆð.ôÇî¶ï¡ô‰ôŠðQî¶ïÖô˜ð=ô™ð)î¶ïvqôð:î¬ïàyqôXwqyqwôFqî¶ïnô¾ô¿ðSî¶ï¤ôðDî¬ïxyôXð%wywywôFyôXwî¬ïôyÿ¶A[^õ7This procedure supplies two blocks of memory and a word count of how big each block is. Cookieswhich contain more words [((cookie.box.dims.w+15)/16)*cookie.box.dims.h] than the suppliedblocks don't act like cookies.The "Bitmap Under"The user may supply a block of memory that Vista will use to maintain the bits that would appear, in thebitmap, where this window is if this window, and those covering it up, did not exist.This is useful primarily because Vista can then, when this window is removed from the tree, fix up thebitmap without calling the display procedure of all the windows that were (partially) hidden by thisone. Thus menus can appear and disappear quickly.Associated with the bitmapUnder is the underChanged procedure. This procedure, if supplied, iscalled whenever the bits in the bitmapUnder change due to another window's painting. This is useful inimplementing a "magnifying glass" window or other window that does not really cover up the windowsunder it, but rather wishes to transform them in some way.Also associated with the bitmapUnder is the mouseTransformer procedure. This procedure, ifsupplied, is called whenever a bitmap location is resolved (by the PlaceToWindowAndPlaceprocedure) to a position within the bitmapUnder window. The mouseTransformer gets a chance topass the bitmap location into a window which it ostensibly covers up. This too is useful in implementinga "magnifying glass" window if you want the user to be able to point "through" the magnifier.The client can associate a bitmap under with a window with this call:SetBitmapUnder: PROCEDURE [ window: Handle, pointer: LONG POINTER _ NIL, underChanged: PROCEDURE [Handle, Box] _ NIL, mouseTransformer: PROCEDURE [Handle, Place] RETURNS [Handle, Place] _ NIL ]The user-supplied space for the bitmap under (supplied by the long pointer) must contain at leastWordsForBitmapUnder[window] words. [For AltoMesa programs the formula is:((window.box.dims.w+30)/16)*window.box.dims.h. The reason for the strange formula: the left edge of the datastored in the bitmap under is kept in the same bit-within-word position as the window's position within the real bitmap so thatgrey patterns stay aligned.]Window Painting and the Display ProcedureInvalid AreasVista attempts to keep track of what parts of the window need to be repainted. A window can be inneed of a partial repaint because a window that formerly obscured it has been moved; several disjointpieces of a window can need repainting if the window is scrolled when it is partially obscured.Within the window object supplied by the client, the boxesCount field indicates how the system shouldkeep track of the "invalid areas" of this window. An invalid area is a rectangular sub-region of theîN°ïfñqî¶ïbôô®ðEî¶ï`Sô‹vð-q ôŒî¶ï^‰ôî¶ïWtî¶ïTqô€ðEôð#î¶ïREôðUî¶ïNÓô™ð0ôšð6î¶ïMô°vqð'ô±î¶ïK>ôð2î¶ïHŸô¿ð&ôÀvqð,î¶ïFÕô‰ð9ôŠð.î¶ïE ô˜ð!ô™ðAî¶ïC@ôð:î¶ï@¡ôáôâvqî¶ï>×ôð1ôvî¶ï=qô™ð/ôš vqî¶ï;Aôƒð&ô„ðCî¶ï9wôêðRôë î¶ï6ÙôðEî¬ï4yôXwyî¬ï2ýî¬ï1y wôFyôXwyî¬ï/õwywyî¬ï.qwywywyî¶ï+ÒqôÓð9ôÔð(î¶ï*vqôžôŸsð&î¶ï(`xð-sô¥ô¦ð4î¶ï&Üô…ð"ô†ð]î¶ï%5ôî¶ï.rôið)î¶ï'tôî¶ïµqô¦ðCô§î¶ïêôœðTôî¶ï ôî ôïðTî¶ï®ôšðOô›î¶ï ãô·ðe ¾¶ œA]o8window that currently has its bits in the bitmap incorrect. The client, within the field, indicates howclever Vista should be at keeping track of the invalid area:BoxesCount: TYPE = {none, one, many};window.boxesCount = none =>No information about the invalid region is maintained. The client's display procedure,when it is called, needs to repaint the entire window (since it has no information).window.boxesCount = one =>One "invalid box" is maintained. As areas become invalid, the box's edges areexpanded, as necessary, to encompass the newly invalid regions. The client's displayprocedure, when it is called, only needs to paint the area defined bywindow.invalidBoxes.box.window.boxesCount = many =>Multiple invalid regions are maintained. As areas become invalid, they are added to thechain beginning at window.invalidBoxes. The boxes are maintained sorted byplace.y value. Consolidation of areas is done as appropriate. The client's displayprocedure, when it is called, needs to paint the boxes in the list headed bywindow.invalidBoxes.Painting on DemandThe client must supply a display procedure which can repaint the window whenever Vista thinks it isnecessary. Vista will call this procedure:display: PROCEDURE [Handle];The area(s) that need repainting are supplied by the invalidBoxes field in the window record:invalidBoxes = NIL =>the whole window needs to be repaintedENDCASE =>the chain of boxes headed by invalidBoxes needs to be repainted -- if the clientindicated boxesCount=one then this chain will contain exactly one element.As an aid to the client, the procedureEnumerateInvalidBoxes [ window: Handle, proc: PROCEDURE [Handle, Box] RETURNS [Box] ]will do the following: it will call the client's procedure with a box from the list of invalid boxes; whenthat procedure returns a box (the area it painted -- typically the box it was passed) it will chop thereturned box out of the invalid list, consolidating as appropriate. The chopping will be done on eachbox in the list for which the returned box covers at least all of one edge; therefore, the length of theinvalid box list will not grow during this process. Iterating on the first box remaining in the list will bekept up until the list is empty.ÿîN°ïfñqî¶ïbô¯ðhî¶ï`Sôð<î¬ï]µywyî¬ï[î¢ïXxqô‹ð*ôŒvq î¢ïV®ôÑð.ôÒð&î¬ïTyôî¢ïQqqôûôüð:î¢ïO§ôªðMô«vî¢ïMÜqô‘ô’ð6î¢ïLvqî¬ïIsyôî¢ïFÕqôŠð(ô‹ð0î¢ïE ôîvqôï î¢ïC@vqôÊôËð7î¢ïAuô$ð#ô%ð)î¢ï?ªvqî¶ï8£tôî¶ï51qôµuqð9î¶ï3gôð+î¬ï0;ywy î¶ï,Éqôëð5vqôìî¬ï)Wyôwyî¢ï'qð&î¬ï%Âwyî¢ï#øqôÏvqð'î¢ï"-ô v qð2î¶ï»ð&î¬ïyî¬ïRî¬ï‡wywyî¶ïéqô”ðWô•î¶ïôºð)ô»ð=î¶ïTô§ðVô¨î¶ï‰ô§ô¨ðbî¶ï¿ôô‘ð]î¶ïôôÿ¼¶A[^ 9The painting is assumed to be deterministic: if Vista calls the display procedure to paint areas that arealready valid, it will repaint what is currently on the screen.The area to be repainted will be clean -- that is there are no bitmap bits in it that are currently black butshould be white -- so that the client can "or" data into the window. [Unless the client has set theclearingNotRequired BOOLEAN in the window.]Painting Not-On-DemandOften the client will wish to repaint his window with new bits -- e.g. when the user has issued acommand. The client should not call his display procedure to effect this. Rather he should update hisdata to reflect the newly-desired content and then callInvalidateBox [window: Handle, box: Box, clarity: Clarity _ isDirty]; -- If clarity=isClear, Vista believes that the box is all white -- and performs no clearing.Clarity: TYPE = {isClear, isDirty};to mark the window, or portion thereof, invalid, and then callValidate [window]to indicate to Vista that any invalid areas should be "validated" by calling the window's displayprocedure. A call on InvalidateBox followed by a call on Validate may result in no call to the display procedure if, forexample, the invalidated areas stick out of the parent.If the client has potentially invalidated areas in a subtree, the procedureValidateTree [window _ rootWindow]is called indicate to Vista that any invalid areas should be "validated". This is necessary if, for instance,the client has removed some window from the tree.Painting CallsThe client's display procedure calls the window package to perform its window painting. The callstypically instruct the window package to do something to a rectangular area within the window. Thewindow package performs all the required clipping of the box at winow edges, doing partial paints toallow for overlapping windows, maintaining "bitmap unders", etc. Some calls take BitBlt operations orsources and perform the appropriate BitBlt function. A good understanding of how BitBlt works isindicated before using any of those procedures.A set of procedures allows a box to be set to a particular shade:DisplayWhite: PROCEDURE [window: Handle, box: Box] DisplayBlack: PROCEDURE [window: Handle, box: Box] DisplayInvert: PROCEDURE [window: Handle, box: Box] DisplayGrey: PROCEDURE [window: Handle, box: Box] DisplayShade: PROCEDURE [window: Handle, box: Box, grey: GreyArray] DisplayBBopShade: PROCEDURE [ source: BBsourcetype, op: BBoperation,ÿîN°ïfñqî¶ïbô‘ô’ð)vuqð!î¶ï`Sôð?î¶ï\áôƒð&ô„ðGî¶ï[ô¾ð.ô¿ð6î¶ïYLvqôwqî¶ïREtî¶ïNÓqôÐðTôÑî¶ïMô– uô—{uqî¶ïK>ôð7î¬ïHŸyôXðEî¬ïFÕuðAî¬ïE îïBlyôwyî¶ï?Îqð>î¬ï=/yî¶ï:‘qôëôìðDî¶ï8Æô•s wsô–ws|sî¶ï6üôð7î¶ï4^qðKî¬ï1¿yð"î¶ï/!qôðOôî¶ï-Vôð1î¶ï&Ot î¶ï"ÝqôÉðMôÊî¶ï!ô®ô¯ðQî¶ïHô«ð<ô¬ð(î¶ï}ô“ðLô”vq î¶ï³ô½ð$}qð#ô¾}qî¶ïèôð/î¶ïvðAî¬ïyôX wyî¬ï› wyî¬ïwyî¬ï’wyî¬ï wyð.î¬ïŠwyî¬ïð)ÿ ´¶ ¿A]L10 window: Handle, box: Box, grey: GreyArray] GreyArray: TYPE = ARRAY [0..3] OF WORDBBsourcetype: TYPE = BitBlt.BBsourcetype;BBoperation: TYPE = BitBlt.BBoperation;A procedure displays a character into a particular place in the window. See the section discussingWindowFont for an explanation of the font argument.DisplayCharacter: PROCEDURE [ window: Handle, char: CHARACTER, place: Place, -- the upper left corner font: WindowFont.Handle _ NIL, bbop: BBoperation _ paint -- or replace or invert or erase source: BBsourcetype _ block -- or compliment -- ] RETURNS [ Place -- the upper left corner of the next guy -- ] A procedure displays a substring in the window. It is designed to be considerably faster than aDisplayCharacter call within a loop. It takes characters from the substring argument, bumping itspointer and returns when the substring is exhausted or when it fills the supplied line length or when itfinds a return character: DisplaySubstring: PROCEDURE [ window: Handle, ss: String.SubString, place: Place, lineLength: INTEGER _ 0, -- wh.box.dims.w - place.x if zero font: WindowFont.Handle _ NIL, bbop: BBoperation _ paint source: BBsourcetype _ block ] RETURNS [Place] So that the client need not always manufacture a Substring, the following procedure will display astring. No feedback is given to the client to indicate how much of the string got painted: DisplayString: PROCEDURE [ window: Handle, s: STRING, place: Place, lineLength: INTEGER _ 0, -- wh.box.dims.w - place.x if zero font: WindowFont.Handle _ NIL, bbop: BBoperation _ paint source: BBsourcetype _ block ] RETURNS [Place] Three procedures copy a bitmap of the client's into the window. The second allows the user to specify ax-offset into his data (a y-offset can be simulated by additions to the pointer) The third allows theclient to specify the exact BitBlt operation to be performed:DisplayData: PROCEDURE [ window: Handle, box: Box, -- window area ... supplies data's dimensions data: LONG POINTER TO UNSPECIFIED, wpl: CARDINAL, -- "words per line" in client's bitmap bbop: BBoperation _ paint ];DisplayOffsetData: PROCEDURE [ window: Handle, box: Box, -- window area ... supplies data's dimensions data: LONG POINTER TO UNSPECIFIED, wpl: CARDINAL, -- "words per line" in client's bitmapîNïfñqî¬ïbyôXð.î¬ï`š wywywôFî¬ï_yôX wywî¬ï]’ywywî¶ï[:qðcî¶ïY¶v qvq î¬ïW^ywyî¬ïUÚî¬ïTVwyî¬ïRÒ zî¬ïQNywyî¬ïOÊzð!î¬ïNFyzyî¬ïLÂwyzð,yî¶ïJjqôßð0ôàð0î¶ïHævqô³ô´ð/} î¶ïGbqôœðYôî¶ïEÞôî¬ïB²yôXwyî¬ïA.qyî¬ï?ªqyî¬ï>&qy î¬ï<¢qywyzð#î¬ï;qywyî¬ï9šqyî¬ï8qyî¬ï6’qywyî¶ï4:qô·ô¸vqð(î¶ï2¶ôð[î¬ï/‹yôXwyî¬ï.î¬ï,ƒwyî¬ï*ÿî¬ï){wyzð#î¬ï'÷ywyî¬ï&sî¬ï$îð!î¬ï#jwyî¶ï!qô‡ð[ôˆî¶ïô±ðDô²ð#î¶ïôvqî¬ï³yôXwyî¬ï/î¬ï« zð.î¬ï'ywôFyî¬ï£ôXwyzð'î¬ïyî¬ï€wyî¬ï¶î¬ï ë zð.î¬ï ywôFyî¬ï VôXwyzð' ¶ A]üU11 offset: INTEGER, -- the x offset ... typically in [0..15] bbop: BBoperation _ paint ];DisplayOffsetBBopData: PROCEDURE [ source: BBsourcetype, op: BBoperation, window: Handle, box: Box, -- window area ... supplies data's dimensions data: LONG POINTER TO UNSPECIFIED, wpl: CARDINAL, -- "words per line" in client's bitmap offset: INTEGER, -- the x offset ... typically in [0..15] -- ];Series of paints in a predefined areaThis following procedure is designed to avoid much of the overhead of successive calls to one of thenormal window display routines. It is not available in Tajo.Trajectory: PROCEDURE [ window: Window.Handle, box: Window.Box _ Window.NullBox, -- area where painting might occur .. default means anywhere -- proc: PROCEDURE [Window.Handle] RETURNS [Window.Box, INTEGER], -- ^^ returns box to paint and xoffset into source -- source: LONG POINTER _ NIL, wpl: CARDINAL _ 1, bbop: BBoperation _ paint, bbsource: BBsourcetype _ block, missesChildren: BOOLEAN _ FALSE, -- currently unused -- grey: Window.GreyArray _ [177777B,177777B,177777B,177777B] ]The client calls the trajectory procedure and passes to it:The window of interest.The box where painting might occur. If the client lies about this, bad things will happen.A procedure of his which will, when called, repeatedly return small areas within the windowwhere painting should occur. Think of them as the "brush strokes"A set of arguments which define the type of bitblt operation that should be performed on eachsmall area.As an example of usage, consider the graphics package drawing a curve. It will call Trajectory with thewindow, the box that circumscribes the curve (allowing for the finite brush width), and a long pointer(and wpl) to the brush. Then the procedure, when repeatedly called from within the Trajectory routine,will return the boxes that define successive brush positions -- that is the curve.To end the trajectory, the client's proc should return Window.NullBox.ÿîNïfñqî¬ïbyôXwyzð)î¬ï`Syî¬ï]µwyî¬ï[êî¬ïZ î¬ïXUî¬ïVŠ zð.î¬ïTÀywôFyî¬ïRõôXwyzð'î¬ïQ+ywyzð)yî¶ïJ#tôð%î¶ïF²qô°ô±ðLî¶ïDçôð=î¬ïARôXsqî¬ï?dsqî¬ï=vsqsq uð?î¬ï;ˆqsqsqsqsqsqî¬ï9šuð7î¬ï7¬qsôFqôXsqî¬ï5¾sqî¬ï3Ðî¬ï1ãî¬ï/õsqsquî¬ï.qsq sqî¶ï*rôð;î¬ï&Üî¬ï#GôÌðGôÍî¬ï²ôºðTô»î¬ïÄôðBî¬ï/ô—ô˜ðKî¬ïAô î¶ï¬ô“ð=ô”ð+î¶ï¾ô¦ð6ô§ð0î¶ïÐôðHôî¶ïâôðRî¶ïMð7sq®¶A]û12The client may wish to alter the brush shape along the trajectory. It can do this by defining the "source"bitmap as a wide one, with several different brush shapes in it, and then returning, together with thebrush-box, the xoffset into the source bitmap.The Window TreeThe following procedures do not force repainting, except as noted below. Instead, they merely markwindow areas as invalid and return. This is so the client can perform several functions and then trigger asingle repaint. To force the repaint, the client calls ValidateTree[].StructureThe windows that are currently known to Vista form a tree. The parent, child, and sibling fieldswithin each window object serve to link this tree together.If a window has descendants, its child field points to its eldest [topmost] child, and successive childrenare linked via their sibling fields. The sibling field of the youngest child is NIL. If a window has nochildren, its child field is NIL. The parent field points to the window which has this window as a child.The parent field of the rootWindow is NIL.Root Window DefinitionThe first window to be defined must be the root window of the window tree. It is defined by the client:DefineRoot: PROCEDURE [window: Handle, grey: GreyArray]Where the client is passing the storage for the rootWindow; the storage for the hardware bitmapshould already have been allocated and Vista will locate it by calling UserTerminal.GetBitBltTable.Repeated calls are OK. It is the responsibility of the client to get the bitmap turned off before callingDefineRoot when an outward call to GetBitBltTable will raise the signal BitmapIsDisconnected.The hardware bitmap's height and width are taken from the Handle, and must satisfy the hardware'sconstraints.The grey array is the "background" that Vista will use to paint the root window.The handle of the root window is accessable via the procedureRoot: PROCEDURE RETURNS [Handle]or the variable rootWindow.Window DefinitionAll window creation is done by the client. The client allocates storage for window objects and initializesÿîNïfñqî¶ïbôðBô‚ð)î¶ï`0ô® ô¯ð[î¶ï^Bôð.î¶ïW;rôiî¶ïSÉqô´ðcî¶ïQþôô‚ð_î¶ïP4ôð8y qî¶ïI-tî¶ïE»qôð@vqvqô®vqî¶ïCðôð;î¶ï@~ô‘ð!vqô’ vqî¶ï>³ô vq uqvqô¡ wqî¶ï<éô vq wqô‚vqð=î¶ï;ôvq v qwqî¶ï4tî¶ï0¥qô…ô†ðRî¬ï.yôXwyð"î¶ï+iqôÊôËv qð%î¶ï)žô• ô–ð9vqî¶ï'Óô›ôœðXî¶ï& v qôô‘v qvqî¶ï$>ôªð9ô«vqð!î¶ï"sî¶ïôðPî¶ïð=î¬ïñywyî¶ïqv qî¶ïxtî¶ïqôŒôðMÿ ¶ ¿B]Lõ13them. The client builds subtrees of windows with the appropriate initialization of their child, parent,and sibling fields.The client inserts a window or subtree of windows into Vista's window tree via this call:InsertIntoTree: PROCEDURE [window: Handle]Before making the call, the client has set many fields in the window(s) appropriately: Other values aredefaulted, so it is recommended that a constructor be used to initialize the window to allow Mesa todefault them to the correct values.box: Defines the window's location (relative to its parent) and sizeparent: Indicates where in the tree structure this subtree belongs. This subtree will be insertedas a child of window.parent.sibling: Indicates where in the tree structure this subtree belongs. This subtree will be insertedas the immediately-older sibling of window.sibling. If window.sibling=NIL, this window willbe the youngest child of window.parent. If window.sibling is non-NIL and not a child ofwindow.parent, a client error has occurred.child: Supplies a window subtree, built by the client. NIL if the client is inserting only a singlewindow.display: The client's repaint procedure.boxesCount: As described above.underVariant: Indicates "Minus Land" bitmapUnder info.cookieCutterVariant: Indicates "Minus Land" cookie info.The client forces all the windows just inserted to be painted by calling ValidateTree passing a windowthat contains all of the inserted windows. If an inserted window has a bitmap under and the new window is partiallyobscured (meaning that all the bits needed for the bitmap under are not available) then ValidateTree will be called on theparent of the inserted window to obtain those bits.Window De-DefinitionThe client can remove a window, together with any window subtree "below" it, from Vista's window treeviaRemoveFromTree: PROCEDURE [Handle]This procedure removes the window and all of its descendants from Vista's window tree without alteringtheir parent, child, and sibling fields. Thus they remain a legal subtree and can be re-inserted withInsertIntoTree.The client forces all the repainting of the windows exposed by calling ValidateTree passing a windowthat contained all of the removed windows.îNïfñqî¶ïbô˜ðYô™vqvqî¶ï`Sôvqî¶ï\áðYî¬ïZŠyôXwyî¶ïWë}ô ð&ô¡ðBî¶ïV!ô¸ðSô¹î¶ïTVôð#î¬ïQ¸yqðBî¬ïOyqô—ðSô˜î¬ïMOôî¬ïJ±yqô–ð>ô—î¬ïHæôôy qwqî¬ïGô¿ðBwqôÀî¬ïEQôð+î¬ïB²yqô—ð"ô˜wqð)î¬ï@èî¬ï>Jyqôð!î¬ï;«y qî¬ï9 yqð*î¬ï6oyqð%î¶ï2ýôŒð2ôvqî¶ï12ô‰ð,sôŠð3î¶ï/‹ô•ðXxsô–î¶ï-äôð3î¶ï&Ütî¶ï#jqô†ðHô‡î¶ï! î¬ïtyôwyî¶ïqô‘ð,ô’sqî¶ï8ô–vqvqvqô—ð,î¶ïmv qî¶ïûô•ðGvqô–î¶ï1ôð*¢¶êAV!14Window MovementRemoving and Inserting WindowsThe default or normal way for a client to alter the window tree, either to restructure it or to rearrange iton the screen, is to remove a window or subtree from the tree, alter it, and then insert it. Such aprocedure is universally applicable; however there are a couple of special cases that are optomized by thewindows package to minimize the window repainting that would occur if the remove followed by insertprocedure was followed.Stacking a WindowA common operation is to alter the ontop-ness of a set of windows. The windows package has aprocedure which effects this operation and minimizes repaints:Stack: PROCEDURE [window: Handle, newSibling: Handle, newParent: Handle _ NIL]If newParent is not NIL, then window is moved to be a child of newParent. The sibling-listcontaining the window window so that window is now immediately above newSibling in the stack.Supplying newSibling=NIL puts window on the bottom of the sibling stack. Unless window isalready on top, supplying newSibling=window.parent.child puts window on the top of the stack.If window is on top, the previous expression is a client error which is not guarded against.Moving a Window: ScrollingAs discussed earlier, scrolling is performed by moving a window (the scrollee) around within its parent(the frame). Typically the scrollee with be very tall and the same width as the frame: thus the scrolleewill completely obscure the frame's bits and the only function of the frame is to clip the scrollee. Aprocedure which effects moving a child and minimizes repaints:Slide: PROCEDURE [window: Handle, newPlace: Place]The function is called "Slide" to distinguish it from tree rearrangement. It is given a new [x, y] wherethe window should go. The procedure can be used for any child movement; typically it is used forscrolling, and then the new place is vertically aligned with the old. For example, given a scrollee windowwithin a frame, one can scroll the data upward by:Slide [ scrollee, Place [scrollee.box.place.x, scrollee.box.place.y-100] ]Moving a Window Iconically: I & IIThe user's moving a (typically small) window around on the screen is also a common tools and desktopfunction. This case is different that the one above because the "icon" being moved is typically small andÿîNïfªqî¶ïa×rôiî¶ïZÐtôî¶ïW^qô‹ðGôŒð%î¶ïU”ô½ðHô¾î¶ïSÉô„ðUô…î¶ïQþô˜ô™ðHî¶ïP4ôî¶ïI-tî¶ïE»qôÍð-ôÎð0î¶ïCðôð>î¬ï@ÅyôXwyð:wyî¶ï=SqôÈvqwqvqôÉvqî¶ï;ˆô–vqvqô—v q î¶ï9½ôÁ v qwqvqð,ôÂvqî¶ï7óôˆvqvq ô‰ î¶ï6(ôvqðSî¶ï/!tî¶ï+¯qô ð\ô¡ î¶ï)äô‘ð>ô’ð,î¶ï(ô¬ðVôî¶ï&Oôð>î¬ï"ÝyôXwyð"î¶ïkqôœðiî¶ï¡ô·ðaî¶ïÖôƒð\uqô„î¶ïôð2î¬ïšyôXðJî¶ï’tôð"î¶ï qô•ð\ô–î¶ï Vô„ðMô… ¶ B]üø15quick-to-paint. This makes the trade-offs in minimizing repaints different and results in this procedurecall:SlideIconically: PROCEDURE [window: Handle, newPlace: Place]The above procedure moves the window "correctly" in that the window will, for example, slide "under"siblings as appropriate. This logic makes it relatively slow and it doesn't keep up with user mouse-movement very well. SlideIconically is not available in Tajo.An alternative procedure is much faster in a restricted set of circumstances:Float: PROCEDURE [ window: Handle, temp: Handle, proc: PROCEDURE [window: Handle] RETURNS [place: Place done: BOOLEAN] ]This procedure requires that the window be a bitmapUnder window. It also requires that the usersupply a temp window, exactly the same size as window, not in the window tree, also with abitmapUnder, for scratch storage. The procedure repeatedly calls the client's procedure and does acontinuous move to the new place as long as the done boolean is FALSE. The window is forced to thetop of the sibling stack before the move begins. A new place which would entail moving the window soit is not completely visible is a client error. ValidateTree is called to pick up the bits that need to beon the bitmap when the window is moved away."Growing" a WindowAltering the size of a window is also a common operation. Frequently, the old and new window bitmapareas are not disjoint. This requires a single call (instead of a remove and insert) to save painting:SlideAndSize: PROCEDURE [ window: Handle, newBox: Box, gravity: Gravity _ nw ]SlideAndSizeAndStack: PROCEDURE [ window: Handle, newBox: Box, newSibling: Handle, newParent: Handle _ NIL, gravity: Gravity _ nw ]These procedures minimize the amount of invalidation they must do -- that is they try and "save" asmuch of the current window content as they can. The gravity argument indicates what should happen tothe window's content when the size changes (this applies both to the bits within the window and to thewindow's children:Gravity: TYPE = {nil nw, n, ne, e, se, s, sw, w, c, xxx}gravity=nw => contents stay in the upper left corner: this is the normal case.gravity=center => contents stays in the middle (e.g. trimming occurs equally at all edges).gravity=nil => the contents stay the same place on the bitmap.gravity=xxx => no attempt is made to save the contents: it is all repainted.ENDCASE => the contents stay attached to the indicated compass point, which is either a corneror the middle of a side: like nw but flushed differently.îNïfñqî¶ïbôŸð_ô î¶ï`Sî¬ï]µyôXwyð"î¶ïZCqô’ô“ð[î¶ïXxô¼ð-ô½ð8î¶ïV®ôð>î¶ïS<ðMî¬ïPžyôXwyî¬ïNÓî¬ïM î¬ïK>wywywyî¶ïGÌqô·ð!vqð+ô¸ î¶ïFôävqð"vqð%î¶ïD7ôÊðNôËî¶ïBlô”ð0vq ô•wqî¶ï@¡ô‰ð3ôŠð2î¶ï>×ôð1vqô‘î¶ï=ôvqî¶ï6tî¶ï2“qô‹ðdî¶ï0Èô¿ð/ôÀð8î¬ï-VyôX wyð7î¬ï)äwyî¬ï(ð1î¬ï&Owyî¶ï"Ýqô®ô¯ðSî¶ï!ô†ðOô‡î¶ïHô–ð8ô—ð.î¶ï}ôî¬ïßywyð+î¬ïAqðAî¬ï£yôÃqôÄð4î¬ïyô qð"}qî¬ïfy qð>î¬ï Èwyô•qð4ô–î¬ïýôð9ÿ ä¶¶A\U 16Moving an area within a windowThe client may need to move a piece of the window without repainting the whole thing. This occurs, forexample, as editors handle inserts and deletes. Such an operation is tricky, since during the area move,the window is difficult to repaint since its "current" state is ill-defined. This is discussed below. Theprocedure which takes a box within a window and copies it to somewhere else in the window is:DisplayShift: PROCEDURE [window: Handle, box: Box, place: Place]To avoid difficulties with the client's display procedure, this call, although it may produce invalid areaswithin the window (bits that should be moved into visible areas of the window but are not availableeither due to being clipped or obscured), does not call the display procedure, but simply leaves thewindow marked invalid. It is the client's responsibility to call ValidateTree[] as soon as he hascorrected his data structures to reflect the call.Also, DisplayShift does not invalidate the areas where the box has been moved "from". If they shouldbe repainted, invalidating them is the client's responsibility.FontsThe following section describes the WindowFont interface. The text painting procedures of theWindow interface take as an argument a Handle on an object from WindowFont. These fonts are allin strike-format.Object and HandleVista defines a Object and Handle which are mostly private to the implementation. Handle: TYPE = POINTER TO Object; Object: TYPE = RECORD [ height: [0..7777B] _ NULL, width: PACKED ARRAY CHARACTER [0C..177C] OF [0..255] _ NULL, ... , swapper: PROCEDURE [Handle] _ NIL, address: LONG POINTER, ... ];InitializationVista font routines deal only in .strike fonts. The client executes the following procedure to create aninternal font of his choice:Initialize: PROCEDURE [font: Handle]îNïfªqî¶ïa×tôî¶ï^eqôƒô„ðJî¶ï\›ô—ðcô˜î¶ïZÐô¥ðMô¦î¶ïYôÔð6ôÕð'î¬ïU”yôX wyð)î¶ïR"qô‹ð(vqôŒð<î¶ïPWô´ðUôµ î¶ïNŒô±ð)ô²vqð!î¶ïLÂvqôÀð³rî¶ï;Aqôäð$v qð0î¶ï9wvqôô‚vqv qî¶ï7¬ôî¶ï0¥tî¶ï-3qvqvqð0î¶ï)Áy wyw yî¶ï'÷ wywyî¶ï&,î¶ï$a wy wyî¶ï"— î¶ï Ìwyî¶ïwyî¶ï7 î¶ï0t î¶ï¾qô¦ðiî¶ïóôî¬ï yôXwyB¶ :AZÑå17Where the supplied Handle points to a font record, allocated by the client, which is at leastSIZE[Object] words long. The fields the client is responsible for filling in before calling Initialize arefont.swapper and font.address. The rest of the fields are READONLY, and are filled in by calling theInitialize procedure. The font must be swapped in at Initialize time.UsageThe bits within the font object that define the character pictures are private to the implementation. Theonly public interfaces allow the client to determine the sizes of the characters in screen dots:CharWidth: PROCEDURE [char: CHARACTER, font: Handle _ NIL] RETURNS [[0..LAST[INTEGER]]]FontHeight: PROCEDURE [font: Handle _ NIL] RETURNS [[0..LAST[INTEGER]]]A font argument of NIL for these routines, as well as for the text painting routines of the Windowinterface, means to use the defaultFont. The defaultFont is set by callingSetDefault: PROCEDURE [font: Handle]Using this defaulting mechanism before the defaultFont is set is a client error.SwappingVista allows the data which defines the bitmap representation of the characters in the font to be swappedby the client.Whenever Vista is about to utilize the bitmap data in a font and the font.address is NIL, it calls theclients swap procedure to fill in the font.address with a pointer to the font. Whenever Vista is doneutilizing the bitmap data and the clients swap procedure is not NIL, it calls the clients swap procedure to(possibly) swap out the data.Thus a client that wishes to swap should supply a swap procedure and should set the bitmap pointer toNIL on swap out. And a client that wants fonts to be permanently in memory should set the swapprocedure to NIL.For AltoMesa programs, if the font character pictures and the bitmap are both not in the MDS, they must be in the samebank. This is due to a restriction on BitBlt.The Other Parts of VistaThe current implementation of Vista has dependencies on outside interfaces. This is the result of itsevolution and has resulted in a need for clumsy mechanisms for starting and changing theenvironment that Vista executes in. At some later date, these dependencies on outside interfaces willbe removed. The Mesa/Tools group will supply modules that may be used to support Vista throughîNïfñqî¶ïbôvqð&ôî¶ï`Swqvqôšô›ð&uqv qî¶ï^‰vqô€vqwqôî¶ï\¾v qôð<î¶ïU·tî¶ïREqôðFôŽð$î¶ïPzôð`î¬ïMyôX wywywywywywyî¬ïI–wywywywywyî¶ïF$qô¶vqwqô·ð*vî¶ïDZqôv qv qî¬ï@èywyî¶ï=vqð+v qî¶ï6otî¶ï2ýqô†ð[ô‡ î¶ï12ô î¶ï-Àô ð"ô¡ð#vqwq î¶ï+öô”ð&vqð&ô• î¶ï*+ôð.ô‘wqð(î¶ï(`ôî¶ï$îô•ðDô–ð!î¶ï#$wqôÀðWôÁî¶ï!Yôwqî¶ïsô ðgô¡î¶ïcôð-qî¶ï\rôiî¶ïÇqô“ðLô”î¶ïÙô ô ð>î¶ï ëôŽð,ôð:î¶ïýôð_ê¶¶A\U18Vista's interfaces, but the client will be able to provide his own implementation of dealing withbitmaps, etc.The following steps are necessary to start up Vista as it is currently configured: Initialize Vista with the root window object that will be used.In the Alto world, the implementation modules for UserTerminal must be started.Get the bitmap allocated.Let Vista know the bitmap parameters and get the root window inserted into the tree.This can be accomplished by Window.DefineRoot[window: @, grey:, bitmapExists: FALSE];UserTerminalOps.StartUserTerminal[wantWaitScanLine: TRUE];[] _ UserTerminalOps.SetBitmapBox[[0, 0], [608, 808]];[] _ UserTerminal.SetState[off];Window.DefineRoot[window: @, grey: , bitmapExists: TRUE];[] _ UserTerminal.SetState[on];The call on StartUserTerminal need only be made if running under Alto/Mesa. The argumentshould be TRUE if calls on UserTerminal.WaitForScanLine are going to be utilized. The reasonfor inserting the root window into the the tree between allocating the bitmap (SetState[off]) andhaving the bitmap displayed (SetState[on]) is to prevent the unitialized bitmap from being flashedonto the screen before the background grey has been painted into it.UserTerminalOps.SetBitmapBox is also only useful if running under Alto/Mesa and it changesWindow.rootWindow.box to be a copy of the box (trimmed to fit the hardware limitations ifnecessary) passed in. There are some instances in the Alto/Mesa system, that it is necessary for theclient to do the allocation of the memory for the bitmap. A call onUserTerminalOps.SetBitmapSpace should be inserted immediately after the call onUserTerminalOps.SetBitmapBox.Before the bitmap can be deallocated a call on DefineRoot with bitmapExists: FALSE must bemade to suppress any paints into any window while the bitmap is not there. After the bitmap hasbeen reallocated, another call on DefineRoot must be made to notifiy Vista that it can once againpaint into the windows.UserTerminalThe interface UserTerminal describes the state of the user input/output devices (i.e. display bitmap,display cursor, keyboard, mouse, and keyset), and allows the client to manipulate them. Thisinterface takes as fixed many of the characteristics of these devices and only allows variations such asthe number of keys or the size and resolution of the display. This interface deals with many of thelowest level attributes of the terminal and, with a few exceptions, should not be of interest to Tajoclients. This section presents definitions and functions of general interest first and then moreîNïfñqî¶ïbôËð>ôÌð#î¶ï`0ôî¶ï\›ðSî¬ïZCð?î¬ïWëðOî¬ïU”î¬ïS<ôÝð,ôÞð(î¶ïO§ôî1ïLyðDwyî1ïJ#ð4wyî1ïH6ð6î1ïFHî1ïDZî¬ïBlôòð(ôóð!wyî1ï@~ôî¶ï<éqô¦vqð3ô§î¶ï:ûô wqvqôŽî¶ï9 ô¢ô£ð>vqî¶ï7ôŽvqôð&î¶ï51ôðDî¶ï1œvqô•ð/ô–î¶ï/®ôíð%ôîð4î¶ï-Àô™ð/ôšð6î¶ï+Òôÿôð4î¶ï)ävqôsôtî¶ï'÷vqî¶ï$aô°ô±v qvqwqî¶ï"sô£ð?ô¤ð!î¶ï †ôžð"v qôŸî¶ï˜ôî¶ï‘rî¶ïûqô‚ vqôƒð=î¶ï ôåð$ôæð9î¶ï ôôŽðPî¶ï2ô˜ð4ô™ð0î¶ïDô¥ðTô¦î¶ï VôäôåðXÿ L¶ ?]ü19primitive ones that should only be used with proper knowledge, if at all. Clients can determine the physical attributes of the display via the following exported variables.screenWidth: READONLY CARDINAL[0..32767];screenHeight: READONLY CARDINAL[0..32767];pixelsPerInch: READONLY CARDINAL;The bitmap display is addressed by xy coordinates defined as follows.Coordinate: TYPE = MACHINE DEPENDENT RECORD [x, y: INTEGER];The state of the display is defined as:State: TYPE = {on, off, disconnected};on - The display is physically on and visible to the user (bitmap allocated).off - The display is physically off and not visible to the user (bitmap allocated).disconnected - The same as off with no allocated bitmap.Clients may alter the state of the bitmap display by callingSetState: PROCEDURE [new: State] RETURNS [old: State];Tajo clients may not call UserTerminal.SetState directly. They should use TajoMisc.SetState. Clientsmay determine the current state of the bitmap display by callingGetState: PROCEDURE RETURNS [state: State];The bitmap display is capable of displaying black-on-white or white-on-black. Clients maydetermine or alter the current state of the background by using the following procedures.GetBackground: PROCEDURE RETURNS [background: Background];SetBackground: PROCEDURE [new: Background] RETURNS [old: Background];Background: TYPE = {white, black};Clients may momentarily blink (video reverse) the display by callingBlinkDisplay: PROCEDURE;Some displays have the capability to display a border around the outside of the active display region.Clients can determine if the display has this capability by interrogating the following exportedvariable.hasBorder: READONLY BOOLEAN;îNïfñqî¶ïbôðKî¶ï^‰ôÒðNôÓî¶ï[]yôXwôFî¶ïYyôX wôFî¶ïV®yôXwôFyî¶ïSqôðEî¶ïOíyôXwôFyôXwyî¶ïLXqôð'î¶ïI-yôXwyî2ïFvqôðKî2ïBÖvqðPî2ï?ªvqvqî¶ï<ð<î¶ï8êyôX wy wy î¶ï5UqôŒð]ôî¶ï3gôð@î¶ï0;yôX wôFyôXî¶ï,¦qôÿð[î¶ï*¸ôðYî¶ï'°yôXwôFyôXî¶ï%Xwywyî¶ï"-wyî¶ï˜qôuqð'î¶ïlyôX wyî¶ï×qôŒð5ôð1î¶ïéôäôåðDî¶ïûî¶ïÐyôX wôFyÿ¨¶‰@W‚â20If the display has a border, then clients may set the pattern to be displayed in the border by callingSetBorder: PROCEDURE [oddPairs, evenPairs: [0..377B]];The following function is provided for clients who need to synchronize bitmap alteration with displayrefresh.WaitForScanLine: PROCEDURE [scanLine: INTEGER];[Note: Some implementations of this interface will only implement waiting for scan line zero. In Alto/Mesa, thisprocedure is only available if the argument to StartUserTerminal is TRUE. The module UserTerminalsA must bemade resident. Tajo clients need not worry about these details.].The following procedure will return a bitblt table with the bitmap fields filled in for the currentbitmap.GetBitBltTable: PROCEDURE RETURNS [bbt: BitBlt.BBTable];It is worth noting that clients cannot directly get at the bitmap. The bitmap parameters are containedin the bbt returned above. For a complete description of a BBTable see the interface BitBlt.In the event that the bitmap is currently disconnected (deallocated), the following error is raised.BitmapIsDisconnected: ERROR;The cursor manipulation routines supplied here should not be used by general Tajo clients (seeCursor for more comprehensive cursor functions).The display cursor is defined by a 16x16 bit array as follows.CursorArray: TYPE = ARRAY [0..16) OF WORD;Clients can determine the current bit pattern for the cursor by callingGetCursorPattern: PROCEDURE RETURNS [cursorPattern: CursorArray];The cursor pattern is set by callingSetCursorPattern: PROCEDURE [cursorPattern: CursorArray];The keyboard and function keyset defined in this interface is uninterpreted. This means that up/downkey transitions are noted by the state of the bits in the following unencoded array (see interfacesKeyStations and Keys for uninterpreted and interpreted key/bit assignments).keyboard: READONLY LONG POINTER TO READONLY ARRAY OF WORD;The coordinates of the mouse and cursor can be found by the following exported variables.mouse: READONLY LONG POINTER TO READONLY Coordinate;cursor: READONLY LONG POINTER TO Coordinate;ÿîNïfñqî¶ïbô–ð!ô—ðEî¶ï^òyôX wyð"î¶ï[]qôŠð2ô‹ð3î¶ïYoî¶ïVDyôXwywyî2ïSî¶ï0¥yôXwôFyôXwôFyî¶ï-qôðGî¶ï)äyôXwôFyôXî¶ï&Oqôð$î¶ï#$yôXwyî¶ïqô€ð+ôuqî¶ï¡ô¹ôºðJî¶ï³vôqvqð8î¶ï‡yôX wôFð'yî¶ïòqôúðEôûî¶ïÇyôXwôFyôXî¶ïowôFyôX"¶(?Xãû21Clients can alter the coordinates of the current mouse position by callingSetMousePosition: PROCEDURE [newMousePosition: Coordinate];UserTerminalOpsMuch of UserTerminalOps is private to the implementation of UserTerminal for the Alto/Mesaworld. However, there are some parts that the client needs to initialize Vista. As discussed earlier,one procedure must be called before using any of the parts of UserTerminal: StartUserTerminal: PROCEDURE [needWaitScanLine: BOOLEAN _ TRUE];Vista uses machineFlavor, which is an exported variable from UserTerminalOps, to know whatkind of machine it is running on.machineFlavor: MachineFlavor;MachineFlavor: TYPE = {standard, widebody, xmesa39, xmesa, dolphin, dorado, spare};At any point that the machine type might change out from under Vista, for example upon restarting animage, the client must call Window.NoticeMachineFlavor.To set how much of the screen is to be used for the bitmap, the next time it is allocated, clients call SetBitmapBox: PROCEDURE [box: Window.Box] RETURNS [result: Window.Box];Window.rootWindow.box contains the current parameters and the client may examine it directly.The bitmap may not be changed while allocated. If an attempt is made to do this, the following error israised. BitmapChangeWhileAllocated: ERROR;If the client wishes to allocate his own memory for the bitmap instead of allowing UserTerminal to do it,then the following procedure may be called. It is also subject to raisingBitmapChangeWhileAllocated, and it is the client's responsibility to make sure that the amount ofmemory available at location address, is sufficient to contain a bitmap the size specified in the call toSetBitmapBox. SetBitmapSpace: PROCEDURE [address: LONG POINTER, words: CARDINAL];The following convenience routines map between screen and bitmap coordinates. ScreenPlaceToBitmapPlace: PROCEDURE [Window.Place] RETURNS [Window.Place]; BitmapPlaceToScreenPlace: PROCEDURE [Window.Place] RETURNS [Window.Place];îNïfñqî¶ïbôðJî¶ï_yôXwyî¶ïXrî¶ïTyqôŒvqôvqî¶ïR‹ôžôŸðMî¶ïPžôðKî¶ïM,ywywywyî¶ïIºqô¿ ôÀvqð%vq î¶ïGïôð!î1ïEQyî1ïC†wyð@î¶ï@qô•ô–ðGî¶ï>Jôvqî¶ï:Øôªð3ô«ð4î¶ï7fyôwywyî¶ï3ôvqôÁð$ôÂð$î¶ï2)ô‰ðQôŠî¶ï0_î¶ï,íôywqî¶ï){ô…ð7ô†ð2î¶ï'°ôð,ôî¶ï%åvqôœôð?î¶ï$ô¬ðKôî¶ï"Pvqî¶ïÞyôð&wywyî¶ïlq w qð4î¶ïúywywyî¶ï0wywyÿ¾¶éBR"â HELVETICA TIMESROMAN TIMESROMAN TIMESROMAN TIMESROMAN TIMESROMAN HELVETICA HELVETICA HELVETICA HELVETICA HELVETICA HELVETICA TIMESROMAN TIMESROMAN … Dq"â*÷1ø8«?DJýQWó^cñjìrw}‚ÿÿj/…ƒ•ÿ™jÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿVista.bravoPKSeptember 29, 1980 12:22 PM