Inter-OfficeMemorandumToCedarInterestDateNovember5,1982FromScottMcGregorLocationPaloAltoSubjectTheViewersWindowPackageOrganizationPARC/ISLXEROXFiledon:[Indigo]Documentation>ViewerDoc.TiogaandViewerDoc.Press.Documents:[Indigo]Viewers>Viewers.df,asexportedbytheCedarbootfile.TheViewersWindowPackageDisclaimerThisdocumentiscurrentlybeingwrittenandhenceisincomplete.ItreflectsthestateoftheViewerspackageforCedarversion3.5.Youmaybeabletofindamorerecentversionon[Indigo]Viewers>ViewerDoc.tioga.IntroductionTheViewersWindowPackageisthearbiteroftheuserinputanddisplayhardwareintheCedarprogrammingenvironment.Itprovidestheillusiontotheprogrammerthatthereisaprivatedisplay,mouseandkeyboardassociatedwitheachapplication,whileallowingtheusertosimultaneouslyinteractwithmanysuchapplications.Thebasicobjectmanipulatedbyclientprogramsandvisibletotheuseristheviewer;arectangularareawitharbitrarycontentswhichmaybemadevisibleontheuserdisplay.AviewertakesitsnameinthatitallowsthehumanusertoviewandinteractwiththedataassociatedwithaCedarapplication.Theunderlyingapplicationssoftwarehascompletecontroloverthedisplayedcontentsofaviewerandhasavailablearichuserinterfaceforuserinput.Thescreenpositionandsizeofaviewermaybemodifiedbytheuseraswellasunderprogramcontrol.ThisdocumentationiswrittenfortheprogrammerintendingtousetheViewersWindowPackagetobuildanewapplication.ItisorganisedalongthebroadareasoffunctionalitythattheViewerssystemprovidesandattemptstoexplaindesigntheoryandsomepragmatics.Forexamplesofusage,seethereferenceswithineachsection,andforexactdetailsconsulttheinterfacesdirectly.Onepointofnotation:usedthroughoutthisdocument,clientreferstoaprogramcallingtheViewersinterfaces,whereasuserreferstothehumaninvokingViewersoperationswiththemouseand1pqda " p M]d]|-]7f]>8? MYdY-Y7fY: MUdU< s&-U 7fUr{NQp MDRdDR,69| M@i d@i".0657:M>eAs8!u)23t 3 p/g"5&)q-Q. 6e7ACpE. %R),/<25'8:>C~H,X.t (% p$I!R"%I)+.1%47<}BD`F#  D &(b-(.1 8;>@MA_E!vw "C%( 0|4\: <?A  FXq _"Z&,,.3147>:7;u>F>FpAFBFC ,l6#'$):-136A9_?7@ErI6#g&uu(9(p+R+.3)6Y8; BhEFP   '\,/K539=?`EMs +!R$',.16g9<=sBEfHIswhD@!$&F)4*.4sy< 6 #N% -358A:?Es !("(,/368d @tCME+v !&n*.15 <?<E&F  '!&)|+/4 8;x AG  $d'(u. . p1 2h 578>C5E 5 u^ 5 5p 5 5!#&>+,1!6 =@CH7v)TVm$keyboard.ScreenLayoutTheUserDesktopFromtheuserpointofview,theblackandwhitescreenisdividedintofourareas.Thetopquarterinchofthedisplayisusedforthemessagewindowandasmallsetofsystemcommandbuttons.Thebottomofthedisplayisavariableheighareareservedfordisplayingicons,whicharesmallpictorialrepresentationsofnormalviewersmadeiconictoconservescreenspace.Theremainderofthedisplayisdividedintoleftandrightcolumnswithamoveablepartitionbetweenthem.Theusermayoptionallyattachacolordisplay,whichisequivalenttoanadditionalcolorcolumn.Unlikemanywindowpackages,viewersmaynotoverlap,butinsteadspreadouttocoverasmuchaspossibleoftheavailablespaceontheuserdisplay.Withinacolumn,theheightofaparticularviewerisdeterminedbysatisfyinganumberofconstraintssetbytheViewerssystem,theimplementingprogramandtheuser.Viewersconstraintsincludebalancingofthecolumns;i.e.viewerswillbeexpandedsothattheentirecolumnareaisused,andthatnoviewerissmallerthantheheightrequiredforthecaptionandcommandmenuatthetopofeachviewer.Aclientprogrammayspecifyaheighthintintheviewerinstance'sopenHeightfield,whichwillbehonoredifitdoesn'tconflictwithotherconstraints.Inaddition,theusermaysetaheighthintthatoverridestheopenHeightvaluebyinvokingtheAdjustmenucommand.User-sethintsarediscardedwhenaviewerismadeiconic.Thecurrentimplementationdoesnotdealparticularlywellwithovercontrainedcolumns;i.e.whenthesumoftheViewersenforcedheightsplustheclientopenHeighthintsexceedstheheightofthecolumn.Inordertosolvetheconflictingconstraints,eachviewerisgivenonenthofavailablecolumnheight.Ideally,Viewersshouldeitherpro-ratetheexistingspaceaccordingtotheclientrequestsorforcesomeoftheviewersintheoverconstrainedcolumntobecomeiconic.Internally,thetreeofviewersispartitionedintofoursubtrees,correspondingtostatic(typicallythoseviewerswithapermanent,fixedpositiononthescreen),theleftcolumn,therightcolumn,andthecolordisplay.Viewersinthestaticsubtreeincludeallicons,themessagewindowatthetopofthedisplay,aswellasthesystembuttonslocatedintheupperrighthandcorner.TheboundarybetweentheleftandrightcolumnsaswellastheheightofthecolumnsmaybesetbyinvokingtheAdjustmenucommandinanyviewerandthenslidingthemouseacrossthecolumnboundary.Thecolumnheightisquantizedtotheheightofeachrowoficons,permittinguptotworowsoficonsorasfewasnone.Iconsaredisplayedbehindthecolumns;inotherwords,viewersinacolumnoverlappingthedisplayofaniconwillhidetheiconuntiltheusershortensthecolumn,orremovesalltheviewersfromthatcolumn.MultipleDesktopsEachtreeofviewerscorrespondstoauserdesktop,onlyoneofwhichisdisplayedatatime.Viewerssupportsninedifferentuserdesktopsandprovidesaninterfacetomoveviewersfromonedesktoptoanother(seeVirtualDesktops.mesa).Theusermayexaminethecontentsofallofthedesktopssimultaneously,orselectadifferentdesktoptoviewbyinvokingtheFlysystemcommandbutton.Thedesktopdisplayisreplacedbyascaled-downgraphicalrepresentationoftheninedesktops,whichmaybeexaminedindetailwhenclickedwiththemouse.CedarGraphicsprovidesthefunctionalitytorenderatruescaledrepresentationofalloftheviewercontentsoneachdesktop,butthegreyrepresentationusedprovidesgreatlyimprovedperformance.Whenmovingfromonedesktoptoanother,alloftheviewersinthestaticsubtreearecopiedtothenewdesktop,leavingtheleft,rightandcolorsubtreesbehindintheolddesktop.Thestatic2pb)t ^(wZ8poXl"u$(+/35:=@EyHyoVxPm2 ^!%'i)/94q758l<>@@DoTQ1!*%'Y(-14:u@?BHoEs9E!$i&*/348D;=@ DF&oCt( #M(**1>569;=9@hEG.oAQa!$K%(%,p u2A31Ap9A:#A=A CEuo@%# +-369<?9@EH o>~uR>~>~p>~ >~#&,u.>~/>~p3F>~4o>~7o?>DHo<Oy I$ :[ "%(v+ 259' BH8*F!#).14O82 ?CaH7 #nq!Z%(&*, 3 ;(>rBDuHC5e &J+s059?QAG93,$O&)-1.1S6A7:XDFI@2o/ #g1"+# *-06 ?uAH/A/pD/Ej/o-M #',W.b05u89-8-p:-;9-?uBT-B-pE-F<-o,M+u,M),Mp,M,M"$}&*n/G4*6:@]D5 o#5h0h  "%t'>+/186<?vEGOo! (*/1369m<?B'EGo=N#%( ,0[3)wpo  $&u'(*p/O0T36k8L<>D^FGqoC"%+/-3T54:p@.@DoM"!#w)+-,r 4e:s CEZGoN<!$%)M,1k4f6;?E_o >! "%4) 2468;D?EGoWj %) .3 9U o #%*,.157:=BpDI@o 5J!t$H'*^-3A79< >{DGev) TVm$viewersincludeimportantsystemcommands(e.g.theFlybuttonandthemessagewindow)aswellasalltheicons.OneinterestingViewersmodificationwouldbetotocopyonlythoseiconswhichareselected,givingtheusertheabilitytoleaveiconsonmultipledesktopsattheexpenseofhavingtodesignateapotentiallylargeseticonstocopy.ViewersThedisplayofaviewerconsistsoftwonestedrectangles.Theouterrectangleboundstheviewerwindowoverhead,consistingofspaceforanoptionalblackborderaroundtheviewer,anoptionalscrollbarspaceontheleft,ablackcaptionbaratthetop,andanoptionalmenubelowthecaptioncontaininganarbitrarynumberofmenulines.Theinnerrectangledefinestheviewerclientarea,whichisavailabletoanapplicationfordisplayofitsdata.Eachviewerhasaparent,asiblingandachildviewer,anyofwhichmaybeNIL.Viewersmayberecursivelynestedwithin(i.e.childrenof)otherviewers,inwhichcasedisplayofthecaptionandmenuwillbesupressedandnospacereservedintheouterwindowrectangle.Thecoordinatesforthewindowandclientrectanglesarecomputedwithrespecttotheenclosingparent'sclientrectangleorigin.Iftheviewerhasnoparent,itisknownasatoplevelvieweranditsrectanglecoordinatesarewithrespecttothelowerrighthandcornerofthedisplay.Aviewermayextendoutsideofitsparent'sclientrectangle,inwhichcaseitwillbeclippedduringdisplay.Siblingviewersmaynotoverlap.ViewerClassesTheViewerspackageallowstheprogrammertocreateaclassofviewer,allinstancesofwhichwillsharecodeforcommonoperations.Aviewerclassisarecordthatdefinesasetofoperationsandparameterscommontoallviewersofaparticularuserdefinedtype.Forexample,theTiogadocumentpreparationsystemcreatesaviewerclassforalloftheeditabletextviewers,sothateachinstanceofaTiogaviewerusesthesamecodetodisplay,scroll,acceptinputfromtheuserandsoforth.Aviewerclassrecord(asdescribedinViewerClasses.mesa)containsthefollowinginformation:flavor:ViewerClasses.ViewerFlavor_NIL;Eachclasshasauniqueatomwhichassociatesanamewiththeclassrecord.init:ViewerClasses.InitProc_NIL;Duringthecreationofanewviewer,thisprocedureiscalledinordertopermittheclienttoinitialiseprivatedatastructures.paint:ViewerClasses.PaintProc_NIL;TheViewerspackageassumesthatthebitmapiswrite-onlyandthattheclientcanreconstructitsscreenimageondemand.Whenevertheinformationonthescreenforaparticularviewerbecomesinvalid,thePaintProcwillbecalledbythesystemtorestorethecorrectdisplay.ThePaintProcispassedagraphicscontextclippedtotheboundsoftheviewer,awhatChangedparameterwhichtheclientmayusetoencodeprivateinformationaboutwhattoupdate,andaclearbooleanthatindicateswhethertheviewerhasbeenwhitenedbeforethepaintcall.Thereisacompletesectiononpaintingfurtheroninthisdocument.destroy:ViewerClasses.DestroyProc_NIL;TheCedargarbagecollectornormallydeallocatesstorageassociatedwithaviewerwhenitisdestroyed,butsometimesaclientfindsitconvenientornecessarytofreeresourcesornotethedestructionofaviewerinstanceexplicitly.Thisprocedureiscalledjustbeforetheviewerisremovedfromtheviewertree.3pob!Fd#*-u/b!0b!p28b!2b!69=;@FdHo`yA~ #((P 0F4e6H79<?CfFo^{!$-(*m."14 9?AFCI5o]+ #'),.UwYpoVC.#+$'+ 3 59y?RD.FoUFuUFEUFpUFUF "&@(w*b/3c7<>CEoS $R)!+- /]246;?CFoQ  "$x(P,V/%28=D?uCQDQpGQHCQoPP}RB %T',D-/oMZ  %j(*)^,14K6 :%=2x?,M@MpA8MBMGoLj Y!#).+j/4^6:.=&ACFoJu& #%)L.0s26q; oGJ 7#e&) 0E29 <(@BDoFB\9#$&+]-/457D;=xu>FB?FB@DpH7FBHFBoDG" h #(x*$,0I37;b=?vDFoBlT'$L( .2/368:<A{EoAL" t =(p9)q" )+/u091z9p4 9495:<BpD/HC8I $&.*-/F0x47XDlG4}  Z$&*u-/135;,=C(DG3b"R8!$ '*,159=ACmFmI*1h.0#%2479@ o,P%.x&,P',Pp(,P)Cs#8'F -o.2Y5t7;o'8h sx"'8"'8p$ '8$ vB #(R+137(8<>tBElI@# H o yr"ox# y$ yp& y6#&_(-. 58F;=AIC E%#e*,s 4 68<?@H FkT#&(,.05`7;=BH7X$?);.C0279<@BD OMV!k$j&(-11 9N=+@B,GIK!')^-0+39n=@CF<eM%T),-0Rou%Rx&u'up(u9"( /4 ;;>s?D=HI A i !%)*\ 1Y392:=CEsH % +/157T;e>!BEI F v) -TVm$%notify:ViewerClasses.NotifyProc_NIL;Mouseandkeyboardinputfromtheuseriscommunicatedtoaviewerasalistofresultsdescribedinatiptable(seethetipTablefieldbelow).Thisprocedurewillbecalledwheneveraninputeventforaparticularviewerisreceived.tipTable:TIPUser.TIPTable_NIL;ATIPTableisalistofproductions,mappingmouseandkeyboardoperationsintoalistofresultsmeaningfultotheclient.PleaseseethesectiononMouseandKeyboardinputformoreinformation.modify:ViewerClasses.ModifyProc_NIL;Keyboardinputdependsonaviewerowningtheinputfocusdescribedlater.Thisprocedureiscalledwheneveraviewerlosesoracquirestheinputfocusinordertoprovidefeedback,suchasablinkingcaret.set:ViewerClasses.SetProc_NIL;Someviewerclasseschoosetoimplementthisinterfaceasawayofsettingthecontentsorstateofaviewer.Thedataandopargumentsmaybeinterpretedanywaytheclientchoosesandthefinaliseparameterdetermineswhetherthenewinformationshouldbereflectedonthedisplay.Tioga,Buttons,andLabelsarethreeviewerclasseswhichimplementthisinterfacetosetthetextcontentswhenpassedaROPEorREFTEXT.get:ViewerClasses.GetProc_NIL;Aviewerclassmayimplementthisinterfaceasameansofallowingaclienttoquerythecontentsorstateofaviewer.LiketheSetProc,theopparametermaybeinterpretedbytheclassimplementorastheyseefit.scroll:ViewerClasses.ScrollProc_NIL;TheScrollProciscalledwithanoperationparameter,correspondingtoscrollingup,scrollingdown,thumbingtoaparticularplaceinthedatastructure,orqueryingtheclientastoitscurrentscrollposition.Forthescrollupandscrolldownoperations,theamountpassedistheuser'srequest,measuredinpoints.Itisuptotheclienttointerprettheamountwithrespecttotheirinternaldatastructures,adjusttheirdisplaydatastructuresandrequestrepaint.Forthethumboperation,theamountpassedisthepercentagetoscrollintotheviewer;i.e.47wouldmeantostartthetopofthedisplay47%intothedatadisplayed,asinterpretedbytheclient.Thequeryoperationrequeststhattheclientreturntwonumbersforfeedbacktotheuser,correspondingtothepercentageofthedatadisplayedatthetopandbottomoftheviewer;i.e.iftheentiredatastructurewerevisible,theclientwouldreturn0and100.Iftheclientcannotreasonablycomputethequerypercentagesorchoosesnotto,thenitmaysimplyreturnfromtheScrollProcwhenthisoperationisencountered.menu:Menus.Menu_NIL;Aviewermayoptionallydisplayamenuofcommandsunderneaththecaption.SeethesectiononMenusformoreinformation.icon:Icons.IconFlavor_document;Whenaviewerisiconic,theclientPaintProcisinterceptedandisinsteaddisplayedasasmallpicture,determinedbytheIconFlavorsethere.TheIconsinterfacehasanenumeratedsetavailable,aswellasaninterfacetocreatenewicons.TheclientmayalsopainttheirowniconusingtheCedarGraphicsfacilitiesbysettingtheiconFlavortoprivate,whichwillcausethepaintingoficonicviewerstonolongerbeintercepted.IftheiconFlavorisprivate,thenitisuptotheclienttonoticethattheyareiconicandpaintappropriately.cursor:Cursors.CursorType_textPointer;4pob)#x%?b)&'b)p'Jb)_{"&:(,- 78:Z>@B;DF^V""$)-*25<(>@D\Zk ] #(!)oYb x"oY#WYp$zYWZ}^_5 l (q.L25; BEFI5U D :$(+'-z2 48;*AE*G[T oQ$x&Q'nQp(QO 6 @"?#a',u.O /PO 2hp5O 6O <?CIMdN $%+a-1536:?@FGEJu8EEpSEEu" E"Ep$E$E*-/ 7'9<?@CH7CnunCnCnpWCnCn &]+.1 9|>6@fFJHAi "'A)-(15:@CI@@ Ls!(%x&@ '@ p*2@ *@ x+@ ,@ .p1@ o=1 ]x!="=p#=; @#N%+],-2$39(:5=?lC<E9y5&9"%8*u-l9y.9yp/9y0P9y6C9; BE&G7  o5Q"x$t5Q%]5Qp&5Q2 q #8%A+ 2v ;=LBEk1*#~ %>)*-q0 68>AfEWG5I/B_" $i(*$,04N ;T=BG#H- 2!' (* ,+-0V4$5;>CFF,4'E $),1K4i :=BHC*s  &%)h*- 35k8;>BDF(a{ E"'{*z-d/2 9t;4 BXDeF'>_#&)-|14:=C$EG% p $&g(+13y58H:?AzCH#-rs!,$z)+y/63a78;q>@ZBFr"H x# +j-B2a47:?;>CEG / | &G' o! ;x!!p!R $%)+]27 9v;AqCFRh8 oyo V"&,.6 5d8!9>JDnF!GPR i" )@+/u2R3cRp6R7RADG3 &l(-(/ 6u89Rp<=ADH\D !"$)D+E 3k47n >c?DHI _ w#E&U(,/b2 o 5 "" v) TVm$RViewerswilldisplayacursorwhenmovedoveraviewer,determinedbythevaluehere.TheCursorsinterfacehasanenumeratedsetavailable,aswellasaninterfacetocreatenewcursors.Thefollowingviewerclassfieldsareeitherrarelyusedornotcurrentlyimplemented.Theyaredocumentedhereforcompleteness:save:ViewerClasses.SaveProc_NIL;TheSaveProciscalledwhentheclientisexpectedtowritetheprivatedatastructuretoadiskfile.ThisiscurrentlyonlyusedbyTioga.copy:ViewerClasses.CopyProc_NIL;ThedataassociatedwithaparticularviewerisprivatetotheclassimplementationandhencetheViewerspackagedoesn'tknowhowtoreplicatethestructure.Thisprocedurepassesanoldviewerandanewviewerandrequeststhatthedataforthenewviewerbemadethesameastheold.caption:ViewerClasses.CaptionProc_NIL;Thecaptionnormallydisplaysthenameandstatusoftheviewer.Ifthisisnotacceptabletoaparticularclient,thentheymayimplementthisprocedureandpaintthecaptionthemselves.Thegraphicscontextpassedisclippedtothecaptionarea.coordSys:ViewerClasses.CoordSys_bottom;ThecoordinatesystemofthegraphicscontextpassedtotheviewerPaintProcwillnormallyhaveitsoriginatthelowerleftcorneroftheviewer,withxandyincreasingtotherightandupward.IfthecoordSysissettotop,thentheoriginwillbesettothetopleftcornerwithyincreasingdownward.bltContents:BOOLEAN_FALSE;Thisiscurrentlyunused.paintRectangles:BOOLEAN_FALSE;Thisiscurrentlyunused.Itisimportanttonotethattheimplementorofaviewerclasscandefaultanyofthefieldsiftheychoosenottoprovidethatparticularfunctionality;thesystemwilldotherightthingwithrequestsonviewersthatdonotimplementaparticularoperation.TheprogrammercreatesanewviewerclassbyallocatingandinitialisingaViewerClasses.ViewerClassRecandthencallingViewerOps.RegisterViewerClass,passingtheclassrecordandauniqueatomwhichnamesthenewclass.Thisoperationcreatesabindingbetweentheclassoperationsandanynewlycreatedviewerinstances(seetheViewerInstancessectionbelow).Subclassing(asinSmallTalk)isnotdirectlysupportedbythesystem;theprogrammermustexplicitlycopyandmodifyanexistingviewerclass.Asimpleexampleofcreatingandregisteringaviewerclasscanbefoundon[Indigo]Viewers>LabelsImpl.mesa.ViewerInstancesOnceaViewerClassisdefined,instancesmaybecreatedwhichwillinheritinformationfromtheclass.Manyofthepredefinedviewerclasses(listedinthenextsection)provideinstancecreationoperations,otherwiseaclientmaycallViewerOps.CreateViewer,passingtheclassandinitialdatafortheinstance.AViewerClasses.ViewerRecdefinesthedataassociatedwitheachviewerinstance.Duringviewercreation,theclientmayinitialisesomeofthefields,theViewerspackagewillinitialiseothers,with5pb)#&+W.~/4 ;=@MDH` 'd)} /14457=S>BE^ B "%r)-025u;w DH\[ ? oY!x#)Y$Yp%5YW] "%*(*^015R7Al HIE +j!%, .58m<>C Cu"Q#(*K,1o@$&O>w c!E#)f.d247S;BIE<"#!$y(*-14618:3 @BoDH7;(K "$6u%;(&^;(p';((;(+.>2H469:=??B=FI9 Fo7 xS7 7p]7x77p"74V3o2x22p2x!j2"#2p%2/V3- z5\8! )+,1D47;>}@CBFqG+^" % -04u7B+^7+^93;>pBo+^Cl+^E)G#-$V * '8H !u$(P.26 =A I%!$'b,@E$G#tBA"'S),146:v?@SE"B[y H#7',@147;AF R] !(#(Z.0279 AE `$4to%)| 1D3}8=1@CH't (pQa"H(++@-B26<8={ EHAK !&*u.0m26;-@KE 2x #&e6R;B=A CG[L $S&) 0d36;VAF 5 "e%'*#.605;!= CRGv) TVm$Otherestdefaulting.Theremainderofthissectiondescribesthedatastructureinsomedetail,andisofparticularinteresttoaclientimplementingaviewerclassorcreatingatoolcomprisedofmanyembeddedviewers.Eachviewerinstancemaintainsapointerbacktoitsclassdatarecord:class:ViewerClass_NILTheclassfieldisinitialisedbyViewersduringinstancecreationandremainsconstantforthelifetimeoftheviewer.Eachviewercontainstworectangles,describingtheouterboundaryoftheviewerandaproperlycontainedinnerareaavailablefordisplayingclientinformation:wx,wy,ww,wh:INTEGER_0,cx,cy,cw,ch:INTEGER_0Thewxandwyfieldsdefinethecorneroftheviewerwithrespecttoitsparent'sclientorigin.Inthecaseofatoplevelviewer,wxandwywillbewithrespecttothebottomleftcornerofthedisplayscreen.Thewwandwhfieldsdescribethewidthandheightoftheviewer,measuredinscreenpixels.Thecx,cy,cw,andchfieldsdefineaninnerrectangleandrepresenttheclippingboundaryfordisplayoftheclientinformation.cxandcyaremeasuredfromtheparent'sclientorigin,justasthewxandwyfields.Theclientshouldinitialisethewx,wy,ww,andwhfieldsduringviewercreationifandonlyiftheviewerwillbeembeddedinaparentviewer,sincethecolumnconstraintalgorithmswillrecomputethesevalues.SinceviewerpositionandotherinformationiscachedbyViewers,clientsshouldneverdirectlysetanyoftheviewerrectanglevalues,butinsteadshoulduseroutinesintheViewerOpsinterfacetochangethesizeorpositionofaviewer.Theviewerdatastructuremaybelockedwithnon-exclusivereadorexclusivewritesemantics,makinguseofthelockdatastructurewithineachviewerinstance.Theclientshouldneveraccessthisfielddirectly,butshoulduseroutinesprovidedintheViewerLocksinterface.Amoredetailedtreatmentoflockingmaybefoundelsewhereinthisdocument.lock:ViewerClasses.Lock_[NIL,0]TheTIPTabledefineshoweachviewerinterpretsmouseandkeyboardinputandiscopiedfromtheclassrecordwhenavieweriscreated(thereisalatersectiondescribingthemouseandkeyboardinputmechanisminmoredetail).Insomecases,theclientmaywishtochangethebehaviourofaparticularviewerandmaydosobymodifyingthisfield.Afinepoint:ifaviewerownstheinputfocus,thenitsTIPTableiscachedbythenotifier,whichpresentlymustberesetbyreleasingandthenrecapturingtheinputfocus.tipTable:TIPUser.TIPTable_NILEachviewerhasatextnameassociatewithit,whichinthecaseoftoplevelviewers,isdisplayedinthecaption.Theclientmaymodifytheviewername,butmustbesuretorepaintthecaptionifapplicable(viaViewerOps.PaintViewer[viewer:viewer,hint=caption]).name:Rope.ROPE_NILSomeviewerschosetoassociateabackingfilewiththeirdatastructures.Whilethislogicallybelongswiththeimplementorsdata,itappearsintheviewerinstancedataasaconveniencetoclients.Itmayberemovedinthefuture.file:Rope.ROPE_NILAtoplevelviewermayoptionallyhaveamenuofcommandspermanentlydisplayedbelowthecaption.Ideally,theclientshouldpassamenuwhenavieweriscreated.Toaddamenutoanexistingviewer,theclientmustuseViewerOps.SetMenutoresetinternalrectanglecachesandtorepaintthenewmenuonthedisplay.6pb)g Q"#%e(,2v47=?*BFI` ! *+0B35S:;>E]G$^\@3!s"'f*,[.51f4koY xfYOYpW  b  u%)/,4Z6<AoCEUd'Re %: +.j2%8v:J<AFDE_Q"Z " )v-6 oNxN Np LN!NoKCxKKpK NKIS48 A"' (+=/279I;1u@kISAISpD'ISDISIGv!$ &)W,).A16R8':?B9FHF% "&,2.25y9;>BI@D]deZ!u$I&L*.t04<:6= C%EBbg# ,g.U1+35;?eAG.AP!!)&(,1~ 79ADG:?g, $0%(8,/18:V;@DH=o 2 !b$y+/59>~D,GO< T9"&+D.358h: KCxEF27 y"K&) u2727p47576u7p?7@7F6/7 H$',2?58=LAEG4WI"')v+ 3 :q;?D2#%(6o0F x! 0F!0Fp#0F#0F-!& ,103*9&<?p@E4H,VH %)+K,/4~ ;.=BD*]0#S%#(,.258:?2AH I( Kv "[$^*-13T6(:H;<AMDGD'SAr#%(-d17:=@ZBiH7%g4 ~o"b x"o"#W"p 2{Il%w(*4.;/2=5%69G<AC'I@sd= Y%/',%0U26o8y;=RBDI S*/roIx0IIpIx8I!IpU!|"'),0"3 :>@E= m!H&f((*/4u79O: BmD/Iw`aoRxpUxp+ca $.'(,.5 >DXH lB#&($,/1'57$<?4BCBG9H :{"$13X6;AFgI@ 5! Vv) *TVm$Kmenu:Menus.Menu_NILWhenatoplevelviewerismadeiconic,itnolongerdisplaystheclientdata,butinsteadappearsasasmallsymbol,easilyrecognisablebytheuser.Theinstance'siconfieldisnormallyinitialisedfromtheviewer'sclass,butmaybeoverriddenbytheclientduringviewercreation.TheIconsinterfaceprovidesroutinestoaccessexistingViewersicons(Viewersincludessymbolicpicturesforadocument,tool,typescript,andafiledrawer)ortocreatenewiconsfromeitheraprocedureorasetofbitmapsstoredinafile.TheclientmayspecifywhetheraniconistobelabelledbyViewerswiththeviewername.Iftheinstance'siconfieldissettoprivate,thentheclientPaintProcwillbecalledeventhoughtheviewerisiconic,whichishowtheclockicondisplaysthecurrenttime.icon:Icons.IconFlavor_toolWhenavieweriscreated,theclientmayspecifyinwhichcolumnaviewerwillbedisplayed.ClientsshouldonlychangethisfieldinanexistingtoplevelviewerbycallingViewerOps.ChangeColumn.column:ViewerClasses.Column_leftViewerswillallocateascrollbarareaonthelefthandedgeofavieweraswellasprovideappropriateuserfeedbackifthisbitisspecifiedduringviewercreation.Theactualscrollingoperationareperformedbycallingtheviewer'sclassScrollProc.scrollable:BOOL_TRUEClientsmaysettheiconicbitduringthecreationofatoplevelviewerinordertoinitiallydisplaytheviewerasiconicatthebottomofthedisplayoropeninitscolumn.Aclientmaynotchangetheiconicbitforanexistingviewer,exceptbycallingViewerOps.OpenIconorViewerOps.CloseViewer.iconic:BOOL_TRUEAnembeddedviewerisdisplayedwithaone-bitwideblackborderifthisfieldisset.Toplevelviewersarealwaysdisplayedwithaborder.border:BOOL_TRUEAclientmaytesttoseeifeditshavebeenmadetoaviewerbytestingthenewVersionbit.ViewerimplementorsshoulduseViewerOps.SetNewVersiontosetthenewVersionbitanddisplaythe"[NewVersion]"messageintheviewercaption.newVersion:BOOL_FALSEMumblenewFile:BOOL_FALSEMumblevisible:BOOL_TRUEMumbledestroyed:BOOL_FALSEMumbleinit:BOOL_FALSEMumblesaveInProgress:BOOL_FALSEMumbleinhibitDestroy:BOOL_FALSE7pob1 ;xb1b1p_"H\"&((**.j359= ?D9I@]) #L%9'+@. 4#7:9;AW G\Ro: '), /4=8>uA\RB5\RpEI\RE\RZ|4 # (+16U;AC!D)Y# _y"$&**,0s378?3@BDEW\#!v&+D-&01x34:<A,D9FU! q #%'u)U*HUp-U.U14Y8?>AuCGT !L#Z$'**-058X="oQ}oN$r #&+:,056; =?y FGMEL !#(+<.249GoJ"$H$1!T$9&-(y*.F1y3468:"<>C F|;@%**.5F8Q<B>HD3"& oBD xBDBDpBDx)BDBDp?ue??p`?'? %'q,./2:59;?wA1F<> yT#%W',.O135l;S<@CFFoFX!x#UF$=FpDBoA\ x"XA#AAp?Go<  x<<p:Ko7x77p7x#7 7t 3 Rp0TV|DzL!&=(,m.2/<BD^F.?w+[po(V" $)*-036H7{>AD,G.o& _"h$)Q. 2B3^9X<@B.EFGo%Fgg %+U-$.1349 D4ox":&>(0*/Q 6;q?CHo 7%(j*H.L/2J6P8=r@BD* oC ES", )+z17B:<}ACH!o ?T #%*,0&2 9@DgIo wpo  y0 %%(-K.1M68t9=AD}Go 5 %ye "%Z'.158= DI5v)TVm$havingverylowdatastructureoverhead.RulesAruleviewerdisplaysasarectangleofasinglecoloronthedisplay,andiscreatedusingtheRulesinterface.Theyareusefulforcreatinglinegraphicswhendesigningthelayoutoftools.TextTextviewersareimplementedbytheTiogaDocumentPreparationsystemdescribedindetailon[Indigo]Documentation>TiogaDoc.tioga.TheViewerToolsinterfaceprovidesasetofoperationsthatallowaclientprogramtocreatetextviewersaswellastofetchandstoretheircontents.ThereareagreatmanyadditionaloperationssupportedbytheTiogaeditor,exportedbytheTiogaOpsinterface,whichisdescribedintheTiogadocumentation.MouseandKeyboardInputmumbleLockingTheViewerLocksinterfacedefinesaninterlockingmechanismtoarbitrateaccesstotheViewerwindowtree,viewercolumns,aswellasindividualviewers.Aparticularviewermaybelockedforreadingorforwriting.AreadrequestimpliesthatthecallingcodewouldliketoexaminevaluesintheViewerClasses.ViewerRecandinsurethatthesevaluesareinvariantforthedurationthatthereadlockisheld.Anynumberofclientscansimultaneouslyholdreadlocksonasingleviewer.AwritelockisanexclusiveaccesstoaviewerfortheimpliedoperationofmodifyingoneormoreofthefieldsintheViewerClasses.ViewerRec.Locksareprocessre-entrant,meaningthatasingleprocessmayrequestalockmultipletimeswithoutdeadlock;i.e.ifaprocesscurrentlyhaswriteaccesstoaviewer,itmayinadditionrequestreadorwriteaccess(thisobviouslydoesn'tgrantanynewpermissions,butisusefulwhenaclienthasalreadylockedaviewerandwishestocallcodethatmayattemptalock).Duetotheorderingofthereadandwriteresources,aprocessholdingareadlockmaynotrequestawritelockonthesameviewerwithoutfirstreleasingthereadlock.Theviewertreeaswellastheparticularcolumnsareanothersetofresourcesthatmaybelocked.Lockingacolumnisequivalentto(butnotimplementedas)lockingalloftheviewersinthatcolumn.Lockingtheviewertreeisequivalenttolockingallofthecolumnsforwriteinadditiontotherootpointerforthetree.Theviewertreemustbelockedbytheclientanytimeatoplevelviewerchangessizeorpositioninthetreethatcrossescolumnboundaries.Sinceallpaintingoperationsareprotectedbyareadlockontheupdatedviewer,theviewertreelockwillnotbegranteduntilpaintingactivityhassubsided.Thehierarchyoflocksintheviewerswindowpackage,fromhighesttolowestis:theviewertree,awritelockonacolumn,awritelockonaparticularviewer,areadlockonacolumn,andareadlockonaparticularviewer.Aclientmayonlyrequestanewlockifisatthesameorlowerlogicallevel.Thedocumentationintheviewerinterfaceshasbeen(willbe)updatedtoshowwhichlockstheoperationrequires,sothattheclientcanavoiddeadlocks.Afinepoint:ifaclientprogramneedstolockmultipleviewers,itmustacquirethelockforeachviewerintheproperorder.Routinesareprovidedbelowthatcorrectlysorttheparameterlistforuptothreeviewers;otherwisetheclientmustorderthelockrequestssoastolocktheviewersinreforder(treatingtheviewerrefasalongcardinalandlockingthehighestfirst).Columnsmustbelockedintheorder{static,left,right,color}.9pob)"[w^po[ &(*.136Y;>V?DHoZ0P Z#&+;-3`7=>?CEwVpoS "=$<&*1L 8=9CgEHoR6,.1- 9u?lELFI5oP 8!*"')x-0h5l74:=<=A^D0GoN6j $ +< 18v:{<@E2oM@k $%+-Y/3 t H(NpEt AJp=! j$b& .]57=rACF<<3;W "?%.& -a3(4 :?SBXDJH:4!&+f.D05)8<?yA8F8&!$(+/)3\5;=@'EH7=$mk!#G'* 3c69=?@DD+Ib5!#}$) +J-28:A1CEI53n"01[0 % '(,1]4G9:<BRE/_5#&k)./057: ;A1F I*. sgi#(&)++ 367l;l?@CF,ev #Z&)s,x127:;>'CErG*?  %&),/2@78;;>@CF) !'&d3! 'Q,/84O6y8>>IA$D4F1$JX2 !"%' 02"68:K<A]BE#4g-] % &+-/:179S<>CEH!d#e&O)+02509;?-@CFP@!w$N'1+0 8<>D@ >o"$~).158\;b>@BGr;2 A%**V/3X89=?BEFI\_"+%7'P( .348 ;=2>nCFG/ b!'$'*/036869;4=A BF =  ="' ->/36H8>?C]Gqfn= #.&)z-9 sv# &(+1"6i7;2@B|EzG+<2%(-24:=j?FfH /!/#'l*.149;X=>ADHI@ ,S ""#$'-0/46;?EH 5t"6!%?v) *TVm$Usersareadvisedtomakeuseofthecall-backoperationsprovidedwhentheyneedtoperformlockedoperationsonviewers,andnottryandusethelockingprimitivesdirectly.Thesuggestedusageistocreatealocalprocedurecontainingthecriticalcode,whichispassedtotheroutinesbelow.Thelocalprocedurewillthenhavefullaccesstoallofthevariablesintheouterprocedure.PaintingmumbleIconsmumbleMenusmumblePragmaticsmumbleInterfaceSummaryButtonsButtonsareaclassofviewersthatdisplayatextlabelandcallaprocedurewhentheuserclicksthemouseoverthem.Thisinterfaceprovidesroutinestocreateanddestroybuttons,aswellastheabilitytochangethevisualappearanceofthetextlabel.CaretsImplementorsoftexteditors(andmaybesomeothertypesofeditors)providefeedbacktotheuserwheretextinsertionwillgobymeansofablinkingcaretonthescreen.TheCaretsinterfaceallowsaviewerclassimplementortodisplayblinkingcaretswithouthavingtoworryaboutissuesoftiming,clipping,etc.ChoiceButtonsWhenbuildingtoolsandotherapplicationsusingViewers,clientsoftenrequireuserinterfaceabstractionsforenumeratedtypes,stringparameterstheusercanedit,andbooleanvalues.ChoiceButtonsisahighlevelinterfacebasedonButtonsandViewerToolsthatprovidestheseabstractionsasprimitives.ContainersAclientoftenwishestobuildatoolthatconsistsofseveralviewersassociatedwitheachother.Containersareaverysimpleviewerclassthatpermitotherviewerstoberecursivelyembeddedandscrolled.Routinesareprovidedtoconstrainembeddedviewerstobeclippedtotheedgesoftheparentcontainer.CursorsTheCursorsinterfaceexportsasetofbitmapssuitablefordisplayinthehardwarecursoraswell10pb) ~[!#&c,R 3)9#=@:CE` Vv #&2(t+F-0N5< ;AD^p_% +.w36;<A@CE]3"(%I(+/024d6@yD t Y pUt QpN2t JpFt B p?1t ;w7po4V" $)*-036H7{>AD,G.o3=Dk!&,b13x7:M?.DFEI@o1^" )+-0w.@po+v Y1!$)->046;@FHo)^k!^#D%5)n+,<1469B>AAEIo(( M $o&*0349=?<C/Go&(w#* po `_# +Z/349e=(B EIo E !%*# 1437:a=@Fio e"s(A,K.y36 >AGeoj  w poK"v#&)z.0]5: @CFo r5!&$)g,H04}9x;9== D4o  %'-p4#9:<AqCEqI5oU w po 5G\!"%&, 1!3]89<B%FSHv)eTVm$asprimitivesenablingaclienttocreatenewcursorbitmaps.Thecursorbitmapshavealogicalhotspotassociatedwiththemthatdefinesthesinglepointinthecursorwheretheuserispointing;e.g.forabullseyecursorthehotspotisinthecenterwhereasthetextpointercursorhasitshotspotattheupperleft.EndOpsAbootfileclientmayregisteraprocedurewhichwillbecalledsynchronouslyaftertheCedarbootsequenceiscompleted,butbeforeuserinputisenabledandanyautomaticcheckpointmade.HourGlassThisinterfaceallowsaclienttodisplayanhourglasscursorwithflowingsandandisusedduringCedarbooting.IconManagerThisisaprivateinterfacethatgovernsthebehaviouroficonsinresponsetoselectionandusertypein.IconsTheIconinterfaceexportsasetofbitmappicturesusedtodisplayiconicviewers.AclientmaycreatenewiconsfromeitherabitmaporaprocedurethatmakesuseofCedarGraphicstodisplaytheimage.AclientmayspecifyarectanglewithinaniconthatwillbelabelledwiththenameoftheparticulariconicviewerbyViewers.ImplErrorsArudimentarydebuggerandsignalcatcherisexportedbyImplErrorsthatgivestheuserthechoiceofrejecting,proceeding,orsavingeditsandrollingbackwhenanerroroccurs.Generaluseisnotrecommended.InputFocusInputFocuscontrolsthedestinationofmouseandkeyboardactionsaswellastheinterpretationoftheseactionsthroughTIPtables.Aviewerclassimplementorwouldusethisinterfacetoacquiretype-inortoinquirewhichviewertype-inwascurrentlydirected.LabelsLabelsimplementsaclassofviewersthatdisplayasimpletextmessageinasinglefont.Thelabelmaynotbeselectedoredited,buthastheadvantageoverTiogatextviewersofverylowdatastructureoverhead.MBQueueSomeapplicationsrequireawaytoserialiseuserinputfrombuttons,menus,andtype-inwithouttyingupthenotifierprocess.MBQueuepermitstheapplicationtoenqueueanddequeueoperations.MenusMenusareahorizontalsequenceoftextlabels,eachwithanassociatedprocedurecalledwhentheuserclicksatthemenuitem.Thisinterfaceprovideslowlevelroutinesforcreatingandmodifyingmenus,butnotforassociatingthemwithaparticularviewerorredisplayingaviewerafteritsmenuhaschanged.11pob)- Q"[$(++(/f58<BE[Fuo`p`)`!Y$(+ .2l46S:m>r@CDo^Du !p#&(`*,|058W;?DFHyo]3iadwYpoWf"$-*.137 ADZFoUsi #.'m*W-/N4j79? FwRpoOZ.[!E"')/36;? ACBF~oMwJ_ poGZ "'*A02657=?qE*GoEwBpo?Nz' !2#U%)/2F38<BD#Go>1`< !&(M)e/269:>DF<o<)#v$*o.036[9:@C$E|I5o:  k"gw7 po4* 0g"L&f+S,25 <>?:BEhHo3"  # $)*,/J37:<@`Eo1{P w.( po+b  %'l+.49d;#>!?BO o)[S"G'v)5-11 9=@CgI@o(Ot!=%K).b16w$po!  !').0 47l<>?D Ho S!&E(+g-4i7;>\C[E)HNot1wXpoC  #%G*p-g14u9>|A2EoCc#*0E2 :d #8(c-/4&5P91w[ poYC$I$)J,>-0-24S6:S=@FGoWls/#(*.b 579wTpoQ0R;"%*Z, -63459=i?qAGfoOP %u)*/S157wL$ poIM  #K( /137?9=bBDQI@oGD`T wDApoAj "P'9(+f.1# w>po;.@"J$(149;Q ADGo9 g #N&(p* w6# po3K>z ($' .056;>iA w/po-j #'-0^36{9c;!DBFo![- J$()-/368 !%T' )l-M0569=wBVw po ["'*/P169H<AODU o <!&E,,w po |1!r$P',.449<?7CJGo 5s"P(+/2p4av)e6TVm$ViewerOpsViewerOpsisanimportantinterfacedefiningstandardoperationsonviewers.Routinesthatmanipulateviewersizeandposition,registernewviewerclasses,createnewviewers,aswellasmostpaintandinputnotificationslivehere.ViewerSpecsScreenlayoutconstantsaredefinedintheViewerSpecsinterface.ViewersStallNotifierBugbaneusesthisprivateinterfacetonotifyViewerswhenaprocesshasbeensuspended,pendinghandlingofabreakpointofanuncaughtsignal.ViewerToolsViewerToolsprovideslowlevelaccesstothecontentsofTiogatextviewersandpermitsclientstocontrolselectionandeditingwithinthem.SeetheChoiceButtonsinterfaceforcreatingtextpromptfieldsandotherhigherleveluserinterfaceabstractions.ViewersSnapshotClientinvokedCheckpointandRollbackroutineslivehere.VirtualDesktopsThisinterfacepermitsclientstomoveviewersfromonedesktoptoanother,locateviewersonotherdesktops,aswellastochangethescreendisplaytoanotherdesktop.WindowManagerWindowManagercontainsamiscellaneouscollectionofroutines,themostimportantbeingtheabilitytoenableanadditionalcolumnofviewersonacolordisplay.WindowManagerPrivateThisisaprivateinterfacecontainingthecurrentviewertreerootandsomeinputnotificationroutines.13wb&po_dh!6',2 9;BH o] 6 &+.37<? DjF6I@o\U  $'$wX poV  `%`')n 1r wRpoO$&P*A/f3 4"8;I> EoNN+  "(wJ poH> a"&(w*0;158|=_@EI@oF`C9"&+x.L0 :b@FBH7oDYe"%(. wApo> 3"(. 0w;po8x!#',0L38c:6?CHo7' V!%( ,E027w3 po1 d!: * 0m2J8:>DHo/pW "$'(-/04hw,!po)`Kg 7 ').3*690<?C o'v)epTVm$ TIMESROMAN TIMESROMAN HELVETICA TIMESROMAN TIMESROMANY TIMESROMANLOGO TIMESROMAN TIMESROMAN  C ,* 4 ?0GWM vXu^f+lpj/sq*!:ViewerDoc.tioga17-Dec-82 10:58:02