sibo-playground/docs/2-02 Window Server Reference 2.30_djvu.txt

SIBO 'C' Software Development Kit 


WINDOW SERVER REFERENCE 


Version 2.30 


March 1, 1999 


(C) Copyright Psion PLC 1990-98 


All rights reserved. This manual and the programs referred to herein are copyrighted works of Psion PLC, 
London, England. Reproduction in whole or in part, including utilization in machines capable of 
reproduction or retrieval, without express written permission of Psion PLC, is prohibited. Reverse 
engineering is also prohibited. 


The information in this document is subject to change without notice. 


Psion and the Psion logo are registered trademarks, and Psion, Psion MC, Psion HC, Psion Series 3, Psion 
Series 3a, Psion Series 3c, Psion Siena and Psion Workabout are trademarks of Psion PLC. 


TopSpeed is a registered trademark of Clarion Software Corporation. IBM, IBM XT and IBM AT are 
registered trademarks of International Business Machines Corp. Microsoft and MS-DOS are registered 
trademarks of Microsoft Corporation. Apple and Macintosh are registered trademarks of Apple Computer 
Inc. VAX and VMS are registered trademarks of Digital Equipment Corporation. Brief is a registered 
trademark of Underware Inc. Psion PLC acknowledges that some other names referred to are registered 
trademarks. 


Contents 


1 Introduction..............sccssscssssssscssserssersceesesessecsseesseesseesseesseesseesseesseessessssesceessesscesscsssessacesseees 1-1 
Versions Of the WiIndOW S€LVe..........s:ceesecesseecsseecsseeeesseecsseecseecsseeeesaeecsaeecsseessneeeesaeessaeers 1-1 
VGTS1ON: Ai ts Schaal sate ceed ait edited ah eit Saal Aiea te ale tae 1-2 
Version 3.5:Window S€Lrvet .........:ccceseccssecesecessseecsseecseecsseecesaeeesaeecsaeecseessseeeesaeersaeers 1-5 
NELSON 3? WINGOW SELVED 225: 32 ¢<iocecedsees ete saenesedovst odes adehlevee bens step scnneat poeat ede poteneneerentedes 1-7 
Specific to: the: MC x.sssi iesieipae ate bind ei hedges en ei aisbena aoe 1-7 
WIEISIB library Ut 8. foc) cic oe sores aan id oebvanct none subpool saust sae sutg cat tonstoteestugekint odesdieesattounteteunes 1-8 
The WLIB header ..:..3:2iacnis ev bileiaic ee bite neki eel ees 1-8 
Connecting to the WINdOW SELVET...........::ccsseccsseecesseeesneecseeceeeceseaeecsaeecsacecseecesaeeesaeeesaeers 1-8 
Using the CLIB startup module on the HC, S3, S3a or Workabout ........ceeeeeeeeneees 1-8 
Using the PLIB startup module on the HC, S3, S3a or Workabout ............eeeeeeeeeeee 1-9 
Using the CLIB startup module on the MC... eee eeeeeeseecesreceseeceeecseessseeeesaeeesaes 1-10 
Using the PLIB startup module on the MC ues eeeeeeeseeceseesneeseeesseeseseeeesaeeseeeesaes 1-10 
Error Handling ’::.vicctcaccsstcevedsed cecedtatccveisenccveishtecvviaalccovdsnd cdevleaetdevdchdedsvacsd cduvdcadevsvdcabedendess 1-11 
How errors are signalled.............cccccccssscceeesnceeeeseeeeeeeeeeceesnaeeecesneeeeesnaeeessennseseeeseneeess 1-11 
Errors in blind operations...............::ccccsssccccesencceceenceeeeeeaeeeceenneeeeseeeeeeeeaeeeeseneeeesseneeeess 1-11 
Cleaning Up atten AM CrrOr sess. ceseh step seek ecey ots heehee sestetesadahsate seubedepedesextpatetedepededenteeasbedy 1-11 
Panic NUMDEFS 5. .2y3..2.sfee.beeiysiee abe telbecoyaceb lates Te gevseee Bight lesoylenb Qiyael egaeoesb epee aay 1-12 
Series 3 compatibility MOde......... eee eeeesseecsseeeeseeeseecsscecseecsseeeesaeeesaeecseessneeseneeeceeaeers 1-12 
Clients and the Window Server ...........cesccsseccesceceseeesseecsseecsceceseaeecsseesseeceeesesseeesaeeeeaeers 1-13 
Client=Side fun Ct Ons 2 se, cect oes aseusdseetaeyoceasite baus env gedesenngranteeesodepesh ppantetesodehacegsantoverets 1-13 
Client-side buffer and flushing ..0........ ee eeseessececeseeesseecseessseeceseeeesaeecsaeersaeeesseeeesaes 1-13 
"Testing: fOr a. CONMECHON: <0: 05. ed eenn sess cdueste tases nays ces vategesd east ote sainpeyh cvusbsee dike saheouslenesets 1-13 
Foreground and background clients ............c::cceesesceeeeseeeeeeeeneeeeeeeaeeeeseneeeeeseneeeeeseeeeess 1-14 
EVES 3.32, oS cscsendedat evegsawteteigsanboteveDet aapsieicanpete beateaBue dees ta ceavphiatededede duc dthedessSe eauvadehetey 1-14 
Task Switching ve.ccstecicicstecaeiesscderdeseesendeseiderdcpvigancces iguedenvedaedadevicebecevdcae cde vecsbeesvecseers 1-14 
‘Task switchins: onthe HG c...0..s55: ceseteesscavteses tavecee ohbed ents test see aales ents tents vende aahebenteeectts 1-15 
Task switching on the Workabout .........:cceseceeseessceeeseecsseecesaeeesseecsaeessaeecssaeeesaeessaeers 1-15 
Task switching on the S3 and the S3a ou... eee eeeeeeeeeeseeeeeeesneecsaeecsseeceseesseessseeeesaes 1-15 
Task switching on the MC... ceeeeesseecsscecesceceseecesacecsseecsseeceseeessseeesseersseecsseeeesaes 1-16 
Tconiseéd ChEmts?: 2.34 set centae ented eet ae Midd hee eee at cee sh RO ees ae cee 1-16 
Client, priorities: s.viiesescavkid hate eines aie ear. 1-16 
Systeri-Mmi dal CHEMts 2.4 5 sect eheveres sxtg caste depores acts stutedevetesarng stetevesedebocesstutedstaceborepstnteane 1-17 
Client management 1: .1..20..252.3450 yee. esepneeg aeyael besedesbcgepaeh becapdesd cdepaeidesspaestcdepaeibesiaeats 1-17 
WATdOWS 36% otuihat be sted ahh ee ele AG aati Aletta et Se tems thet alte Res 1-18 
Window Trees: sired ister aiitisiney elites diitar nite ren ani ca temraieataniie 1-18 
Ownership of WING OWS 1 c.cecse ze sioeecedseesetey exepededovet bt adetaee bees bdep sceneaty peat depotenetpeestedes 1-18 
Background client drawing..........ceseeseccesseessseessscecsseeessaeeesaeecseecsseeeeesaeerseeesseeeesaes 1-18 
Dota WIT & TE STOW acs 2. 50if sa vedive sce n en's cab anisk og shag see dovskosys souteabvavsteges ntntesdsanst eevesietest eat sen' 1-19 
Backed-up Windows............sscccsscccsseecssceceseceesaceesseecseecsseecssaeeesseecsacecsseecsseesesaeersaeers 1-19 
No-redraw WIndOWS ...........sccceseccessseeceseeceseceesneecsseecsscecsseeceseeeesaeecsseecsseeceseeeesaeeesaeers 1-20 
Bitmap: sequences: is.i.s.cicsiesavicstesarceses sas cevecderdepvicancees sees’ Sovdcabedevacebedovdcaecdevechoede veces ees 1-21 
Using an attached bitmap to avoid redraws ...........ceeeeeeeseeeeseeceseeeeseeesseesaeesseeseeeeees 1-22 
SPLiteS ss aegiiek ie oddities Hehieesyeaioe est Rite etal Mei caval isis mavaneal aunts aie) 1-23 
ROOT a WANG o-oo. ctes tee dedad tive dasd va dadne eb velegeigosehedidedeatiscoseleds Cecestuadecedeli decestecacalet vecesuvyecstates 1-24 
Redraw eventss:. cca tac cena iri Ge aii eae Oe een 1-24 
MW pdateTesion &. :: isnt ete ctstet sek teats ON a ie Re et Re ae Oh Ae elie nd ek 1-24 
Invalidating rather than Arawing .............cescccceesseceeeseeeeeeeeeeceeaeeeceseeeeeeeeeeeeseseeeeeaaees 1-24 
Validating before drawing or redrawing ...........eseceeeseeesseessseecseecscecseeseseeeesaeeesaeenaes 1-25 
Dita wits st cccchhigntenreiee hb ee nen ie ae re ieee esa apa ae 1-25 
Redra wil Stn crit ab Ait ete ah it ate a Alte tit ih alate al Mia alias ah alte tats Bey 1-25 
Going deat 3.2.34) seventies ia atin cav dial iscavai eles sine umeeneieuad 1-26 


Redraw. PriOrity. cescce.csticvegeiateds vedativegvintedegulone veg nent ovededdeevessdtesdeseldsavison dh gedseacdgatuserseees 1-27 


WINDOW SERVER REFERENCE 


ii 


More about windows: :..2.cs:taniet aciidenidestigis eibedyiedias aston giasbieesothbeaagivel cespienbenee beh 1-27 
Creating and initialising a WindOW SySteM............cesceeseseseeesneeceneeceseeeeseeeneeeesaeereaeers 1-27 
Destroying a WiINdOW SYSteM............ccccssccceeseneeeeeeneeeeeeeseeeceenneeecesseeeeeeeaeeeceseneeeeseeeeess 1-27 
Event sources other than the Window Servet...........::ccsscccscecsseeceseeesseecseessaeseeessneeeees 1-28 
Visibility Of WINdOWS 3322: cciscsvccccyses edapbest hydeibebedoesie sep sosnedyeelbedoy sue enebdadaestcgeyeeiaedn ey 1-28 
SCHOLL TG irs So ts Bate tet AON cactect ah shah ots tioae oak ae oak thc ond aut eects aut Bate oe ai aes 1-28 
Continuous:scrolling’. :iscs.coa. nuttin ietene abesioaudi tee darenenr sai elineveadentesde 1-29 
EXE CUESOL ses edteriiess du sdus oasis svodetsats odeesscedetlsshvedes suvpeeussaupedebsatssesbedes edateunpvestetes sSetceey ss 1-29 

Bitty os cise .ts 2 heius -2e5s 20s szaheeed oPeupe ch seus dts ave cus sdivs dab SocvesBevseed Sava ons Leicester esse Heveeet Dees nee 1-30 
Drawing to the screen from a DItMap oe ee ee eee eee eeseeeeeeeeeeseeeseetseerseesseteeeeenaes 1-30 
Creation and storage Of DitmMapS............ ee eeeeesseeesneceneecseecsseeeeseeessaeecseeesaeessaeeseeeeses 1-30 
Drawing to: bitmnaps)is.c isthe chats deisests tas epee weadte setsdis navieao ee dis apiessetee ess 1-31 
Bitmap files is .cy5 expec oss sts Fass seestiesehs deeb eels ch vse Bab eaidteessebs da eeshadhwss is dhassvistevstedadieeevis’ 1-31 
WSIS WSPCX sscasicshoeteassteagaceicdesesestepsace rose lasts tasnazvovasdasd tusugsnvucanesaguanetaszoaneaseoaneaavyees 1-31 
Capturing the screen to a bitmap file 00.0... ee ees eeseceseeceseeeeeeessaeessaeecsaeeeseeeneeeees 1-32 
Screen capture program for the HC... ee eeeeessecsseeeeseeeeseeeesaeecsaeecseeceseeeesaeersaeers 1-33 
Capturing the screen directly to a PCX file... eee cee cess eeeeesseeseeeeetretseetseenes 1-33 
The physical structure of bitmap files and bitmaps... eee esses eee eeee tees eeeeees 1-36 
Hinbedded ‘bittinapy Giles os. 2552505 iiss cececceh tiga Vick sasee bai 55g teed acdeouh oe ohdbed Sachuouncesscted bacdeothce 1-37 

PEXt ONS ass Me eisst ache voheedsst sess shiestvsias Aso beste tire seh ti hee Aid soda ened A 1-38 
Fast fonts.s; 23 is.si0s shes tees. d eelsistes th kesects thoes Os hu eigen Mh aalstiens ss aie ayeck 1-38 
ROM- based fon tsiis:-c0.2 isvapesncsaseastiassceasaseatas sateen lsovetas sac caagiasaeahdaieaaeesiazearageapeasaaeaoeas 1-38 
AG, fot i5s 2 5h sees Se She Se east es Sesh ne white Suu twek ca ssee ch iea eouboa von ebbideah aster chedeneetoeseess 1-39 
DS TOMES 2 soises oostbasid co deas ne tbessc-aobestanetiescpsosisians thee vaieesssenthess dusvoiaesapbislvsutaassenraiennee 1-40 
MIC POD tS ecbasks eo laeescets avis Pub steeseits betel cteysends hbebt savusceds beast Qvuseadssibeds saeyeeuPacbbensd Sdeyet’ 1-41 
S3a anid: Workabout fonts :s:sisseasscscesedavisentes ace sntavabenbaciaouckdsaatertad aounkgawsteebedcaoeendastess 1-41 
BOnt file Si. 85555455 ech actos See veh) sebecek Sak goes! gus ooeh Syed Soaks gu deiel Sus Sob bduuoueh saceeeuil felonehdeeteeene Peters 1-42 
Using wsfcomp. iA isiniacak lene bunssiiban let iaalsniadee ars 1-43 
Frit 1 fOrIM At OF 03 sobs 2 es 0s Feed ooh de ea Fec cots taessda dhe ealsTeeseda thas padeoseuds Ra ieaiteesreds eae ss 1-44 
PSXt Ara Win Oi sexes acstesvssletcatice stcaesseateasvacasaaie Seats ieceaneaee Seahodencsasaaunceusaaecesasain Soutaneeaae 1-44 
The physical structure of font files 0... eee eeseeeseeceseeceseeeeeaeeesaeecsaeessaeessneeeeteeeesaes 1-46 
Embedded ‘font files: sies4..0:55eciibe nacte Sid coieis aattaas tapi vies Aabsand Astor Mapes Apts 1-47 

Graphics Output se s.is.:20u5cedscibe dt sceescevecies Bel sveyecutteike nd seves ceva tivndes lavas rail tebasun eke res idee sane ed 1-47 
Pixel COOrdIN ATES ‘1s sotesiecseadesies.nasinceeagaiavestaalataustesivestasiacauadaWioentestaceadasspensactandeetaniaass 1-47 
Graphics Stucts)s.3 wiki ie dil ea asa ek ein el ind nadeilsiodd hal eailiel 1-48 
Gfaphics-output.s:.:i.ci0 lob kia eu RA than n adie AS 1-49 
Graphics output other than to the current graphics COnteXt ..........eeeeeeeeeeeeseeeeeeeeneers 1-49 
Graphics: CONLEXES 2. 23s isccisss tose tesa anda dhssengs ast sateshsosenseies otesabueanaaengaaeesiaaeanageapeasea latent 1-50 
Current :sraphics:COnteXt sss ces. seh bist does Sehhck Laetdocdeeehih cab doe ocboacusnehbicedosd sdsvenehidendesiesesesu 1-50 
Permanent and temporary graphics CONtEXtsS 0.0... eeeeeesseeeeseeeeeceeeeceaeecsaeessteeeeeeees 1-50 
Creating a permanent graphics CONtEXt..........eeseeseeseseeesseeeseeceseeeesaeecsaeecsaeecseeseeesees 1-50 
Creating a temporary graphics CONtEXt........ eee eeseceseeceececneeeeseeeesaeecsaeesseessseseeeeees 1-51 

Keyboard) ini puts, cose: cehnc0k Sos ek 555 05) Se a Paans Savke as seed geet beuceul Sees Seek aha weace eh et sande des ceubeoehe tess 1-51 
Key press: CVents is3 sess sssschasisvsdispiascdessie aah ivstsetedess Map dietsasede Aaedosa sanded Aaa dasssuseee Stes 1-51 
Gaprurin Keys: sys2.. 3 ste z eee la ceeds sbetuese sa chek ods ees adyeseadsnens Dh kebabs one dade. eubiaiessts Hayes 1-51 
Pausing the: Chenitveisisvccsscihiovatiavscssaganatssnatuepenasteatietageotesietestiatapeatas tenia Gseeandsy casters 1-52 
Setting task keyss ssi stistisssic i cetioteaticisiiesiocd sissies aabieieed Po Balle ele 1-52 

Mouse tiputs..c0s5.4.ciest ie ao oi Aiste sapien arte ee Aswan beche Aawenedephie Aaoiebe Ar tash age 1-52 
MOUS€:1COfiS 55. fsisceescusteiie fel scveseus tate fab aegseuts abet st caeuscevssbbea stvyscudsibendsueyecuvectbesteveves’ 1-52 
MOuSe: GVENIS sscssssestssiascesdsvaseetssisceasdassoenta shots etd ssdteataaietasndausbectesusteeseaseoetacasteetdeast oes 1-52 
Capturing the MOUS! ss, ssi scisead Se aheess iadeeed Saabeeas gadewed Sesenshsiadened Sabencbeacbensd Seen aeoens 1-53 
Grabbins the Mouse:,: 5.4.5: Ri sisi Biaien Risin RAsn adie sree 1-53 
Input-only Windows ws. css ices cos cssiesseds sesnbttiossesdeesbtiessdsstossietdosrasdueesibsiaessessseeds 1-53 
INA CH VE: WINDOWS 7253 i5s.c-asiscdouelesvstssniachovelgsvetesieslaouenassacsagiasgeehdanseaaeediazeatagapeasaseoeas 1-53 
THe rubber. bani. .5)1:555 sieves seesihcs ioieeetec ohhh sien eek ceghike ice couboa guoteh bieeast ashen ehesendedesesecs 1-53 

SYStEM-SlALtUp sess vs sdssisesscheesessih casseas seeded ovvstess onegbvieceonsisoovageseacevnedsonvapsueaceonedsentesdoeeeet 1-54 
Using the window server's notifier on the HC .00.... eee ee eee eeseeesseeseeeseeesretseeeeeaes 1-54 
The $WS_FL environment variable on the HC ...........ccccccccccsscsseceeseceesseeesseeenseeeseeens 1-55 
SB ail sisi5i be aetna is oe hehe Gh oes Socket UE Gh SE Loh ae eed AEE Da ied Sevsabehe gtades ceusabensgoteey 1-56 
Replacing the shell:on the AC issiscc.ccciscsccssssscsvenbisbssasvesdsctevendichovenssabssiovenducscvaasscasvees 1-56 
PO EPOC 65 sess Poss ceusdes Bhs toes casesehs Bens seha ches Soya thvss cha cuts cada tease ctachus cay stanseves ave subs Uxtaves eves 1-59 


CONTENTS 


2 General Window Server Functions.............s.scccscssrsssrssrsserssersserssessesssssserssesesesssssesssessseeeeees 2-1 
The connection to the Window Servel...........:ccesccccesesceeeeeseeeceseeeeeneeeeeeseeeceenneeeeeeeeseeneeeess 2-1 
Connect and initialise a window (WStartup)............ccceccceeessceeceseeeceeeeeeeeeetneeeeeeneeeess 2-1 
Connect to the window server (WCOMNECH).........:ccccccccssssscccececceseesneeeeeeecessessseeeeeeeeeees 2-3 
Screen dimensions.i.pixel:pitch CiMeMSIONS............ceeseceeseeesseeeeeecseecsneeseseeesseeeesaee 2-5 
Disconnect from the window server (WDiSCONNECL)...........:ccccccessssseceeeeceesessseeeeeeeeeees 2-5 
Flush buffered commands (WFIUSH) ..............cccscccccccesseessceeeeceeessesseeeeeeeceesesseeeeeeeeeees 2-5 
Series 3 compatibility MOdES 2.0.0... eee eeseesseeesseecssceceseeeesaeecsaeecsaeecseecssaeeesaeessaeesseeeeenaes 2-6 
Set or cancel compatibility mode (wCompatibilityMode) ..........eeeeeseesseeeeneeeeneeeeee 2-6 
Inquire state of compatibility flags (wInquireCompatibility) 00.0.0... eee eeeeeeneeeeteeeeee 2-7 
Error Handling ivvic.s.ccsdesgeseadssteaiedescccevdsatcaavdsadcespstercceedsedcduviaesddes sete cdovdche cdevacaecasvacdeseandess 2-7 
Return to defined state (WCleanup)............ccccccsssccceeeeneeeceseeeeeceeneeeeeesaeeeessnneeeeseeeeess 2-7 
Check for an error (WCheCKPOINE) ............cccceesscccececessssnceeeeeceeseesseeeeeeeceeseeseeeeeeeeenes 2-7 
Disable/enable leaves (WDisableLeaves) ..........:::cccccccsssssssccececcesesssceeeeceesssssnseeeseeeees 2-7 
Priority Changing: s.cccceesesisieatecacieaesdisoeatacsebeatsdevbdardsoeiuaracoviseaacesvasarieveuserdesvuderscnvedandeveede 2-7 
Set process priority handling on or off (wSetPriorityControl)...........ceeeeeseeeseeeneeeee 2-8 
Enter compute mode (WStartCompute) ...........eeeeeeeseeesseeeneeesseecsaeecsseeceseesteessseeeesaes 2-8 
Leave compute mode (WEndCompute)............:ceeceesecesseeesseeceseeceseesseeeesaeeesaeecseessnees 2-8 
General client functions: ... s.cccicce.ccedeses cendesceud ccesdcee ceulcal cdundcacess (dees setedevdaatedevicabeseedaadenteded 2-8 
Get information about a client (WClientInf0) «00.0.0... ccccscccccceessessteeeeeeeeeseseeeeeeeeees 2-8 
Position client in task order (WClientPOSitiONn) ............ccccccesssecceeesssssseeeeeeeeeseessseeeeenes 2-8 
Mark client as iconised (WClientIcomised) ............ccccccceessscccecccessecceeeceeesssssseeeeeeeessaee 2-9 
Make client system modal (wSystemModal) ...........eesceseseeeeseceneeceseeesseeceseeeesaeeeseeesaes 2-9 
Cancel system modal state (wCancelSystemModal) ...........eeceeeeeeseeseneceteeeeneeteeeeee 2-9 
Enable pause key (wEnablePauseKey) ............sceeeeceseeceseceseeesacecsseecseecsseecseeessaeeesaes 2-9 
Disable pause key (wDisablePauseKey) .............eeceecceeseeceeneeeseecececseesneecsseeeesaeessaeers 2-10 
Get client list (WGetProcessList)..........cccccccccssesssccceeeeceseceeeecesseesseeeeeeeeessseeeeeeseesesaaea 2-10 
SCreem= based OUtpute: bv. 2.4 sshd cau des Seng sha eet es ow sda oh leech oh gs eec bast cde edd osestece ete un edetaestoess 2-10 
Present an information message (WInfoMSgCorne?)...........:sccssseeesseeseneeseeteneeseneeeees 2-11 
Present an information message (WINfOMS) ...........::::cccesscceeeeeneeeeeeeeeeeeneeeeestneeeeesees 2-11 
Present a flashing busy message (WSetBUSYMSQ)............::ccsseeceseeseessseeseneeeeseeeeeneenaes 2-11 
Cancel a flashing busy message (WCancelBusyMS®)............seccsseecsseeceeeeeeeessneeesseees 2-12 
ACLs s aviesacte eaves ier oe iseeneieaeageads eves iaes the Hae eae Pave cia series at eens 2-12 
Present and wait for an alert (WSAlertW)..............cccccceeeeceeeessesecceeeeceececeeeeeeeeeeeeeeeeeees 2-14 
Present an alert (WSAIertA) 00... ccccccccceeeeeeeeeeeeeseeesesseseeeeeeeeseeeeeeseesseeseseeeseeeeeeeeeees 2-18 
Update a pending alert (wsAlertUpdate) 00.0... eee eeeeesseeceseeeeecseecseeceseeeesaeesaeessaes 2-19 
Status WINdOWS ss. scceccssecsecessccadeeseadagcesnacauceantcoudeseaesvensedsouevas ceauevbaecoeesaa ceseccaaedevccgacenscoaasens 2-19 
Enable the permanent status window (wsEnable).............::::cccsscceeeeeseeeeeeeeeeeneeeeeeees 2-21 
Set the state of the status window (WsStatuSWindOW) ..........:ccccccssssseceesesssssteeeeeeeeeees 2-21 
Get screen extent for tile with status window (wWsScreenEXt)...........cc::ccccccssssseeeeeeeees 2-21 
Update the permanent status window (wsUpdate) ..........ceeceeseeceeseeeeneeeeseseneeseeeees 2-22 
Disable the permanent status window (WsDisable).............:::cccsscccceseeeeeeeteeeeeeneeeeeeees 2-22 
Enable temporary status windows (wsEnableTemp)...............cccssccceeseeeeeeeeeeeeeeteeeeeeeee 2-22 
Disable temporary status windows (wsDisableTemp)..............::::ccssceeceeeeeeeeeeeneeeeeeees 2-22 
Set list of modes to display in status window (WsSetList) ..........:eeseeeseeeseeereeeeneeeee 2-23 
Set select position in status window mode list (wsSelectList) ...........::cceeeeseeeeeteeeeeee 2-23 
Inquire state and extent of status window (wInquireStatusWindow)...........::eseeeee 2-23 
Configuring the Window Serve ..........:ceseceesseessseecsncecsseecsseecesaeeesaeecsaeecseeceeesesaeeesaeeseaeers 2-24 
Configure the window server (WSySte€M)..........:::sscccsseecsseceseeesseecsseecseeeeseeeesaeessaeers 2-24 
Attached Cle tS as ccs. sescecseseicceds suns ctesecnecenscc sungerherensedeestussdeeniatecdestavecegriatedssateradsgaaneeredets 2-25 
Attach to client (WAttachToClient)............cccccsssccccccccssssssseeeecseesseeeeeecesssessseeeeeeseenaea 2-26 
Attach to foreground client (wAttachToForegroundClient) 0.0.0... .eeeseesseeeesneeeeneees 2-26 
Detach from client (WDetachClient) ............ccccccccccccecssssssecceeessesseeeeeceeeseeseeeeeeseeeaaee 2-26 
Miscellaneous ..........::ccccseccceesssceeeeeseeeeeseeeceeseaeeccssnneeceeeeeecessaeeecesaeeesseaeeeeeeeeeeceenneeeeeeeeas 2-26 
Get information on supported features (wSupportInf0) «0.00.0... eee eeeeeeeseeeeeeeeeeeeeeneers 2-26 
Set or cancel key click disable state (wDisableKeyClick) 0.0.0... ceseeseeeeseeeeeeeeeeeeeee 2-26 


iii 


WINDOW SERVER REFERENCE 


iv 


Bs SWAMKOWS io csssscesctsccadcssdesesscicseaccssecdecueScansdescdceasuesdeasssasscestacsdeasesssdseosecsicosessscscesceddusecasestecdcessues 3-1 
Creating and initialising a WINdOW.......... ces eeeceeeseecesseeeseecseeceseeeesaeecsaeecseecsneesesaeeseaeers 3-1 
WiIndow attributes 0.0.0... cccccssscccecceesseesneceeeecesseesseeeeeecceeseesnseeeeeeseeceseeeesaeeeeeeeeeees 3-1 
Create a window (WCreateWindow)........ccccccccccssssssccecceceseesssessseeeeeceeessssseeeeeeeeeeseeenaee 3-4 
Set window attributes (WSetWindOW) ..........cccccccccsssssseceecceessesseeeeeeeeeessesseeeeeeeeeseeenaes 3-5 
Get window attributes (wInquire Window) ............::cceeescceeeesenceeeeeeneeeseeaneeeeseaeeeseeaees 3-5 
Initialise window tree (WInitialiseWiNdOWTTee) .............:cccccccceeseesseeeeeceeeeeeessssseeeeees 3-5 
Destroy a window and its descendants (wCloseWindowTree) ............:::cceesseeeeeereeees 3-6 
Get window to window offset (wInquireWindowOffset) .............:::ceesssseeeeeeteeeeeeteeeees 3-6 
Reassign the root window (WReassignRootWindow)............:scccsssecesseeesseeseneeseseeeesaee 3-6 
Visible and invisible WindOWS ..........:cccccccsesssccccccecesessseceeeccceeseesseeeeeeccsssssseeeeeeeeeesessaeeeees 3-6 
Make window invisible (WMakelInvisible).............:::ccccccssssssscceceeeessessseeeeeeeeesessseeeeees 3-6 
Make window visible (WMakeVisible) ..............cccscccccccccessesseceeceeessessseeeeeeecessessaeeeees 3-7 
SIDS POSTMONS $5. oe0: wes sredlsun teen seeehtegakelcskp steko gee sded site etetetedadedsule peste ceadetenep paktedeyoseesses testes 3-7 
Change position in sibling list (WWindOWPOSItiON)............ceeeeceeeeeeseeeeseeeeeeeesneeeenees 3-7 
Get position in sibling list (WGetWindowPosition) .............:ceeeeeeseeceseeeneeteneeesneeeesaes 3-7 
Scrolling. hicp eine eps when A revel ase telat edeavas eno eine ania es 3-7 
Copy a rectangle (WScrollRect)...... eee eeeeeccesseeeceeseeeecsaeeecesseeesessaeeesesseesssaeeeess 3-7 
Scroll a window (WScrollWin)..........ccccccccsssssecessessscceecccesseesneeeceseeesseeeeeeesesseesneeeeeees 3-8 
Redra win 8% so.5i0 nt eke a tieees chat agepont doeti h oati eied ea a Ae eek tad ou Ah nt 3-8 
Start a partial redraw (wBeginRedraw)..........eeeeeccessecesseceseeeseecsacesseeceseeseeesesaeeesaes 3-9 
Start a full redraw (WBeginRedrawWiI0)............:::cceesescecesseceeeeeeceseneeeeeeeeeeeseeeeseaaees 3-9 
Start a partial redraw (GC) (wBeginRedrawGC)...........cccsscscecesscceeeneeeeeeeeeeeeseneeeeeeees 3-9 
Start a partial redraw (GCO) (wBeginRedrawGC0) ..........csccceessscceeeeeeeeessneeeeeeseeeees 3-10 
Start a full redraw (GC) (wBeginRedrawWinGC)...........ccecccceesececeeseceeeeeeeeeseneeeeeeees 3-10 
Start a full redraw (GCO) (wBeginRedrawWinGC0) ...........:ccceeesseeeeeeeeeeeeneeeeeeseeeees 3-10 
End a redraw (WEndRedraw)..........ccccsssssscccccesseesneceeeeccessessneeeeeeeeessesseeeeseceessessaaeeees 3-11 
Veal Catt Tay Peo cceats ween title cor stels cae Stct ete Mock 30s oth oY sear bnd sane uboe tant san vatbeoedanel otoesntem estes 3-11 
Validate a rectangle of a window (wValidateRect) ............:cceesccccesececeeeeeeeesneeeeeeeneees 3-11 
Validate a whole window (WValidateWiIN)...........ccccccccccccssssssscceeeccssseeeeeeeeessesseeeeeees 3-11 
Invalidatings::ssinycisiis de meheeaa ates pak Gani Sieeny dae dere banyan dele helasyare daha ews 3-12 
Invalidate a rectangle (wInvalidateRect) .............ccessseeessccceeesneeeeeeeneeeceereeeeeneeeeeseeeeess 3-12 
Invalidate a window (WInvalidate Win) ...........cccccssccccccccsssssssceeeeseesneeeeeeeeessesseeeeeees 3-12 
PORT. CUES OR secede otaseteeceasdh degttev detec eaddetatuteaseaeteasttieviesiatlsea stab cetats testius terre desta 3-12 
Draw a text cursor (WT eXtCUISor) .............ccceceeeeeeeeeeeeeeeessesseeeseseeseeeeesseseeesesseeeeeeeeees 3-12 
Draw a text cursor (WDrawTextCuTrsoL) ..............::cceeeeeeeeeeeseeeeeeeeeeeeeeeeeseseseeseeeeeeteeeees 3-13 
Erase a text cursor (WEraseTextCursor) ..........:::ssssssssssssecccceceeeceeeeeeeeeeeeeeeeeeeeeeeeeeeeeees 3-13 
Bitmap SEQUENCES vse. u- ssn, cies beep suvesins sekyetesovny tant sWheeteteteeasteg sts beresacebath pede Cevesaeabedeyateteasbicer be 3-14 
Attach bitmap sequence to window (WSetWinBitmap)...........c:ceeseesscceseeseneeeeseeeesaee 3-14 
Change a bitmap (wChangeWinBitmap) .............esceescccssceceseesseesseeseneesseeesseeeeeeees 3-15 
Free a bitmap sequence (WETCE)..........cesecesseeesseecsneesseeceseecssaeeesaeecsaeecsaeesseesenaeeesaes 3-15 
SS PRICES stato a dosstast, oeateetesteh svt gested vorets telat ty cectet Mi stt cous ctetced set revestst heey stiternpetatedep liken eens 3-15 
Create a sprite (WCreateSprite) 2.0... eeeeeeeesseecsseeceecseeceeeceseeeesaeecsaeesseessaeesseeeees 3-15 
Change a sprite's bitmaps and position (WSetSprite) 00.0.0... ceeeeesseeceseeeneeesneeeeseeeesaee 3-16 
Freé-a sprite. (WEICG):. c.vccdsceavecsecesecasaveas cendecatccaaseas cedessetcedeschtccavsancess actu cenvedaa censeete oes 3-16 
COCKS s<docdece states, coveslsste anche tee stubssagesehs ceeatensace nish slenstus sans bstha tes stuketeeaceuategaten ies bebategstat events 3-16 
Create a clock (WsCreateClOck) ...........ccccssscsccccceessessseeeeccccessesseeeeeeecesesssseeeeeeeeeeeeenaes 3-17 
Create a clock - Enhanced version (wsCreateClock2) ..........ccccccccesssssceceesessseeeeeeeeees 3-19 
Set the clock offset (WsSetClOCk) ........ccccccccccessessssccccecccesseesseeeeeceeesseeseeeeeeecessesseaeeees 3-22 
Bre6:a: CLOCK (WELEE) ce ococeesvecsees sites oduedns odes odegosdesnnpocessdegsuesenes cach sdey sishcues sesh suey sianeves ove 3-22 
MouSe 1COMS }.2c25.2cc.ssseteghecevdesvedsavegetdcoedevedsa vcdantevbesevsnns (devdesvevevdcedcdevdsobevencdersgevdsoueseredintes 3-22 
Load a mouse icon (gOpenMouselcon) ...........cseceeesecesseecsseecsseeceseeeesseessseesseeesseeeesaes 3-23 
Freé a MOUSE 1CON (WELEE)..3s.c35cces ceseseevecievessvedecuetceaevveusedneust coaueseudedecuencesvavesceaueesbess 3-23 


CONTENTS 


4: ‘Graphics: OuCPuUls.isss.cccrscsscecsscsvssencavosdensasoesensadosdansedesensdedecsnntesossnatesosteatecsesoasssecdoadeseasoassesanee 4-1 
Graphics <COMLE RUS ois conse Ps sues cacsecgs dey suena dee seen see sda genes stip sdeaa dee set deppaeae eset topes aces 4-1 
Creating a permanent graphics CONtEXt......... ce seeeseecsseeesseeceseeesceeseaeecsaeecsacesseeseeseseeeesaes 4-4 

Create a permanent GC (gCreateGC) 0000... ceesececeesseeecessaeeeseseeesenseeesesseeeees 4-4 
Create a permanent GC with default values (gCreateGCO) .00... eee eeeeeesseeeeereeeeneees 4-5 
Free a permanent GC (WETee) ..........:cceccceeeesssneeeeceecesesesaneeeeeeceseesnaneeaeeeeeeeeeeeesnaeeeeees 4-5 
Creating a temporary graphics CONtEXt ........ es eeeeeesseeesseeeseecseeeeseeeesaeecsaeecsaeesseeseneeeesaes 4-5 
Create a temporary GC (gCreateTempGC) .00...... cece eeeseeceesreeeeesseeeeeeseeeeesseeeess 4-5 
Create a temporary GC with default values (gCreateTempGC0) ........ cee eeeeeeeeeeeneees 4-6 
Free a temporary GC (gFreeTempGC)......... eee eeeeceeceesreeeeeseeecessseeesesaeeseeeeseeeees 4-6 
Setting. a graphics Context-....ccce.eiyisetesiiesdegiyiaeb agin de beeoyievncain des Degeylivg dhe ee leeeyienbegnaedess 4-6 
Set a graphics context (GSetGC) ...... ces eescceeseccssneeesneecsneecsseeecesaeecsaeecseesesaeeesaeessaeers 4-6 
Make a permanent GC current (gSetGCO) ....... eee eeeeeeesseeesseeseneeeeseeeesaeessaeeeesseeensaes 4-7 
LAM @vdra Wi Geis esac doece sted eces ota sees ean eScahtunsStebantdededadis scchadis ofatadieacenstedodegadig nines ted slagotessinecdel 4-7 
Draw a line (gDrawLine)............::ccccessscccessnceeeeseneeeeeeaeeeesenneceeecsseeeeeeeaeeeseeaneeeeneaseeess 4-7 
Draw a sequence of lines (gDrawPolyLine).............cccccccceeessceeceesneeeeeeeeeeeseneeeeeseaeeeees 4-7 
Draw a box (gDrawBoX)..........cccsscceessseceeeseeeeessnneeceeseeceeseaeeeeeseaeeeceesaeeesneneeeeeseaeeeess 4-8 
Border a rectangle (gBorderRect) .........seeeeessceesseeceseeeeseeceseeeesaeecscecsneeeeseeeesaeessaeers 4-8 
Border a drawable (gBorder) ............ccsccccesesccceeeeeeeeeeenceceeesaeeecessaeeeeeeeaeeeeseneeeeesneeeess 4-10 
Draw a 'shadowed' border (gBorder2Rect) ...........::cceeseccceeeeeceeeeeeneeeceeseeeeessneeeeeseneeeees 4-10 
Draw a 'shadowed' border (gBorder2) ..............ccsecccceeseeceeeeeneeeeeeeeeecesneeeeeeeneeeeeseeeeess 4-12 
Draw a graphics object (gDrawObject) ......... ces eeseeeeseeceseecesseeesseecsseecseeceseeeesaeessaeers 4-12 
Area filling a scccscissticssisats cveisetaesedeatccveisetecopicetcdevicabecovdcansacsvisendesviderdcebicancens ddendevvecenedeced 4-12 
Change a rectangle (gCIrRect)....... eee eecececeesceeeceeseeeeeesaeeecessaeeeceseeesenseeeceeseeeees 4-12 
Invert an obloid (gINVODIOI) ..........ceeeeceeeeeceeeeecceecesnceeeeseaeeeceeeaeeecsenaeeeeneneeeeesnseeess 4-13 
Fill a rectangle with a bitmap (gFillPattern) .0...... ee eee eeeeeesecsneeceseeeeseeeseeeesaeessaeers 4-13 
"PEXt LOLS Sey sech sees essik Laan ce eaa Sas eon Lees eet esas pas eee sei baigae eaae beeen aa 4-14 
Open a font (GOpenFOnt)........ eee eeeessceceseeceseeesseecseecsseecesaeeesseecsaeecseecsseeeesaeessaeers 4-15 
Set pos to open font/bitmap/mouse icon (gSetOpenAddress)...........:ceseeseeeseeeeneeeeee 4-15 
Bréé:a: font: (WEPCE):.. fs 502-5505 Ses eden bass ects cede ateganncosahsves sPehanti ben teveg sta gous sceeategsacersepeehewvs 4-16 
Get font information (gFontInf0) .............ceeessccesescecceeeneeeceseneeeeesneeeeesnaeeeeeeneeeeeseeeeess 4-16 
Get text width (gTextWidth) ...........eeeccceeesscceessceeeeseeeeeeeeneeecesaeeeeeenaeeeeseneeeesseeeeess 4-16 
Clip text to pixel width (gTextCount) oes eeeeeesseesecesseessseecseecseeseessseeeeseeeesaes 4-17 
Get a font width table (gGetWidthTable) ...............cceeeccceesssecceeneeeeeseeeeeeseneeeeeseeesseees 4-17 
Set the system and internal fonts (wSetSystemFont) .............eeeeeseeeeseeceseeeeseeeeeneenaes 4-17 
Open a font from a multiple font file (gOpenFontIndex) 00.0... eee eeeeeeseeeeseeeeeeeees 4-18 
Configure a font group (gConfigureFonts) .............eeeeeesseecsseeeeeseecsneecsseeeeseeeesaeessaeers 4-18 
Read a font header from a file (gReadFontHeader) ................ccsscceeeeeeeeeeeeeeeeeeneeeeeeee 4-19 
Read a font group header from a file (gReadFontGroupHeader)............eeeeeeeeeeeeeeee 4-19 
PEXt OUtpUt TUM CELONS. ss... se Seek fe sano see Get see dae noes bee stot Sabet cae ualea ones tanteee dieeaass restetene ts 4-19 
Print text (@PrintT ext) s.ic0.ccccccsacesecadacesvecscevsvicdesvauscaesues cess iuarceevscan ces setnces vaca censeeavens 4-20 
Print clipped text (gPrintClipText) oe eeeesseecesnecesseeseeeesaeecsaeessseeceseesseessseeeeeaee 4-20 
Print text in a box (gPrintBOxText) ..........eccceeeseecceeneeeceenceeeeeeaeeeceeneecseeeeeesseeeeseaeees 4-20 
Print text with embellishment (gXPrintText) ............ccsccccesceceesseceeeeeneeeeeeeeeesneeeeeeees 4-21 
Print shadowed text (gShadowText) .0.........cccceeesesceceeesneeeceeneeeeceeneeeeeeneeeecseneeeesseneeeess 4-23 
Draw a text button (WDrawButtOM) 0.0.0.0... ccc cccceececccceccccceeeeeececeeeeeeeeeeeeeeceeeeeeeeeeeees 4-24 
Draw a text button (WDraWButtOn2) 00.0.0... .ccccesscccccccesseeceeceeeessssseeeeeecesssseeeeeeeeeseeenaee 4-25 
Bittaps ss vscctessesho ces ys atsae shits roves cach cat sees Leak det aU cate enti et oet celal ot cant shal ote ate aalt sht aur 4-26 
Create a bitmap (gCreateBit) 0.0... lee eeseecesneecsneecsseecsseecesaeeesaeecsaeecseessseesesaeessaeers 4-26 
Load:a. bitmap: (@OpenBit) :..., sis. scjseecsedpocevevspeees et godeqeveg vanes codes viguastedeyotes ahpsuseevep eds 4-27 
Freea bitmap: (WFree) s.icc.cccivtesricvecsericceeientccuebsedsdepdses cduvdsetedepicaecdevdcndcdevcavsdeveaneeed 4-28 
Save a bitmap (gSaveBit) .............::::cscseeesterensceenotesoseescneosscnerssnenseesseneresenensenonseees 4-28 
Save part of a bitmap (gSaVeREct) 0.0... eeeeeeeseessseecsneeceseeceseeeesseecsacecseessseeeeseessaeers 4-28 
Copy a bitmap to a window (GCOpyBit) ........ eee eeseceseeceseecesseeesseecseecseeesseeeesaeessaeers 4-29 
Copy a bitmap onto itself (@COpyRect)........ eee eeseeesseeceseeceseeeesseecseecsseeesseesesaeessaeers 4-30 
Read a bitmap (gPeekBit) 0.0.0... ee eee cesecssceesseeceseeeesseecsaeecsaeecseeeesaeecsaeessaeessneeeesaes 4-30 
Check if a bitmap is valid (gCheckBitmapID) ........... ec eeeeeeeeeeneeeeseeceneeceseeeesaeessneers 4-30 
Mill tiple biti aps sees sce kh coeeseks oosig os tec decst tg saeha wtilevete celgoditie tp veut ees oteneatg Fane exssotepantgsaneovecets 4-30 
Open a bitmap file (GINItBit) 20... ee eee eeeneecsneecsneecsseecesaeecsaeecsaeecseeeeseesesaeessaeers 4-31 
Load a bitmap from an open file (GGetBit) 0... eee eeeeeceseeceseeeeseeenseeesaeessaeesseeeees 4-31 
Draw a bitmap from an open file (gDrawBit)......... eee eeeeseeeeseeeeeecnseeesaeeesseeseeeees 4-31 
Query the size of a bitmap (GQUETYBIt)..... eee ee eeeeeeesteeceneceseessseecssceseseeeesaeeeseeesaes 4-31 
Close an open bitmap (WEFTCE) .......... ce eeeeceesceesseeeeseeeesseecsaeecsseeceseeeesaeessaeesseeseneeeesaes 4-32 


WINDOW SERVER REFERENCE 


vi 


Initialise a multiple bitmap file (gInitMultiSave) ..0..... ee eee eesseeceseeesseeeeseeesseeeesaeees 4-32 
Save a bitmap to a multi bitmap file (gSaveMultibit) oe eeeeseeceneeeeeeeeeeeeeeees 4-32 
Save part of bitmap to multi bitmap file (gSaveMultiRect)....... eee eeeeeeseeeeeneeeeeees 4-32 
End multiple bitmap save and close file (gEndMultiSave) «0.0.0... eeeeeeseeeeseeeeneeeeeees 4-32 
Inquire screen or bitmap checksum (gInquireChecksum)............:esecesseeeeseeeesneeeeneees 4-32 
Adding graphics output fUNCtiIONS ......... ee eee ceseecssceceseeeeseeeesaeecsaeecsseaeeesaeecsaeecseeesseeeesaes 4-33 
Load @ DYL (WLOad DY L) vssccck. cccvceseeencccsecevssesvawen cae cvsvdeanees cosesdeedeancueeccuvsvesdcancsaeees 4-33 
Call a DYL function (WCalIDYL)..........cccccccccccccssssscceeesssssceeeeeceeseesseeeeseesessaeeeeeeeeees 4-33 
Call a DYL enquiry function (WCalIDYLReply) .........e ee eeeeeeseeceseeeeseceneeeeseeeesaeessneers 4-33 
5 EVENAS.........sccceccssssecssseseserceseccssceessseeseseneesesecseceseseseseeeesesessenessecesssesseseseeseseesesesssceseseseessesseses 5-1 
Getting the TEXte vent s-..1 ccc es i resdeatietesgsaisestastebesskteassetaaiendaakeeshasthovandantecstenthocaatanioiebias 5-1 
Wait for an event (WGetEVentWaAllt) .........ccccccssccccccceecceessesseeeeeeceeseeseeeeescesesssssaeeeees 5-1 
Asynchronously request an event (WGetEVent) 00.0.0... eeeeeeeeseeeeeesseeeceeseseeeeseeeeeeeas 5-2 
Asynchronously request selected events (wGetEventSpecial) ...........ceeseeeeeeesneeeeneees 5-2 
Change event types selected (wGetEventUpdate) .0....... ee eeseesseecsseeesseeeeseeeesneeeeneers 5-2 
EVEN TYPOS ics des sesiesud ovbsectccchdeunesvs jotacaes avai Seshuaua Saunier Ueevencs caevenededevetes sessersdeduecees Sysseeenedunees 5-3 
Key press'event CWM_ KEY) vecssiess.ccciess cepisscsetedics eva dscsevsnde eh sess sesaspasdess Sassdasavesnoess ous 5-3 
Redraw event (WM_REDRAW) ...............cccceceessseeeeeeeeeeesessseeeeseseeeeeseeeessessesseeeeeeseees 5-6 
Background event (WM_BACKGROUND).............cccscccceeenseeeesneeeeeesaeeeeseneeeeeseeeeess 5-6 
Foreground event (WM_FOREGROUND)...........:::ccccessceeeeeeceeeeeeeeeeeeaeeeeesnneeeessneeeees 5-6 
Cancellation event (WM_CANCELLED) ..............cccccccccccccessesssceeeeeeeessesseeeeeeeeeeeesaaes 5-6 
User message event (WM_USER_MSG) ............eccccccccesessssnneeeeeeeeeessnaeeeeeeeeeesesnneeeeees 5-7 
Machine switched on event (WM_ON)............ccccssssccccecessssseeeeeeeeeeecesseesseeeeeeeeeseeeaaes 5-7 
Command received from another client (WM_COMMAND)............:::cccccccssessseeeeees 5-7 
Inform shell of process termination (WM_TASK_UPDATE) .............:::ceeseseeeeeteeeees 5-7 
Inform application key handler (WM_TASK_KEY)..........cescceeseccesseeeeseeseneeeeneeeesaee 5-7 
Change of date event (WM_DATE_CHANGED) ..............ccccceseceeeeeeeeeeeeeteeeeeseneeeees 5-7 
Escape-key event (WM_ESCAPE)..........:::esscssscccesseeeseeceseecssceceseeeesaeeesaeessaeessseeeesaes 5-8 
Deiconisation event (WM_DEICONISE)..............cccccssssscccccccesssssseeeeeeecesssssseeeeeeeeenes 5-8 
Attachment event (WM_ATTACHED)...............ccccccccccccccccceeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeees 5-8 
Detachment event (WM_DETACHED)................ccccccccccccccccceecceeeeeeeeeeeeeeeeeeeeeeeeeeeeeees 5-8 
Keyboard state change event (WM_KEYBOARD_STATE_CHANGB).................55 5-8 
MouSe Events s..icc cisieseeoh hehe aise be staceseastedtatecandeseeuuvdanteenb dee vena nieideeobbesbomesGdecendervateriagens 5-9 
Mouse event (WM_MOUSB)................cccccsesesesseseseeseeeeeessseseeeesseseeseeesseeseseeeseseeeeeeees 5-9 
Start rubber band (WM_RUBBER_ BAND INIT)...............cccccccccsccccceeeeeeeeeeeeeeeeeeeeees 5-9 
Complete rubber band (WM_RUBBER) ..............:::ccesesceeeeeenceeeesneeeeeenaeeecesneeeeeseneeeess 5-10 
Activation event (WM_ACTIVE)...........cc::ccccccccssssssseceececessesseeeeeeeesesessseeeeeeeeseeeenaes 5-10 
Vent: fUN CHONG? 2500 etree sera botadtedves sende Gotan aueteterieiteas ues alt he Rut esa het e ee eee 5-10 
Request a cancel event (WCancelGetEVent)............cssecccccceeeeeseneeeeeceeeeeeesneeeeeeeeeeeeeaeee 5-10 
Request a user event (WUserMS) 000... eeeecceeseeeceeseeecesseeeecesseeecessaeeecessaeeceesaeeeees 5-10 
Send a command to another client (WSendCommand) .............:ccccessscceeeeeeeesessteeeeees 5-10 
Get a command from another client (WGetCommand)............::ccccssssscceeeeessessseeeeeees 5-10 
Enable the reception of WM_ON events (wInformOn).............::::cccessseeeeeseeeeeeeteeeees 5-11 
Enable/disable the reception of WM_ON events (wInformOnAl])...........:.:::cceseeees 5-11 
Captarin’ keys: ic22.vitensite sta eee hse] ail iapa aie eeitiee tin 5-11 
Capture a key (WCaptureK ey) ........eeeeesceseseceseeeeseeeesseecsseecsaeeceseeeesseecsaeesseessneeeesaes 5-11 
Cancel key capture (wCancelCaptureKey) ..0.......eeeeeeseceseeeeseeceseeeesaeeesaeessaeesseeensaee 5-12 
Setting task Switch Keysy 2. c:ccvccecessccnatel«ostsdesotepsdepeeseadebotes stag ence beut-depeloasropiebedeyeteperepn ice 5-12 
Set a task switch key (WSetTaskKey) .........ceeeeceeesecesseessseesseeceseecsacecsseeseeeeneeesseeeesaes 5-12 
Cancel a task switch key (wCancelTaskKey) ..........cesccesseeessseeeeeeesseeceneeceseeeeeeeeeeens 5-12 
Set a back task switch key (wSetBackTaskKey) ..........cesccessceceseeeeeseecsseesseeseeeseneeeees 5-13 
Cancel a back task switch key (wCancelTaskKey) .00...... ees eeesceceseceseeeseeeeeeeeesaeeseaeers 5-13 
Capturing: the Mouse. .2cc2itec.yeeetiedy tiie Diana divi ge ea ee pitied 5-13 
Capture the mouse (WCaptureMouse) ............. cc eeeeeeesseecesseeeceseeecessseeeseseeecensaeeeees 5-13 
Release the mouse (WReleaseMouse) ............:::ssssssssssecccccceceeeeceeeeeeeeeeeeeeeeeeeeeeeeeeeeeeees 5-13 
The TUBBER- Dan on ccicz cnn Socctsenedtetasidetes ach doesuedea texters oa teodesedeeedeaetacorsesintalecstacedivrdehedeesde seeders 5-14 
Rubber banding (WRubberBand)...............cccccccceeeseeceeeeneeeeeeeceeeeesneeeeeeeaeeeeseneeeeeseneeeees 5-14 
WM. RUBBER 6 Vents: 5 oie. 5.882 ON oR titk eb aN odehit ack nbelesh dik sh Sekine sh eet 5-15 
Capturing mouse and keyboard event ...........eeeeeeseesseessscecsseecseeecesaeessneecsaeessneeeeeaes 5-15 


CONTENTS 


6 Window Server Reference Update ................ssscssssscssscssccsscscecsssccesssscsesssscscssssscsesssscssesssccseees On 


Screen sizes 


Keyboards sccicicesiticciictiaseiseniesebiercsceiaetdecele dedeviaancdvelennceesicandeesddndegevidnndeviddarce nedeveeedees 
Latin S WIN OWS: eink ec at Leto a ae beet a tet rat Leet taal sae A et, he Sel al beh a ne! Sad Noh ie look 228 6-3 
S€LleS SC sos eee ee ee ee 6-3 
SIC shot Be eciet sR Scetcatilecuss Bick covers decussate bemborideteusietaebsndetes otis teeusvedeteuedictsebsaudedsnedsstuchetee 6-3 
CHOC Secs Restate sect ea Sac ae tea a eb ev hae avg ba ecole n a ase eet ase ea 6-4 
A ao) U0: RACER te Oe ROAD NCEE A A nS SR AN EO SA ARP A RR I ee eR 6-4 
SOPICS:. BC occas Sc ces udscwsaea bedacus wae sues ceac tus viv auauen duacousvdesseusaasan suey aeaga ue auuaeesudeaseuseeeaonese 6-4 
Window Server Versions. ...........ssssccccccssssssvvsseccccecenssvescccccscnsssvescvccesensnsesesesscesesusvseseveeeees 6-4 


CHAPTER 1 


INTRODUCTION 


Before reading this manual you should read (at least) the introductory chapter of the PLIB Reference 
manual. 


This manual describes the C functions in the WLIB library that access the services of the window server. 
This manual completely supersedes previous versions and takes account of: 

e version 4 of the window server 

e the Series 3a and Series 3 corporate computers 


The window server is a system process (with process name SYS$WSRYV) that runs under the EPOC 
operating system to provide "client" processes with shared access to the screen, keyboard and (if there is 
one) a pointing device. 


“ehentl screen 
window 
“Gent? Saiver keyboard 
SyoswoRy 
client 3 pointing 
device 


A server process is required because EPOC is a single-user multi-tasking operating system as opposed to a 
multi-user system. On a single-user system, all the application processes must share the same screen and 
keyboard. Using a server process to share a resource is a common technique on multi-tasking operating 
systems! and EPOC has particularly good support for client-server architectures (see the chapter 
Processes and Inter-Process messaging in the PLIB Reference manual). 


Having connected to the window server, a client requests services by sending the window server an inter- 
process message. However, the application programmer does not program at the message passing level but 
uses the C function interface described in this manual. 


Versions of the window server 


This section summarises the differences between window servers that run on the following computers: 
e the HC range of hand-held corporate computers 
e the Series 3 palm-top computer (abbreviated to $3) 
e the Series 3a palm-top computer (abbreviated to S3a) 
e =the Workabout corporate hand-held computer 
e the MC range of notebook computers (MC400 and MC200) 


'File servers and printer servers are commonly used to share centralised mass storage devices and printers 
respectively on, for example, a network. A file server is also used in EPOC (with process name 
SYS$FSRV, described in the Files chapter of the PLIB Reference manual). 


1-1 


WINDOW SERVER REFERENCE 


As well as different versions on different machines, the process of continuous development has produced 
four generations of the window server: 


version 2 
version 3 


version 3.5 


version 4 


found on MCs with ROM versions less than 2.40 
found on HCs with ROM versions less than 1.50 


found on S3s, HCs with ROM versions of 1.50 or greater and on MCs with 
ROM versions of 2.40 or greater 


found on the S3a and Workabout. 


You can obtain the machine type and whether it is version 2, 3 (which includes 3.5) or 4 of the 
window server from the information returned by wconnect. 


Version 4 


The following lists the changes for version 4 of the window server: 


Task keys now cycle 
round all instances of 
applications 


Double pixel mode 


Bitmaps 


Merging of HC and S3 
features 


$WS_FNTS environment 
variable 


On the S3a, where more than one instance of an application is running, 
pressing the TASK key for that application (ie one of the membrane keys) 
causes control to cycle round from one instance to the next, bringing each 
one into foreground in turn; the SHIFT+TASK key cycles round in reverse. 
Where the S3a is running in S3 compatibility mode, the diamond key must 
now be used to switch modes. This key generates a W_KEY_MODE event. 


All graphics commands now handle drawing with double sized pixels. 
This feature is designed for the S3a to run in S3 compatibility mode. 

It is also available in individual windows by setting the 
W_WIN_DOUBLE_PIXEL flag; this causes all graphics in that window to work 
in double pixel mode. 

A new flag G_Gc_FLAG_DOUBLE can be set in a graphics context (GC) to 
draw in double pixel mode. 

Note that the Workabout does not use double pixel mode when running in 
S3 compatibility mode. 


A set of new bitmap functions are available that open a bitmap file and 
permit bitmaps within the file to be loaded or drawn directly. 

Multiple bitmaps can be loaded from a file without needing to close and 
reopen it for each bitmap. 

Part or all of a bitmap can be drawn directly from the file. 


Some HC features from the later releases of version 3.5 of the window 
server have now been added to the S3a variant of the window server. These 
are: 


- the window server system flags set by calls to wsystem that were 
previously relevant to the HC but not the S3a, are now relevant to both. 
The initial value of these flags is loaded from the environment variable 
$wS_FL as in the HC variant. 


The environment variable $ws_FNTS contains a series of words each of 
which contains the index of a font used by the window server. The fonts 
are as follows: 


e System font 

e = Notifier/Alert font 

e Status Window font 

e Symbols font used for the status window diamond symbol 
e Medium 2 digital clock font 

e Medium 2 date font 

e §©Notifier/alert button font 


e Small status window clock font 


Font ID indirection 


Keyboard/event buffer 
size 


Date changed event 


Default icon ID 


Grey 


New window 
background modes 


Scrolling/Moving 
windows 


Alert changes 


Load additional 
functions 


Sprites 


1 INTRODUCTION 


Font IDs based on ws_Front_BasE will be available for this and all future 
versions. 


Font IDs based on ws_FonT_Bask2 are for internal use only. Developers may 
use these fonts but NO guarantee is given that they will be available in 
future versions. 


The keyboard/event buffer size has been increased from 8 to 16 events per 
application. 


Whenever the date changes, a w4_DATE_CHANGED message is delivered to any 
application in non-compatibility mode on the S3a while in foreground. 
Applications in non-compatibility mode in background will receive the 
message when they come to foreground. If this event occurs while the 
machine is off, the message will be delivered when the machine is next 
switched on. 


A new #define called ws_pzEFAULT_Icon has been supplied to identify the 
built-in default icon; the grey part of the icon ID is ws_DEFAULT_ICON+1. 


Grey is available on the $3a and Workabout (in one shade only). At a 
software level this has been implemented by introducing the concept of a 
plane. 

There are two planes to which drawing can be directed, both of which have 
the usual background attributes. The normal plane can be thought of as 
being the ‘original’ plane, handling black. The grey plane as its name 
implies handles the display of grey. 

Drawing is normally done to one or both planes. However, the two planes 
are not entirely independent; for example, to display grey, the normal plane 
should be clear and the grey plane set. If a pixel in the normal plane is set, 
it is displayed black regardless of the grey plane setting. This is best thought 
of as the normal plane ‘overlaying’ the grey plane. 

Appropriate values in a new flags field in the c_cc struct cause graphics to 
be directed either to the grey plane or to both planes. 


New background modes have been added to the normal plane: 
W_WIN_BACK_CLR_NO_REDRAW, W_WIN_BACK_SET_NO_REDRAw and 
W_WIN_BACK_NONE_NO_REDRAW. The ..._No_REDRAw modes have the effect of 
telling the window server to set the background for the plane but that no 
drawing (or re-drawing) will be done to it. Note that w_wIn_BACK_CLR Is the 
default background mode for the normal plane. 

Similarly, the grey plane has corresponding background modes: 
W_WIN_BACK_GREY_CLR_NO_REDRAW, W_WIN_BACK_GREY_SET_NO_REDRAw and 
W_WIN_BACK_GREY_NONE_NO_REDRAW as well as the expected 
W_WIN_BACK_GREY_CLR, W_WIN_BACK_GREY_SET, W_WIN_BACK_GREY_NONE and 
W_WIN_BACK_GREY_BITmap. Note that the default background mode for the 
grey plane is w_WIN_BACK_GREY_CLR_NO_REDRAW. 


Scrolling and moving windows has been optimised so that a plane is only 
moved if it has drawing enabled. Drawing to a plane is disabled by 
specifying any of the background modes: ...._NoO_REDRAW. 


All existing calls to wsAlertw appear in a new style. The maximum number 
of message lines can be increased to four by OR'ing the ws_aLeRtT_B flag 
into the mode parameter and by building an appropriate text string. 


Additional graphics primitives can be loaded from a dynamic library 
(DYL). The associated functions are wLoadDYL, wCallDYL, 
wCallDYLReply. 


These are animated sequences of bitmaps which are 'connected' to a 
window. Unlike the pre-version 4 animated sequences, a sprite is not 
displayed as part of the window background. The window server takes care 
of saving and restoring the contents of the underlying display. This can give 
the impression of the sprite 'floating' above the underlying display. 


WINDOW SERVER REFERENCE 


1-4 


In addition to or in relation to the above mentioned topics, the following functions are new to 


version 4: 
wCompatibilityMode 
gInitBit 

gGetBit 


gDrawBit 


gQueryBit 


wFree 


gInitMultiSave 


gSaveMultiBit 
gSaveMultiRect 


gEndMultiSave 


gInquireChecksum 


gOpenFontIndex 


gConfigureFonts 
gReadFontGroupHeader 
gReadFontHeader 
wSetSystemFont 


wsCreateClock2 


wStatusWindow 
wsSetList 


wsSelectList 


wiInquireStatusWindow 


wiInquireCompatibility 


wSupportInfo 


wDisablekeyClick 


wGetEvent Special 


wGetEventUpdate 


Sets or cancels S3 compatibility mode on the S3a and Workabout. 
Opens a bitmap file ready for calls to gcet Bit or gDrawBit. 
Loads a bitmap from the bitmap file opened by ginitBit. 


Loads the relevant scan lines (one at a time) from an opened bitmap file 
for drawing. In effect, it performs a gGet Bit, gCopyBit and wFree. 


Queries the size of a bitmap within a file opened by ginitBit. 


Either: 

closes the bitmap file opened by gInitBit but leaves loaded any bitmaps 
that came from that file 

or: 

frees a sprite. 


Opens and initialises a multiple bitmap file ready for calls to 
gSaveMultiBit, gSaveMultiRect and gEndMultiSave. 


Saves a bitmap to a multiple bitmap file. 
Saves part of a bitmap to a multiple bitmap file. 


Ends a multiple bitmap save and closes the file which was opened by 
gInitMultiSave. 


Calculates the checksum of a screen, a bitmap or backed up window. 


Opens a font from a multiple font file as created by version 2.00 upwards 
of the font compiler or opens a font from a single font file. 


Configures a font group. 

Reads a font group header from a font file. 
Reads a font header from a font file. 

Sets the system and other internal fonts. 


This is an enhanced version of wsCcreateClock and allows the creation of 
new clock types. 


Sets the state of the permanent status window. 
Sets the list of modes to be displayed in the status window. 


Specifies the new position for the diamond symbol in the status window 
list. 


Returns the state and extent of the various status windows available and 
the status window currently displayed. 


Returns the current state of the compatibility flags of the calling client. 


Returns information on supported features such as grey and compatibility 
mode. 


Disables the key click for an application. After setting this state, the 
window server disables the key click while the application is in 
foreground and resets it when the application goes to background. 


Asynchronously requests selected events. This is an enhanced version of 
wGetEvent and allows the selection of the type of event to be delivered. 


Changes the event types previously enabled in an outstanding wGetEvent 
Or wGetEventSpecial call. 


wSetPriorityControl 


wiInformOnAll 


gShadowText 
gBorder2Rect 


gBorder2 


gDrawObject 


wDrawButton2 


wCreateSprite 


wSetSprite 


1 INTRODUCTION 


Sets process priority handling to on or off. 


Enables or disables the reception of wu_on events. If enabled, wu_on 
events are delivered to a client whether it is in foreground or 
background. 


Prints shadowed text. 
Draws a shadowed border within a specified rectangle. 


Draws a shadowed border as for gBorder2Rect but lying within a 
rectangle which is set to the whole window or bitmap. 


Draws a graphics object scaled to fit within a specified rectangle. 


Draws a button. The function can draw both the old S3 style buttons and 
the new S3a style buttons. 


This function creates a sprite for a given window, a sprite being a 
sequence of up to 13 bitmap sets. Each bitmap set can have up to 6 
bitmaps, 3 for the normal plane and 3 for the grey plane. 


Changes the bitmap sets and position of a sprite. 


The following functions have been enhanced or changed: 


wSystem 


wlextCursor 


wSetWinBitmap 


gFillPattern 
gCopyBit 


gPeekBit 


gSaveBit 


Version 3.5 


New flags have been added to allow certain features of the status window 
to be disabled: wsERV_FLAG_SW_NO_LOW_BATTERY, 
WSERV_FLAG_SW_NO_PACKS, WSERV_FLAG_SW_NO_LINK, 
WSERV_FLAG_SW_NO_CAPS. 


A new flag w_cursor_GREy can be set in the flags member of the 
wW_CURSOR Struct to make the text cursor appear grey. 


A member of a bitmap sequence can be made to appear grey by OR'ing the 
WS_WIN_BITMAP_GREy flag into the mode member of the ws_wIN_BITMAP 
structure. 


Both functions now have a special way of handling grey when working on 
backed up windows with grey planes. 


Setting the most significant bit of the window/bitmap ID parameter causes 
the "peeking" to select the grey plane. 


This function will now save a double bitmap when saving the screen or a 
backed up window with a grey plane. 


The following lists the changes for version 3.5 of the window server: 


Notifier can be handled 
by the window server 


Going deaf 


Setting task keys 


where the window server optionally hooks the p_notify and p_notifyerr 
calls (removing the need for the syssntry process). Can also (optionally 
on the HC) take on the responsibility for automatically notifying the user 
of a process that terminates with a panic or a negative reason code. The 
window server also provides the notifier-like alert services wsAlertw and 
wsAlerta. Only available on HC and S3. 


On the HC and the S3, the window server now presents a "Hung up" status 
window when the foreground client does not respond ("listen") to redraw 
events (within 5 seconds). On the MC (and previously on the HC), the 
window server "slimes" invalid areas with a grey pattern. 


where the window server can be set to respond to two keys that cycle 
through the tasks in the two directions (see wset TaskKey, 
wSetBackTaskKey, wCancelTaskKey and wcancelBackTaskkKey). These task 
keys are in addition to the normal system task keys on the HC and MC and 
this feature is provided for the $3 (which does not have a system task key 
on the keyboard). 


1-5 


WINDOW SERVER REFERENCE 


Password support 


Faster text drawing 


Mono and italic font 
styles 


Info/busy messages 


Status window drawing 


Clock drawing 


Inter-client commands 


Link paste handled by 
the window server 


Terminating clients 


SYSSWSRV.$05 


where the window server can be set to activate the password alert when the 
machine is switched on. Only available on HC and S3. 


where a font that has no character wider than 8 pixels and is represented in 
a special fixed-width form is drawn significantly faster. 


A proportional font may be drawn mono-spaced (G_sty_mono). A font may 
be drawn italicised by shifting the top half of each character across by one 
pixel (G_STY_ITALIC). 


Info messages (see wInfoMsg and wInfoMsgCorner) are transient messages 
displayed in a corner of the screen. A flashing busy message may be 
displayed using wSetBusyMsg. Can also (optionally on the HC) take on the 
responsibility for using an info message to inform the user of a low battery 
when the machine is switched on. Only available on HC and S3. 


where a task status window is drawn by the window server as controlled by 
calls to wsEnable, wsDisable, wsEnableTemp and wsDisableTemp. Intended 
primarily for the S3 but available also on the HC. Not available on the 
MC. 


where an analogue or a digital clock image is redrawn and updated 
automatically by the window server (see wsCreateClock and wsSetClock). 
Only available on HC and S3. 


A client of the window server can send up to 127 bytes of data to another 
client (see wSendCommand, wGet Command and the wM_commanp event). On the 
S3, this provides the mechanism by which the System task (sys$sHLL) 
sends commands to application tasks to, for example, save their data and 
exit. 


On the S3 and HC, the window server handles the services that are needed 
to link paste data from one application to another (provided by sys$sHLL 
on the MC). 


When a client disconnects, the window server makes the client's owner 
foreground (the owner is the last process to p_presume the disconnecting 
client). If the owner cannot be found, the shell is made foreground. Applies 
to the HC and S3 only. 


The task that handled keyboard events no longer exists on the HC and S3 
versions, causing most process numbers to start one lower than before. 


In addition to those mentioned above, the following miscellaneous functions are new to version 3.5: 


wSystem 


gTextCount 


wGetWidthTable 


wlextCursor 


wiInformOn 


wDrawButton 


gSetOpenAddress 


wGetProcessList 


wAppKeyHandler 


1-6 


Changes the system wide behaviour of the window server. For example, to 
set whether the window server automatically reports a process terminating 
with a panic. 


Calculates the number of characters that can be displayed in a given pixel 
width. 


Gets the font width table. 


An enhanced version of wrext Cursor, supporting an obloid text cursor and 
the disabling of the cursor flash. 


If the foreground client has called this function, the window server sends it 
a WM_ON event when the machine is switched on. 


Draws an S3 style button, depressed or otherwise. Not available on the 
MC. 


Used immediately before gopenFront, gopenBit Of gOpenMouselcon to load 
the font, bitmap or mouse icon from anywhere within the file. 


Returns an array of the process IDs of the clients of the window server. 


Special handling of the S3 membrane keys. Intended for use by the $3 
System task only. 


1 INTRODUCTION 


The following functions have been enhanced: 


gBorder 
gBorderRect 


wConnect 


wDisableLeaves 


Version 3 


These functions take the following new flags: w_BorD_CORNER_1, 
W_BORD_TOP_ON, W_BORD_TOP_OFF, W_BORD_BOT_ON, W_BORD_BOT_OFF. 


Takes the new w_coNNECT_DISABLE_LEAvES flag. Equivalent to calling 
wDisableLeaves (TRUE) except that it also affects whether wconnect itself 
leaves or returns an error. 


Now returns the old state. 


The following lists the changes for version 3 of the window server: 


Backed-up windows 


Capturing keys 


System modal clients 


Pause key 


Windows 


Graphics output 


where a window may optionally be created (as determined by a parameter 
to wCreateWindow) such that any drawing to it is also drawn to a back-up 
bitmap. Many of the functions that operate on bitmaps can also operate on 
the backup bitmap through the ID of the window it is backing up. 


where a client may capture specific keys regardless of whether it has the 
foreground or not; provided by wcapturekey and wCancelCapturekey. 


where a client may alter its system modal state; provided by wsystemModal 
and wCancelSystemModal (a client can connect as a system modal client in 
any version). 


where the foreground client can be paused by the user pressing the pause 
key. The pause key may be enabled and disabled using wenablePauseKey 
and wDisablePauseKey. 


A function wGetWindowPosition gets the position of a window in its 
sibling list. An obscure function wRreassignRootWindow reassigns the root 
window (only used for development). 


Additional graphics output functions for improved screen aesthetics: 
gInvObloid, gXPrintText, gBorderRect, gBorder and gCheckBitmapID. 


All the above are available on version 3 and 3.5 of the window server. 


Specific to the MC 


Console implemented 
by window server 


Pointing device 


View multiple tasks 


Load additional 
functions 


On the HC, S3 and the S3a, the console device LDD con: is implemented 
by connecting directly to the window server. On the MC, the console 
device is implemented by an intermediate sysscons display process that 
draws and redraws the console window. 


The window server supports a pointing device only on the MC. The 
functions associated with a pointing device are: wcaptureMouse, 
wReleaseMouse, gOpenMouselIcon, wRubberBand. 


On the MC only, the windows belonging to more than client process may 
simultaneously be visible on the screen. The functions associated with 
viewing multiple tasks are: wclientIconised, wAttachToClient, 
wAttachToForegroundClient, wDetachClient. 


On the MC only, additional graphics primitives can be loaded from a 
dynamic library (DYL). The associated functions are wLoadDYL, 
wCallDYL, wCallDYLReply. 


WINDOW SERVER REFERENCE 


Using WLIB 


On all machines other than the MC, the WLIB library may be used in conjunction with: 
e =the CLIB library (with the CLIB startup module) 

e ~=with both CLIB and PLIB (with the CLIB startup module) 

e the PLIB library (with the PLIB startup module) 


Because the console is implemented by a separate process on the MC, you can't reasonably use the 
WLIB functions with the CLIB startup module. On the MC, we recommend using the PLIB library 
with the PLIB startup module (as described in more detail below). 


The WLIB header 
To get the constants and typedef for the functions in the WLIB library, you should include: 
#include <wlib.h> 


as well as the header files for using CLIB and/or PLIB. 


Connecting to the window server 


To use the services of the window server, a process must first connect to it by calling wconnect (or a 
function that calls wconnect such as wStartup). 


Not all processes are clients of the window server but an application process that is presenting a user 
interface is likely to be a client”. 


How you connect to the window server depends on whether you are using the CLIB or the PLIB C 
startup module and what machine you are running on. 


Note that the default project files set up by the installation of the SDK use the CLIB startup module. 
Using the CLIB startup module on the HC, S3, S3a or Workabout 


The CLIB startup module automatically opens a channel to the console device con:. This channel is 
used to implement the CLIB functions that access the screen display and the keyboard. For example, 
such functions as printf, gets, cprintf and cgets. 


On an HC and all Series 3 machines, the console device is implemented such that opening it connects 
to the window server, making the process a client of the window server. When using the CLIB startup 
module, you take advantage of this console connection - as described in this section. If you mistakenly 
attempt to connect a second time by calling wconnect or wStartup in your program, the process will 
be panicked with panic number 100. 


When the CLIB startup module opens con:, it puts the channel in the static variable winHandle, 
which may be referenced as: 


GLREF_D VOID *winHandle; 


As well as connecting to the window server, opening a channel to the console creates and initialises a 
backed-up window (which does not have to be redrawn). 


As described in the Console chapter of the I/O Devices Reference manual, you can obtain the ID of 
the console window using the r_1Nq I/O function, as in the following program: 


#include <plib.h> 
#include <p_cons.h> 
#include <wlib.h> 


2One exception to this rule is on the MC where an application uses the services of the console process 
(with process name SYS$CONS) to access the screen and keyboard. In this case it is SYSSCONS that is the 
client of the window server - not the application process. On the MC, an OPL program (which is really a 
process of SYS$OPLR) uses SYS$CONS to draw to the screen. 


1-8 


1 INTRODUCTION 


GLDEF_C INT main(VOID) 
{ 
CONSOLE_INFO cinfo; 
WS_EV event; 


p_iow (winHandle, P_FINQ, écinfo) ; 
gCreateGC0 (cinfo.window_handle) ; 
gPrintText (10,20,"Hello world!",12); 
do 

{ 

wGetEventWait (&event) ; 

} while (event.type!=WM_KEY) ; 
return (0); 


} 


where cinfo.window_handle is the console window ID. After displaying the "Hello world!" message, 
the program waits for a key press event and then exits. 


In CLIB programs you can prevent the automatic opening of a console channel by defining the 
function p_xwind in your code, as in the following example: 


extern void *winHandle; 


void p_xwind (void) 
{ 
winHandle=(void *)1; 


} 


int main (void) 


{ 


return (0); 


} 


You should ignore the warning, given during the linking of your program, that the symbol _p_xwind 
is duplicated. 


If you use this technique, your CLIB program should not, of course, make any reference to stdin, 
stdout Or stderr, unless you have redirected them. Setting winHandle to | (an illegal value for a 
handle) will guarantee that any such reference will fail with a panic. 


Using the PLIB startup module on the HC, S3, S3a or Workabout 


The PLIB startup model does not open a channel to the console and the simplest way to get going is 
to use the wstartup function that: 


¢ connects to the window server 
e creates and initialises a backed-up window to cover the whole screen 
¢ creates a permanent graphics context on that window 


After calling wstartup, you are in position to draw to the graphics context - as in the following 
example: 


#include <plib.h> 
#include <wlib.h> 


GLDEF_C INT main(VOID) 
{ 
WS_EV event; 


wStartup(); 
gPrintText (10,20,"Hello world!",12); 
do 

{ 

wGetEventWait (&event) ; 

} while (event.type!=WM_KEY) ; 
return (0); 


} 


1-9 


WINDOW SERVER REFERENCE 


Using the CLIB startup module on the MC 


On the MC, the console device is implemented quite differently from the HC. When the con: device 
is opened on an MC, a console display process is created by loading the SYS$CONS.IMG executable 
from the ROM. When the opener of the console device calls the channel's I/O functions, the console 
sends inter-process messages to the console display process which then sends inter-process messages 
to the window server. The console process keeps a character map of the console screen which it uses 
to redraw its window as necessary. The console process also manages a title bar that allows the 
window to be moved and/or resized and a menu bar that allows the program to be stopped. 


Because the console device is implemented in this way, the console does not support the p_F1nq I/O 
function as described above for using the CLIB startup module on the HC. Because it is the console 
and not the application process that is the client of the windows server, you can't use the console's 
window. There is nothing to stop you from connecting to the window server using wStartup or 
wConnect but you will then be running an application with two independent window systems and two 
clients. The console channel is still in winHandle so you can close the console and terminate the 
display process but this is hardly satisfactory. 


In conclusion, on the MC, you are better off embracing the EPOC system more completely and using 
the PLIB startup module. Despite what is said elsewhere, you can use some CLIB functions with the 
PLIB header - those that do not rely on any initialisation. You can, for example, use strcpy - but you 
can't use any I/O function such as open, or a memory allocation function such as malloc. 


Using the PLIB startup module on the MC 


As on the HC, the simplest way to get going is to use the wStartup function. 


The MC is available with both version 2 and 3.5 of the window server. Version 2 does not support 
bitmap backed-up windows. Even with version 3.5 on the MC, backed-up windows are less attractive 
on a large screen where the bitmaps consume large amounts of memory and the processing overhead 
of maintaining the bitmap is likely to be more noticeable. 


You can still call wstartup but, with version 2 of the window server, you get a window that is not 
backed-up and you have to deal with redraw events, as in the following example: 


#include <plib.h> 
#include <wlib.h> 


GLREF_D UINT wMainWid; 


GLDEF_C INT main(VOID) 
{ 
WS_EV event; 


wStartup (); 
do 
{ 
wGetEventWait (&event) ; 
if (event .type==WM_REDRAW) 
{ 
wBeginRedrawWin (wMainWid) ; 
gPrintText (10,20,"Hello world!",12); 
wEndRedraw() ; 
} 
} while (event.type!=WM_KEY) ; 
return (0); 


} 
The global variable wMainwid contains the ID of the window that is created by wstartup. 


On the MC with its larger screen, wStartup is probably too simplistic (for example, it creates a 
window the full size of the screen) and is best seen as a quick starting point for exploratory 
programming. In due course, you should look to using wconnect to implement a startup that is 
appropriate to your application. 


1-10 


1 INTRODUCTION 


Error handling 


How errors are signalled 

Should an error (such as out of system memory) occur in one of the window server functions, the 
window server will do one of the following: 

e call p_leave, passing it the (negative) error number 


e return the error number 


By default, the window server calls p_1eave. You can make it return the error number by calling 
wDisableLeaves (TRUE). From version 3.5 onwards of the window server, you can also set the 
W_CONNECT_DISABLE_LEAVES flag when calling wconnect. This is equivalent to calling 
wDisableLeaves (TRUE) except that it also affects whether wconnect itself leaves or returns an error. 


The enter and leave mechanism (which uses p_enter; and .p_leave) is commonly used to implement 
structured error recovery. See the Error Handling chapter of the PLIB Reference manual. 


With the enter and leave mechanism, a call to p_1eave should only occur within the protection of a 
p_enter harness. If you don't use p_enter and you don't call woisableLeaves and p_leave is called, 
the process will be panicked with panic number 47. 


Errors in blind operations 


In the interests of performance, many of the functions performed by the window server have a "blind" 
interface in the sense that the client does not receive any acknowledgement that the operation has 
been performed. 


Blind operations may be stored in a client-side buffer to be processed in batches when some condition 
causes the buffer to be flushed (as described later). The functions that perform blind operations don't 
return anything and are declared as vorp. 


Many of the blind operations can't reasonably fail - such as drawing a line by calling gprawLine. 
However, some functions can fail. For example, increasing or even decreasing the size of a bitmap 
backed-up window by calling wset window can fail to allocate the additional memory (which is 
required transiently when decreasing the size of a backed-up window). 


If an error occurs in a blind operation, the window server goes into a special state in which it discards 
all further blind operations until a function that can fail is called (such as wcreateWindow). 


When such a non-blind function is called, it immediately fails - either by calling p_ieave or by 
returning an error number, as described above. 


When a failure does occur while drawing, you often don't care exactly where it failed and you can 
happily wait until a non-blind function is called (which might mean waiting until weetEventWait, 
wGetEvent Of wGetEvent Special is next called). 


However, if you need to establish that the processing has been successful thus far, you can call 
wCheckPoint which flushes the buffer and signals any failure (by calling p_ieave or by returning an 
error number). 


Cleaning up after an error 


When handling an error while using the window server (say in response to a p_leave), you can use 
wCleanUp to clean up any dangling window server resources where wcleanUp: 


e frees the temporary graphics context (if it exists) 
e ends a redraw if one was in progress 


If there is a current graphics context that is attached to a window, wcleanUp also invalidates that 
window so that it is not left in a partly drawn state. 


1-11 


WINDOW SERVER REFERENCE 


Panic numbers 


See the Error Handling chapter of the PLIB Reference manual for a discussion of panics and panic 
numbers. 


The window server panics a client that attempts an illegal operation, using the following panic 
numbers: 


font does not exist 

illegal window or bitmap ID 

illegal window ID 

null handle given to server 

illegal graphics context ID 

illegal GMODE value (V2 only) 

illegal TEXTMODE value (V2 only) 

illegal font ID (V2 only) 

wBeginRedraw called while already in a redraw 

mouse icon does not exist 

illegal bitmap ID 

window tree is already initialised 

wEndRedraw Called when there isn't a redraw to end 

attempted to change the background of a backed-up window 
wInitialiseWindowTree called when the parent window is not initialised 
illegal parameters passed to wsAlertW, wsAlertA or wsAlertUpdate 
illegal length in gPeekBit (V2 only) 

illegal x+length value in gPeekBit (V2 only) 

illegal ypos in gPeekBit (V2 only) 

tried to connect a second time 

tried to access a permanent graphics context while a temporary graphics context exists 
illegal opcode in message 

command buffer received by wserv is too long 

generally bad message received 

wFree was called with an ID that doesn't refer to a freeable object 
illegal DYL ID 

out of range count sent to wSetWinBitmap 

a bitmap was freed while still in use by a wSetwinBitmap command 
illegal window-bitmap ID 

bad data or version in connect message 

called wGetEvent while the previous call was still pending 

function not available 

illegal clock ID in wssetClock 

illegal sprite ID (V4 only) 

client already has a sprite (V4 only) 

corrupt control block (possibly not connected) 

function number out of range 


Note that because of client-side buffering, there may be a gap between calling the offending function 
and the call to p_panic. When tracking down the cause of a window server panic, you may need to 
insert temporarily calls to wFlush or wCheckPoint to precipitate the panic. 


Series 3 compatibility mode. 


To enable existing applications that were designed to run on the S3, to run successfully on the S3a 
and Workabout while keeping the same 'look' and 'feel', version 4 of the window server can run in 
what is called compatibility mode for that application. This mode is set or cleared by use of the 
wCompatibilityMode function. 


As far as is practicable, the window server on the S3a attempts to emulate its behaviour on the S3. 
For example, in compatibility mode, all drawing to the screen is done in double pixel mode to 
overcome the fact that the S3a has a screen of 480 x 160 pixels compared to the S3 screen of 240 x 80 
pixels. 


When running in compatibility mode on the $3a or Workabout, the version_id member of the 
CONNECT_INFO sub-structure will have ws_vERston_4 set. This constitutes the only difference between 
the $3, S3a and Workabout in compatibility mode. 


1-12 


1 INTRODUCTION 


The Workabout has two different types of compatibility mode. In the first type, a 240 x 80 S3 display 
is centred on the screen, leaving an unused area above and below the display. In this type of 
compatibility mode, the only difference between the S3 and the Workabout is the version_id 
member of conNECT_INFo, aS described above. 


In the second type of compatibility mode for the Workabout, the display covers the full 240 x 100 
Workabout screen and uses a restyled status window. This type is intended for use by only those 
applications that can adjust the dimensions of their windows to match the available screen size. It is 
recommended that this type of compatibility mode should be used only if a centred 240x80 display is 
truly unacceptable. 


References to compatibility mode will occur throughout this manual. 


Clients and the window server 


Client-side functions 


In the interests of performance, not all the window server functions cause an inter-process message to 
be sent. 


For example, the function gtextwidth, which calculates the printed width of a text string, is 
implemented entirely on the "client side" without requiring any context switch between client and 
window server. 


Client-side buffer and flushing 


Also in the interests of performance, functions that perform "blind" operations that have no return 
values (such as most drawing operations) are not sent directly to the window server but are queued in 
a client-side buffer. 


In most cases, the client-side buffer is flushed automatically, when: 

e the buffer is about to overflow 

e an operation that requires a return value is requested 

e an input event is requested by calling wcetEventWait, wGetEvent Of wGetEvent Special 


Applications should not, however, make any assumptions as to whether a particular window server 
function call will or will not cause the buffer to be flushed. 


The client-side buffer can be flushed explicitly (for example, to animate an image) by calling wriush. 
In practice, it is rarely necessary to use wFlush and, although otherwise harmless, using wrlush 
unnecessarily will degrade performance. 


As described earlier, you can also flush the client-side buffer by calling wcheckPoint. 


The client-side buffer is allocated from the heap when wconnect is called and is approximately 300 
bytes long. The address of the data structure that contains the client-side buffer is held in the 
reserved static variable wclientData which may be referenced from C by declaring: 


GLREF_D VOID *wClientData; 


Testing for a connection 


If a process has connected to the window server, wclientData will contain a non-zero value. If a 
process has not connected to the window server, it will contain zero. 


1-13 


WINDOW SERVER REFERENCE 


Foreground and background clients 


Of all the clients of the window server one client is the foreground client and all the other clients are 
background clients. 


The foreground client is the client that receives keyboard input from the user. 


Some special key presses (such as the TASK key as described below) are processed by the window 
server. A client can capture specific key presses (in which case it is sent the key whether it is 
foreground or not) by calling wcapturekey. 


The foreground client has its windows in front of the windows of any background client. On small 
screen versions of the window server, that is, on the HC, S3, S3a and Workabout, the windows of any 
background clients are not visible at all. 


Events 


For each client, the window server keeps a queue of events that inform the client of user input and 
other events. The different types of window server events include: 


e key presses 

e foreground/background changes 

e redraw events (described later) 

e mouse events (if the machine has a pointing device) 


Mouse and key events are time stamped with a 16-bit time in system ticks which may be used to 
calculate the time between successive events that occur within a short time period (such as a double 
click). 


Redraw and mouse events are directed at a particular window by a window handle event parameter. 
This handle is specified by the client when the window is created (and is commonly the address of a 
client data structure that contains the window ID). 


The client can read the next event by calling wcetEventwait, which only returns when there is an 
event to deliver. If the client's event queue is empty, wGetEventwait will wait indefinitely for an event 
to occur. 


Applications that need to respond to events other than just window server events (for example, serial 
input) would use either of the asynchronous functions wGetEvent or wGetEventSpecial which 
request an event without waiting. Asynchronous requests are described in the chapter Asynchronous 
Requests and Semaphores in the PLIB Reference manual. 


Note that wGetEvent Special is only available in version 4 of the window server and is a 
generalisation of wGetEvent in that it permits the caller to select which events are to be delivered. 
Calling wGetEvent Special (WE_EVENT_NORM) 1s equivalent to calling wcetEvent. 


Task switching; 


The window server keeps all the clients in a front to back task order. Position zero in the task order is 
the front position and is held by the foreground client. Position 1 is held by the frontmost background 
task and so on. 


When a program connects to the window server, it normally takes the foreground. (A program can 
connect in background by setting a parameter to wconnect.) 


On an S3, an S3a or an HC that is running version 3.5 of the window server, when a process 
disconnects, the window server attempts to make the "owner" of the process foreground. Here, the 
owner is the process which last resumed it (by calling p_resume). If the owner has terminated or is 
not a client of the window server, the shell is made foreground. 


A client may bring itself or any other client to foreground (or put itself or any other client to 
background) by calling wclientPosition. 


Unless an application has taken steps to disable task switching, the user may switch tasks using the 
machine-dependent task-switching keys, as described next. 


3On large screen versions of the window server when one or more clients have attached to a client, you 
can have multiple foreground clients (in the sense that they all last received a foreground event) but only 
one of them (the frontmost client) receives key events. 


1-14 


1 INTRODUCTION 


Task switching on the HC 


On an HC with an alpha-numeric keyboard (as opposed to just numeric), the window server brings 
the foremost background client (at client position 1) to the foreground when the TASK key 
(SHIFT+LEFT ARROW) is pressed (the former foreground client is moved to the end of the task list). 


On an HC, an application can disable task switching in one of two ways: 
e locking itself into foreground by calling wsystemModal (0) 

e capturing the task key by calling wcapturekey 

Task switching on the Workabout 


On a Workabout, the window server brings the foremost background client (at client position 1) to 
the foreground when the TASK key (SHIFT+ESC) is pressed (the former foreground client is moved to 
the end of the task list). 


On a Workabout, an application can disable task switching in one of two ways: 
e locking itself into foreground by calling wsystemModal (0) 

e capturing the task key by calling wcapturekey 

Task switching on the S3 and the S3a 


Task switching is controlled by the 8 membrane keys (called application keys) above the main 
keyboard. Actually, the window server handles 16 application keys where a second set of 8 keys are 
accessed by pressing the CONTROL shift key. 


These keys are handled co-operatively by the window server and the shell. (The shell has process 
name sysssHu and is known by the user as the System task.) 


When the system starts up, the shell calls wappKkeyHandler to declare itself as the handler of the 
application keys. The shell maintains two data structures pointed to by the reserved statics patapp1 
and DatApp2 which control the assignment of the application keys to particular applications. 


When the system starts up, each application key is assigned to an in-built application. Using the 
shell's user interface, the application keys other than the 2 System application keys (14 in all) may be 
reassigned. 


The application keys are handled as follows: 


¢ On both the S3 and the S3a, if an application key (SHIFTed or otherwise) of an application 
different from that of the foreground is pressed, the window server makes the frontmost process 
of that application foreground‘. If no process of that application exists, the application key 
handler (that is, the shell) is made foreground and sent a wM_TAsK_KEy event. 


¢ On the S3 only, if an application key of the same application as that of the foreground is pressed, 
the window server sends the foreground task a wm_xey event with key code w_kEy_MopE. 
(Applications normally cycle through their display modes in response to this event.) 


¢ On the S3 only, if a SHIFTed application key of the same application as that of the foreground is 
pressed, the window server brings the frontmost background client of that application to the 
foreground (the former foreground client is moved to the end of the task list). 


¢ On the S3a under version 4 of the window server, pressing an application key of the same 
application as that of the foreground brings the frontmost background client of that application to 
the foreground (the former foreground client is moved to the end of the task list). Pressing the 
SHIFTed application key of the same application as that of the foreground does the reverse. 
In response to the DIAMOND key being pressed, the window server sends the foreground task a 
WM_KEY event with key code w_kzy_mopg. (Applications normally cycle through their display 
modes in response to this event.) 
Note, however, that a foreground application running on the S3a in S3 compatibility mode will 
also receive this event when the DIAMOND key is pressed. 


¢ On both the S3 and the S3a, if a PSION shifted application key is pressed, the window server 
makes the application key handler foreground and sends it a wm_TasK_kEy event. 


4The application is identified by its name. For an $3 or S3a application process, the window server reads 
the associated application name from the reserved static patProcessNamePtr. 


WINDOW SERVER REFERENCE 


The shell responds to a WM_TASK_KEY event (which indicates which key was pressed in a parameter) by 
positioning to the appropriate icon. 


The SYSTEM application key is permanently assigned to the shell. 


The CONTROL+SYSTEM application key is assigned to a notional RunImg application such that if this key is 
pressed, the window server makes the shell foreground and sends it a ww_TASK_KEY event. The shell then 
positions to the RuniImg icon (a bubble containing the word IMG). 


The shell calls wset TaskKey to assign SHIFT+SYSTEM as a task key. The window server responds to a task 
key by moving the foreground client to the end of the task list thus bringing the client previously at 
position | to the foreground. 


The shell also calls wset BackTaskKey to assign SHIFT+PSION+SYSTEM to the "back-task" key which brings 
the task furthest from the front to the foreground. 


On the S3 and the S3a, an application can disable task switching in one of two ways: 
e locking itself into foreground by calling wsystemModal (0) 


¢ capturing all the application keys key by making 8 calls to wcaptureKey (capturing all shift states 
in each call) 


Task switching on the MC 


On the MC, the windows of a foreground or background client that has a lower task position will, if they 
overlap, obscure (partially or wholly) the windows of background client with a higher task position. 


The user can change the task ordering by: 


e pressing the TASK to move the foreground client to the end of the task list thus bringing the client 
previously at position | to the foreground 


¢ pressing SHIFT+TASK to cycle through tasks in the reverse direction 


¢ pressing CTRL+TASK and CTRL+SHIFT+TASK that cycle in either direction in such a way that 
iconised tasks are skipped 


e using the digitiser to click on a background task's window 


On the MC, it is also possible to attach a client to another (by calling wattachToClient or 
wAttachToForegroundClient) such that the attached client and the client it is attached to behave as one 
task (with the attached client in front). 


An application can disable task switching by locking itself into foreground by calling wsystemModal (0). 


Iconised clients 


On large screen version of the window server such as the MC, a client can mark itself as iconised by 
calling wclientIconised. 


A client that marks itself as iconised is excluded from a form of window server controlled task switching 
in which only non-iconised tasks are brought into the foreground. On an MC, if the user holds down the 
CONTROL key while pressing the TASK key, the window server selects only non-iconised tasks. 


If an iconised client is brought to the foreground by a call to wclientPosition (normally by another 
process), the window server sends that client a WA_DEICONISE event (which would normally prompt the 
client to deiconise itself). 


Note that it is the client's responsibility to make any changes to its appearance as a result of a change in its 
iconised state. 


Client priorities 


The window server can be instructed (by a parameter to wconnect or bya call to wSetPriorityControl) to 
adjust automatically the process priority of a client when it gains and loses the foreground such that the 
foreground client runs at a higher priority than any background clients. 


A higher priority foreground client that is performing a computationally intensive task (for example, a 
spreadsheet program that is calculating) will totally and indefinitely block any lower priority background 
clients that are ready to run. This can be undesirable - particularly on the MC where the windows 
belonging to background clients may be visible. 


1-16 


1 INTRODUCTION 


To avoid robbing background tasks of all processing, computationally intensive processing should be 
bracketed with calls to wstartCompute and wEndCompute. In between the calls to wstartCompute and 
wEndCompute, the window server holds the client's priority at the background client level regardless of 
whether it has the foreground or not. 


On machines using the small screen versions of the window server, where the windows belonging to 
background clients are never visible, the arguments for using wstart Compute and weEndCompute are less 
compelling but there may be circumstances when their use is still appropriate. For example, if a user 
switches from a task which is printing to continue a game of chess, should the foreground chess task halt 
the background task from printing? 


System-modal clients 


There is sometimes a requirement to disable task switching by locking a so called system modal task in the 
foreground. For example, to notify the user of a condition that must be acknowledged or rectified before 
proceeding. 


A client may declare itself system modal by a parameter to wconnect, or may subsequently change its 
system modal state by calling wsystemModal Of wCancelSystemModal. 


The window server limits task switching to only those processes that have a lower client position than the 
frontmost system modal task (if there is one). 


A client that is system modal would normally be in one of the following client positions: 
e take the foreground in which case task switching is disabled 


e be furthest in the background (that is, with the highest client position) in which case task 
switching excludes the system modal task 


On larger screen versions of the window server (such as on an MC or a PC) where windows belonging to 
different clients are typically simultaneously visible on the screen, a system modal client would normally 
takes steps to make its windows invisible unless it has the foreground (since clicking on them will not 
bring them to foreground). 


Client management 


The window server is in a natural position to undertake most of the work necessary to manage clients, for 
example: 


e handling foreground/background task switching 

e automatically adjusting client process priorities 

e notifying the user of clients which terminate abnormally (on machines other than the MC) 
¢ supporting the link paste mechanism on the S3, S3a and Workabout 


However, there are a few functions to support a special client (typically the shell, sysssHu1) taking on 
some client management. These functions are: 


wGetProcessList Gets the process IDs of the clients of the window server, in front to back order. 
wClientPosition Used to bring a client into the foreground. 

wSendCommand Used to transfer up to 127 bytes from one window server client to another. 
wGet Command 

wAppKeyHandler Used by the shell on the S3 and S3a to handle membrane keys (application 


keys) in partnership with the window server. 


wSystem Modify the behaviour of the window server on a non-client-specific level. For 
example, to determine whether the window server handles the p_notify 
service. See also the section System start-up at the end of this chapter. 


wSetTaskKey Sets the window server to respond to additional keys that cycle through the 
wCancelTaskKey tasks in the two directions. Provided mainly for the $3 and S3a (which do not 
wSetBackTaskKey have a system task key on the keyboard). 

wCancelBackTaskKey 


1-17 


WINDOW SERVER REFERENCE 


Windows 


A window is a rectangle in screen coordinates that provides a coordinate system for clipped drawing. 


Once a window has been created using wcreat eWindow, its initial position and size may be changed (using 
wSetWindow). 


Note that at the window server layer, a window is invisible unless it is drawn to. If a window has a 
boundary (or any other features) it is because the owning client drew it. 


Most drawing is done to a graphics context to which a window has been assigned. Off-screen bitmaps can 
also be assigned to a graphics context. Both windows and bitmaps are sometimes called drawables. 


Window trees 
Windows are linked in a hierarchy or tree with the screen as the root window. 


A window is created relative to its parent window and is called the child window of the parent window. A 
child window may be a parent of further child windows and so on to any depth. 


The position of a child window is held relative to its parent. If a parent window is moved, all descendant 
windows move by the same amount. You can obtain the offset between any two windows (wherever they 
are in the hierarchy) by calling winquireWindowOffset. 


A child window 
e is in front of the parent (and will obscure any drawing to the parent window) 
e is clipped to the boundaries of its parent. 


Note that a child window may be smaller or larger than its parent. A window is often tiled with multiple 
child windows which are smaller than the parent and where parts of the parent window may or may not be 
visible depending on whether there are any gaps between the boundaries of the child windows. A window 
may have a single child window that is slightly smaller than its parent and where the parent provides a 
frame around the child window - any drawing to the child window is clipped to the boundaries of the child 
window and will not corrupt the frame. A window may have as its child a larger window that is providing 
a clipped scrolling view of some information (such as a list) where the view is scrolled by simply moving 
the child window in its parent's coordinates. 


A window is said to be the descendant of a window if it is its child or its grandchild and so on. All 
windows are descendants of the root window. Child windows of the root window are sometimes called 
top-level windows. 


Child windows of the same parent are called sibling windows. Sibling windows have a front to back order 
which is apparent if they overlap. 


Ownership of windows 


Except for the root window, all windows are owned by a particular client. A client does not have access to 
windows belonging to other clients and can only create child windows of the root window (that is, top- 
level windows) or of its own windows. 


On larger screen versions of the window server such as on an MC or a PC, windows belonging to different 
clients may (and typically are) simultaneously visible on the screen. 


On small screen versions of the window server, only the foreground client's windows are visible at any 
time. 


Background client drawing 


Background clients can still draw to their windows whether they are visible or not and programs do not 
normally take any special measures to avoid drawing while in background. In fact, applications are 
typically oblivious of whether they are foreground or background - they just don't get delivered any key 
presses while in background. 


In practice, background clients rarely draw to their windows on a small screen version of the window 
server because they have been robbed of keyboard input. Exceptions are a client that is switched to 
background while it is still processing and a client that is driven by events other than just key presses - for 
example a terminal emulation program or a clock program. 


1-18 


1 INTRODUCTION 


Background clients of a large screen version of the window server commonly draw to their windows while 
in background for two reasons. First, to take on the appearance of a background client (otherwise, unless 
its windows are partially obscured by an overlapping window, it is difficult to differentiate between 
background and foreground tasks). Second, to redraw its windows after being exposed by changes (of 
position, size, front to back ordering or visibility) to windows that previously obscured it. 


Drawing region 


When you draw to a window, the drawing is clipped to the visible part of the window - called the drawing 
region. When the window is partially obscured by overlapping windows, the drawing region is not a 
simple rectangle (it is actually represented by a variable-length array of rectangles). 


For example, suppose an application is displaying a clock as part of its main display area. On the 
completion of a timer informing the application to update the appearance of the clock, the application can 
happily go through the motions of drawing the entirety of the clock, without worrying whether part of 
that display is being obscured by an overlapping dialog box or pulled-down menu. The window server 
ensures that only drawing to unobscured portions of the window is effective: 


In the diagram, any drawing to the dotted region in the Clock window will fail to appear. 


The window server will discard a drawing region (since it can be recalculated at any time) rather than 
maintain it unless the window is being drawn to or is assigned to a permanent graphics context. 


Backed-up windows 


A window can be created in such a way that all drawing to it is duplicated to off-screen bitmaps. The 
window server can then automatically redraw the window without bothering the client. Prior to version 4, 
the window needs to be created with a w_win_BACK_BITMap background. In version 4 upwards of the 
window server the window can be created with one or both w_wIn_BACK_ BITMAP and 
W_WIN_BACK_GREY_BITMap backgrounds (see creating and initialising a window in the Windows chapter). 


This makes life much easier for the programmer. (Otherwise, the programmer has to respond to redraw 
events and has to adopt a more sophisticated programming style, as described below.) 


Prior to version 4, when a backed-up window is created, a single backup bitmap is also created with an 
appropriate size. This bitmap is initialised with zeros corresponding to a clear screen (white on an LCD). 


In version 4 of the window server, when a backed-up window is created which is enabled for drawing both 
black and grey, two backed-up bitmaps are created with an appropriate size, one for the 'normal' plane and 
one for the grey plane (see the Graphics chapter for a fuller discussion of grey). 


If the size of a backed-up window is subsequently increased, the backup bitmaps are also increased and the 
additional area (to the right and below) is filled with zeros. 


If a backed-up window is scrolled using wsScrollRect Of wScrollwin, the area that is scrolled in from 
outside the window is filled with zeros. 


The disadvantages of using bitmap backed-up windows are: 
e it takes longer to draw the image in the first place (since all drawing is duplicated) 
e additional storage is required to store the backup bitmap(s) 


Although the original drawing is slower, the window server redraws a backed-up window with blinding 
speed. 


WINDOW SERVER REFERENCE 


Keeping backed-up bitmaps for a screen-sized window incurs a storage cost which varies according to the 
machine type: 


e On the HC (160 by 80 pixels), a backed-up bitmap occupies a modest 1600 bytes. 
e On the S3 (240 by 80 pixels), a backed-up bitmap occupies 2400 bytes. 


e On the Workabout (240 by 100 pixels) using version 4 of the window server, a backed-up bitmap 
requires 3000 bytes. However, if the window is enabled to use both black and grey, two backed- 
up bitmaps are needed, thus doubling the space required to 6000 bytes. 


e On the S3a (480 by 160 pixels) using version 4 of the window server, a backed-up bitmap 
requires 9600 bytes. However, if the window is enabled to use both black and grey, two backed- 
up bitmaps are needed, thus doubling the space required to 19200 bytes. 


e On the MC400, a full screen (640 by 400 pixels) bitmap requires 32K bytes. 


Slowing down screen drawing is clearly more of a problem on a larger screen and, in summary, using 
backed-up windows on an HC or an S3 with their smaller screens (and smaller windows) makes more 
sense than on an MC. Using backed-up windows on an S3a or Workabout enabled to draw both black and 
grey is questionable. 


Note, however, that the size of the screen does not limit the size of the window. In most practical 
situations, the windows will be smaller on a smaller screen model, but it is sometimes useful to create 
windows that are larger (and possibly much larger) than the screen. For example, when presenting a 
scrolling view of a map that is much larger than the screen size. With such large windows it would not be 
desirable to use a backed-up window. 


No-redraw windows 


As well as backed-up windows, the programmer in search of an easy life should also consider windows 
created with the w_wIN_No_REDRAW bit set (as a parameter to wcreat eWindow). 


For such windows, the window server does not invalidate the window or generate redraw events. What it 
does do when the window is partly or wholly invalidated (that is, when the backup bitmaps would have 
been used if they existed) depends on the background parameter to wcreat eWindow as follows: 


W_WIN_BACK_CLR prior to version 4, clears the pixels in the window (this is the default). This is 
useful, for example, when the window is tiled with child windows but does not 
itself contain any images. 


in version 4, clears the pixels in the normal (black) plane of the window. 


W_WIN_BACK_GREY_CLR available in version 4 only, clears the pixels in the grey plane of the window. 


W_WIN_BACK_SET prior to version 4, sets the pixels in the window. This may be used, for 
example, to implement a black thick border to a child window that is slightly 
smaller and inset from its parent. 


in version 4, sets the pixels in the normal (black) plane of the window. 


W_WIN_BACK_GREY_SET available in version 4 only, sets the pixels in the grey plane of the window. 


prior to version 4, either w_wIN_BACK_CLR or W_WIN_BACK_SET may be used when a window is entirely 
covered with its child windows. For example, when a larger child window provides, in conjunction with 
its parent, a scrolling view over a larger image. 


In version 4, in addition to using either w_WwIN_BACK_CLR or W_WIN_BACK_SET, one of the corresponding 
grey plane attributes w_wIN_BACK_GREY_CLR or W_WIN_BACK_GREY_SET may also be used, if appropriate. 


Note that you should not rely on the fact that a window is always totally obscured by another window 
(such as a child window) to suppress redraw events since the window server can send unnecessary redraw 
events when there is insufficient free system memory to maintain update regions. For guaranteed 
suppression of redraw events you should specify the w_wIN_No_REDRAW bit to wcreateWindow - even when a 
window is always totally obscured. 


In version 4 of the window server, redrawing can also be suppressed on a per-plane basis by setting the 
. .._NO_REDRAW modes. This method is much preferred. 


The w_wIN_No_REDRAWw bit does not need to be set. 


1-20 


1 INTRODUCTION 


The ..._No_rEDRaw background flags can be used as follows: 


W_WIN_BACK_CLR_NO_REDRAW suppresses re-drawing to the normal plane but the window server 
clears the pixels. 


W_WIN_BACK_SET_NO_REDRAW suppresses re-drawing to the normal plane but the window server 
sets the pixels. 


W_WIN_BACK_NONE_NO_REDRAW suppresses re-drawing to the normal plane; the window server does 
nothing to the pixels in this plane - it neither sets nor clears them. 


W_WIN_BACK_GREY_CLR_NO_REDRAW suppresses re-drawing to the grey plane but the window server 
clears the pixels. 


W_WIN_BACK_GREY_SET_NO_REDRAW suppresses re-drawing to the grey plane but the window server sets 
the pixels. 


W_WIN_BACK_GREY_NONE_NO_REDRAW suppresses re-drawing to the grey plane; the window server does 
nothing to the pixels in this plane - it neither sets nor clears them. 


Bitmap sequences 


A window may be given an animated image by attaching a sequence of up to twelve bitmaps to the 
window by calling wsetwinBitmap. The sequence is modified by calling wchangewinBitmap and freed by 
calling wrree (destroying the window automatically frees the bitmap sequence). 


Each entry in the sequence specifies 
e asource bitmap 
e the position of the bitmap in the window 
e the transfer mode 


e the time to wait (in tenths of a second) before copying the next bitmap in the sequence to the 
window 


You should be careful about defining too short an interval between bitmaps (especially in combination 
with large bitmaps) as the computational effort to maintain the sequence may leave little processor 
bandwidth for the application to run. Note that the window server runs at a higher priority than its clients. 


If the sequence contains a single bitmap, the bitmap is not animated. 


Whether animated or not, a rectangle on the window that is currently covered by a bitmap in the sequence 
is automatically redrawn when that part of the window is invalidated. 


Any number of bitmap sequences may be attached to a window. Where there is an overlap, bitmaps from 
sequences attached after another sequence appear behind that sequence. 


Bitmap sequences are not designed to be used with backed-up windows and are typically used to produce: 


e a window with a changing background bitmap for other drawing (however, if there is only one 
bitmap in the sequence, the background does not change) 


e a window that is only drawn from the bitmaps in the one or more bitmap sequences and which, 
like backed-up windows, does not have to be redrawn (and the window should be created with the 
W_WIN_NO_REDRAW attribute). 


Unless the window is created with the w_wIN_No_REDRAw attribute, the window server invalidates the target 
rectangle in the window after it has copied a bitmap (it also invalidates any parts of the previous rectangle 
that is not covered by the new bitmap). The resulting redraw event is intended to prompt the client to draw 
on top of the bitmap. If you do not intend to draw on top of the bitmap, you should create the window with 
the w_wIN_No_REDRAW attribute. 


As well as the changes that occur as the bitmaps in the sequence are cycled through by the window server, 
you can make all manner of changes to the bitmaps themselves - for example, switching bitmaps and 
drawing to them. 


5The limit derives from the requirement to fit the sequence in the client-side buffer. 


1-21 


WINDOW SERVER REFERENCE 


In version 4 of the window server, bitmap sequences are, by default, drawn to the normal (black) plane 
only and the grey plane will display the appropriate grey background as specified in the call to 
wCreateWindow. However, there is nothing to prevent the client from drawing to the grey plane as a result 
of a redraw event. 


A member of a bitmap sequence can be made to appear grey by setting ws_wIN_BITMaAP_GREy for that 
member in the call to wSetWinBitmap in which case the normal plane will display the appropriate normal 
background. 


If bitmap sequences are required which make use of both black and grey, then sprites (discussed later) 
may be used instead. 


Using an attached bitmap to avoid redraws 


If you set up a no-redraw window with an attached bitmap sequence consisting of a single bitmap that fills 
the window, you can draw to the bitmap and have that bitmap copied to the window by calling 
wiInvalidateWin to invalidate the window. For flicker-free operation the window background should be 
set to W_WIN_BACK_NONE. 


In some cases, this may be more efficient than using backed-up windows (where everything is drawn 
twice). 


In version 4 of the window server, as mentioned before, the bitmap can be made to appear grey by setting 
WS_WIN_BITMAP_GREY in the call to wSetWinBitmap. 


The following program uses the technique described above and works on all versions of the window 
server. 


#include <plib.h> 
#include <wlib.h> 


#define NWS_HANDLE 0 
#define MAIN_WIN 1 


GLDEF_D WSERV_SPEC wspec; 

GLDEF_D UINT gcid; 

GLDEF_D UINT wid; 

GLDEF_D P_POINT winsize={160, 80}; 
GLDEF_D WS_WIN_BITMAP bitseq; 


GLDEF_C VOID CreateBitmap (VOID) 
{ 
G_GC gc; 


bitseq.bitmap=gCreateBit (0, &winsize) ; 
bitseq.pos.x=0; 

bitseq.pos.y=0; 

bitseq.rect.tl.x=0; 
bitseq.rect.tl.y=0; 
bitseq.rect.br=winsize; 
bitseq.mode=G_TRMODE_REPL; 
gc.style=G_STY_BOLD|G_STY_DOUBLE; 
gcid=gCreateGC (bitseq. bitmap, G_GC_MASK_STYLE, &gc) ; 
gClrRect (&bitseq.rect,G_TRMODE_CLR) ; 
} 


GLDEF_C VOID CreateWindow (VOID) 


{ 
W_WINDATA windata; 


windata.flags=W_WIN_NO_REDRAW; 
windata.extent.tl.x=0; 
windata.extent.tl.y=0; 
windata.extent.width=winsize.x; 
windata.extent.height=winsize.y; 
windata.background=W_WIN_BACK_NONE; 


1-22 


1 INTRODUCTION 


wid=wCreateWindow (0,W_WIN_NO_REDRAW 

| W_WIN_EXTENT 

| W_WIN_BACKGROUND, &windata, MAIN_WIN) ; 
wSetWinBitmap (wid,1, &bitseq) ; 
wiInitialiseWindowTree (wid) ; 


} 


GLDEF_C INT main(VOID) 
{ 
WS_EV event; 
P_RECT box; 
TEXT bb[32]; 


wConnect (&wspec, NWS_HANDLE, W_CONNECT_PRIORITY) ; 
CreateBitmap(); 
CreateWindow(); 
box=bitseq.rect; 
p_insrec(&box,1,1); 
gDrawBox (&box) ; 
winvalidateWin (wid) ; 
p_insrec(&box,1,1); 
for (77) 
{ 
wGetEventWait (&event) ; 
if (event .type==WM_KEY) 
{ 
p_atos(&bb[0],"Key code: %d",event.p.key.keycode) ; 
gPrintBoxText (&box, 50,G_TEXT_ALIGN_CENTRE, 0, &bb[0],p_slen(&bb[0])); 
winvalidateWin (wid) ; 
if (event.p.key.keycode==W_KEY_RETURN) 
break; 


} 
return (0); 


} 
Sprites 


In version 4 of the window server a window may be given an animated image by attaching a sprite to the 
window. 


A sprite is created at a specified position within the window and the animation produced by creating a 
sequence of up to 13 bitmap sets attached to the sprite by calling wcreatesSprite. The bitmap sets and the 
position of the sprite in the window can be changed by calling wset sprite; the sprite itself can be freed by 
calling wrree. 


Each bitmap set specifies: 


e up to three source bitmaps for the normal plane, i.e. one for each of the three possible transfer 
modes (set, clear and invert) 


e up to three source bitmaps for the grey plane, i.e. one for each of the three possible transfer 
modes (set, clear and invert) 


e the position of the bitmaps relative to the sprite 
e the time to wait (in tenths of a second) before displaying the next bitmap set 


Unlike the pre-version 4 animated sequences, a sprite is not displayed as part of the window background. 
The window server takes care of saving and restoring the contents of the underlying display even if this 
changes during the sprite's existence. This can give the impression that the animation ‘floats’ above the 
underlying display. 


When the sprite is created, setting the flag w_spRITE_CLIP_CHILDREN allows child windows of the window 
to which the sprite is attached, to clip the sprite. If the flag is not set, the sprite can only be clipped by the 
edges of the window to which it is attached or by other non-related windows. 


If the sequence contains a single bitmap set, the resulting display is not animated. 


Only one sprite may be created for each client of the window server. 


1-23 


WINDOW SERVER REFERENCE 


Redrawing 


Windows that are not backed up by bitmaps or an attached bitmap or are not created as no-redraw 
windows must be redrawn as well as drawn. 


If you intend to avoid redraws by using only backed-up windows, no-redraw windows and windows that 
are drawn from bitmap sequences, none of this section applies. 


Redraw events 


A window should be redrawn by a client when it receives a redraw event from the window server (after 
calling wGetEventWait, wGetEvent Or wGetEventSpecial). 


A redraw event indicates 
e the window to be redrawn 
e arectangle within the window that needs to be redrawn 
The rectangle is often ignored (especially for simple windows) and the whole window is drawn instead. 


The window server keeps an update region for each window to record that part of a window that is 
invalid. When the update region is not empty and the event queue is otherwise empty, the window server 
will complete a client's call to wcetEventWait, wGetEvent Or wGetEventSpecial with a redraw event. 


Note that user input events and foreground/background change events are effectively delivered at a higher 
priority than redraw events. This is sometimes desirable and sometimes not. 


Note also that, unlike other events, the sending of a redraw event by itself does not clear or otherwise 
reduce the update region (this is described below). The window server will continue to send redraw events 
indefinitely® until the update region is reduced by the client validating a part or the whole of the region - 
normally by the client calling wBeginRedraw (or a variant thereof), as described below. 


Update region 


The update region is similar to the drawing region in that it consists of a list of rectangles that are used to 
clip graphics output. Whereas the drawing region is used for drawing, the update region is used for 
redrawing. The update region is also used to generate redraw events as described above. 


The drawing region describes that part of the window that is visible. The update region describes that part 
of the window that is both visible and invalid. 


The window server automatically adds to a window's update region when: 
e the window is first created 
e the window's size is increased 


e a previously obscured part of the window is exposed by changes (of position, size, front to back 
ordering or visibility) to a window that previously obscured it 


e the contents of a window is scrolled using wscrollRect or wScrollWin 


A backed-up window always has an empty update region because the window server copies the data from 
the backup bitmap rather than add to the update region. 


Invalidating rather than drawing 


The client can itself add to the update region by invalidating a part of the window or all of the window by 
calling wInvalidateRect or wInvalidateWin respectively. 


It is often simpler for an application (at the expense of performance) to invalidate a part of a window or 
the whole of the window rather than draw to it.’ Invalidating causes the window server subsequently to 
send redraw events to the client. 


6A client that just ignores redraw events will loop indefinitely and "hog" the processor. 


7If a window is not visible or is substantially obscured, invalidating can actually be more efficient than 
drawing. However, this occurs rarely in practice. 


1-24 


1 INTRODUCTION 


The update region of a window is automatically reduced by the window server as a window becomes 
obscured by other windows. However, in practice, the update region is normally reduced (partially or 
wholly) before the client draws or redraws to it. 


Validating before drawing or redrawing 


You always automatically validate before redrawing (by calling a variant of wBeginRedraw) and you would 
normally also validate before drawing (by calling wvalidateWin Of wvalidateRect). 


As well as reducing the update region, validating can also prepare the background, depending on the 
value of the background window attribute, as follows: 


W_WIN_BACK_CLR prior to version 4 of the window server, clear the pixels in the window (this is 
the default) 


in version 4, clear the pixels in the normal (black) plane (this is the default) 
W_WIN_BACK_SET prior to version 4 of the window server, set the pixels in the window 
in version 4, set the pixels in the normal (black) plane 
W_WIN_BACK_NONE do nothing; in version 4, this is specific to the normal (black) plane 
In version 4 of the window server the above attributes can be OR'd with one of the following: 


W_WIN_BACK_GREY_CLR Clear the pixels in the grey plane 


W_WIN_BACK_GREY_SET set the pixels in the grey plane 


W_WIN_BACK_GREY_NONE do nothing; specific to the grey plane 


The w_wIn_Back_cur background is the easiest to deal with and is often used - particularly for simple 
windows or for windows with no grey. For flicker-free drawing or redrawing, use w_WIN_BACK_NONE (and 
W_WIN_BACK_GREY_NONE if using grey) and then program such that every pixel is covered when the 
drawing code executes (for example, using gPrintBoxText rather than gPrintText). 


Drawing 
You normally draw to a window when the data it is displaying has changed (say as a result of user input). 


When drawing a particular rectangle of a (non-backed-up) window, a client should call wvalidateRect 
before commencing the drawing. When drawing the whole window (which is more common), the client 
first validates the whole window by calling wvalidateWin. 


You must validate before drawing if you are relying on the w_wIN_BACK_CLR, W_WIN_BACK_SET, 
W_WIN_BACK_GREY_CLR Of W_WIN_BACK_GREY_SET Window attribute to prepare the background. 


If you are drawing to a window with a w_wIN_BACK_NONE Or W_WIN_BACK_GREY_NonE background, you need 
not validate before drawing to the window. If you don't validate, you will not preempt any redraw event 
when the same area happens to be invalid at the time and the same image may subsequently be redrawn 
unnecessarily (although, frankly, this is unlikely to be noticed by any user). 


When drawing to a window, a client may use a permanent or a temporary graphics context. (Note that all 
graphics output is directed at a current graphics context.) 


When using a temporary graphics context, the calls to graphics output functions would be enclosed by 
calls to gcreateTempcc and gFreeTempcc. If there is no requirement to change the default initial values of 
the graphics context, you would use gcreateTempcco in place of gcreateTempGc. 


When using a permanent graphics context (which was previously created and assigned to the window by a 
call to gcreateGc OF gCreateGco), you would typically use gset cc or gsetcco to make the appropriate 
permanent graphics context current before drawing. 


Redrawing 


While drawing is clipped to the window's drawing region, redrawing is clipped to the window's update 
region (for appearance and efficiency reasons). 


The client informs the window server that it is redrawing rather than drawing by enclosing the graphics 
output function calls between calls to weeginRedraw and wEndRedraw. As well as informing the window 
server that the client is about to redraw rather than draw, the call to wBeginRedraw also validates that 
rectangle of the window (specified as a parameter to wBeginRedraw). 


As with drawing, a client that is redrawing to a window may use a permanent or a temporary graphics 
context. 


1-25 


WINDOW SERVER REFERENCE 


There are no fewer than six variants of wBeginRedraw which vary according to whether a temporary 
graphics context is created (and, if so, whether it is to be altered from its default settings) and whether a 
part or the whole of the window is being redrawn. The full set is as follows: 


wBeginRedraw to redraw a part of the window using an independently created temporary or 
permanent graphics context 


wBeginRedrawWin to redraw the whole of the window using an independently created temporary 
or permanent graphics context 


wBeginRedrawGC to redraw a part of the window using a temporary graphics context that is 
created and initialised with specified values 


wBeginRedrawGC0 to redraw a part of the window using a temporary graphics context that is 
created with default initial values 


wBeginRedrawWinGC to redraw the whole of the window using a temporary graphics context that is 
created and initialised with specified values 


wBeginRedrawWinGC0 to redraw the whole of the window using a temporary graphics context that is 
created with default initial values 


When a begin redraw function is used to simultaneously create a temporary graphics context, the call to 
wEndRedraw automatically frees it. 


Note that if you mistakenly enclose the graphics output function calls between calls to wBeginRedraw and 
wEndRedraw when drawing (rather than redrawing in response to a redraw event), the drawing will 
probably not appear since it will be clipped to the update region (which is most likely to be null). 


Going deaf 


A client that owns one or more windows with invalid areas and which is not requesting events from the 
window server is said to have "gone deaf". 


An application goes deaf because it is performing a task that takes an extended time to complete. 
Examples of such extended tasks are: 


e loading or saving a large file (or some other processing of a large file) 

e astalled write to the parallel port (say, because the printer is out of paper) 
e computing PI to a thousand decimal places 

e a bug that has caused the process to "hang" in an indefinite loop 


Applications that process redraw events have a responsibility to process them within a reasonable time. If 
this is not done, the screen may contain images drawn by some other client (which is very confusing to the 
user). 


With a window server in a preemptive multi-tasking operating system, deaf clients need not block the user 
from switching to another task (as happens in non-preemptive multi-tasked window environments such as 
Microsoft Windows and others, where a deaf application typically leads to an unwelcome mouse icon such 
as an hour glass, a watch or, arguably more positively, a bee). With the window server handling the task 
switch key or keys, an aberrant application task that has hung does not require a system reset - the user 
can task to a suitable system application and terminate the task. 


To make it easier to diagnose when a client has gone deaf, the window server has mechanisms to detect 
deaf clients. On the HC, $3, S3a and Workabout, task switching to a deaf client will cause the "hung up" 
status window to be presented. On the MC, the invalid areas are eventually covered with a grey pattern. 
From the user's point of view, exposing a deaf client is preferable to leaving the debris of some other 
client's windows which may lead the user to blame the wrong application. 


The window server does not detect a client which is reading redraw events but discarding them. 


Applications can avoid going deaf within potentially blocking functions such as a write to a parallel port 
by performing such operations asynchronously - as described in chapter Asynchronous Requests and 
Semaphores in the PLIB Reference manual. The same chapter also describes how to use p_ioyield to poll 
at intervals for the receipt of a redraw message (after using the asynchronous wGetEvent or 

wGetEvent Special) while performing an extended process. Rather than polling, it is worth considering 
using p_execc to create a transient sub-process to perform an extended task and to use p_logona to be 
signalled when the process completes (as described in the chapter Processes and Inter-Process Messaging 
in the PLIB Reference manual). 


1-26 


1 INTRODUCTION 


Applications that are structured to present percentage done indicators or a cancel option (or preferably 
both) while performing an extended task are well structured to handle redraws and can easily avoid going 
deaf. In any case, applications that are deaf (and dumb) to the user for extended periods are generally not 
welcomed by them. 


Redraw priority 


Although redraw events always have a lower priority than user input events and background/foreground 
events, there is a two-level redraw priority that operates between windows. 


By default, windows are created at the lower priority and certain windows may be selected to receive their 
redraw events before the crowd by specifying the w_win_pRiortty bit to wcreateWindow OF wSetWindow. 
This is very much fine tuning, though. 


More about windows 


Creating and initialising a window system 


A window is created by calling wcreateWindow where you specify such things as the parent window, the 
position and size of the window (in the parent's coordinate system), whether the window is backed-up by 
bitmaps and so on. 


When sibling windows are created, they are created in front of any existing siblings (this is only 
significant when sibling windows overlap - they often don't). You can set and sense the front-to-back 
position of a window in its sibling list using wwindowPosition and wGetWindowPosition respectively. 


Each successful call to wcreateWindow returns a window ID. The ID is used subsequently to refer to that 
window. 


After a successful return from wcreateWindow, the window is just a dormant data structure in the window 
server's data segment with no visibility on the screen. You can't draw to the window and you won't get any 
redraw events (or any mouse events if there is a pointing device) until the window is initialised by calling 


wInitialiseWindowTree. 


As its name suggests, wInitialiseWindowTree initialises not just the window but all its descendants as 
well. In practice, a tree of windows is often created as a logical whole and it is desirable to activate the 
whole tree at once by calling wInitialiseWindowTree (passing it the window ID of the parent) after 

having successfully set the tree up from the parent window down by successive calls to wcreatewindow. 


The above is not meant to suggest that all new window systems take the form of a single tree with a single 
parent (although this is the more common case). It is quite possible for the window system to be created to 
consist of a number of (say sibling) windows or window trees. In such a case, you would still create the 
whole system with successive calls to wcreateWindow and then make multiple calls to 
wInitialiseWindowTree to initialise the system. 


Note that wcreateWindow can fail through lack of system memory but wInitialiseWindowTree cannot. 
When creating a window system you must be careful to destroy any partially created system should a call 
to wCreat eWindow fail. 


Destroying a window system 


Just as windows are created a tree at a time, windows are, in general, destroyed a tree at a time by calling 


wCloseWindowTree. 


A client that builds window systems would keep at least the window IDs of the windows in client-side data 
structures. In the client's data space, the data structures that contain the window IDs are unlikely to be 
related in the same tree structure as the windows are in the window server. Where this is the case, it may 
not be convenient for the client to recover the window side relationships and destroy windows a tree at a 
time (effectively bottom up) when destroying a window system. If a client uses its relationships (which are 
probably tree-like but a different tree) to destroy a window system, some windows would be destroyed 
more than once (because wcloseWindowTree has to destroy any descendants as well as the specified 
window). 


In recognition of this problem in destroying window systems, the window server does not consider it an 
error if a window is destroyed more than once. 


This does (quite reasonably) assume that windows systems are destroyed without any intervening window 
creations. 


1-27 


WINDOW SERVER REFERENCE 


Event sources other than the window server 


You need only read this section if you are implementing a program that responds to event sources other 
than just the window server (and therefore the program is using one of the asynchronous functions 
wGetEvent Of wGetEventSpecial rather than wGetEventWait). 


This section assumes familiarity with asynchronous requests - as described in the chapter Asynchronous 
Requests and Semaphores in the PLIB Reference manual. 


When responding to window server events that are requested asynchronously using wGetEvent or 
wGetEvent Special, you should completely process a window server event (after returning from p_iowait 
and having established that wcetEvent or wGetEvent Special has completed) before calling either 
wGetEvent Of wGetEvent Special again to request the next event. 


Bearing in mind the multi-tasking nature of the system and the fact that the window server runs at a 
higher priority than its clients, it is quite possible for the request made by a call to wGetEvent or 
wGetEvent Special to complete while responding to an event from a source other than the window server 
(for example, the expiry of a timer or the receipt of some data from the serial port). 


In particular, if one or more windows are directly destroyed in response to a non-window server event 
there is the possibility that the next window server event (a redraw event say) will relate to a window that 
has already been destroyed. 


To guard against this possibility, you should not destroy a window or a window system directly in 
response to a non-window server event but use wcancelGetEvent to instruct the window server to send the 
caller a WM_CANCELLED event and then respond to the wM_CANCELLED event as you would otherwise have 
responded to the non-window server event. 


After a call to wcancelGetEvent, the window server delivers the w4_cANCELLED event at the highest 
priority - any other events waiting in the window server client event queue are overtaken. The only 
window server event WM_CANCELLED can't overtake is one that has already been delivered. 


Visibility of windows 

A window is invisible when: 
e it has been created (using wcreateWindow) but not yet initialised (using wInitialiseWindowTree) 
e it has been made invisible by a call to wMakeInvisible; 


e the window was created with the w_wIN_FOREGROUND_ONLY attribute set and belongs to a client 
that is currently a background client (this case only applies to large screen versions of the 
window server) 


Note that wInitialiseTree, wMakeInvisible and W_WIN_FOREGROUND_ONLY all propagate their effect to 
descendant windows. 


After being initialised, a window is marked as visible. Once a window tree has been made invisible using 
wMakeInvisible, it may be made visible again by calling wMakeVisible. 


A call to wMakeVisible or wInitialiseWindowTree does not necessarily make all descendants visible 
since wMakeInvisible may have been applied to a descendant. 


The window server treats windows that are invisible as follows: 
e if the window is backed-up, any drawing to it is drawn only to the backup bitmap(s) 
e invalidating a window using wInvalidateRect or wInvalidateWin has no effect 


e¢ windows behave as if they do not exist with respect to mouse input (this only applies when there 
is a pointing device) 


Scrolling 


The contents of a window may be scrolled by a horizontal or vertical direction or a combination of the two 
using wScrollWin Of wScrollRect. 


Both these functions are better understood in terms of rectangle copying rather than scrolling where: 


wScrollRect copies a source rectangle in a window to a rectangle of the same size in the 
same window but displaced. 


wScrollWin works just like wScrol1Rect except that the source rectangle is defined by the 
boundaries of the window offset, in the opposite direction, by the amount of the 
scroll. This is what is normally used to scroll the contents of a window. 


1-28 


1 INTRODUCTION 


Both functions copy only those parts of the source rectangle that are both visible and valid. This means 
that the copy excludes the following from the source rectangle: 


e those parts that are in the update region 
e those parts that are obscured or clipped by other windows 
e those parts that are beyond the boundaries of the window 


Although these parts are not copied, their existence causes the corresponding region of the target 
rectangle to be invalidated. 


If the window is a backed-up window, the copy is also applied to the backup bitmap(s). For a backed-up 
window: 


e the update region is always empty 
e those parts that are obscured or clipped can be recovered from the backup bitmap(s) 
e those parts that are beyond the boundaries of the window are cleared. 


Since these functions access the same window server operations that are applied when a window is moved 
using wSetWindow, the above comments about not copying invalid regions applies to window moving too. 
If you wish to simultaneously move and change the appearance of a window you should use 
wInvalidateWin to invalidate those parts that are to change before using wSetwindow to move the window. 


Continuous scrolling 


The function wScro11win Is often used to scroll the contents of a window in response to user input (such 
as down arrow key presses, for example). Calling this function necessarily introduces an invalid area at 
the upwind border (or borders) of the direction of scroll. 


If the window is a backed-up window, these areas are automatically cleared by the window server by the 
wScrollWin operation and would subsequently be drawn by the client as part of the scroll processing. 


If the window is not backed-up by a bitmap, the window server invalidates those areas brought in from 
outside the window and there is the temptation to leave it to the redraw event handling to draw these 
areas. 


However, this is not good practice because redraw events are delivered only when there is no user input 
and in the quite typical case where the user holds down the key that is causing the scroll, the redraws are 
not processed until the user releases the key. This means that the screen rapidly fills with a copy of the 
image that was at the upwind border of the scroll and the window is only redrawn with something sensible 
when the key is released. 


When using non-backed-up windows you should program as for backed-up windows and calculate the 
area that needs to be drawn after the scroll and then validate and draw it. 


Text cursor 


A client can nominate at most one window at a time to contain a text cursor (which is optionally flashing) 
by calling wrextcursor. The text cursor can subsequently be moved from one window to another by 
calling wrextCursor again. To remove the text cursor from the window that contains it, you call 
wEraseTextCursor. 


The cursor is specified as a rectangle which is, in principle, xored with whatever is underneath it. 
Applications typically define a text cursor as a vertical line in between characters, a horizontal line 
underneath characters or a block cursor that fits over characters. 


In version 4 of the window server, the cursor can be made to appear grey on those machines that support 
grey such as the S3a and Workabout. 


The window server handles the flashing of the cursor and ensures that it does not interfere with any 
drawing or redrawing in its vicinity. 


On large screen versions of the window server where the windows of more than one client are on the 
screen at a time, the window server automatically ensures that only the foreground text cursor is visible. 


1-29 


WINDOW SERVER REFERENCE 


Bitmaps 
Drawing to the screen from a bitmap 


A bitmap is a piece of off-screen memory that is organised in the same way as the screen bitmap. A 
bitmap can rapidly be copied to a window for display using one of: 


gCopyBit to copy a rectangle from a bitmap to a given position in the current graphics 
context 
gDrawBit to copy a rectangle from an open bitmap file to a given position in the current 


graphics context. This is available in version 4 of the window server. 


gFillPattern to fill a rectangle in the current graphics context with repeated copies of a 
bitmap 
wSetWinBitmap to copy bitmaps to a window at specified time intervals from a sequence of 


bitmaps (as described earlier) 
All the above functions can copy a bitmap in one of four transfer modes: 
G_TRMODE_REPL where bits in the source pattern replace corresponding bits in the destination. 


G_TRMODE_SET where Is in the source pattern set corresponding bits in the destination (Os in 
the source do not change corresponding bits in the destination). This would 
normally be used to copy a bitmap on to a previously cleared destination. 


G_TRMODE_CLR where Is in the source pattern clear corresponding bits in the destination (Os in 
the source pattern do not change corresponding bits in the destination). This 
would normally be used to copy a bitmap on to a previously set bitmap. 


G_TRMODE_INV where Is in the source pattern toggle corresponding bits in the destination (Os 
in the source pattern do not change corresponding bits in the destination). This 
is suitable for copying over an existing pattern and may be reversed by a second 
identical application. 


Creation and storage of bitmaps 


A bitmap is created uninitialised by calling gcreateBit or (more likely) it is loaded from a file that 
contains one or more bitmaps using gOpenBit or gGetBit. A bitmap is freed using wrree. 


The function gSetOpenAddress may be used immediately before gopenBit or gGet Bit to load the bitmap 
from anywhere within the file (typically used to load a bitmap which has been embedded into the program 
file). 


In version 4 of the window server, gInitBit is used to open a multiple bitmap file ready for calls to 
gGetBit OF gDrawBit. 


When a bitmap is successfully created, gcreateBit, gopenBit and gGetBit return a bitmap ID (which is 
subsequently used to reference the bitmap). 


The window server keeps a built-in ROM-based grey bitmap (with a chequerboard pattern). This may be 
accessed with the bitmap ID ws_s1Tmap_crey. The bitmap has size WS_BITMAP_GREY_S1ZE_X by 
WS_BITMAP_GREY_SIZE_Y. 


Note that version 4 of the window server supports grey for those machines such as the Series 3a that can 
display true grey. 


When a bitmap is created, it may be stored in the window server's data space or in a named memory 
segment (named memory segments are described in the Memory Allocation chapter of the PLIB Reference 
manual). 


The window server automatically places bitmaps that are larger than 2K in named memory segments. You 
can request that a bitmap be stored in a named segment rather than the window server's data segment 
(regardless of the size). 


A bitmap that is in a named memory segment can be accessed directly by the client using p_sgcopyfr and 
p_sgcopyto (described in the Memory Allocation chapter of the PLIB Reference manual) or otherwise. 


1-30 


1 INTRODUCTION 


Drawing to bitmaps 


Like windows, bitmaps can be drawn to using any of the window server graphics output functions. 


However, unlike windows there is no drawing region or update region (so there is no such thing as 
validating before drawing). Drawing is clipped only to the limits of the bitmap. 


Bitmaps that are loaded from a file are typically read-only (which also makes them shareable). If you are 
going to draw to a loaded bitmap, you should specify the ws_B1T_wRITE attribute when you call either 
gOpenBit OF gGetBit to load the bitmap. 


Graphics output is directed at a current graphics context (which may be assigned to a window or a 
bitmap). As with drawing to a window, a program may use a permanent or a temporary graphics context. 


When using a temporary graphics context, the calls to graphics output functions would be enclosed by 
calls to gcreateTempGc and gFreeTempcc. If there is no requirement to change the default initial values of 
the graphics context, you would use gcreateTempcGco in place of gcreateTempGc. 


When using a permanent graphics context (which was previously created and assigned to the bitmap by a 
call to gcreateGc Or gCreateGco), you would typically use gset cc or gsetcco to make the appropriate 
permanent graphics context current before drawing. 


Bitmap files 


Bitmap files (which normally have the file name extension .pic) may be created in one of the following 
ways: 


e by saving the contents of a bitmap, a screen or a backed-up window using gsSaveBit (which saves 
the whole bitmap) or gsaveRect (which saves a rectangle of the bitmap). In version 4 of the 
window server, if the screen or a backed up window uses grey, saving either of them will create a 
double bitmap. 


e by saving the contents of a bitmap, a screen or a backed-up window using gSavemultiBit (which 
saves the whole bitmap) or gsaveMultiRect (which saves a rectangle of the bitmap). If the screen 
or a backed up window uses grey, saving either of them will create a double bitmap. Available in 
version 4 only. 


e by converting a PCX file using the wspcx program (which runs on a PC). Many PC-based 
graphics applications are able to produce PCX files. 


e by saving the whole screen to a file by pressing SHIFT-CTRL-PSION-S. This is not possible on 
machines without a CTRL key (such as the HC). 


Using wspcx 


The wspcx.exe program (which is placed in the \sibosdk\sys directory by the installation) may be used to 
convert PCX files to window server bitmap files and vice versa and also to link a number of .pic files into 
one .pic file. 


Where the .pcx file contains more than two colours, the following 'rules' apply: 
¢ white is converted to white 
e black is converted to black 
e all other colours are converted to grey 

On conversion: 


e If a.pcx file is marked as being black and white only, then the .pic file will contain a single 
bitmap. 


e =Ifa.pcx file is marked as being in colour, then the .pic file will contain a double bitmap, where 
the first bitmap represents the normal plane and the second represents the grey plane. 


e If a.pcx file is marked as being in colour but only contains an image using the black and white 
"colours", then the .pic file will still contain a double bitmap. 


1-31 


WINDOW SERVER REFERENCE 


To convert a .pcx file to a window server .pic bitmap file, use: 
wspcx -p <input> [-i] [-o<ouput>] [-s] [-x<width] [-y<height>] 


where the -p indicates PCX to PIC conversion and <input> is the name of file to be converted (which is 
assumed to have a .pcx extension unless otherwise specified). The remaining optional parameters are: 


-i Invert the bitmap while converting. 


-o<output> Specifies the output file name and directory (otherwise it is the same as the 
input file name with a .pic extension). 


-x<width> Clip or expand the bitmap to the specified size (in pixels). If expanded, the 
-y<height> bitmap is padded out with blank space. 
-s Suppresses output messages. 


For example: 

wspcx -p -i sausage.pcx 
produces the inverted sausage.pic. 
To convert from a .pic file to a .pcx file, you use: 
wspcx -w <input> [-i] [-o<output>] [-s] 
To just invert the bits in a .pic file without any other conversion, you use: 
wspcx -i <input> [-o<output>] [-s 


To link a number of .pic files into one output .pic file, you use: 


wspcx -l <input> [-o<output>] [-s 


where <input> is a text file (with extension .p/k) that lists the .pic files to be linked to produce a file with 
the same name as the .p/k file but with the .pic extension. A C header file (with extension .ph) is also 
generated that contains #defines for the index number and dimensions of each component bitmap. 


Capturing the screen to a bitmap file 


Pressing SHIFT-CTRL-PSION-S on an MC, S3, S3a or a Workabout saves the current screen to a file called 
screen.pic in the current path of the window server. Any existing file of the same name is replaced. 


In practice, the current path of the window server on a SIBO machine is always LOC::M:\ (it is defined 
when the window server process is started - well before you have any chance of influencing it). 


However, if an environment variable with the name $WS_SD exists, the window server uses its value to 
open the file to be created. For example, running the following program: 


#include <p_std.h> 


GLDEF_C INT main(VOID) 
{ 
p_setenv ("SWS_SD", "B:\\SCREEN.PIC"); 
return (0); 


} 
subsequently causes the screen dump to be written to the root directory of the local B: drive. 


If the save fails for any reason (such as disk full), the file is not produced and no notification of the failure 
is given. 


You can use this behaviour to disable the SHIFT-CTRL-PSION-S screen dump key by setting up $WS_SD to 
contain an illegal file specification. For example, just inserting the following line of code: 


p_setenv("SWS_SD",""); 


disables the screen dump key. 


1-32 


1 INTRODUCTION 


Screen capture program for the HC 


The following program illustrates how you can construct your own screen capture program on an HC, or 
an $3. The program will work on an S3a or Workabout provided that the screen does not contain grey. To 
capture grey, the program code needs to be changed in order to capture the grey plane as well as the 
normal plane (see gPeekBit in the Graphics Output chapter and any reference manual on PCX file 
formats). 


The program has a "quick and dirty" user interface constructed from the simple console functions 
p_printf, p_getch and p_get1 (described in the PLIB Reference manual). The first call to p_printf 
automatically connects to the window server and must precede the call to wcapturekey. 


To save a screen (by default to rem::screen.pic), you task to the application and press PSION+S. 


/* 
SCAPT.C - Capture the screen to a file 
*/ 


#include <plib.h> 
#include <wlib.h> 


GLDEF_C VOID main (VOID) 


INT ret; 
TEXT name[64]; 


p_scpy (éname[0],"rem::screen.pic") ; 
p_printf("\£"); /* connect to window server */ 
wCaptureKey (W_SPECIAL_KEY|'s',0,0); 
for (77) 
{ 
p_printf("\fCapture file is\r\n%s", &name[0]); 
p_printf("\nE to Exit\r\nN to set file Name\r\nPsiont+S to capture"); 
switch (p_getch() ) 
{ 


case 'e';: 

case 'E';: 
p_exit (0); 

case 'n': 

case 'N': 
p_getl("Name:", &name[0], 64); 
break; 


case W_SPECIAL_KEY|'s': 
ret=gSaveBit (&name[0],0); 
if (ret) 
p_notifyerr(ret,"Screen save failed",0,0,0); 
break; 


} 
Capturing the screen directly to a PCX file 


It isn't that difficult to generate a PCX file directly from the screen or any other bitmap. The module 
pcxsave.c (supplied in \sdkdoc\demo) contains the code which supports the function pcxScreenSave that 
saves the entire screen in PCX format of a given name. 


The source of pcxsave.c is as follows: 
7. * 
Save the screen to PCX file 


x7: 


#include <plib.h> 
#include <wlib.h> 


#define BUFLEN 256 


GLREF_D WSERV_SPEC *wserv_channel; 


1-33 


WINDOW SERVER REFERENCE 


LOCAL_D VOID *fcb; 

LOCAL_D UBYTE *pbuf; 
LOCAL_D UBYTE *pobuf; 
LOCAL_D UBYTE obuf [BUFLEN]; 


LOCAL_C VOID FlushBuffer (VOID) 


f_write(fcb, &0buf[0],pobuf-&o0buf[0]); 
pobuf=ésobuf [0]; 


LOCAL_C VOID putb(INT b) 


*pobuf++=b; 

if (pobuf==&0buf [BUFLEN] ) 
FlushBuffer (); 

} 


LOCAL_C INT rev(INT dat) 
{ 


INT i; 
INT rdat; 
rdat=0; 
for (i=0;i<8;i++) 
rdat |=((dat>>i) &1)<<(7-i); 


return (rdat*0Oxff); 


} 


LOCAL_C VOID WritePCXLine(UBYTE *buf,UINT len) 
{ 
UBYTE *p; 
UINT end; 
UINT count; 
INT byte; 


p=buf; 
byte=*ptt; 
count=1; 
do 


{ 
end= (p==(&buf[0]+len)); 
if (byte==*p && count<0x3f && !end) 
{ 
count++; 
ptt; 
} 
else 
{ 
byte=rev (byte) ; 
if (count>1 || (byte&0xC0)==0xC0) 
putb (count+0xC0) ; 
putb (byte); 


byte=*ptt; 
count=1; 
} 

} while (!end); 


1-34 


1 INTRODUCTION 


LOCAL_C VOID WriteHeader (TEXT *name,UINT width,UINT height,UINT bytewid) 
{ 
struct 
{ 
UBYTE manuf; 
UBYTE hard; 
UBYTE encod; 
UBYTE bitpx; 
P_RECT rect; 
WORD hres; 
WORD vres; 
UBYTE clrma[48]; 
UBYTE vmode; 
UBYTE nplanes; 
WORD bplin; 
UBYTE padding[60]; 
} header; 


f_open (&fcb, name, P_FREPLACE|P_FSTREAM|P_FUPDATE) ; 
p_bfil(&header, sizeof (header) ,0); 
header.manuf=10; 

header.hard=3; 

header.encod=TRUE; 

header. bitpx=1; 
header.rect.br.x=width-1; 
header.rect.br.y=height-1; 

header. hres=640; 

header.vres=480; 

header.nplanes=1; 

header .bplin=bytewid; 
f_write(fcb, &header, sizeof (header) ) ; 


} 
#pragma save, ENTER_CALL 


LOCAL_C INT WritePCXFile (TEXT *name) 
{ 
UINT len; 
P_POINT size; 
P_POINT line; 


size=wserv_channel->conn.info.pixels; 
len=((size.x+15)>>3) &~1; 
WriteHeader (name, size.x,size.y,len); 
pbuf=f_alloc(len) ; 
line.x=0; 
for (line.y=0;line.y<size.y;line.y+tt) 
{ 
gPeekBit (0, &line, size.x,pbuf) ; 
WritePCXLine (pbuf, len) ; 
} 
FlushBuffer (); 
return (0); 


} 
#pragma restore 


GLDEF_C INT pcxScreenSave (TEXT *name) 


{ 
INT ret; 


fcb=NULL; 

pbuf=NULL; 

pobuf=s&obuf [0]; 

ret=p_enter2((VOID *)WritePCXFile, name) ; 
p_free (pbuf) ; 

p_close(fcb); 

return (ret); 


} 


1-35 


WINDOW SERVER REFERENCE 


The function writePcxFile writes the PCX header and then loops extracting lines from the screen using 
gPeekBit and converting each line to PCX format. Bytes are written to the output file as they are 
converted (by WwritePcxLine). The above code can easily be converted to extract from arbitrary areas of 
the screen or from any bitmap. 


Note the use of p_enter to implement structured error handling. 


Some of the screen shots used in this manual were captured using scapt.c (also supplied in \sibosdk\demo) 
which uses the function pexScreenSave in pcxsave.c. The source of scapt.c is: 


/* 
SCAPT.C - Capture the screen to a file 
xf 


#include <plib.h> 
#include <wlib.h> 


GLREF_D TEXT *DatCommandPtr; 
GLREF_C INT pcxScreenSave (TEXT *name) ; 


LOCAL_D WSERV_SPEC wSpec; 


GLDEF_C INT main(VOID) 


INT ret; 
TEXT *pc; 
TEXT name [P_FNAMESIZE]; 


pc=p_skipch (DatCommandPtr) +1; 
if (*pc) 
pc=p_skipwh (pct1); 
ret=p_fparse (pc, "REM: :SCREEN.PCX", &name[0],NULL) ; 
if (!ret) 
{ 
wConnect (&wSpec, 0,W_CONNECT_AT_BACK) ; 
ret=pcxScreenSave (&name[0]); 
p_sound(1,512); 
} 
return (ret); 


} 
To build scapt.img from scapt.pr, scapt.c and pcxsave.c, just enter: 
TSC/M SCAPT 


You might consider using Tscx rather than Tsc. See the Installation chapter of the General Programming 
Manual for more information. 


The program scapt.img is designed to be run on the target from MCLINK on the PC. In preparation, copy 
scapt.img to the root directory of the default drive on the target (an S3 say). To capture the screen to say 
fred.pcx in the current directory of your PC, start MCLINK and enter: 


RUN SCAPT FRED 


The target machine beeps faintly (from the call to p_souna) when the screen has been saved. If you omit 
the FRED, you get screen.pcx (from the related file name in the call to p_fparse). 


The physical structure of bitmap files and bitmaps 


Bitmap files start with a PICc_HEAD struct, defined in wlib.h as: 


typedef struct 
{ 
P_FSIG sig; 
UWORD count; 
WS_PIC_HEADER wspic; 
) PIC_HEAD; 


1-36 


1 INTRODUCTION 


The first member of this struct is a p_rstc header: 


typedef struct 
{ 
TEXT app_id[3]; /* application ID */ 
UBYTE chk_sum; /* application ID checksum */ 
UBYTE file_vn; /* file version number */ 
UBYTE app_vn; /* application version number */ 
} P_FSIG; 


where the p_Fsic struct is defined in p_file.h. For a bitmap file, the appropriate values for the p_rsic 
header are: 


P_FSIG sig = {"PIC",'PY+'I'+'C';,0n30;, 0x30}; 


The p_rstc header is followed by a worp count of the number of bitmaps in the file. This is then followed 
by an array of that many ws_PICc_HEADER structs. A ws_PIC_HEADER Struct is defined in wiib.h as follows: 


typedef struct 
{ 
UWORD checksum; 
P_POINT size; 
UWORD byte_size; 
ULONG offset; 
} WS_PIC_HEADER; 


The members of ws_Ppic_HEADER are as follows: 


checksum is calculated by applying the p_crc function (described in the PLIB Reference 
manual) to the bitmap that is referenced by the ws_p1c_HEADER struct 
(excluding all headers). 


size the pixel dimensions of the bitmap (size.x by size.y) 
byte_size the byte size of the bitmap. 
offset the relative offset from the end of this header to the start of the bitmap. 


The bitmap consists of size.y scan lines from top to bottom. Each scan line consists of an array of 
((size.x+15)/16) words describing the pixels in the scan line from left to right. The leftmost pixel in a 
scan line corresponds to the least significant bit of the first word. 


A named memory segment which contains a bitmap (created, for example, using gopenBit OF gGetBit) 
contains just the bitmap, without the ws_p1c_HEADER header. 


One example of the use of the physical bitmap structures described above is to animate the screen from a 
previously generated sequence of equally sized bitmaps from a bitmap file. After creating the bitmap 
memory segment using gOpenBit, gCreateBit OF gGetBit, the steps in the animation sequence are: 


e@ use p_read to read the bitmap from the file into a buffer 
@ use p_sgcopyto to copy the data to the bitmap segment 
@ use gCopyBit to draw the bitmap to the screen 


Since the bitmaps are stored sequentially there is no need to position the file between each p_read - you 
only have to position each time you return to the first bitmap in the sequence. 


Embedded bitmap files 


A bitmap file may be built into a program file by including its name in an add-file list. This process is 
more fully described in the Building an Application chapter of the General Programming manual. 


1-37 


WINDOW SERVER REFERENCE 


Text fonts 


A text font is a bitmap that contains up to 256 bit-images called character graphics. The character 
graphics in the font are indexed by a character code in the range 0 to 255. 


Fonts are primarily used to implement the SIBO character set in different typefaces and sizes. 


A font may also be used to implement any collection of bit-images that have the same height (as an 
alternative to using independent bitmaps). 


A text font may not contain character graphics for the whole 256 code range and within the code range 
supported there may also be "holes" for which there is no character graphic.® 


Although all the character graphics in a font are of the same height, their widths may in general vary. 
When all the characters with codes greater than 31 have the same width, the font is said to be monospaced 
(otherwise it is said to be proportional). 


The SIBO character set is compatible with the IBM code page 850 character set for character codes in the 
range 32 to 255. In some proportional fonts, the code page 850 block graphics characters (for example, 
the box drawing characters) are absent. The characters with codes less than 32 are not compatible with 
any standard and vary from font to font. 


Fast fonts 
Fast fonts are stored in an expanded form that uses more memory but can be drawn faster. 
All characters in a fast font must be less than or equal to 8 pixels wide. 


The window server automatically recognises the difference between normal and fast fonts. Window 
servers before version 3.5 do not recognise fast fonts and will refuse to load them. 


ROM-based fonts 


An application can access the ROM-based fonts by font IDs that are known at compile time. The ROM- 
based font IDs start at ws_rFonT_BASE and you can use WS_FONT_BASE+1 etc for as many fonts as are built 
into the ROM. 


The default font of a newly created graphics context, sometimes called the system font, is in most cases 
the first font in the ROM - with ID ws_FonT_BASE. 


Whenever it is expecting a font ID, the window server converts the constant ws_FoNT_SYSTEM to the 
system font (WS_FONT_SYSTEM is outside the range of possible font IDs). You can also obtain the system 
font ID directly from the system_font member of the W_SERVER_INFo struct (as described under wconnect 
in the next chapter). 


On the HC and the S3, the system font is determined by the sws_sF environment variable which should 
contain a worp binary value of 0 for ws_FonT_BASE and | for Wws_FONT_BASE+1 and so on. If you change the 
value of sws_sFr, you must reset the machine by pressing the recessed reset button to effect the change. 


In version 4 of the window server which runs on the S3a, the system fonts are determined by the sws_Fnts 
environment variable. This contains a series of words each of which contains the fonts used by the 
window server in various situations (listed in the changes section earlier). The full list is repeated below 
and is given in the correct order. 


e §=©System font 

e §=6Notifier/Alert font 

e Status Window font 

e Symbols font used for the status window diamond symbol 
e Medium 2 digital clock font 

e Medium 2 date font 

e §©Notifier/alert button font 


e Small status window clock font 


8If a client passes a character code for which there is no graphic, the graphic with the highest code is 
selected. 


1-38 


1 INTRODUCTION 


On the MC, the system font is determined in the same way except that two environment variables are used 
- sws_sF2 and sws_sr4. If the screen has fewer than 300 lines (as on the MC200), sws_sr2 is used. 
Otherwise (as on the MC400), sws_sr4 is used. 


The following program illustrates how the environment variable may be changed. 
#include <p_std.h> 


GLDEF_C INT main(VOID) 
{ 
WORD flags; 


flags=1; /* choose WS_FONT_BASE+1 */ 
return (p_setenviron("SWS_SF",6,&flags,2)); 
} 


Changing the system font may upset existing applications. 


In version 4 of the window server used on the Series 3a, fonts can be collected into what are called ‘font 
groups’. A more detailed discussion of this concept can be found in the description of gconfigureFonts in 
the Graphics Output chapter of this manual. 


Briefly, font groups are a collection of fonts with a single identity. Essentially, each font within the group 
will have been specially designed with a style or a combination of styles in mind. Where a font group is to 
be used to print text, the window server will select the best font from within this group according to 
criteria based on the style or combination of styles selected (i.e. bold, italics etc). Having selected a font 
from within the group, it may, if necessary, algorithmically apply further styles. 


The font groupings for the Series 3a and Workabout machines are summarised in the header file fonts.h, 
which also supplies a range of defined constants that can be used to identify the various ROM-based fonts. 


HC fonts 
On a standard HC, there are six ROM-based fonts: 


WS_FONT_BASE - large proportional 
(the system font). Also the system 
font on the MC400. 


Normal text (15) Bald text 
Ttale text Mang text 


ier Doble bl 


ia a =] feo i 
SS ee 


fF) 
0 
i 
A 

| 

I 
I 


| a eee . S| 


Fi 
: 
| 
f 
l 
i 
i 
i 
( 
i 


J 
oS 
fo 
t f 
a4 
C 
| 
td 
5 ft 
da 
i i 
ii 
Hf 
a 
EE 
( ¢ 
i 


aA aot oa eee eos es ee re 
_ = oe a SES S| asa 
— od 


1-39 


WINDOW SERVER REFERENCE 


<< +, «LCE Fox Po aot -Com Co 


a ot, ct a ey a Ree ee i eee | = 


1oDeset 4. = -on Coo 
| | ee ee ee | a 
olsen pn BO Eee. we LC ble et neem en toc] jalor we oe Se I --e 


Be Ef aicahe sm ne npsicias [SIE Lees lame ems ge cect tenth 


co) a pee eee OO oe EOC 


ofc eet eee Qt CoS = eS 


coCI + ee ee ee oe EO 
tt ee pes Heo Os) ---s |] SCO Dek RBG Ngee) OC 
on |e oa eee eo Dose ES oo cao Coa Ea Oe 
Oo fed 0 I a a ee ey eo]D Do oo aM oe tH a 
Cars Pes oS cee Dali sn LW mS WbeoCoeD al H LO 
oom Oo oe meee ac] PO [OD oS Seco Coe am sor 
Owl © Danese +o ee ea is od MO 
tsi O eet OR Oem coe laws] [| oO et oe Oe moe I ane CO 
wo EO at 
a: woo tee bao] JO = Soe oo eee oC Fado 


Mow eS aa ad ae ee 
vie GS Tt 


Goes) Cer oo oP ooo, or ss Le Le oT Oo er boo 00 2 oo oo La Le GN Oo ue so rh oo eT oo Le Le 


paced 


(the console font). Only used on the 


HC. 


Bold 
Mono text 


proportional. Also the system font 
on the MC200. 


monospaced. The monospaced font 
on the MC. 


Hormal text (8) Bold tex 


Italic text Mono text 


ca 
_ TI 
= 
— 
= 
= 
a 
= 
cs 
-—i 
cu 
= 
ou 
—_— 
—o 
= 
— 
coc 


Double herant Double bo] 


- 
% 
wu 
+ 
= 
—_ 
= 
o 
~~. 
—_— 
fn} 
—" 
+ 
* 
a 
_ 
a 
= 
— 
J 
= 


+ 
m 
a 

+4 
= 
= 
= 

= 

+ 
te 

au 

= 

+ 

Lome! 


WS_FONT_BASE+2 - fast monos 


= 
— 
— 
— 
=! 
— 
—— 
— 
— 
[ a | 
—" 
—— 
Semene 
<u 
—— 
—— 
—=a. 
= 
— 
ae | 


WS_FONT_BASE+3 - wide 


a 
Lion] 
bom | 
— 
+ 4+ 
Ko 
a 
a 4 
a 
m4 
=a 
Lo 
oO + 
=z 


WS_FONT_BASE+1 - small 


1-40 


1 INTRODUCTION 


WS_FONT_BASE+4 - fast proportional. 
The system font on the S3. Used to 
present alerts on the HC. 


Normal text (8) Bold text 
itelic tent Mono text 


me 
| 
ro 
Reaho oT [pe TO SB eS) ae PO 


“xs pe/ a 


Double hevdht Double bold 


Gee Deal aa 
Soop ogee 


Le ek Py BE ee oe 


=_TS 


Pee nc: Me co 


=F 
~ ES Sono OP Ge 


PRPS seo Te 


rF 
E 
¥ 
4 
tT 
d 
t 
5 
‘ 
Fi 
1 

E 
é 
"1 


TAT So oo oe ee 
IS PSE a moe 
Honk 0. PA SO Ao 

900 MO eR 
Shoe pk ee oD On ree 
“he ge De eos ee TT | 
OBES Sete oe ep oo 


2 UR Pe Te de boos Fw fos] 
"14 [ES 4 cate eta 


Ont: 
| 


Ira | 


WS_FONT_BASE+5 - fast bold 
proportional. The bold font on the 
S83. 


P= lc 
et 


Hornal text (&) Bold text 
Italic text Hono tert 


Double height Double bol 


en A ee a 
t= raw 


Osmo oo 
ei pe eee ea 


ne 
pod 
pond 
Lad 
= 


Fe es So oe 


= 
Ems Soo! Sa 


ee | SMe KS eS) ee 
‘ees we se SD 


+H BSE Se ge mE 
eT pe ee ee eto 
SS me foe SE Ge ee Se oe ee | 
tll ee ee 
‘Pe oe Ie eee eS ee | 
Sey [SS CN ee ee | 
SOCHS|4 "Oo = = ame + + 


8 
1 
2 
2 
4 
a 
6 
7 
8 
4 
A 
C 
D 
E 
F 


I Go La | 
heel a: 
& b= 
“its 


. TERRES SS ee 


The figure on the first line of each sample display gives the height of the font in pixels. Each figure 
represents a 160 pixel wide bitmap (the width of the HC screen). 


On HCs with ROM versions less than 1.50 (and which is not running version 3.5 of the window server), 
the final two fonts are absent and the console font is not "fast". 


The Ist, 2nd and 4th fonts are the MC fonts. The 5th and 6th fonts are the S3 fonts. The character set of 
the console font (the 3rd font) is consistent with the MC fonts. The S3 and MC fonts differ mainly in the 
characters for codes 0 to 31. 


$3 fonts 
On an S3, there are three ROM-based fonts: 


Hormal text (2) Bold text WS_FONT_BASE - fast proportional (system font) 
italic teat Mono tent 


Double hevdht Double bold 


Hormal text (8) pole est WS_FONT_BASE+1 - fast bold proportional 
Ttalic text Hono 


Double height Double bo] 


CH2S456789 6 O1FS456789  Ws_ronT_BasE+2 - numeric 
S12S4557S9 OLER4E67S9 


QUEER TES OL28M56 789 


1-41 


WINDOW SERVER REFERENCE 


The figure on the first line of each sample display gives the height of the font in pixels. 


On the S3, there is no monospace font as such. The proportional fonts are designed such that a reasonable 
monospace font is obtained by using the monospace style attribute c_sty_mono. 


See the last two fonts in the list of HC fonts above for the full set of characters. 
MC fonts 
On a standard MC, there are three ROM-based fonts: 


Normal text (15) Bald text Ws_FONT_BASE - proportional (MC400 system font) 
Thali text Mono text 


ier Doble bl 


Normal tere (1 1) Bold toxt WS_FONT_BASE+1 - small proportional (MC200 system font) 


Italic text Mong text 


unl heatt Double bl 


Normal text C16) Bold WS_FONT_BASE+2 - monospaced 
Ttalic text Mono text 


Double height Double 


The figure on the first line of each sample display gives the height of the font in pixels. 


See the first, second and fourth fonts in the list of HC fonts above for the full set of characters. 
$3a and Workabout fonts 


On the S3a and Workabout, thirteen ROM-based fonts are defined; the first three are Series 3 fonts, 
examples of which are shown earlier. Access to these fonts is summarised in fonts.h. 


The following figures show sample displays of the fonts with font heights given in pixels. Accompanying 
each of these displays is the corresponding set of character codes. 


Note that the sample displays are 200 pixels wide. 


WS_FONT_BASE+2 - numeric font 


O1SE456739 6 O123456-785 
Oiee4oors? CLEA 735 


OEMS TES 0128456789 


ee tee ee ae ete ae ce ce ae ae ce ae ae 


4 
q 
E 
q 
) 
7 
3 
q 
) 
q 
q 
3 
q 
q 
q 


ee te te ce ae ae ae eae ee 
Eee eee ce 
Eee eee cee cece Pe ae ce ae 
BOO ee cee cee 
BO ee ce eee ee cen) 
HOO ee ae ce ce 
Meee eee cee ce ce Pe ce ae 
Meee eee cee ce ce ace ce ge ae 
BOO ee cee cee 
BOO ee cee ce ce 
HOW ee cee 
Eee eee ce ee ce cee ee 
Eee ce ee ce ee ce ace ce ce ae 
Eee eee eee ce ace ac oo 


1-42 


1 INTRODUCTION 


Som logd-t2 rol - 
Poe eer oe SDS eS eo 


Oe Dates | oe | lel 


a et ed oe et ee SS] SS Stes 


po ke ee ee EL 
cl pt K--SsNSedi P es] bed - 


eS et ete SL St 
eae ee et ed te 
i Se ae a 


S| cor Me ey a ey TS ed se == 


ORAS Sg Sa 
Bae SP Seeder | Wak 
ISR og ee un 0 

2PLIS pA A See OR ea Il 
ee at ee ee 


2 Oe ge et 


Same tine on ceo ew 


“1 — 
ae | 
co [mete mau 
* eg 
Zz ie = 
Oo om} i_—] 
S. = | 
Q = 
= jw 
oO am —_ 
& —— 
1 —_+ 
(oa) od se 
Be a = 2 
Q oo) 
|e Co ae 
H eS a 
a r= 
pn So So 
| oo 
2 |z=-—=s 


SOO Pods - eH: 


i 


a) a Eo fee eee te I 


ee de eee tt Ee 


Oop ke tt ee eee Ee oe IER On 


oj t e eo ae or Ss] Lo 


oO ee eo LES 8: 
ee Oe ee ce 


Lae. PHOS OMS eresoalbsala oS - 


Of Me Le MC a Sl 


ee Leo aT ee ee 


of [Os Sele = co ee TM a 


TREO a eT td a 
sp tS CMO Oe ao et oe Faas 
ee de en | 


= a oe OT 
Go CO bo oP oo oo a Ld La 


point 


Double bold 


ble haaght 


WS_FONT_BASE+4 - Roman 8 


——_ 
= 
au 

——_ 

= 

= 
= 

[==] 

—, 

oo 

— 

—_ 
= 
a 

— 

a 
7m 
= 
a 
Lm 

= 


_ 

ac 

a 

—_— 

= 

= 

= 
—_—a 

~~ 

a= =e 

qu 

+ 

a 

=a 

ng 

=~ 

Lames | 


Ou 


td 


point 


WS_FONT_BASE+5 - Roman 11 


sO OO 1red-t'}e con. 
See Ge et xo Me See 7. 
I 1a ee a ae | 


Pe Le 


+ nS ee ee GY oo IF 
=. 9B-ssemie ral Cp 
oO eee Peo Else 45 +b; 
ne OO ede re I py ho 


2 Eo Bet ettitte oe 


Cet a ee ced cele to 


Fw wo fed -olet + ates 
FOR seid sos | woke 
Heros o med coe ——w eo a 


2 OM OOO a Me oo BB Eco 
=—=—00 @ oer 8.4 mes 


lit Double bol 


az 
_l 


Double he 


1-43 


WINDOW SERVER REFERENCE 


~~ OO io ast .e col. 
wwe etx eee, oe 
1 oul — — on 4 il oe ay 
an pe ee et ee ee SS] SE Ee 
+ wee ese ee G2! oe I 
«S-Ni ral be. 
PARR aoa. ba. 


po] . wo OOPS ot dc be SI 


. OE w Eee ate 
OT NA ee Pe cater Sh 
Sw wo Se ole et+ aoe 
eTrOR cee mst ] Yeo 
Henao oo ees 
NOH eS oS om ews 
eS Woo 8. BH Oe 


3 point 


WS_FONT_BASE+6 - Roman 1 


~~ Oo det, w roll. 
oN ene SS: ix ot RE ] 
|| —— = wee ee SF IW Le 
ae ON de ee ee RD Oe 
+ 40M Gl FIFO A 
x BSS) AN-o ww r Sal ea : 
Oo dn pd oe. 
_ OF we ote tty , 
OO NOL Gy Dot Sot fot Do 
SmnWo wo see ott uo om 
eto toe woes | Geo 
theo o moo oe Eo ot 
Oe eee 


6 point 


WS_FONT_BASE+7 - Roman 1 


1-44 


1 INTRODUCTION 


SOO Pods Om. SOS podatews col. So Omelet col. 


Dow oes Ce ele sea : oe ee — ee ln : eee Ce: OK oO Se 7 


ne a | lo ee |S 7 ee oe | 


oe de ee ee ee 2 oie et ed ee tee | SS SS En, ee el ee ee Oe SS = SO. 


oon ee ee Geet re (EMO + ee ee GE! oF Ie wee at ee ee oe! oo IE 
SOMO mabe pet bao. x... Nemo Ss Oe, 
a bee Te Bae Le ese le. mimo eae EE so: 

MO ea - OOH ee IS os -*# wo eM oo eo | eo 
. Ped See oabala | 2 PRE mS eo Eee ~™OS os ese Cel , 
eS OO LL De med oD st T- OO ee eS ae NEMS. Sate eC Se 
SINS wm Jageoseacb ase SMiNWS wo Sem vot®stt+ Lidge MM SMiwo ow Sep ost Loon 
eb Oo em oto | ase | Pe ero we ses | ewes] ele Bee Oe Oe oso | woe 
EO a oT SEC oon eos wo ot x IFO oo woe ot 
2 Balad ae Sosa et BE ae PE --0- ee 8 | Os NO woke OR ew on 

eS a SE es itt ToS a sss Ae 2 at ee oe ee 


Ce ee oom 
es We 0 oe Lk Se SPO com tee ew Gm OOo Loe me oo om el Oo Oo ee Ld La 


afl — 
at eT 
R= a = 
- | J = _ 
z il. 2 see 
a=| = S| mf! = a |" cL 
io) _—_e Q = on La =} 
aie = - j= a co | eo Js 
o |e ae Co — |= =| — 
2 a 2 |= —_ $ —o 
aa — | ne a(t o— 
212 = 2c o=— =. — 
' cat) (ta 
| 3 Se 5 —_ PS] 
¢ ley Ga a a + Se — 
fm PS fl ee — fal i 
Yn = —rs Yn = n oS ca 
< [4-5 < | aox m a 
a cc i es i = Be 
| = goo oe | fo La 
ee ee ee a |e ce sy —__! 
6 | ws a — 2 | 2—-o2 
o = i) : i) Soe =" 
fy Pe ie | fy a — fy 
yo jot =. y |S a oo Sas 
QO |wG 2 {== — 2 oo 


1-45 


WINDOW SERVER REFERENCE 


— | 
- + TS 
-* 


WS_FONT_BASE+11 - Swiss 16 point 


Normal text (16) Bold texl 
Raictext Mono text 


I 
aw: 
Oo-~~ 


Doubleheiant Double bold 


| 


ee ee 
“CMe Se ART + 
Peete il a a SD: 
Yo Ie Oo OO! 


Tre DD eon fw Hos 
a | 


co EG Oo ef SS Se TT Ooo 


Comb BBO. Ay = ooo 
Wom -— oom wow 


a 
Ob Zo oS mo Omuzs 


re en ee ee) 
<a 


nce | ee <= Rl a — le a 


Chgset aomec ~~“ oo 
od 


H 
I 
2 
3 
4 
5 
6 
i 
G 
J 
A 
Bf 
C 
D 
E 
F 


a 


mais 
++: 


WS_FONT_BASE+12 - monospaced 6 x 6 


MorMal] text (6) Bold text 
ftelic text Mono text 


Double height Double bold 


Tee De ee OD a = 
Gees FLEW! & +] 


eS eeceteac ee ea 

Sr ge here -- rR Te ow 
= PRP SPH Se Te tra +e ee 
~ Bits eat oo) oa, 


a RSS Ar ra ee EO tf OTD 
BPM BEBS| = 2 Gees See t+ FE Om 


ee ee ee 
eT PSE. APs ee -— 
Tote So PT = OO 

OE TE ee et 
a0 | So get oo a ees 2] 
Me TR Se oe OS te 
“Pe Toe Te ee ee eT 
- GBeelelepot-can fag oi sa | 


ee | er 


oe: 
= 
re | 


Font files 


An application can load a font from a font file by calling gopenFont (which returns a font ID if it is 
successful). 


The function gsetopenAddress may be used immediately before gopenFront to load the font from 
anywhere within the file (typically used to load a font which has been embedded into the program file). 


If another process of the same or a different application loads the same font, the font is shared and not 
reloaded. 


Font files normally have the extension .FON. 


In version 4 of the window server, an application can load an individual font from a multiple font file by 
calling gopenFont Index and specifying the relative position of the font. Like gopenFont, it too returns a 
font ID if successful. 


Multiple font files can be created by version 2.00 upwards of the font compiler and are given extensions of 
.FON, the same as for single font files. 


1-46 


1 INTRODUCTION 


Using wsfcomp 


The wsfcomp.exe program (which is placed in the \sibosdk\sys directory during installation of the core 
software) compiles a font source file (which normally has the extension .fsc) to a font file (fon). A font 
file should always be generated from a font source file by the use of wsfcomp.exe: developers should not 
attempt to generate font files directly. 


To compile mono.fsc to produce mono.fon you use: 
wsfcomp mono 


The font source file contains a header section followed by the patterns which make up the font, as in the 
following extract from the beginning of a font source file: 


*name System mono 
*special 1 
*descent 2 
*height 10 
kmaxwid 7 

*flag ascii 

*flag cp850 

*char 28 


00000000000 
00001100000 
00001100000 
01111111100 
00111111000 
10011110111 
000001100000 
000000000000 
11111111111 
00000000000 


0000000 
0000000 
0001000 
0001100 
1111110 
1111110 
0001100 
0001000 
0000000 
0000000 


0000000 
0000011 
0000011 
0010011 
0110011 
1111111 
1111111 
0110000 
0010000 
0000000 


where the keywords are as follows: 
*name The font name (maximum length 16 characters) 


*special 1 An optional statement to produce the 'special' fast font. It must come before the 
*height statement. The parameter is ignored currently but should be 1| to allow 
for future upgrades. 


*descent <n> The descent for the font. 
*height <n> The height of the font. 
*maxwid <n> Not the real maximum width, but the width of widest normal character. Used as 


the width for c_sty_mono spacing and is returned in the c_rFont_1nFo struct. 


*flag ascii Sets the flags member in the G_FonT_INFo struct. 


1-47 


WINDOW SERVER REFERENCE 


*flag cp850 
*flag bold 
*flag italic 
*flag serif 


*char <n> Skip all characters up to the specified code. Character codes follow sequentially 
until the next *char <n> statement. The character number must always be 
greater than or equal to what the character would have been. 


In version 2.00 upwards of wsfcomp.exe, multiple source files can be converted into a multiple font file by 
specifying the -L flag and creating a .flk file containing a list of .fsc files to be compiled. The output file is 
a .fon file of the same name as the .flk file. A .fh header file is also created containing a #define for the 
index value of each font built and also a #define for the number of fonts built. 


The #define for each index is built as follows: 

#define <FLK file name>_FI_<FSC file name> index_value 
The #define for the count is built as follows: 

#define <FLK file name>_COUNT count 


This version of the font compiler also supports the conversion of PCL bitmap fonts (as used by the HP 
laser jet printer) to either .fsc source files or directly to .fon files. 


To use a PCL file as source, use the -C flag. By default a .fon file is created but by using the -F flag as 
well, a .fsc file is created instead. Note that the default extension for the PCL source file is .sfp. 


Also in version 2.00 of wsfcomp, output file names can be overridden by using the -O<filename> option. 
Font information 


Given a font ID (either of a ROM-based font or of a loaded font), you can call gFont Info to obtain such 
information about the font as: 


e the name of the font and whether it corresponds to a character set 
e the lowest and highest code for which there is a graphic 


e the height of the font and how much of that height is above and below the base line (called the 
ascent and descent respectively) 


e whether the font is monospaced, the width of the character 0 (ASCII code 0x30) and the width of 
the widest character graphic 


Note that in addition to the font ID, gront Info takes as parameters the style (eg bold, double height) with 
which that font is to be printed because the width and height of a font can be changed by the style. 


The following functions are required when laying out text (for example, to word wrap): 


gTextWidth Calculates the printed width of a text string. 

gTextCount Calculates the number of characters that can be displayed in a given pixel 
width. 

wGetWidthTable Gets the font width table. 


These functions also take the font ID and the style as parameters. 
Text drawing 


A text string may be printed to a drawable (as specified by the current graphics context) using one of the 
following functions: 


gPrintText to draw text from a pixel position 

gPrintClipText to draw text clipped to a given width 

gPrintBoxText to draw text in a box with left, right or centred alignment (commonly used to 
draw flicker-free) 

gXPrintText to draw text with embellishment 

gShadowText to draw text with a shadow effect (version 4) 


1-48 


1 INTRODUCTION 


All the above functions are subject to the values of the text drawing fields in the current graphics context. 
These specify: 


the font ID 


the font style (normal, bold, underlined, inverse, double height, monospaced or italic) 


the text transfer mode (this is not used by gPrintBoxText, gXPrintText Of gShadowText) 


The font style is either c_sty_Normat (zero) for normal style or a combination of the following: 


G_STY_BOLD 


G_STY_UNDERLINE 


G_STY_INVERSE 


G_STY_DOUBLE 


G_STY_MONO 


G_STY_ITALIC 


Prior to version 4, the above styles are applied to a font algorithmically in the following way: 


G_STY_BOLD 


G_STY_UNDERLINE 


G_STY_INVERSE 


G_STY_DOUBLE 


G_STY_MONO 


G_STY_ITALIC 


Generated by "bolding" character graphics - effectively drawing it twice with a 
one pixel right shift on the second draw. This does not produce as good a result 
as designing a bold font but it saves a having to store another font. 


Where each character (including space) is drawn with a horizontal line beneath 
its graphic. See also gxprintText for a different style of underlining. 


Where the bits in the character graphics are inverted before drawing. 


To generate double height characters where each row of pixels in the graphic is 
doubled up before drawing. As with bolding, you will get a much better result 
by designing a taller font. 


To add space around the characters of a proportional font to turn it into a 
monospaced font. For this to be effective, the proportional font should be 
designed with monospacing in mind (as is the built in font on the Series 3). 


To generate a crude (but surprisingly effective) italic font by shifting the top 
half of each character across by one pixel. 


Fast text printing of a fast font only works with normal style or with just c_sty_mono. The use of any other 
style will cause text drawing to fall back to the slower algorithm. 


In version 4 upwards, use can be made of font groups as described at the beginning of the section on 
ROM-based fonts; applying a style to a font group will cause the window server to select the most 
appropriate font from within the group and might not need to use the above algorithms. 


Therefore, if a font is used with a style or combination of styles, there is no easy way of knowing whether 
a font within a font group has been used or whether a style has been algorithmically applied to a single 
font or even whether styles have been applied to a font within a font group. 


The text transfer mode (which affects gprintText and gPrintClipText) is one of: 


G_ 


TRMO 


TRMO 


TRMO 


;_TRMO 


DE_SET 


DE_REPL 


DE_CLR 


DE_INV 


where Is in the font set bits in the destination and Os do not change bits in the 
destination (used to print on to a previously cleared area). 


where Is and Os in the font overwrite the destination (used to print over 
unprepared areas). 


where Is in the font clear bits in the destination and Os do not change bits in 
the destination (used to print on to a previously set area). 


where Is in the font toggle corresponding bits in the destination and Os in the 
source pattern do not change bits in the destination (used to print over an 
existing image and may be reversed by a second application). 


1-49 


WINDOW SERVER REFERENCE 


The physical structure of font files 


The information in this section is intended to allow applications to read data from a font file. A font file 
should always be created by use of wsfcomp.exe. 


As with bitmap files, font files start with a p_rsic header: 


typedef struct 
{ 
TEXT app_id[3]; /* application ID */ 
UBYTE chk_sum; /* application ID checksum */ 
UBYTE file_vn; /* file version number */ 
UBYTE app_vn; /* application version number */ 
} P_LFSIG; 


where P_Fsic is defined in p_file.h. 

For a normal font file, the appropriate values for the p_rsic header are: 
P_FSIG sig = {"FON",'F'+'O'+'N', 0x30, 0x30}; 

For a fast font file, the appropriate values are: 
P_FSIG sig = {"FN1",'F'+'N'+'1', 0x10, 0x10}; 


The window server automatically recognises the difference between normal and fast fonts. However, 
window servers before version 3.5 do not recognise fast fonts and will refuse to load them. 


The p_rsic header is followed by the data which makes up the ws_FoNT_FILE_HEADER (not supplied in any 
\sibosdk\include header file - define your own if you need it): 


typedef struct 
{ 
P_FSIG sig; 
UWORD checksum; 
UWORD size; 
G_FONT_INFO info; 
UWORD private[10]; 
} WS_FONT_FILE_HEADER; 


The checksum is calculated by applying p_crc to the data that follows the ws_rFoNT_FILE_HEADER header 
(the character width array and the font bitmap). 


The size is the byte size remaining in the file after the size field. 
The G_FonT_INFo struct is as returned by gFont Info: 


typedef struct 
{ 

UWORD low_ch; /* lowest code in font */ 

UWORD high_ch; /* highest code in font */ 

UWORD height; /* height of font */ 

UWORD descent; /* height of bottom part of character */ 

UWORD ascent; /* height of top part of character */ 

UWORD numeric_width; /* Width of numeric character */ 

UWORD max_width; /* The width of the widest character in the font */ 

UWORD flags; 

TEXT name [FONT_NAME_LEN]; 

} G_FONT_INFO; 


The G_Font_inro struct is followed by 20 bytes of private data, written into the file by wsfcomp.exe. 
In a normal font, the ws_FoNT_FILE_HEADER is followed by: 

e an array of (high_ch-low_ch+2) worRD offsets into the font bitmap 

e the font bitmap, stored like the body of a bitmap in a bitmap file 


The font bitmap contains the characters in the font as one long string in code order. The window server 
literally bit copies the characters from this font bitmap to the drawable (the screen or a bitmap). 


1-50 


1 INTRODUCTION 


Each word in the array of offsets contains the doubled pixel offset within the font bitmap with the least 
significant bit of the word set to | if the character is missing from the font and left as 0 otherwise. The 
offset corresponding to a missing character must be that of the next existing character. An extra offset is 
stored at the end of the array containing what would have been the offset of the next character so that the 
width of a character may be calculated by subtracting its offset from the offset of the next character. 


Fast fonts are stored in an expanded form that uses more memory but can be drawn faster. In a fast font, 
the ws_FONT_FILE_HEADER Is followed by: 


e an array of 256 Byte character pixel widths (each set to between zero and 8, inclusive) 


e the font bitmap for all 256 characters (which is 256*height bytes long), stored like the body of a 
bitmap in a bitmap file 


All characters in a fast font must be less than or equal to 8 pixels wide. The font bitmap contains all 256 
characters, stored left aligned in their 8 pixel slot. Unused bits are, by convention, set to zero. 


Embedded font files 


A font file may be built into a program file by including its name in an add-file list. This process is more 
fully described in the Building an Application chapter of the General Programming manual. 


Graphics output 


Pixel coordinates 


The graphics output functions (and other functions such as window creation) operate on a drawable - 
either a window or a bitmap. In either case, you are actually drawing a two-dimensional array of pixels in 
which each pixel is either black or white. 


Version 4 of the window server can support grey as well as black. In this case you draw to a pair of two- 
dimensional arrays, referred to as the normal (or black) plane and the grey plane. 


Arrays of pixels are represented by data structures called bitmaps (whether on or off the screen) where the 
bits in the bitmap represent pixels. When a bitmap is imaged on an LCD screen, a clear bit shows as white 
and a set bit as either black or grey. 


With a mixture of black and grey, the situation is more complicated; two arrays of pixels are needed to 
display an image which means that two bitmaps are needed. When the pair of bitmaps are imaged on an 
LCD screen, what is seen depends on the corresponding bit values of both planes. This is best illustrated 
by the following diagram: 


GREY bit setting 
0 1 


0 
NORMAL 
bit 
setting 1 


Note that a bit set in the normal plane and in the corresponding position in the grey plane is seen as black. 


Internally, a bit in a bitmap is addressed by the index of the word that contains it and the position of the 
bit within that word. Externally, a bit is addressed (somewhat more usefully) by its pixel coordinates. 


When thinking of pixel coordinates, it is best to think in terms of discrete cells arranged in rows and 
columns rather than in terms of continuous Cartesian coordinate systems based on real numbers’. Pixel 
coordinates are based on a pair of integers (x,y) that identify a particular pixel by the column (x) and the 
row (y) in which it lies. 


9 Although such a view may well be appropriate at higher levels. 


1-51 


WINDOW SERVER REFERENCE 


In a bitmap or window, the top-left pixel has coordinates (0,0). The x coordinate is based on the column 
number (which increases to the right) and the y coordinate is based on the row number (which increases 
downwards). Pixel coordinates are signed and can address pixels that are outside the bitmap. 


It is often useful to address pixels that are beyond the boundaries of the bitmap. When any drawing 
operation is performed, it is clipped to the extent of the bitmap. When drawing to a window, the drawing 
operation may be clipped to much else besides the window's extent. 


There is no graphics function that draws a single pixel since this is too inefficient to be of use!9. In 
practice, pixel coordinates are used to specify: 


lines by the coordinates of the ends of the lines 


rectangles by the coordinates of the top left internal pixel and the coordinates of the 
bottom right external pixel 


When drawing a horizontal line the line includes the pixel with the lower x coordinate and excludes the 
pixel with the higher x coordinate. 


Similarly, when drawing a vertical line the line includes the pixel with the lower y coordinate and 
excludes the pixel with the higher y coordinate. 


When drawing a line in which both coordinates change, the window server turns the coordinates of the 
end pixels into a rectangle with a top-left internal pixel and a bottom-right external pixel. The line 
drawing algorithm then fills in those pixels that are intersected by a mathematical line between the 
corners of the mathematical rectangle on the boundary of those pixels that are in the rectangle. 


Surprisingly, when the rectangle has unit height or width, you get a horizontal or a vertical line 
respectively as with a zero height or width. 


There are some useful functions that operate on rectangle data structures in the Integer Conversions and 
Rectangle Functions chapter of the PLIB Reference manual. 


Rectangles can also be specified by the coordinates of the top left (internal) pixel and the width and height 
of the rectangle in pixels. 


Graphics structs 
The structs described below (defined in p_graf.h!!) are used extensively by the WLIB functions. 
The p_Pornrt struct is used to represent a pixel coordinate or a displacement: 


typedef struct 
{ 
WORD x; 
WORD y; 
} P_POINT; 


The P_RECT struct specifies a rectangular block of pixels in terms of the top-left internal pixel and the 
bottom-right external pixel: 


typedef struct 
{ 
P_POINT tl; /* top left pixel (internal) */ 
P_POINT br; /* bottom right pixel (external) */ 
} P_RECT; 


The P_EXTENT struct also specifies a rectangular block of pixels - but in terms of the top-left internal pixel 
width and height of the block in pixels: 


typedef struct 
{ 
P_POINT tl; /* top left pixel */ 
WORD width; /* width of extent */ 
WORD height; /* height of extent */ 
} P_EXTENT; 


An empty rectangle is a rectangle that has one or both of its sides zero or negative. 


101f you really must set individual pixels, you can use gClrRect on a rectangle with unit sides. 


'1 The header p_graf-h is also included by including plib.h. 


1-52 


Graphics output 


1 INTRODUCTION 


The following graphics output functions operate on the drawable that is referenced by the current 


graphics context: 


gDrawLine 
gDrawPolyLine 


gDrawBox 


gBorderRect 
gBorder 


gBorder2Rect 
gBorder2 


gDrawObject 


gClrRect 
gInvObloid 
gCopyBit 
gDrawBit 


gCopyRect 


gFillPattern 
gPrintText 
gPrintClipText 
gXPrintText 
gPrintBoxText 
gShadowText 


wDrawButton 


wDrawButton2 


to draw horizontal, vertical or angled lines 


to draw a box 


to draw a border inside a rectangle in one of a number of styles 


to draw a border inside a rectangle with a shadowed effect. Available in version 
4 only. 


to draw a scaleable graphics object inside a rectangle. Available in version 4 
only. 


to set, clear or invert a rectangle of pixels 

to invert all the pixels in a rectangle except for the four corner pixels 

to copy a rectangle from a bitmap (or a backed-up window) to a given position 
to copy a rectangle from an open bitmap file. Available in version 4 only. 


to copy a rectangle to a displaced position (only really suitable for bitmaps - 
wScrollRect should be used for windows) 


to fill a rectangle with repeated copies of a bitmap (or a backed-up window) 
to draw text from a pixel position 

to draw text that is clipped to a given width 

to draw text with embellishment 

to draw text in a box with left, right or centred alignment 

to draw text with shadow effects. Available in version 4 only. 


to draw a S3 style button (essentially a rectangle containing a text string), 
depressed or not. Available in version 3.5 of the window server, but not 
available on any version of the MC 


to draw a button in both the S3 and S3a styles. Available in version 4 only. 


Graphics output other than to the current graphics context 


There is a set of graphics output functions are not directed at the current graphics context. These 


functions are: 


wScrollRect 
wScrollWin 


wlextCursor 


wDrawTextCursor 


wEraseTextCursor 


winfoMsg 
wiInfoMsgCorner 
wSetBusyMsg 
wCancelBusyMsg 


wsCreateClock 
wsSetClock 


wsCreateClock2 


to scroll a window or a bitmap by copying a rectangle to a displaced position. 


to control the drawing of a flashing rectangular text cursor in a window. 


to display temporary text messages at the corners of the screen. Requires 
version 3.5 of the window server, but is not available on any version of the MC. 


to draw and update a S3 style clock (analog or digital) in a window. Requires 
version 3.5 of the window server, but is not available on any version of the MC. 


to draw a S3a style clock (analog or digital) in a window. Requires version 4 of 
the window server. 


1-53 


WINDOW SERVER REFERENCE 


wsEnable to control the display of a task status window. Intended primarily for the S3 but 
wsUpdate available also on the HC with version 3.5 of the window server. Not available 
wsDisable on the MC. 

wsEnableTemp 

wsDisableTemp 

wsStatusWindow to control the state of a status window and the display of modes within that 
wsSetList window. Intended for the S3a running version 4 of the window server. 
wsSelectList 

wsAlertW to access p_notify-like services but with enhanced formatting and an 
wsAlertA asynchronous version (so that an application can continue processing while 
wsAlertUpdate waiting for the user to respond). Requires version 3.5 of the window server, but 
wsAlertCancel is not available on any version of the MC. 


You can also draw to a window indirectly by attaching one or more bitmaps to it (using wSetWinBitmap) 
and then draw to the bitmaps. 


Graphics contexts 


A graphics context is a window server resource at which graphics output is directed. 
A graphics context contains the following: 
e a drawable (a window or a bitmap) that is the ultimate recipient of the graphics output 


e whether to set, clear or invert pixels when drawing lines using gDrawLine, gDrawPolyLine, 
gDrawBox, gBorderRect, gBorder, gBorder2Rect, gBorder2, wOrawButton Or wDrawButton2 


e the font, style and transfer mode to use when drawing text using gPrintText, gPrintClipText, 
gxXPrintText, gPrintBoxText, wDrawButton Of wDrawButton2 


The drawable is set once and for all when the graphics context is created. The rest of the content can be 
set up when the graphics context is created and it can also be altered subsequently using gSet cc. 


Current graphics context 


Rather than make each function take the ID of a graphics context as a parameter, the graphics output 
functions are directed to a current graphics context. 


Using a current graphics context makes sense because you typically need to call several text drawing or 
line drawing functions (all to the same graphics context) to draw something. 


When you create a graphics context, it is automatically made current. If you have created more than one 
permanent graphics context, you can set which one of them is current by calling: 


gSetGc to make the specified graphics context current and to change its value 
gSetGco just to make the specified graphics context current 

Permanent and temporary graphics contexts 

You can draw to a permanent or a temporary graphics context. 


When your program draws to more than one drawable, it is normally simpler to use a temporary graphics 
context that is created and then freed each time you draw to one of the drawables. 


A client can only create one temporary graphics context at any one time. When a temporary graphics 
context is created, it is automatically made current. If a permanent graphics context was current before a 
temporary graphics context was created, the permanent graphics context is made current when the 
temporary graphics context is freed. 


Creating a temporary graphics context is an efficient "blind" operation, which is stored in the client-side 
buffer. 


Creating a permanent graphics context 

To create a permanent graphics context for drawing to any drawable, you use: 

gCreateGC to create a permanent graphics context with specified initial values 
gCreateGC0 to create a permanent graphics context with default initial values 


A permanent graphics context is freed by calling wrree. 


1-54 


1 INTRODUCTION 


Creating a temporary graphics context 


There are six functions that create a temporary graphics context: two for drawing to any drawable and 
four for redrawing to a window. 


The two that are used for drawing to any drawable are: 

gCreateTempGC to create a temporary graphics context with specified initial values 
gCreateTempGC0 to create a temporary graphics context with default initial values 

A temporary graphics context that is created with one of the above functions is freed with grreeTempGc. 
The four that are used for redrawing to a window are: 


wBeginRedrawGC to redraw a part of the window using a temporary graphics context that is 
created and initialised with specified values 


wBeginRedrawGC0 to redraw a part of the window using a temporary graphics context that is 
created with default initial values 


wBeginRedrawWinGC to redraw the whole of the window using a temporary graphics context that is 
created and initialised with specified values 


wBeginRedrawWinGC0 to redraw the whole of the window using a temporary graphics context that is 
created with default initial values 


A temporary graphics context that is created with one of the above functions is freed with wendRedraw. 


Keyboard input 


Key press events 


A client is informed of a key press by wcetEventWait, wGetEvent OF wGetEvent Special completing with 
a WM_KEY event type. 


The wm_key event parameters are: 
e akey code 
e acode modifier that indicates what shift keys were pressed at the time 
e =arepeat count 


The key code may correspond to a code page 850 character code or, if the key does not correspond to a 
character in code page 850, a special key code (for example, w_key_uert for the left arrow key). 


For single key presses, the repeat count is 1. If a key is held down, the repeat count will normally be 
greater than |. A repeat count gets to be greater than | when the client is unable to process keys at the rate 
at which the system generates repeated keys. 


Counter intuitively, application programmers are best advised just to ignore the repeat count. 


When a user holds down a key, there is presumably some feedback on the screen of the processing of that 
key. The user will release the key when the screen image is such that enough key presses have been 
generated (think of, for example, deleting text with the BACKSPACE key or scrolling with a down arrow 
key). When the user releases the key, he or she will expect the processing to cease as soon as the key is 
released. 


This behaviour is exactly what you get by ignoring the repeat count. If you process the key count, this only 
benefits users that can anticipate the number of repeats generated by holding the key down for a given 
period (and that kind of ability is arguably only required when playing a computer game). 


Capturing keys 
Normally, the window server sends all key presses to the foreground client. 


All key presses, that is, except those that the window server processes itself (which includes keys to task 
switch and the key that pauses the foreground client). 


In much the same way as it is useful for the window server to process keys, it is sometimes useful for a 
special client to receive keys whether it has the foreground or not. Such a client can capture specific key 
presses by calling wcapturekey (and such captures can be cancelled by calling wcancelcaptureKey). 


1-55 


WINDOW SERVER REFERENCE 


Pausing the client 


If a client has called weEnablePausekey, the user can pause the client's drawing when it has the foreground 
by pressing the pause key. 


On the HC, the pause key is PSION+LEFT-ARROW and on the $3, S3a and MC, it is CTRL+S. The user 
resumes the client by pressing any key. The key press that resumes the client is not delivered to the client. 


The pause key may be disabled by calling woisablePauseKey. The pause key is disabled by default. 
Setting task keys 


From version 3.5 onwards of the window server you can call: 


wSetTaskKey to set and cancel a key which cycles the foreground task 
wCancelTaskKey 

wSetBackTaskKey to set and cancel a key which cycles the foreground task in the opposite 
wCancelBackTaskKey direction 


These task keys are in addition to the normal system task keys on the HC and MC. This feature is 
provided for the S3 and S3a (which do not have a system task key on the keyboard). 


Note that the system screen calls wset TaskKey to assign SHIFT+SYSTEM as a task key. 


Mouse input 


This section only applies when the window server is running on a machine with a pointing device (a 
digitiser or a mouse). 


Mouse icons 
The window server automatically draws a corresponding mouse icon when the pointing device is over a 
window. 


Each window is assigned a mouse icon when it is created using wcreateWindow and the mouse icon can 
subsequently be changed by calling wset window. By default, a window is created with the same mouse 
icon as its parent. Unless otherwise specified, windows tend to have the standard built-in mouse icon with 
ID w_wIN_MI_STANDaRD - the mouse icon used by the root window. 


A window can effectively have no mouse icon by giving it a built-in invisible icon with ID 
W_WIN_MI_NULL. 


The window server automatically removes the mouse icon while a window it obscures is being drawn to. 


The mouse icon is drawn such that its "hot spot" (which varies according to the icon) is over the pixel that 
is being pointed at. 


Mouse icons are handled much like bitmaps and fonts: 
e There are ROM-based mouse icons with IDs that are known at compile time. 


e You can load a mouse icon from a file by calling gopenMouseIcon (which returns an ID if 
successful). Such mouse icons may be freed when no longer required by calling wrree. 


Mouse events 


A client is informed of a mouse event (movement, press or release) by wGetEventWait or wGetEvent 
completing with a wM_MouSE event type. 


The wM_MOUSE event parameters are: 


e the window at which the mouse event is directed and the position of the mouse relative to that 
window 


e the type of the mouse event (movement, press or release) 
e the state of the mouse button and of the shift keys 


A window will not receive any mouse events at all if the w_wIn_No_mousE attribute is set (in which case 
the other mouse related attributes are ignored). 


By default, mouse movement events are not generated. If the w_w1N_MousE_pRac attribute is set, mouse 
movement events are reported when the mouse button is down. If a window has the w_wIN_MousE_MOVE 
attribute set, mouse movements are reported when the mouse button is up. 


1-56 


1 INTRODUCTION 


Capturing the mouse 


Normally, a mouse event is directed to the window that was pointed to when the event occurred. If the 
mouse has been captured by a window, a mouse event that occurs in the root window or in any of the 
capturing client's windows is directed at the capturing window or to the relevant child window of the 
capturing window. There is a mouse event parameter that indicates whether the position was inside or 
outside the window. 


Capturing is often used to limit the mouse interaction to a window system to the exclusion of others as, for 
example, in the implementation of a pull-down or a pop-up menu. 


A client can capture the mouse to a particular window by calling wcaptureMouse and release the mouse by 
calling wReleaseMouse. 


Grabbing the mouse 


The mouse can also be "grabbed" while the mouse button is pressed by setting the w_wIn_mMouSE_GRAB 
attribute on a window. The grab is automatically released when the user releases the mouse button and a 
WM_MOUSE event of type wM_MoUSE_RELEASE is sent to the grabbing window. 


Grabbing the mouse is not quite the same thing as capturing it. When the mouse is grabbed, the grabbing 
window always gets the wm_MoUSE_RELEASE event - even if it occurs over another client's window. Also, 
grab is terminated with the mouse up, but capture persists until it is relinquished. 


Input-only windows 


A window that is used for mouse input but that is never drawn to should have the w_wIN_INPUT_ONLY 
attribute set. 


Input-only windows are never visible on the screen (and they do not obscure other windows) although they 
may (and typically would) have a different mouse icon from their surroundings. 


Inactive windows 


A window tree is made inactive by setting the w_wIN_1nacTIVE attribute of the window at the head of the 
tree. 


If a mouse click occurs anywhere in a window with this flag set or in any of its descendants, a wM_ACTIVE 
event is sent to the window (rather than a ww_mousz event). A client would normally respond to a 
WM_ACTIVE event by making the window tree active again by clearing the w_wIN_1nacTIVveE attribute. 


The rubber band 


The rubber band is an input mode, controlled by the window server, for allowing the user to do one of the 
following: 


e specify a new position for a rectangle 
e specify a new position and size of a rectangle 
Rubber band mode is typically used to allow the user to move and/or resize a window. 


Once a client has entered rubber band mode, it must be completed before proceeding with any other input 
(although the user might abandon it). While in rubber band mode, the window server handles all user 
interaction with the rubber band. When the user completes the rubber band, the window server generates a 
WM_RUBBER event. 


A rubber band that is used just to move (but not resize) appears as an XORed box. The rubber band for 
resizing as well as moving appears as in the following diagram: 


1-57 


WINDOW SERVER REFERENCE 


Each of the 8 triangles may be dragged with the mouse to stretch or shrink the rubber band in the 
direction of the triangle. Releasing the mouse will leave the rubber band in its stretched state. The mouse 
icon disappears while the rubber band is being dragged. 


To move the rubber band, it should be dragged from a point inside the box but outside any of the triangles. 


The arrow keys can be used to move the rubber band in the corresponding direction. The shifted arrow 
keys can be used to resize the rubber band moving the bottom and right edges. If the CTRL shift key is also 
pressed, the affect of the arrow keys (whether shifted or not) is amplified. 


Pressing RETURN selects the current position and size of the rubber band. The window server generates a 
WM_RUBBER event giving the position and size of the rubber band and also indicating whether the rubber 
band moved and/or changed its size. 


Pressing ESC cancels the rubber band. The window server generates a WM_RUBBER event that indicates that 
the rubber band was cancelled. 


Rubber band mode is entered by the client calling wRubberBand. The parameters to wRubberBand include 
those that indicate: 


e the initial size and position of the rubber band 

e the window at which the wM_RUBBER event is directed 

e the window in which the rubber band is drawn (and therefore clipped to) 

e whether the rubber band is completed on a mouse up event 

e whether the rubber band can be resized as well as moved 

e optional limits on the size and movement of the rubber band 

¢ an optional grid snap on the allowable positions and sizes of the rubber band 


If a mouse down event occurs in a window that is set with the w_wIN_RUBBER_BAND_CAPTURE attribute, it 
and subsequent mouse and keyboard events are captured to the window server's rubber band processing 
until the rubber band mode is terminated. This first mouse click generates a WW_RUBBER_BAND_INIT event 
to which the client must respond with a call to wRubberBand. 


If when calling wRubberBand in response to a WM_RUBBER_BAND_INIT event you specify that the rubber 
band should be completed on a mouse up event, you should also set the window attribute 
W_WIN_RUBBER_BAND_COMPLETE_ON_RELEASE (this handles nasty race conditions in which the mouse up 
occurs before the call to wRubberBand). 


System start-up 


When the system starts up (for example, when you press the recessed reset button), the following happens: 


e the operating system "hand crafts" syssnuuu (null process), sys$maNc (supervisor) and sys$FsRV 
(file server) 


e the file server creates the sysswsRv (window server) process 
e the window server creates the sys$sHLuL (shell) process 
e in some cases, the window server creates the syssntFry (notifier) process 


The window server normally loads the shell and the notifier from the ROM. However, on the HC, S3, S3a 
and MC, the window server first looks for sys$SHLL.IMG and SySS$NTFY.1IMG in the root directories of the 
local devices in alphabetical order (for example, Loc: :a\, Loc::B:\ and Loc::\m on an HC). 


In some cases (such as on the S3, S3a and optionally on the HC), version 3.5 and upwards of the window 
server handles the notifier itself and does not create a notifier process. 


Using the window server's notifier on the HC 


By default on the HC, the window server runs Rom: : syssntFy. imc. If the HC is running version 3.5 of 
the window server, you can switch to the window server's notifier with the following benefits: 


e less memory is consumed by the system 


e it looks better 


1-58 


1 INTRODUCTION 


The HC can be switched to the window server's notifier with the following program: 


#include <plib.h> 
#include <wlib.h> 


LOCAL_D WSERV_SPEC wSpec; 


GLDEF_C INT main(VOID) 


INT NotifierPid; 


if ((NotifierPid=p_pidfind("SYSSNTFY.*") )>0) 
{ 
wConnect (&wSpec, 0,W_CONNECT_AT_BACK) ; 
wSystem (WSERV_FLAG_NO_NOTIFIER_REBOOT, WSERV_FLAG_NO_NOTIFIER_REBOOT) ; 
p_pterminate (NotifierPid, 0); 
wSystem (WSERV_FLAG_HOOK_NOTIFIER, WSERV_FLAG_HOOK_NOTIFIER) ; 
} 


return (0); 


} 
If syssntFy exists, the program connects to the window server and: 
e stops the window server from re-booting the notifier 
e kills the notifier process 
¢ causes the window server to hook the notifier 


On the HC, the font used by the notifier is determined by the Internal Font environment variable, sws_ir, 
which should contain a worp binary value of 0 for ws_ront_Base, | for ws_FONT_BASE+1, and so on. 


If you change the value of sws_1r, you must reset the machine by pressing the recessed reset button to 
effect the change. The height of the font should not exceed 12 pixels. 


The "factory" setting of sws_t1F is 4 (which selects the S3 font). 


In version 4 of the window server, the fonts used by the notifier are determined by the sws_Fnts 
environment variable. This contains a number of words containing the font ids used by the window server 
as described at the beginning of this chapter. 


In particular, the second word contains the ID of the notifier font while the seventh word contains the ID 
of the notifier button font. 


The $WS_FL environment variable on the HC 


On an HC with version 3.5 of the window server, the initial value of the internal parameter that is set by 
wSystem 1s loaded from the sws_ri environment variable when the window server starts. 


After setting sws_r1 to the desired worp value, you must reset the HC by pressing the recessed reset button 
to make the new value effective. 


Recall that environment variables survive a soft reset but are cleared (and loaded from a ROM 
initialisation file) on a hard reset (where the ON key is pressed at the same time as the reset button). 


The wsystem flags parameter is made up by ORing a number of bit fields of the form wsERV_FLAG_xxx 
where some of the values of xxx are!?: 


NO_NOTIFIER_REBOOT If set, the window server does not boot or re-boot the notifier. 
HOOK_NOTIFIER If set, the window server attempts to hook the notifier. 
NO_PANIC_NOTIFY If clear and the window server has successfully hooked the notifier, the window 


server notifies the user of a process that terminates abnormally with a panic or 
with a negative reason number. This flag is ignored unless the window server 
has hooked the notifier. You would set this flag to prevent the window server 
from reporting abnormal terminations when HooK_NOTIFIER Is Set. 


12See the description of wsystem for the full set and also for the application of these flags to the $3, the 
S3a and the MC. 


1-59 


WINDOW SERVER REFERENCE 


LOW_BATTERY_WARNINGS _ If set, the window server notifies the user of a low lithium or main battery. Note 
that the window server only checks for low battery when the machine is turned 
on and that the window server is only informed of the machine being switched 
on after p_setonevent (TRUE) has been called. The on-event state is FALSE after 
any reset. 


HUNG_UP If set, the window server presents a "hung up" status window if the foreground 
task is not using backed-up windows and fails to respond to redraw events. 


After a hard reset on an HC with version 3.5 of the window server, the $ws_FL environment variable does 
not exist (which is equivalent to it being zero). 


The following example program sets the $ws_FL environment variable: 


#include <plib.h> 
#include <wlib.h> 


GLDEF_C INT main(VOID) 


WORD flags; 


f lags=WSERV_FLAG_NO_NOTIFIER_REBOOT |WSERV_FLAG_HOOK_NOTIFIER 
| WSERV, FLAG LOW_BATTERY. WARNINGS |WSERV_FLAG_HUNG_UP_SW; 

return (p_setenviron("SWS_FL",6,&flags,2))j; 

} 


After running this program and resetting the HC, the window server will: 
e provide the notifier service 
e report low battery voltages 
e present a hung-up status window if an application hangs 


¢ report a process that terminates with a panic or with a negative reason number 


S3a 


In version 4, some HC features from the later releases of version 3.5 have been added to the S3a variant of 
the window server. This includes: 


e the use of the environment variable sws_rt for the initial value of the window server system flags 
(as referenced by wsystem). 


Replacing the shell on the HC 


By default, the window server runs Rom: :SyS$SHLL.1Mc. This program provides a classical command- 
driven user interface to perform such commands as copy and pir and to run programs (for example, LINK) 
in response to the program's file name being entered. 


When developing a turnkey system, it is advisable to run an alternate custom shell that provides a 
restricted end-user environment. With version 3.5 of the window server, this is particularly 
straightforward as the window server can be persuaded to take over many of the responsibilities - 
particularly the link paste services - that previously had to be provided by the shell. You simply call your 
main application sys$sHELL.1Mc and place it in the root directory of any drive. The window server will 
run the shell on system start-up and it will also re-run the shell should it terminate. 


Since any restarting EPOC system will pick up a sys$sHLL. mc (such as the debugger, for example), it is 
a good idea not to call such a program sysssHuL but to rename it when you copy it to its intended working 
destination. 


To revert to the ROM shell when using an SSD-based syss$su11, first remove the SSD and then either 
terminate the existing shell process or reset the machine. If you have placed a sys$sHLL. IMG in M:\, you 
can revert to the ROM shell by hard resetting the machine (which clears the contents of m: \ and resets the 
environment variables) or you can place an alternate syS$sHLL.1mc in an SSD drive (since the drives are 
scanned in alphabetic order). 


The following simple shell/application program terminates any sys$nTFy process and sets up the window 
server to provide the notifier service and other services (as described above) and then presents a user 
interface that reports on key presses. 


1-60 


1 INTRODUCTION 


/* 
HCSHELL.C - Sample shell for the HC 
*/- 


#include <plib.h> 
#include <wlib.h> 


GLREF_D UINT wMainGc; 
GLREF_D WSERV_SPEC wSpec; 


LOCAL_D INT FontHeight; 
LOCAL_D INT FontAscent; 


LOCAL_C VOID SetFontHeight (VOID) 


{ 
G_FONT_INFO info; 


gFontInfo (WS_FONT_SYSTEM, 0, &info) ; 
FontHeight=info.height; 
FontAscent=info.ascent; 


} 


LOCAL_C VOID CDECL PrintLine(INT line, INT align, TEXT *fmt,...) 
{ 
INT len; 
P_RECT box; 
TEXT b[80]; 


box.tl.x=4; 

box.br.x=wSpec.conn.info.pixels.x-4; 
box.tl.y=FontHeight*linet+4; 
box.br.y=box.tl.y+FontHeight; 
len=p_atob(&b[0],fmt, &fmt+1); 
gPrintBoxText (&box, FontAscent,align,0,&b[0],len); 


LOCAL_C VOID HandleKeyPress (WMSG_KEY *pk) 


PrintLine (2,G_TEXT_ALIGN_CENTRE, "code:%02x mod:%02x count:%02x", 
pk->keycode, pk->modifiers,pk->count) ; 


LOCAL_C VOID MainEventLoop (VOID) 


WS_EV event; 


SetFontHeight (); 
gBorder (W_BORD_SHADOW. D|w BORD_SHADOW_ON) ; 
PrintLine(0,G_TEXT_ALIGN_LEFT, "Free memory: %dKbytes",p_sgfree()>>6); 
for; (F<) 

{ 

wGetEventWait (&event) ; 

if (event .type==WM_KEY) 

HandleKeyPress (&event.p.key) ; 


} 


GLDEF_C INT main(VOID) 


{ 
INT NotifierPid; 


1-61 


WINDOW SERVER REFERENCE 


p_setonevent (TRUE); /* required on the HC */ 

wStartup(); 

wSystem(WSERV_FLAG_NO_NOTIFIER_REBOOT, Oxfff); 

if ((NotifierPid=p_pidfind("SYSSNTFY.*") )>0) 
p_pterminate (NotifierPid, 0); 


wSystem(WSERV_FLAG_HOOK_NOTIFIER|WSERV FLAG_LOW_BATTERY. WARNINGS |WSERV_FLAG_HUNG_UP_SW 


, 


WSERV_FLAG_HOOK_NOTIFIER|WSERV. FLAG _LOW_BATTERY. WARNINGS |WSERV_FLAG_HUNG_UP_SW) ; 
MainEventLoop() ; 


return (0); 


} 


You may prefer to use the following shell (the source may be found in \sibosdk\demo\lkshell.c) when 
using the remote debugger on the HC: 


/* 
LKSHELL.C - Just starts up the link 
xy: 


include <plib.h> 
include <wlib.h> 


LOCAL_D WSERV_SPEC wSpec; 
LOCAL_D UINT wMainGc; 
LOCAL_D UINT wMainWid; 
LOCAL_D INT FontHeight; 
LOCAL_D INT FontAscent; 


LOCAL_C VOID SetFontHeight (VOID) 
{ 
G_FONT_INFO info; 


gFontInfo (WS_FONT_SYSTEM, 0, &info) ; 
FontHeight=info.height; 
FontAscent=info.ascent; 


} 


LOCAL_C VOID CDECL PrintLine(INT line, INT align, TEXT *fmt,...) 
{ 
INT len; 
P_RECT box; 
TEXT b[80]; 


box.tl.x=4; 

box.br.x=wSpec.conn.info.pixels.x-4; 
box.tl.y=FontHeight*linet+4; 
box.br.y=box.tl.y+FontHeight; 
len=p_atob(&b[0],fmt,&fmt+1); 
gPrintBoxText (&box, FontAscent,align,0,&b[0],len); 
} 


LOCAL_C VOID MainEventLoop (VOID) 
{ 
WS_EV event; 


SetFontHeight (); 
for (3-7) 
{ 
wGetEventWait (&event) ; 
if (event .type==WM_REDRAW) 
{ 
wValidateWin (wMainWid) ; 
gBorder (W_BORD_SHADOW. D|w BORD_SHADOW_ON) ; 
PrintLine(0,G_TEXT_ALIGN_LEFT, "Free memory: %dKbytes",p_sgfree()>>6); 
} 
else if (event.type==WM_KEY && event.p.key.keycode==W_KEY_RETURN) 
wiInvalidateWin (wMainWid) ; 


1-62 


1 INTRODUCTION 


GLDEF_C VOID main(VOID) 
{ 
INT NotifierPid; 
WORD stat; 


p_setonevent (TRUE) ; 
wConnect (&wSpec, 0,W_CONNECT_PRIORITY) ; 
wSystem (WSERV_FLAG_NO_NOTIFIER_REBOOT, WSERV_FLAG_NO_NOTIFIER_REBOOT) ; 
if ((NotifierPid=p_pidfind("SYSSNTFY.*") )>0) 
{ 
p_logona (NotifierPid, éstat) 
p_pterminate (NotifierPid, 0) 
p_waitstat (&stat); 
} 


’ 
’ 


wSystem(WSERV_FLAG_HOOK_NOTIFIER|WSERV FLAG_LOW_BATTERY. WARNINGS |WSERV_FLAG_HUNG_UP_SW 


’ 


WSERV_FLAG_HOOK_NOTIFIER|WSERV. FLAG _LOW_BATTERY. WARNINGS |WSERV_FLAG_HUNG_UP_SW) ; 
if (p_pidfind("SYSSNCP.*") <0) 
p_presume (p_execc ("ROM: : LINK", NULL, 0) ); 
wMainWid=wCreateWindow(0,0,0,1); 
wsCreateClock (wMainWid, WS_CLOCK_WITH DATE|WS CLOCK_WITH_SECONDS, 104, 66,0); 
wiInitialiseWindowTree (wMainWid) ; 
wMainGc=gCreateGCO (wMainWid) ; 
MainEvent Loop () ; 
} 


To save memory, the program processes redraw messages rather than keep a backup bitmap. Pressing 
ENTER causes the "Free Memory" figure to be re-evaluated. 


There is further information on creating a replacement shell in the HC Programming Guide. 


PC EPOC 


On the PC version, the window server looks for the shell and notifier in the following directories: 
e the current directory 
e the directory that contains sysswsRv.IMG 


e the ROM 


1-63 


CHAPTER 2 


GENERAL WINDOW SERVER FUNCTIONS 


The connection to the window server 


Before you use any window server services you must connect to the window server. 


How you connect to the window server depends on whether you are using the CLIB or the PLIB C startup 
module and what machine you are running on. See the section Connecting to the window server in the 
first chapter for a full discussion. 


The CLIB C startup module opens the console device con: before calling main. On the HC, S3 and S3a, 
the console device open function connects to the window server. If you try to connect a second time, your 
program will be panicked with panic number 100. 


Provided the C startup module has not already connected the process, you may call either wstartup or 
wConnect to connect. The convenience function wStartup calls wconnect and then carries on to perform 
additional setting up that will satisfy the requirements of many applications. For a more sophisticated use 
of the window server, you would use wconnect directly. 


wStartup Connect and initialise a window 
VOID wStartup (VOID) ; 
Perform the following actions: 

e Connect to the window server using wconnect. 

e Create a window to cover the whole screen and store its ID in wMainwid. 

e Initialise wMainwid so that it is visible. 

e Create a permanent graphics context on the window and store its ID in wMainGe. 


On version 3 of the window server, the window is created with a backed-up bitmap (so that no redraws are 
required). 


The code for wstartup is effectively!: 


#include <plib.h> 
#include <wlib.h> 


#define NWS_HANDLE 0 
#define MAIN_WIN 1 


GLDEF_D WSERV_SPEC wSpec; 
GLDEF_D UINT wMainGc; 
GLDEF_D UINT wMainWid; 


!The actual code in WLIB is written in 8086 assembler. 


2-1 


WINDOW SERVER REFERENCE 


GLDEF_C VOID wStartup (VOID) 
{ 
UINT field_set; 
W_WINDATA windata; 


wConnect (&wSpec, NWS_HANDLE, W_CONNECT_PRIORITY) ; 
field_set=0; 
if ((wSpec.conn.info.version_id&WS_VERSION_MASK) !=WS_VERSION_2) 

{ 

field_set=W_WIN_BACKGROUND; 

windata.background=W_WIN_BACK_BITMAP; 

} 
wMainWid=wCreateWindow (0, field_set, &éwindata,MAIN_WIN) ; 
wiInitialiseWindowTree (wMainWid) ; 
wMainGc=gCreateGCO0 (wMainWid) ; 

} 


The created graphics context is the current graphics context and, after calling wstartup, you are ina 
position to draw to the window. If necessary, you can reference wSpec, wMainGe and wMainWid by 
including the following declarations: 


GLREF_D WSERV_SPEC wSpec; 
GLREF_D UINT wMainGc; 
GLREF_D UINT wMainWid; 


The following example is suitable for an HC, an S3 or an S3a: 


#include <plib.h> 
#include <wlib.h> 


GLREF_D UINT wMainGc; 
GLREF_D WSERV_SPEC wSpec; 


GLDEF_C INT main(VOID) 
{ 
WS_EV event; 
G_GC gc; 
P_RECT box; 
TEXT bb[32]; 


wStartup(); 
box.tl.x=box.tl.y=0; 
box.br=wSpec.conn.info.pixels; 
p_insrec (&box, 8,8); 
gBorder (W_BORD_SHADOW. D|w BORD_SHADOW_ON) ; 
gc.style=G_STY_BOLD|G_STY_DOUBLE; 
gSetGC (wMainGc, G_GC_MASK_STYLE, &gc) ; 
for (77) 
{ 
wGetEventWait (&event) ; 
if (event .type==WM_KEY) 
{ 
p_atos(&bb[0],"Key code: %d",event.p.key.keycode) ; 
gPrintBoxText (&box, box.br.y>>1,G_TEXT_ALIGN_CENTRE, 0, 
&bb[0],p_slen(&bb[0])); 


if (event.p.key.keycode==W_KEY_RETURN) 
break; 


} 


return (0); 


} 


2-2 


2 GENERAL WINDOW SERVER FUNCTIONS 


wConnect Connect to the window server 
VOID wConnect (.i.WSERV_SPEC *pwserv_spec, VOID *pnws_handle, UINT flags); 
Connect to the window server. 


The parameter flags should contain a combination of the following bit masks: 


W_CONNECT_AT_BACK Connect as a background application (the default is foreground). 
W_CONNECT_USER_FLAG The value of this flag is returned by a wclientInfo call. 
W_CONNECT_SYSTEM_MODAL Makes the client system modal. 

W_CONNECT_PRIORITY Enables the window server's process priority handling for the client. In 


version 4 of the window server, process priority handling can be both 
enabled and disabled by a suitable call to wsetPriorityControl. 


W_CONNECT_DISABLE_LEAVES If set, the window server will return negative error numbers rather than call 
p_leave. Equivalent to calling woisableLeaves (TRUE) except that it also 
affects whether wconnect itself leaves or returns an error. 


The parameter pnws_hand1le is a handle that the window server will use in events sent to the client that 
are not directed at a window (for example, key events). 


The parameter pwserv_spec is the address of a wszRV_spPEc struct that must be maintained for the 
duration of the connection (it holds information used by WLIB functions). The wszrv_spec struct is 
typically implemented as a static variable or as allocated memory. 


The wserv_spPeEc struct is defined as: 


typedef struct 
{ 
UWORD handle_check; /* used internally */ 
CONNECT_INFO conn; 
Fi /* used internally */ 
} WSERV_SPEC; 


typedef struct 
{ 
UWORD client_handle; /* used internally */ 
W_SERVER_INFO info; 
} CONNECT_INFO; 


where wConnect writes information useful to the client in the connEcT_1NFo sub-struct conn (the only part 
of wsERv_spxc that should be accessed by the client). 


The w_SERVER_INFO Struct is defined as: 


typedef struct 
{ 
P_POINT pixels; /* display size */ 
UWORD width_1000_pixels_mm; /* width of 1000 pixels in mm */ 
UWORD height_1000_pixels_mm; 
UBYTE set_is_dark; /* TRUE if set pixels are dark */ 
UBYTE version_id; /* machine type and window server version */ 
UWORD system_font_handle /* ID of default font */ 

cece /* extra space for future expansion */ 

} W_SERVER_INFO; 


where: 

pixels the size of the screen in pixels (pixels.x wide by pixels.y high). 

width_1000_pixels_mm the width and height (in millimetres) of 1000 screen pixels for applications 

height_1000_pixels_mm that wish to draw objects of a certain physical size or to correct for the pixel 
aspect ratio. Note that, for the Series 3 (but not for other machines, 
including the Series 3a) these two values are not reliable. 

set_is_dark TRUE if a set bit appears dark on the display (as on an LCD display) and 


FALSE otherwise (as for a CRT display). An application can invert drawings 
according to this flag so that they appear the same on both types of display. 
(Not reliable on a PC version of the window server.) 


WINDOW SERVER REFERENCE 


version_id the machine type and window server version number. 
version_id|WS_TYPE_MASK is one of WS_TYPE_MC, WS_TYPE_HC, WS_TYPE_S3, 
WS_TYPE_S3A or WS_TYPE_S3c depending on whether the machine is an MC, 
HC, S3, S3a or Workabout. The value of version_id|WS_VERSION_MASK is 
WS_VERSION_2, WS_VERSION_3 Of WS_VERSION_4 depending on whether a 
connection was made to version 2, version 3 or version 4 of the window 
server. In this context, version 3.5 is grouped with version 3. 


system_font_id the ID of the default font that you get when you create a graphics context. 
(Alternatively, you can use WS_FONT_SYSTE™ to specify the system font.) 


Note that any application running on the S3a in S3 compatibility mode will find that the version_id is set 
to WS_TYPE_S3A|WS_VERSION_4. In a similar situation, an application running on the Workabout will have 
version_id Set to WS_TYPE_S3C|WS_VERSION_4. Therefore, the window server is not providing a 
completely identical interface to such applications. 


Whether wconnect was called directly or indirectly, the address of the wsERV_sPEc variable which was 
passed is recorded in the reserved static wserv_channel. This can be used in general purpose code to 
obtain the above information. For example: 


GLREF_D WSERV_SPEC *wserv_channel; 
LOCAL_D P_POINT ScreenSize; 


ScreenSize=wserv_channel->conn.info.pixels; 


The following example program (which requires the PLIB C startup module) illustrates the use of 
wConnect to connect to the window server. 


#include <plib.h> 
#include <wlib.h> 


#define WBORDER 8 


GLDEF_D WSERV_SPEC wspec; 
GLDEF_D UINT wid; 
GLDEF_D WMSG_KEY key; 


GLDEF_C VOID CreateWindow (VOID) 
{ 
UINT border; 
W_WINDATA windata; 


windata.flags=W_WIN_NO_REDRAW; 
windata.background=W_WIN_BACK_SET; 


border=wCreat eWindow (0, W_WIN_NO_REDRAW|W_WIN_BACKGROUND, &windata, 2) ; 
windata.extent.t1.x=WBORDER; 

windata.extent.t1.y=WBORDER; 

windata.extent .width=wspec.conn.info.pixels.x-(2*WBORDER) ; 
windata.extent .height=wspec.conn.info.pixels.y-(2*WBORDER) ; 
windata.background=W_WIN_BACK_NONE; 

wid=wCreat eWindow (border, W_WIN_EXTENT |W_WIN_BACKGROUND, &windata, 1) ; 
wiInitialiseWindowTree (border) ; 


} 


GLDEF_C INT main(VOID) 
{ 
WS_EV event; 
G_GC gc; 
P_RECT box; 
TEXT bb[32]; 


wConnect (&wspec, 0,W_CONNECT_PRIORITY) ; 
CreateWindow(); 

box.tl.x=box.tl.y=0; 
box.br.x=wspec.conn.info.pixels.x-(2*WBORDER) 
box.br.y=wspec.conn.info.pixels.y-(2*WBORDER) 


’ 
’ 


2-4 


2 GENERAL WINDOW SERVER FUNCTIONS 


for (77) 

{ 

wGetEventWait (&event) ; 

if (event .type==WM_REDRAW) 
{ 
gc.style=G_STY_BOLD|G_STY_DOUBLE; 
wBeginRedrawWinGC (wid, G_GC_MASK_STYLE, &gc) ; 
p_atos(&bb[0],"Key code: %d",key.keycode) ; 


gPrintBoxText (&box, box.br.y>>1,G_TEXT_ALIGN_CENTRE, 0, &bb[0],p_slen(&bb[0])); 

wEndRedraw(); 
} 

if (event .type==WM_KEY) 
{ 
key=event.p.key; 
if (key. keycode==W_KEY_RETURN) 

break; 

wiInvalidateWin (wid) ; 
} 

} 

return (0); 


} 


The function creat eWindow sets up a two-window parent-child system where the parent implements a 
thick border and all drawing is done to the child window. The main function contains an event loop that 
handles redraw events and key events to display the code of the last key pressed. Note the use of 
wInvalidatewin to update the screen on receipt of a key event by forcing a redraw. 


The true screen and pixel dimensions of the various LCD screens are as follows: 


Machine Screen Pixel Pixel Screen Screen 

type (pixels) pitch (mm) size (mm) size (cm) size (in) 
HC 160x80 0.34x0.43 0.31x0.40 5.44x3.44 2.14x1.35 
S3 240x80 0.385x0.43 0.355x0.40 9.24x3.44 3.64x1.35 
Workabout 240x100 0.26x0.30 0.23x0.27 6.24x3.00 2.45x1.18 
S3a 480x160 0.259x0.259 0.20x0.20 12.477x4.156  4.915x1.637 
MC200 640x200 0.33x0.33 0.30x0.30 21.12x6.60 8.31x2.60 
MC400 640x400 0.33x0.33 0.30x0.30 21.12x13.20 8.31x5.20 


In the above table, the horizontal measure is shown before the vertical measure. The pixel pitch measures 
the horizontal and vertical distance between the same points on adjacent pixels. The difference between 
the pixel size and the pixel pitch gives the gap between pixels. 


wDisconnect Disconnect from the window server 


VOID wDisconnect (VOID) ; 


Disconnect from the window server and free resources within the client process and within the window 
server. 


A client is automatically disconnected if it terminates. 


wFlush Flush buffered commands 


VOID wFlush (VOID); 


Flush any contents of the client-side buffer. This will ensure that the window server has received and 
executed all previous functions. 


Note that wr1lush does not report any errors that occur in the processing of the client-side buffer. The 
function wcheckPoint (described below) flushes the buffer and reports errors. 


The client-side buffer is automatically flushed when: 
e the buffer is about to overflow 


e the client calls a function that returns a value that requires the window server process to run (for 
example wcreateWindow returns the ID of the window it creates). The functions grextwidth, 
gTextCount, gFont Info and wCheckBitmapid do not flush the client-side buffer because they are 
implemented by code that runs in the client's process. 


e = the client calls weetEventWait, wGetEvent OF wGetEvent Special 


Most applications don't need to call wriush and calling wriush unnecessarily will degrade performance. 


2-5 


WINDOW SERVER REFERENCE 


Programs that perform animation or that respond to an event source other than the window server (such 
as a serial I/O device) may need to use wFlush. For example, the following code, intended to produce 
some animation: 


gClrRect (prect,G_TRMODE_INV); /* invert a rectangle */ 
p_sleep(5L); /* pause for half a second */ 
gClrRect (prect,G_TRMODE_INV); /* invert it back again */ 


does not have the intended effect. The code should be as follows: 


gClrRect (prect, G_TRMODE_INV) ; 
wF lush () ; 

p_sleep(5L); 

gClrRect (prect, G_TRMODE_INV) ; 


When debugging a program, it can be useful to insert calls to wFlush (which are removed subsequently) to 
force the screen to be updated. 


Series 3 compatibility modes 


Both the Series 3a and the Workabout can be set to operate in Series 3 compatibility mode. The 
motivation for this is to be able to emulate Series 3 graphics, so that unmodified Series 3 applications can 
run on either machine. Naturally, grey is not available to any application running in Series 3 compatibility 
mode. 


On the Series 3a, the compatibility mode is implemented by allowing all Window Server graphics 
commands to draw with double size pixels. Because the Series 3a's screen has 480 x 160 pixels, compared 
to the Series 3's 240 x 80 pixels, doubling up the pixels on the Series 3a screen gives the 'look' and ‘feel’ of 
the Series 3 screen for Series 3 applications running on the Series 3a. 


On the Workabout, with its 240 x 100 screen, full Series 3 compatibility is implemented by restricting 
drawing to a 240 x 80 region, centred on the screen, leaving ten rows of pixels unused at both the top and 
bottom of the screen. 


The Workabout has a second compatibility mode that, while not allowing the use of grey, allows an 
application to draw to the full 240 x 100 extent of the screen. This mode can only be used with a Series 3 
application that is written in such a way that it can adjust the sizes of its windows according to the screen 
dimensions of the machine on which it is running. It is recommended that this mode be used only if the 
appearance of a Series 3 application running in full Series 3 compatibility mode on the Workabout is truly 
unacceptable. 


Drawing with double size pixels is a feature that is available in version 4 of the window server. As well as 
being used for compatibility mode on the Series 3a, it can be set for individual windows; see the Windows 
chapter for further information. 


The following two functions relate to compatibility mode. 


wCompatibilityMode Set or cancel compatibility mode 
VOID wCompatibilityMode(UINT flags,.i.WSERV_SPEC *pwspec) ; 
On the S3a and Workabout, full S3 compatibility mode is turned on by setting flags to W_CTBY_S3. 


On the Workabout, the S3 compatibility mode that allows use of the full 240 x 100 extent of the screen is 
turned on by setting flags to W_CTBY_S3_SCR. 


On both machines, Series 3 compatibility is turned off by setting flags to zero. 


The pwspec parameter must point to the same WSERV_SPEC structure that was passed to the wconnect 
function (see earlier in this chapter). wcompat ibiltyMode modifies information such as the screen 
dimensions, held in this structure. 


2-6 


2 GENERAL WINDOW SERVER FUNCTIONS 


winquireCompatibility Inquire state of compatibility flags 
UINT wInquireCompatibility (VOID) ; 


The function returns the current state of the compatibility flags of the calling client. The flags are the 
same as set by the function wcompatibilityMode. 


Error handling 


wCleanUp Return to defined state 
VOID wCleanUP (VOID) ; 
Put the window server back into a defined state by: 

e freeing the temporary Graphics Context if it exists 

e ending the redraw if one was in progress 


If there is a current graphics context that is attached to a window, wcleanup also invalidates that window - 
so that it is not left in a partly drawn state. 


The function wcleanup is typically called in response to a p_leave. 


wCheckPoint Check for an error 
INT wCheckPoint (VOID) ; 
Flush the client-side buffer (as for wriush) and return zero if there was no error. 


If there is an uncleared error or if an error occurred in the processing of the buffer, call p_leave (err) or 
return err, depending on whether woisableLeaves has been called, where err is the negative error 
number. 


wDisableLeaves Disable/enable leaves 


UINT wDisableLeaves(UINT flag); 


If £1ag is TRUE, the window server functions will (for the calling client) return an error code rather than 
call p_leave when they encounter an error. If f1ag 1s FALSE, enable p_leaves. 


Returns the previous value of £1ag (not before version 3.5). 
By default, the window server functions that can fail call p_1eave when an error occurs. 


Not available in version 2 of the window server. 


Priority changing 


The window server will not change a client's process priority unless the client has priority control 
enabled. 


Priority control is enabled if the client sets the w_conNEcT_PRIorRITY flag when it connects to the window 
server or, if running version 4 of the window server, the client calls wsetPriorityControl (TRUE). 


Priorities are set as follows: 
e when a client loses the foreground or calls wstartCompute, its priority is set to E_PRIORITY_BACK 


e when a client gains the foreground and is not in compute mode, its priority is set to the higher 
priority E_PRIORITY_FORE 


A client with priority control enabled should not change its own priority. 


2-7 


WINDOW SERVER REFERENCE 


wSetPriorityControl Set process priority handling on or off 
INT wSetPriorityControl(UINT state); 


Introduced in version 4 of the window server, this function enables and disables process priority handling 
for a client. Setting state to TRUE enables it, while setting state to FALSE disables it. 


The function always returns 0. 


wStartCompute Enter compute mode 
VOID wStartCompute (VOID) ; 


Mark the client as being in compute mode, setting the caller's process priority to E_PRIORITY_BACK 
regardless of whether it has the foreground or not. 


Should be called before performing a computationally intensive task. 


Has no effect unless the client has priority control enabled. 


wEndCompute Leave compute mode 
VOID wEndCompute (VOID) ; 

The caller is marked as not being in compute mode. 

Its priority will be set to E_PRIORITY_FORE whenever it is foreground. 


Has no effect unless the client has priority control enabled. 


General client functions 


wClientinfo Get information about a client 


INT wClientInfo(UINT pid); 
Return a word mask giving information about the window server client with process ID pia. 


If pia is a client of the window server, the function returns a bit mask that contains the following bit 
fields: 


W_CONNECT_CONNECTED this is set 
W_CONNECT_USER_FLAG if set, the W_CONNECT_USER_FLAG was specified at connect time 
W_CONNECT_SYSTEM_MODAL if set, the W_coNNECT_SYSTEM_MopAL flag was specified at connect time or 


the client is in a system modal state as a result of calling wSystemModal 
W_CONNECT_PRIORITY if set, priority control is enabled. 


If pid is not a client of the window server, the function calls p_leave (E_FILE_NXIST) or returns 
E_FILE_NXxIST, depending on whether wDisableLeaves has been called. 


On version 2 of the window server, the function returns zero if pid is not a client of the window server. 


wClientPosition Position client in task order 
VOID wClientPosition(UINT pos, UINT pid); 


Position client pid to position pos in the task order, zero being at the front and any value greater than the 
number of connected tasks being at the back. 


The constant WS_LAST_CLIENT_POSITION is provided to position a client at the back. 
Passing a pid of zero is equivalent to passing the pid of the caller. 


On a large screen version of the window server such as the MC, if the client pia is marked as iconised and 
it is positioned to the front by a call to wclientPosition, it will be sent a WM_DEICONISE event. 


2 GENERAL WINDOW SERVER FUNCTIONS 


wClientlconised Mark client as iconised 
VOID wClientIconised(UINT state); 
Mark the caller as iconised if state is TRUE, Otherwise mark it as deiconised. 


This function only applies to large screen version of the window server such as the MC (and is not 
available on hand-held machines such as the HC, $3, S3a and Workabout). 


On an MC, if the user holds down the CONTROL key while pressing the TASK key, iconised task are 
skipped and only non-iconised tasks are selected. 


If a client is marked as iconised, the window server generates a wM_DEICONISE event to client pid if 
wClientPosition (pid, 0) is called (normally by another client) to make client pia the foreground client. 
The wM_DEICONISE event would normally prompt the client to deiconise itself. 


On the MC, the window server recognises the shell (with process name sys$shll) and sends it a 
WM_DEICONISE event when the PSION+TASK key is pressed while the shell is iconised. 


wSystemModal Make client system modal 
VOID wSystemModal (UINT pos); 
Make the caller system modal and place it at position pos in the task list. 


The window server limits task switching to only those processes that have a lower client position than the 
frontmost system modal task. If there are no clients with a lower client position, the system modal task is 
locked into the foreground. 


When wSystemModal is used, pos is commonly zero - to lock the client to the foreground. 
Not available in version 2 of the window server. 


It is important to note that calling this function does not prevent a task from being made foreground. For 
example, a user pressing ENTER on a task in the system screen will cause that task to be made foreground. 


To handle an attempt to bring an application into foreground, it must test for a ww_FoREGROUND event. In 
response to this event, the application can call wcLientPosition to return itself to background. 


wCancelSystemModal Cancel system modal state 
VOID wCancelSystemModal(UINT pos); 
Cancel the caller's system modal state and place it at position pos in the task list. 


Not available in version 2 of the window server. 


wEnablePauseKey Enable pause key 
VOID wEnablePauseKey (VOID) 

Allow the user to pause the calling client's graphics output when it has the foreground. 

Useful, for example, to stop information scrolling off the top of a display. 


On the HC, the pause key is PSION+LEFT-ARROW and on the $3, S3a, Workabout and MC, it is CTRL+S. 
The user resumes the client by pressing any key. The key press that resumes the client is not delivered to 
the client. 


The pause key may be disabled by calling woisablePauseKey. 
The pause key is disabled by default, except in Console applications, where it is enabled by default. 


When the user presses the pause key, the client will be stalled within a window server function and can 
not therefore process any events that occur in the meantime. Applications that redraw their windows or 
that respond to events other than the window server (such as the receipt of data from the serial port) 
should not enable the pause key. 


Not available in version 2 of the window server. 


2-9 


WINDOW SERVER REFERENCE 


wDisablePauseKey Disable pause key 
VOID wDisablePauseKey (VOID) ; 

Disable pause key processing for the calling client. 

The pause key is enabled by calling wEnablePauseKey. 


Not available in version 2 of the window server. 


wGetProcessList Get client list 
VOID wGetProcessList (UWORD *pbuf) ; 


Write the process IDs of the clients of the window server as a zero terminated list in front to back order to 
pbuf. 


There should be at least ws_max_cLIENTS+1 words of memory at pbuf. 


Not available in versions prior to version 3.5 of the window server. 


Screen-based output 


When using the window server, graphics output can be directed at: 
e a graphics context (as described in the Graphics Output chapter) 
e a particular window (as described in the Windows chapter) 
e the screen as a whole (as described next) 


On the HC, the font used for output that is not graphics context directed is determined by the sws_iF 
("Internal Font") environment variable. 


This should contain a worp binary value of 0 for ws_ronT_BasE and | for Wws_FoNT_BASE+1 and so on. If 
you change the value of sws_1Fr, you must reset the machine by pressing the recessed reset button to effect 
the change. 


The "factory" setting of sws_1F is 4 (which selects the S3 font). 


In version 4 of the window server, the environment variable $ws_FNTs is used to contain the indices of the 
fonts to be used by the window server for notifies, clocks and so on. 


In order, they are: 
e System font 
e §=6Notifier/Alert font 
e Status Window font 
e Symbols font used for the status window diamond symbol 
e Medium 2 digital clock font 
e Medium 2 date font 
e §=Notifier/alert button font 


e Small status window clock font 


2-10 


2 GENERAL WINDOW SERVER FUNCTIONS 


winfoMsgCorner Present an information message 
INT wiInfoMsgCorner (TEXT *pmsg,UINT corner) ; 
Displays the zero terminated string pmsg for 2 to 2.5 seconds or until cancelled. 


The message is displayed in one of the four corners of the screen depending on corner, which should be 
one of: 


W_CORNER_TOP_LEFT to display pmsg in the top left corner 
W_CORNER_TOP_RIGHT to display pmsg in the top right corner 
W_CORNER_BOTTOM_LEFT to display pmsg in the bottom left corner 
W_CORNER_BOTTOM_RIGHT to display pmsg in the bottom right corner 


The length of pmsg (excluding its zero terminator) should be less than or equal to w_INFO_MSG_MAX_LEN 
(64) bytes. A longer pmsg is truncated. 


The message display is cancelled when: 


e the calling client loses the foreground (the message is never displayed if the caller is a 
background client) 


e wiInfoMsgCorner OF wInfoMsg is called again 
e the message is explicitly cancelled by calling winfomMsg (NULL) Of wInfoMsg("") 


The function behaves as for wcheckPoint in that it flushes the client-side buffer and reports any uncleared 
error - either by calling p_ieave or by returning the error number. 


winfoMsg Present an information message 


INT wiInfoMsg(TEXT *pmsg) ; 


Displays the zero terminated string pmsg in the bottom right hand corner of the screen for 2 to 2.5 seconds 
or until cancelled. 


Behaves as for wInfoMsgCorner (&msg, W_CORNER_BOTTOM_RIGHT). 


wSetBusyMsg Present a flashing busy message 


INT wSetBusyMsg(TEXT *pmsg,UINT corner_delay) ; 


Displays the zero terminated string pmsg as a flashing "busy" message in the specified corner of the 
screen. 


The message continues to display whenever the caller has the foreground. 
The message is cancelled by calling wcancelBusyMsg, wSetBusyMsg (NULL) Of wSetBusyMsg(""). 


The parameter corner_delay specifies both the corner of the screen in which the message will appear and 
a delay to stop the message from appearing instantly. The delay is used to stop the message from 
appearing at all when there is the possibility that the task can be completed in a short time. 


The time delay should be ored in with the corner mask, which should be one of: 


W_CORNER_TOP_LEFT to display pmsg in the top left corner 
W_CORNER_TOP_RIGHT to display pmsg in the top right corner 
W_CORNER_BOTTOM_LEFT to display pmsg in the bottom left corner 
W_CORNER_BOTTOM_RIGHT to display pmsg in the bottom right corner 


The delay is specified in half seconds. For example: 
wSetBusyMsg ("Saving",W_CORNER_TOP_LEFT | 6); 


will display the message in the top left corner after 3 seconds if it has not been cancelled before the time is 
up. 


The delay can range from 0 to 63 half seconds, inclusive. 


2-11 


WINDOW SERVER REFERENCE 


The length of pmsg (excluding its zero terminator) should be less than or equal to w_BUSY_MSG_MAX_LEN 
(20) bytes. A longer pmsg is truncated. 


The function behaves as for wcheckPoint in that it flushes the client-side buffer and reports any uncleared 
error - either by calling p_leave or by returning the error number. 


While the window server is loading a large bitmap or font (gopenBit or gOpenFont) or saving a large 
bitmap (gSaveBit), it doesn't maintain the busy message. In these cases, the busy message will not flash 
and it might not even appear. 


wCancelBusyMsg Cancel a flashing busy message 


INT wCancelBusyMsg (VOID) ; 
Cancel a busy message. 


Entirely equivalent to wSetBusyMsg (NULL). 


Alerts 


The functions that support alerts are available on S3, S3a and Workabout machines - and on HC 
machines that are running version 3.5 or later of the window server. 


Alerts present a p_notify-like display where the user is presented with a message and prompted to 
respond by pressing a button. Unless you are already familiar with the notifier services, you may find it 
useful to read the Notifier Services section of the Error Handling chapter in the PLIB Reference manual. 


Alerts extend the specification of p_notify as follows: 


e the maximum number of message lines is increased from 2 to 3. In version 4 of the window 
server, the maximum number is increased to 4 (provided the screen is large enough to display 
four lines of text in an alert) 


e message lines may be centred or placed at a specified horizontal position 


e rather than specify the address of a text string, it is possible to specify built in text strings by 
number (the same text strings that are obtained using p_gettext) 


e an asynchronous function is also provided so that the calling program can perform other tasks 
while waiting for the user to respond 


The alert functions are: 


wsAlertW presents the user with a message and waits for a response. This function is 
similar in effect to p_notify. 


wsAlertA is the asynchronous form of wsAlertw. Using this, the program can perform 
other tasks while waiting for the user to respond. There is no asynchronous 
form of p_notify. 


wsAlertUpdate is used to update a pending alert (which was launched using wsAlerta). 
For example, the program: 


#include <plib.h> 
#include <wlib.h> 


LOCAL_D WSERV_SPEC wSpec; 


GLDEF_C INT main(VOID) 
{ 
wConnect (&wSpec, 0,W_CONNECT_PRIORITY) ; 
wsAlertW (WS_ALERT_CLIENT, "Hello World",NULL, NULL) ; 
return (0); 


} 


2-12 


2 GENERAL WINDOW SERVER FUNCTIONS 


when compiled and linked to produce a program with the name sample.img, presents the following 
display on the HC. 


Hello World 


Continue 
Esc 


From top to bottom, the display consists of 3 parts: 


Title Displays the program name. If the reserved static patstatusNamePtr contains 
other than NULL, it is assumed to point to a zero terminated string which is 
taken as the program name (of up to 8 characters in length and stopping when 
a'.' is reached). If patstatusNamePtr iS NULL (which it will be if not explicitly 
set), the process name is used. The process name is normally the name of the 
executable and, for a single source file program, the name of the executable is 
normally the name of the source file so you can deduce that the above example 
had the file name sample.c. On the S3, the title area also contains the date and 


time. 
Message The message area contains up to 3 lines of text. 
Buttons The button area contains one, two or three buttons. 


On the S3a, running version 4 of the window server, the display is slightly different. Using the above 
code results in the following: 


Sample 
Hello World 


Continue 


On the Workabout, the appearance is as follows: 


Sample 


Hello World 


Continue 


If there is a single button, it is activated by Esc. With two buttons, the left button is activated by Esc and 
the right button is activated by ENTER. With three buttons, the buttons are activated by, from left to right, 
ESC, SPACE and ENTER. 


Version 3.5 of the window server added the ability to provide the notifier services (accessed via p_notify 
and p_notifyerr). In EPOC terminology, the window server is said to "hook the notifier". 


On the S3, S3a and Workabout, the window server always hooks the notifier. 


WINDOW SERVER REFERENCE 


On an HC, version 3.5 the window server does not by default hook the notifier (for backward compatibility 
with version 3 of the window server). However, an HC may be configured such that the window server 
does hook the notifier - as described in the section System start-up in the first chapter. 


If you remove the first parameter from wsAlertw or the first two parameters from wsAlerta, the remaining 
parameters correspond to the 5 parameters to p_notify. 


If the window server has hooked the notifier, the program: 


#include <plib.h> 


GLDEF_C INT main(VOID) 
{ 
p_notify ("Hello World",NULL,NULL, NULL, NULL) ; 
return (0); 


} 


produces the same result as the above example using wsAlertw - visually at least (and assuming that the 
program is still called sample.img). 


However, there are differences between wsAlertW and p_notify: 


e = The alert presented by p_not ify is system modal - the user can't task away from it. In contrast, 
wsAlertw is not system modal. For example, if a program reports a "No system memory" error 
using wsAlertw, it can reasonably include a "Retry" option because it is possible to task to 
another process and release memory (say by exiting a task) before returning to the alert and 
selecting the Retry button. 


e =6The caller of p_notify need not be a client of the window server. 


e = When p_notify is called, the alert is presented regardless of whether the calling client is 
foreground or not (although calling p_not ify does not displace the foreground client). If a 
background client calls wsAlertw, the alert is not drawn until that task is made foreground. In 
some circumstances, it may be desirable to call wclientPosition(0,0) and then wrlush to make 
the caller foreground before calling wsAlertw. 


e As well as having an extra leading parameter, wsAlertw has a stack-based calling convention 
which is prototyped in such a way that unnecessary trailing NULLs may be omitted whereas 
p_notify uses a register calling convention that requires all 5 parameters to be present. 


The similarities between p_notify and wsAlertw are: 


e In terms of setting up the display, all the features of wsAlertw are also available via p_notify 
and vice versa. (Unfortunately, this means that the additional parameters associated with the 
increased functionality have been squeezed into the existing p_notify compatible parameters in a 
somewhat inelegant way.) 


e =They are both designed not to fail when there is no free system memory. Both are ideal for 
reliably reporting errors - including a "No System Memory" error. 


The extra parameters are provided by passing data structures that are differentiated from a zero terminated 
string by a leading zero. It follows that zero length strings should not be used as parameters to any of the 
alert-based functions (they should be converted to NULLS). 


Calling an alert-based function does not flush the client-side buffer. 


On the HC, the font used to present alerts is determined by the sws_ir environment variable - as described 
earlier. 


wsAlertW Present and wait for an alert 
INT wsAlertW(INT mode, TEXT *pT1, TEXT *pT2, TEXT *pOl, TEXT *p02, TEXT *p0O3); 


Present a p_notify-like display where the user is presented with a message and prompted to respond by 
pressing a button. As with p_notify, the function waits for the user to respond and returns the index (in 
the range 0 to 2) of the button pressed. 


When called from a regular application, the mode parameter should be ws_ALERT_CLIENT. Other values can 
only be used by a special "alarm server" client. (The alarm server is a system component on the S3 and 
S3a.) 


Except for the additional mode parameter and except for the behavioural differences noted above, this 
function provides the same services as p_notify - as described in the PLIB Reference manual. 


2-14 


2 GENERAL WINDOW SERVER FUNCTIONS 


The following describes only the extensions to the functionality normally provided by p_notify. 
Note that wsAlertw is actually prototyped as: 
INT CDECL wsAlertW(INT, TEXT *,TEXT *,TEXT *,...); 


so that you can leave out trailing nuLLs when it is appropriate to do so. The compiler will complain if you 
leave out trailing nuLLs in a call to p_notify (because p_notify uses a register calling convention which 
does not permit a variable number of parameters). 


Access to built in text 


You can access operating system text (such as an error message) by passing a 3 byte array in place of a 
text string to any of the 5 text parameters. The contents of the array should contain: 


byte 0 zero 
byte | Oxfe (0376 in octal) 
byte 2 the signed index of the operating system text as passed to p_gettext. 


For example, the following program, again compiled and linked as sample.img: 


#include <plib.h> 
#include <wlib.h> 


LOCAL_D WSERV_SPEC wSpec; 


LOCAL_C VOID AlertErr(INT err,TEXT *msg) 


TEXT bb[3]; 
bb[0]=0; 

bb[1]=0xfe; 
bb [2]=err; 


wsAlertW(WS_ALERT_CLIENT,msg, &bb[0],NULL) ; 
} 


GLDEF_C INT main(VOID) 
{ 
wConnect (&wSpec, 0,W_CONNECT_PRIORITY) ; 
AlertErr (E_GEN_NOMEMORY, "Failed to save"); 
return (0); 


} 
when run on the HC, displays: 


Failed to saye 
Mo system memory 


Continue 
Esc 


when run on the S3a under version 4 of the window server, displays: 


Failed to save 
No system memory 


Continue 


2-15 


WINDOW SERVER REFERENCE 


and when run on the Workabout displays: 


Sample 


Failed to save 
No system memory 


Continue 


LEsc_] 


Formatted text with 3 message lines 


If the first two bytes at pT1 are zero, pT2 is ignored and wsAlertw assumes that the two zero bytes are 
immediately followed by: 


e an array of three DEsc structs 


¢ immediately followed by a character buffer of maximum length w_ALERT_TEXT_MAx_LEN (80) that 
contains the text for the three lines 


The struct Desc is defined in wlib.h as: 


typedef struct 
{ 
UBYTE hposition; 
UBYTE length; 
UWORD offset; 


} DESC; 
where 
hposition is either 0xff for centred text or any other value to specify the pixel position 
from the left of the alert 
length is the length of the text for the line, to be taken from the buffer 
offset is the offset of the start of the text relative to pti 


Such a data structure would normally be built up by a function as in, for example: 


LOCAL_C VOID CDECL Alert3(TEXT *m1,TEXT *m2,TEXT *m3) 
{ 
TEXT *pt; 
TEXT **pps; 
DESC *pd, *pdend; 


struct { 
WORD zero; 
DESC line[3]; 
TEXT buf [W_ALERT_TEXT_MAX_LEN]; 
} al; 


al.zero=0; 

pt=éal.buf[0]; 

pps=é&ml1; 

for (pd=éal.line[0],pdend=pd+3; pd<pdend; pd++) 
{ 
pd->hposition=0xff; 
pd->length=p_slen(*pps) ; 
pd->offset=pt-— (TEXT *)&al; 
pt=(TEXT *)p_bcpy (pt, *pps++,pd->length) ; 
} 

wsAlertW(WS_ALERT_CLIENT, (TEXT *) &al,NULL, NULL) ; 


} 


2-16 


2 GENERAL WINDOW SERVER FUNCTIONS 


where the following line: 
Alert3("Line 1","Line 2","Line 3"); 


when executed on an HC, displays: 


Line 1 
Line 7? 


Line 3 
Continue 


Esc 


when executed on the S3a under version 4 of the window server, displays: 


Continue 


and when executed on the Workabout, displays: 


Sample 


Line 1 
Line 
Line 3 


Continue 


LEsc_] 


Text with 4 message lines 


This is possible in version 4 of the window server and is achieved by oring the ws_ALERT_B attribute into 
the mode parameter. The interpretation of the parameters pt1 and pt2 is changed. 


The text referenced by the parameter pT1 is used as the title and is placed above the main box. This 
contrasts with the normal practice of wsAlertw in using the program name as the title. 


The text referenced by the parameter pr2 is a single string but can include up to three carriage return 
characters (0x13 or '\r' in C programs). Each carriage return character causes the remaining text to be 
wrapped to a new line and each line is centred within the main display box. 


Note that this text need not contain carriage return characters. If the text is too long to fit onto one line, 
carriage returns will be inserted at appropriate points. Whole words, however, will not be split. 


2-17 


WINDOW SERVER REFERENCE 


The sample code fragment below illustrates how this can be done. Note also the use of three buttons in 
this example: 


TEXT *ptxt,text[108]; 

ptxt = p_scpy(&text[0],"This is an example \r to demo"); 
ptxt = p_scpy(ptxt,"nstrate the use \r"); 

ptxt = p_scpy(ptxt,"of four\r"); 


ptxt = p_scpy(ptxt," message lines in the alert box"); 


wsAlertW(WS_ALERT_CLIENT|WS_ALERT_B, "Title Line", &text[0],"A","B","C"); 


This results in the following alert when run on a Series 3a machine under version 4 of the window server: 


Tithe Line 


This is an example 
to demonstrate the use 
of four 
message lines in the alert box 


Although the Workabout uses version 4, its screen is not large enough to display four lines of text in an 
alert. If the above code is run on Workabout, the fourth line is not displayed and the appearance of the 
alert is as follows: 


Title line 


This is an example 
to demonstrate the use 


of four 


Note that the techniques used to access built in text and formatted text with three message lines as 
described earlier, cannot be used with the attribute ws_ALERT_B set. 


If any illegal parameters are passed, the function will raise a W_PANIC_ALERT panic. 


wsAlertA Present an alert 
VOID wsAlertA(INT mode,WORD *pstat,TEXT *pt1,TEXT *pt2,TEXT *pbl,...); 


This function is not suitable for general use in applications. It is intended to be used only by the process 
designated to be the alarm server; any application, however, may use wsAlertw. 


Presents a p_notify-like display where the user is presented with a message and prompted to respond by 
pressing a button. 


Functionally identical to wsalertw except that it returns immediately without waiting for the user to 
respond. It is the asynchronous form of wsAlertw. 


Asynchronous requests are described in the chapter Asynchronous Requests and Semaphores in the PLIB 
Reference manual. 


When the user does respond, the calling process I/O semaphore is signalled and the index of the button 
pressed (0, | or 2) is written to *pstat. 


Once launched, there is no way of cancelling an asynchronous alert - it can only be completed by the user. 


If any illegal parameters are passed, the function will raise a W_PANIC_ALERT panic. 


2-18 


2 GENERAL WINDOW SERVER FUNCTIONS 


wsAlertUpdate Update a pending alert 
INT wsAlertUpdate (TEXT *pt1,TEXT *pt2,TEXT *pbl,...); 


This function is not suitable for general use in applications. It is intended to be used only by the process 
designated to be the alarm server; any application, however, may use wsAlertw. 


Update an asynchronous alert where the parameters pt1, etc are as for wsAlerta. 
Does nothing if the user has already responded to the alert. 


If any illegal parameters are passed, the function will raise a w_pANIC_ALERT panic. 


Pe ee En a ee 
Status windows 


Status windows are part of the $3, S3a and Workabout user interfaces. 


In principle, status windows are also supported on an HC that is running version 3.5 of the window server. 
However, their use requires the cooperation of a client which has declared itself as the application key 
handler by calling wappKeyHandler (the application key handler is the shell on the $3, S3a and 
Workabout). In practice, it would be difficult for an external developer to set up status windows on the 
HC. 


The window server supports two kinds of status window: 


temporary If temporary status windows are enabled, the window server displays a pop-up 
transient status window in front of the foreground client's existing windows 
when PSION+MENU is pressed. The status window remains for 2 to 2.5 seconds. 


permanent While enabled, the window server maintains a permanent status window to the 
right of the screen and behind existing windows. If an application supports a 
permanent status window, it is meant to "tile" its main top-level window with 
the status window. On the S3 and S3a, higher level software toggles the 
presentation of a permanent status window in response to a CTRL+MENU press. 


The following shows the S3 World application's display with a temporary status window to the right of the 
screen using a version prior to version 4 of the window server: 


7 616 B44 


Wellinatoriy 
Hew “ealand Dist! 11689 fi 


There is no difference between the appearance of a permanent and a temporary status window. 


The status window gives the user a view of (from top to bottom): 


a program icon A client's icon is determined by a structure pointed to by the application key 
handler. 
a program name If the reserved static patStatusNamePtr contains other than NULL, it is assumed 


to point to a zero terminated string that gives the program name (of up to 8 
characters, terminated by any'.'). If patstatusNamePtr is NULL, the process 
name is used. 


time and date The time and data is presented following the information in the £_conrte struct 
as obtained by calling p_getctd. 


2-19 


WINDOW SERVER REFERENCE 


The following shows the S3a World application's display with a temporary status window to the right of 
the screen using version 4 of the window server: 


3 616 64 4 


gellington, 
Dist: 11689 Miles United|_Thuz9 


|New Zealand 


Note that the S3a has a larger and finer grained screen (480 x 160) pixels). 


In version 4 of the window server, the status window has been modified. The program name and the 
program icon have changed places and four new features can be displayed (although not all are shown in 
the above example): 


e Low battery indicator 
e SSD pack indicators 
e Remote link indicator 
e Caps lock indicator 


Each of these features can be disabled by setting the appropriate flags when configuring the window 
server uSiNg wSystem. 


The following illustration shows the S3a Database application display with a permanent status window to 
the right of the screen. The application's main window has been neatly tiled with it: 


First Name(s}: A.P. 
Surname(s)-+ Another 
Address: 123 Anyavenue 
Anytown 
Anycounty 


Post Code: <1 0A 
#2 Home: 071-123-4567 


Find: another 


On the Workabout, an equivalent display of the Database application appears as shown below: 


Name->A.P. Another 
a Home: 071-123-4567 
Address: 123 Anyavenue 
Anytown, Anycc 


Find: another 


Applications can have different 'modes' of operation, the precise definition being dependent on the 
application. As well as using menu options and ‘hot' keys to switch between the different modes, an S3a 
application can set the diamond key to cycle around some or all of them. 


By using the wsSetList function, introduced in version 4, the program icon in the status window can be 
replaced by a list of modes. In the S3a display shown above, all three modes of the Database application 
are shown with the diamond symbol pointing to the current mode. 


Note that the Workabout status window does not display either the application's icon or a list of modes. 


2-20 


2 GENERAL WINDOW SERVER FUNCTIONS 


Compatibility mode status window 


In version 4, applications on the S3a and Workabout can run in $3 compatibility mode. This allows an 
application to have the 'look' and 'feel' of the same application running on an S3. On the S3a, this is 
achieved by doubling up the pixels. For example, a line which is 10 x 1 pixels on the S3 will be drawn 20 
x 2 pixels on the S3a and should 'look' the same. On the Workabout, applications running in compatibility 
mode will normally exactly match the S3 appearance. 


If an application is running in compatibility mode on the S3a or Workabout, then a call to wsEnable 
creates a compatibility mode status window which looks and behaves like an S3 status window. 


Alternatively, the version 4 function wst atusWindow can be used to create a compatibility status window. 


wsEnable Enable the permanent status window 


VOID wsEnable (VOID) ; 


Create and maintain a permanent status window, behind existing windows. Does nothing if a permanent 
status window already exists. 


Before calling wsEnab1e, the calling application should resize its main window such that it is tiled with 
the status window. 


Under version 4, the required window extent should be determined by calling wInquirestatusWindow to 
get the size of the status window and then performing a simple calculation. Under earlier versions of the 
window server, uS€ wsScreenExt. 


In version 4, if running in compatibility mode on the S3a or Workabout, the status window will have the 
appearance of the S3 status window. 


wStatusWindow Set the state of the status window 


VOID wStatusWindow(INT state); 


Available in version 4 only, this sets the permanent status window into one of a number of mutually 
exclusive states by setting the parameter state to one of the following: 


W_STATUS_WINDOW_OFF no status window is visible 

W_STATUS_WINDOW_SMALL display the small version of the status window 
W_STATUS_WINDOW_BIG display the full size version of the status window 
W_STATUS_WINDOW_CTBY display the S3 compatibility status window 

Calling this function with the parameter value w_sTATUS_WINDOW_oFF is equivalent to calling 
wsDisable(); calling this function with the parameter value w_sTATUS_WINDOW_BIG (or 
W_STATUS_WINDOw_cTBy if in S3 compatibility mode) is equivalent to calling wsEnable(). 


See the description of wInquireStatusWindow (or, for versions of the window server earlier than version 
4, wsScreenExt) for a means of determining the size and position of a status window. 


wsScreenExt Get screen extent for tile with status window 
VOID wsScreenExt (P_EXTENT *pext) ; 


This function should only be used when running versions of the window server earlier than version 4. It is 
available in version 4 for compatibility only. 


It is strongly recommended that the function wInquireStatusWindow be used instead of wsScreenExt in 
version 4 of the window server. 


The function writes the extent of the screen remaining to the data structure pointed to by pext when there 
is a permanent status window. 


2The resize may fail with out of memory - so it is best to delay wsEnable until after the resize is 
successful. 


2-21 


WINDOW SERVER REFERENCE 


The P_EXTENT struct is defined as: 


typedef struct 
{ 
WORD x; 
WORD y; 
} P_POINT; 


typedef struct 
{ 
P_POINT tl; 
WORD width; 
WORD height; 
} P_EXTENT; 


Series 3 applications that support permanent status windows running under older versions of the window 
server (i.e. earlier than version 4) can use wsScreenExt to determine the extent of the window to use while 
a permanent status window is enabled. 


Recall that the size of the entire screen (used in the absence of a permanent status window) may be 
obtained from the wsERv_sPEc struct filled in by wconnect. For example: 


GLREF_D WSERV_SPEC *wserv_channel; 
LOCAL_D P_POINT ScreenSize; 


ScreenSize=wserv_channel->conn.info.pixels; 


wsUpdate Update the permanent status window 
VOID wsUpdate(INT flags); 

Update the displayed permanent status window. 

The parameter flags can be one of: 


WS_UPDATE_NAME to change the displayed permanent status window name (for example, after 
changing DatStatusNamePtr). 


WS_UPDATE_CLOCK to update any displayed clocks (for example, after changing settings such as 
12/24 hour, analog/digital, the time separator and so on). 


wsDisable Disable the permanent status window 
VOID wsDisable (VOID) ; 
Destroy the permanent status window (if one exists). 


Before calling wsDisab1le, the calling application should resize its main window to take up the whole 
screen. As with wsEnable, the required window extent may be determined by calling 
wiInquireStatusWindow and doing a simple calculation. 


wsEnableTemp Enable temporary status windows 
VOID wsEnableTemp (VOID) ; 
Enable the window server's processing of PSION+MENU to present a temporary status window. 


Unlike wsEnable, the effect of this call is system wide. On the S3 and S3a, wsEnableTemp is called by the 
shell as part of its initialisation. 


wsDisableTemp Disable temporary status windows 


VOID wsDisableTemp (VOID) ; 
Disable the processing of PSION+MENU to present a temporary status window. 


The effect of this call is system wide. Calling wsDisableTemp on the $3 and S3a will disable temporary 
status windows for all applications. 


2-22 


2 GENERAL WINDOW SERVER FUNCTIONS 


wsSetList Set list of modes to display in status window 


INT wsSetList (UINT count, TEXT **plist,UINT pos); 


Available in version 4 only, this function sets up the text for the list of modes to be displayed in the status 
window. 


The count parameter is the number of text items in the list; the plist parameter is a pointer to an array of 
string pointers (one string per mode) and pos is the position within the list where the diamond symbol is 
to be placed. The first position is given a value of 0. 


If the diamond symbol is not to be shown, pos should be set to w_STATUS_WIN_NO_DIAMOND. 


To replace the list of modes with the application icon, count should be set to w_sTATUS_WINDOW_ICON. 
With count set to this value, the other two parameters are ignored. Typically, a call would look like this: 


wsSetList (W_STATUS_WINDOW_ICON, NULL, 0) ; 


The function returns 0 if successful or =_GEN_Nomemory if it fails to allocate space for the new list. 


Note that calling wssetList on the Workabout has no visible effect, since its status window does not 
display a list of modes. 


wsSelectList Set select position in status window mode list 


VOID wsSelectList (INT pos); 


Available in version 4 only, this function allows the diamond symbol in the list of modes in the status 
window to be (re-)positioned. 


The position is specified by giving a value to the parameter pos. The first position is given a value of 0. If 
the diamond symbol is not currently shown, setting a position will cause it to reappear. Giving pos a value 
of w_STATUS_WIN_NO_DIAMoND causes the diamond symbol to be removed from the status window. 


Note that calling wsselectList on the Workabout has no visible effect, since its status window does not 
display a list of modes. 


winquireStatusWindow Inquire state and extent of status window 
INT wiInquireStatusWindow(INT state,P_EXTENT *pextent) ; 
Available in version 4 only, this function does two things: 


e it returns the current state of the status window as set by wstatusWindow. It returns one of the 
values w_STATUS_WINDOW_OFF, W_STATUS_WINDOW_SMALL, W_STATUS_WINDOW_BIG and 
W_STATUS_WINDOW_CTBY. 


e it fills in the pextent of the status window corresponding to state. In other words, by setting 
state to one of the values w_sTATUS_WINDOW_OFF, W_STATUS_WINDOW_SMALL, 
W_STATUS_WINDOW_BIG Of W_STATUS_WINDOW_CTBY, it supplies the position, width and height of a 
status window of that type. 

Further, if state is given a value of -1, the extent of the current status window is supplied. 


It is interesting to note that if the status window is off, the extent information describes a status window 
located at the right hand edge of the screen with zero width and full height. 


For a description of the p_ExTENT structure, see wsScreenExt. 


2-23 


WINDOW SERVER REFERENCE 


Configuring the window server 


The functions which have a system wide effect on the window server (as opposed to just affecting the 
calling client) are: 


wSystem which is described next 
wsEnableTemp to enable/disable permanent status windows (as described above) 
wsDisableTemp 


These functions should only be used when an application takes over the whole machine. This is more 
likely on an HC than say an S3, S$3a or Workabout. 


wSystem Configure the window server 
INT wSystem(UINT new_flags,UINT flag_mask) ; 


Set an internal set of flags to modify the system-wide behaviour of the window server where: 


new_flags is a bit mask containing the values of the bit flags to be modified 
flag_mask is a bit mask indicating (by those bits that are set) the bit flags that are to be 
modified 


The function returns the old value of the flags. 
The flags are of the form ws—ERV_FLAG_xxx where xxx is one of: 


Stops the window server from restarting the shell (that is, sys$shll.img) 
NO_SHELL_REBOOT whenever it terminates. Clearing this flag when there is no shell running causes 
the window server to restart the shell. Available on all machines. 


NO_NOTIFIER_REBOOT The same as above except it applies to the notifier process (sys$ntfy.img). 
Available on the HC and MC. 


Prior to version 4, the window server on the S3 always provides the notifier 
itself and never starts a sys$ntfy.img. 


Under version 4, this flag can be set for the S3a and Workabout because the 
possibility of building a separate notifier process exists. 


HOOK_NOTIFIER If set, the window server attempts to hook the notifier, as explained in the 
earlier Alerts section of this chapter. All MC versions are unable to hook the 
notifier. 


Prior to version 4, this flag applies to the HC only; the S3 effectively assumes 
that it is permanently set. 


Under version 4, this flag can be set for the S3a and Workabout. 


NO_PANIC_NOTIFY Disables the window server from reporting processes which terminate with a 
panic or a negative reason code. Available on the HC, $3, S3a and Workabout 
but not the MC. This flag is ignored unless the window server has hooked the 
notifier. On machines other than the MC, you would set this flag to prevent the 
window server from reporting abnormal terminations when HOOK_NOTIFIER is 
set. 


UPDATE_MSGS Enables the window server to send wM_TASK_UPDATE events to the shell to 
inform it of the termination of any process (not just clients of the window 
server). The MC version does not support WM_TASK_UPDATE events. 


Prior to version 4, this flag applies to the HC only; the S3 effectively assumes 
that it is permanently set. 


Under version 4, this flag can be set for the S3a and Workabout. 


2-24 


2 GENERAL WINDOW SERVER FUNCTIONS 


LOW_BATTERY_WARNINGS _ If set, the window server notifies the user of a low lithium or main battery. Note 
that the window server only checks for low battery when the machine is turned 
on. On the HC, the window server is only informed of the machine being 
switched on after p_setonevent (TRUE) has been called. The MC version of the 
window server does not support low battery warnings. 


Prior to version 4, this flag only applies to the HC; on the S3, the window 
server always reports low battery warnings. 


Under version 4, this flag can be set for the S3a and Workabout. 


HUNG_UP_SW If set, the window server presents a "hung up" status window if the foreground 
task is not using backed-up windows and fails to respond to redraw events. The 
MC version of the window server does not support status windows. 


Prior to version 4, this flag only applies to the HC; the S3 effectively assumes 
that it is permanently set. 


Under version 4, this flag can be set for the S3a and Workabout. 


The following flags are introduced in version 4 and apply only to S3a and Workabout machines. 


SW_NO_LOW_BATTERY If set, it disables the low battery indicator in the status window. 
SW_NO_PACKS If set, it disables the two pack indicators in the status window. 
SW_NO_LINK If set, it disables the link indicator in the status window. 
SW_NO_CAPS If set, it disables the caps lock indicator in the status window. 


Prior to version 4, when the window server starts, the internal flags are all clear although, on the HC, this 
can be altered by setting the sws_rn environment variable. 


Under version 4 of the window server the internal flags on the S3a and Workabout can be altered, like on 
the HC, by setting the sws_rL environment variable. 


In practice, wsystem 1s more likely to be used on the HC rather than the S3, S3a, Workabout or MC. See 
the section System start-up in the Introduction chapter for further discussion (including further details on 
$wS_FL) and examples of the use of wsystem. 


Attached Clients 


This section only applies to large screen versions of the window server, such as the MC. 


Clients can attach to and detach from each other by use of the wattachToClient, 
wAttachToForegroundClient and wDetachClient Calls. 


The client that calls the attach function is attached in front of the client it is attaching to. 


When clients are attached they move round in the task order together - when one of the attached tasks 
moves, it pulls the other task (or tasks) with it. When they become foreground, all attached tasks are sent a 
WM_FOREGROUND event. 


Two examples of the use of attached clients on the MC are: 


e The system notifier sys$ntfy uses wAttachToForegroundClient to attach itself to the foreground client 
to display its message. 


e The voice server uses wAttachToClient to attach itself to its client (where both are clients of the 
window server) to implement a dialog box as a separate process. 


In both cases, the attaching client is behaving as if it were part of the client it is attached to. The notifier 
could have been implemented using wclientPosition to make itself visible but the holder of the 
foreground would then inappropriately go into background (and get a wM_BACKGROUND event). 


When a client attaches to another, the window server sends a wM_ATTACHED event to the client being 
attached to. When the attaching client detaches, it sends a wm_DETACHED event to the client being detached 
from. 


A detaching client is positioned to the back of all clients. 


2-25 


WINDOW SERVER REFERENCE 


wAttachToClient Attach to client 


INT wAttachToClient (UINT pid); 
Attach the caller to client pid. 


If client pid does not exist, the function leaves or returns E_FILE_NXIST. 


wAttachToForegroundClient Attach to foreground client 


VOID wAttachToForegroundClient (VOID) ; 
Attach the caller to the foreground client. 


Does nothing if the caller has the foreground. 


wDetachClient Detach from client 


VOID wDetachClient (VOID) ; 
Detach from a client and position to the back of all clients. 


If the caller is no longer attached to another client (say because that client has terminated), the caller is 
just positioned to the back. 


PSO Oe a eae | 
Miscellaneous 


A number of general functions which do not fit under any of the previously discussed topics are described 
here. Unless otherwise stated, they are all introduced in version 4 of the window server. 


wSupportinfo Get information on supported features 


VOID wsSupportInfo(.i.W_SUPPORT_INFO *pinfo); 


The function fills the w_suppoRT_INFo type structure with information on the currently supported 
features. The supplied parameter pinfo must point to a structure of type Ww_SUPPORT_INFO. 


It can set the following values in the flags member: 
W_SUPPORT_GREY if set, the window server supports the current scheme for drawing grey graphics 


W_SUPPORT_CTBY_S3 if set, the window server supports a Series 3 compatibility mode (there is no 
distinction between different Series 3 compatibility modes, such the two that 
are available on the Workabout) 


Currently, no other information is returned. The rest of the w_supPpoRT_INFo structure is set to zeros. The 
function is well placed for expansion in future versions and releases of the window server. 


The w_SUPPORT_INFO structure is defined as follows: 


typedef struct 
{ 
UINT flags; 
UINT fillers[15]; /* will be filled with 0's */ 
} W_SUPPORT_INFO; 


wDisableKeyClick Set or cancel key click disable state 


VOID wDisableKeyClick(INT state); 
If state is set to TRUE, the behaviour of the key click for an application is changed: 


e = The key click is disabled while the application is in foreground. 
e = The key click state is reset when the application goes to background. 


Setting state to FALSE cancels this state for an application. 


2-26 


CHAPTER 3 


WINDOWS 


Creating and initialising a window 


Window attributes 


The functions: 
wCreateWindow 
wSetWindow 


wiInquireWindow 


to create a window and set its attributes 
to set a window's attributes 


to sense a window's attributes 


take the address of a w_winpata struct as a parameter to hold the window attributes where the w_winpaTa 
struct is defined as: 


typedef struct 


{ 
WORD x; 
WORD y; 


} P_POINT; 


ttypedef struct 


{ 
P_POINT 


tale 


WORD width; 
WORD height; 
} P_EXTENT; 


ttypedef struct 


{ 


UWORD flags; 
P_EXTENT extent; 
WORD mouse_icon; 
UBYTE background; 
UBYTE filler; 

} W_WINDATA; 


where: 


flags 


extent 


mouse_icon 


background 


is a set of binary attributes, described below. In the root window, the flags field 
is zero (so all the binary attributes are clear). 


is the position and size of the window relative to its parent in pixel coordinates. 
In the root window the extent coincides with the whole screen. 


is the ID of the window mouse icon (only used when the machine has a 
pointing device such as on the MC) 


specifies whether the window is backed-up by a bitmap (or bitmaps) and, if not, 
how the window should be prepared when it is validated 


3-1 


WINDOW SERVER REFERENCE 


background (up to version 3.5) 


In versions of the window server up to and including 3.5 the background field of the w_winpata struct 
should be one of: 


W_W 


W_W 


W_W 


W_W 


IN_BACK_BITMAP all drawing to the window is duplicated to an off-screen bitmap. Redraws are 
automatically done from this bitmap, so no ww_REDRAW events are ever 
generated. When the background has this value, it may not be altered by calling 
wSetWindow. Not available on version 2 of the window server. 

IN_BACK_CLR clear the pixels in the window on validation (the root window has this value). 
This is the default value. 

IN_BACK_SET set the pixels in the window on validation. 

IN_BACK_NONE do nothing on validation (on the assumption that the drawing covers every 


pixel). Best for flicker-free graphics. 


background (version 4) 


In version 4 of the window server, there are changes in meaning and values caused by the introduction of 
grey. To control drawing to the normal (black) plane, one of the following must be set: 


W_WIN_BACK_BITMAP all drawing to the normal (black) plane of the window is duplicated to an 
off-screen bitmap. Redraws are automatically done from this bitmap, so no 
WM_REDRAW events are ever generated. When the background has this value, 
it may not be altered by calling wset window. 

W_WIN_BACK_CLR clear the pixels in the normal (black) plane of the window on validation (the 
root window has this value). This is the default value. 

W_WIN_BACK_SET set the pixels in the normal (black) plane of the window on validation. 

W_WIN_BACK_NONE do nothing to the normal (black) plane of the window on validation (on the 
assumption that the drawing covers every pixel). Best for flicker-free 
graphics. 

W_WIN_BACK_CLR_NO_REDRAW to clear the pixels in the normal (black) plane of the window but prevent 
any drawing or redrawing to this specific plane. 

W_WIN_BACK_SET_NO_REDRAW to Set the pixels in the normal (black) plane of the window but prevent any 
drawing or redrawing to this specific plane. 

W_WIN_BACK_NONE do nothing to the normal (black) plane of the window on validation but also 

NO_REDRAW prevent any drawing or redrawing to this specific plane. 


To control drawing to the grey plane, one of the following must be ored into the background field with 


one of the above normal plane values: 

W_WIN_BACK_GREY_BITMAP all drawing to the grey plane of the window is duplicated to an off-screen 
bitmap. Redraws are automatically done from this bitmap, so no ww_REDRAW 
events are ever generated. When the background has this value, it may not 
be altered by calling wset window. 

W_WIN_BACK_GREY_CLR clear the pixels in the grey plane of the window on validation (the root 
window has this value). 

W_WIN_BACK_GREY_SET set the pixels in the grey plane of the window on validation. 

W_WIN_BACK_GREY_NONE do nothing to the grey plane on validation (on the assumption that the 
drawing covers every pixel). Best for flicker-free graphics. 

W_WIN_BACK_GREY_CLR to clear the pixels in the grey plane of the window but prevent any drawing 

NO_REDRAW or redrawing to this specific plane. This is the default value. 

W_WIN_BACK_GREY_SET to set the pixels in the grey plane of the window but prevent any drawing or 

NO_REDRAW redrawing to this specific plane. 

W_WIN_BACK_GREY_NONE do nothing to the grey plane of the window on validation but also prevent 

NO_REDRAW any drawing or redrawing to this specific plane. 


3 WINDOWS 


If drawing is enabled to both the normal (black) and the grey planes, then both planes will be moved when 
scrolling or moving a window. 


If no drawing is intended for one of the planes in a window, then overheads can be cut by disabling the 
unused plane. For example, if no drawing is to be done to the grey plane, disable this plane by NOT 
setting any of w_WIN_BACK_GREY_CLR, W_WIN_BACK_GREY_SET, W_WIN_BACK_GREY_NONE OF 
W_WIN_BACK_GREY_BITMAP. 


Note that if both w_wmn_BAcK_BITMAP and w_WIN_BACK_GREY_BITMapP are set, then the window will be 
backed up to two bitmaps, one for the normal plane and one for the grey plane. 


Also note that setting one of: 


W_WIN_BACK_CLR_NO_REDRAW 


W_WIN_BACK_SET_NO_REDRAW 


W_WIN_BACK_NONE_NO_REDRAW 


and setting one of: 


W_WIN_BACK_GREY_CLR_NO_REDRAW 


W_WIN_BACK_GREY_SET_NO_REDRAW 


W_WIN_BACK_GREY_NONE_NO_REDRAW 


is equivalent to setting the w_wIN_No_REDRaw bit (as a parameter to wcreat eWindow). 
flags (all versions) 
The following bits of f1ags apply to all versions of the window server on all machines: 


W_WIN_NO_REDRAW windows with this flag set never receive redraw events. This flag may not be 
altered by a wSetwindow command. 


W_WIN_PRIORITY redraw events for windows with this flag set have priority over redraw events 
for windows with this flag clear. 


flags (version 4) 

The following bit of f1ags applies to version 4 of the window server: 

W_WIN_DOUBLE_PIXEL when set, causes all graphics in this window to work in double pixel mode. 
Large screen flags 

The following bit of f1ags applies only to large screen versions of the window server such as the MC: 


W_WIN_FOREGROUND_ONLY if set, the window is only visible while the client is foreground. Note that a 
descendant window of a roREGROUND_ONLY window is necessarily also 
FOREGROUND_ONLY regardless of the value of this flag. This flag may not be 
altered by a wSetwindow command. 


Mouse-related flags 


The following bit of f1ags apply only when the machine has a pointing device, such as on the MC: 


W_WIN_NO_MOUSE a window with this flag set will not receive any mouse events (however, 
the mouse cursor is still displayed). All other mouse-related flags have no 
affect when this flag is set. 


W_WIN_INACTIVE if a mouse click occurs anywhere in a window with this flag set or in any 
of its descendants, a wM_AcTIVE event is sent to the window. 


W_WIN_INPUT_ONLY if set, the window is input-only. Input-only windows are invisible and exist 
solely for the purpose of detecting mouse events. This flag may not be 
altered by a wSetwindow command. 


W_WIN_MOUSE_MOVE if set, mouse movement events are generated when the mouse button is up. 
W_WIN_MOUSE_DRAG if set, mouse movement events are generated when the mouse button is 
down. 


3-3 


WINDOW SERVER REFERENCE 


W_WIN_MOUSE_GRAB if set, the mouse is automatically grabbed when the mouse button is 
pressed. The grab is automatically released when the mouse button is 
released and a wM_MOUSE event of type WM_MOUSE_RELEASE is sent to the 
grabbing window, even if the release occurs outside the window. If 
W_WIN_MOUSE_DRAG is also set, any intermediate wM_MouSE_MOVE events are 
also delivered to the grabbing window. 


W_WIN_RUBBER_BAND If a mouse down event occurs in a window with this bit set, it and 

CAPTURE subsequent mouse and keyboard events are captured to the window server's 
rubber band processing until the rubber band mode is terminated. This first 
mouse click generates a WW_RUBBER_BAND_INIT event to which the client 
must respond with a call to wRubberBand. This flag may not be altered by a 
wSetWindow command. 


W_WIN_RUBBER_BAND If when calling wRubberBand in response to a WM_RUBBER_BAND_INIT event 

COMPLETE_ON_RELEASE you specify that the rubber band should be completed on a mouse up event, 
you should also set this bit. This flag may not be altered by a wSet Window 
command. 

wCreateWindow Create a window 


INT wCreateWindow(UINT parent_id, UINT field_set, .i.W_WINDATA *pwindata, UWORD handle); 
Create a window and, if successful, return the positive ID of the window where: 


parent_id is the window ID of the parent window. To create a top-level window, where 
the parent is the root window (ie the whole screen), pass parent_id as zero. 


handle is the client's own identifier for the window (which must be non-zero) to be 
embedded in events which are directed at the window (for example, redraw and 
mouse events). In medium to large applications, handle is commonly the 
address of a control block which contains the window ID. 


field_set is a set of bit flags which specify (by being set) which fields in the pwindata 
struct are to be used to set the window attributes. In most cases, an attribute 
which is not set from pwindata is inherited from parent_id (as detailed 
below). If field_set is zero, pwindata 1s ignored. 


pwindata is the address of a W_WINDATA struct as described above. If field_set is zero, 
pwindata is ignored. 


The bits in field_set are made up of the same bit masks as for pwindata->flags to indicate that the 
corresponding bit in pwindata->flags should be used. And, in addition, field_set may contain: 


W_WIN_EXTENT to uSe pwindata->extent 
W_WIN_MOUSE_ICON to use pwindata->mouse_icon 
W_WIN_BACKGROUND to uSe pwindata->background 


If a field_set bit is clear, the corresponding attribute is inherited from the parent window parent_ida, 
except for: 


W_WIN_RUBBER_BAND_CAPTURE 
W_WIN_INACTIVE 
W_WIN_NO_REDRAW 
W_WIN_PRIORITY 
W_WIN_FOREGROUND_ONLY 


These five attributes are never inherited from any parent window. If they are not set explicitly, by setting 
the appropriate bit in fielda_set and the corresponding data value in the w_winpata struct pointed to by 
pwindata, they are set to zero. 


If parent_id has one or more child windows, the new window is created in front of its siblings. 


After a successful return from wcreat eWindow, the window is just a dormant data structure in the window 
server's data segment with no visibility on the screen. You can't draw to the window and you won't get any 
redraw events (or any mouse events if there is a pointing device) until the window is initialised by calling 
wInitialiseWindowTree, described below. 


3-4 


3 WINDOWS 


If the function fails because there is insufficient memory, it calls p_leave (E_GEN_NOMEMORY) or returns 
E_GEN_NOMEMoRY, depending on whether wDisableLeaves has been called. 


See the description of wconnect for an example. 


wSetWindow Set window attributes 


VOID wSetWindow(UINT wid, UINT field_set, .i.W_WINDATA *pwindata) ; 


Set one or more window attributes of the window with ID wia where field_set and pwindata are as for 
wCreateWindow, described above. 


The function wSetwindow ignores the following bits in field_set which correspond to window attributes 
which are not modifiable: 


W_WIN_NO_REDRAW 

W_WIN_INPUT_ONLY 
W_WIN_FOREGROUND_ONLY 
W_WIN_RUBBER_BAND_COMPLETE_ON_RELEASE 


You cannot modify any of the attributes of the root window. 
In practice, wSetWindow 1s commonly use to move and/or resize a window. 


If the size of a backed-up window is increased, the backup bitmap(s) will also be increased and the 
additional area (to the right and below) is filled with zeros. 


In this situation, the call can fail with an out-of-memory condition; it should be noted that such a failure 
might not be reported immediately because of the buffering of window server requests (see the Clients and 
the window server section in the Introduction chapter). 


Any areas of the window that are exposed as a result of making the call to wset window (because the effect 
has been to expand or move the window) are invalidated. Areas that are covered, moved offscreen, or lost 
because the window has become smaller are marked as valid, thus preventing any redraws that might have 
been pending for these areas. The validity of any other areas is not affected by the call. 


winquireWindow Get window attributes 


INT wiInquireWindow(UINT wid, .i.W_WINDATA *pwindata) ; 


Write a copy of window wia's extent and flags to *pwindata (pwindata->mouse_icon and 
pwindata->background are left undefined). 


wlnitialiseWindowTree Initialise window tree 


VOID winitialiseWindowTree(UINT wid); 

Initialise window wid and all its descendants. 

None of these windows may be initialised again. 

Provided that the window is not made invisible between creation and initialisation, the following occurs: 


backed-up window! The backup bitmap (which is initialised with zeros when the window is created) 
is copied to any visible parts of the window, clearing it. In version 4 of the 
window server there may be two backup bitmaps which are copied to the visible 
parts of the window's normal and grey plane respectively. 


no-redraw window2 Any visible pixels are cleared if the background attribute is w_wIN_BACK_CLR or 
set if the background attribute is w_win_Back_seEt. In version 4 of the window 
server, these attributes clear or set the visible pixels in the window's normal 
plane while w_wIN_BACK_GREY_CLR and W_WIN_BACK_GREY_SET Clear or set the 
visible pixels in the window's grey plane. 


non-backed-up redraw _— Any visible parts are added to the update region (which will subsequently cause 
window redraw events to be generated). 


!Where the window attribute background is W_WIN_BACK_BITMaP (and/or w_WIN_BACK_GREY_BITMAP in 
version 4 of the window server). 


2Where the w_wIn_No_REDRAw window attribute is set. 


3-5 


WINDOW SERVER REFERENCE 


wCloseWindowTree Destroy a window and its descendants 


VOID wCloseWindowTree(UINT wid); 


Destroy window wid and all its descendants, freeing any associated window server resources (such as an 
attached graphics context). 


When destroying a window system, it is sometimes difficult to destroy windows bottom-up with respect to 
the window parentage tree. To make life easier, the window server allows windows to be destroyed more 
than once as long as other window server objects, such as graphics contexts, bitmaps, fonts, icons or 
windows are not created in the mean time. 


If you are using wGetEvent or wGetEvent Special rather than wGetEventWait, you should be very careful 
about destroying windows while a request made by calling wcetEvent or wGetEvent Special is pending. 
Bearing in mind the multi-tasking nature of the system and the fact that the window server runs at a 
higher priority than its clients, it is quite possible for an event to be delivered before the window is 
destroyed in which case there is the possibility that the next event will relate to a window which has 
already been destroyed (a redraw event, say). 


The solution to this problem normally involves calling wcancelGetEvent, as described in the first chapter. 


winquireWindowOffset Get window to window offset 


INT wiInquireWindowOffset (UINT from_wid, UINT to_wid, .i.P_POINT *poffset); 
Write the offset of to_wid relative to from_wid tO poffset and return zero. 
The P_POINT struct is: 


typedef struct 
{ 
WORD x; 
WORD y; 
} P_POINT; 


Useful when positioning windows relative to each other. To find the absolute position of a window on the 
screen set from_wid to zero (the root window ID). 


If the window server has a pending error with error number err, the function calls p_leave (err) or 
returns err, depending on whether wDisableLeaves has been called. 


wReassignRootWindow Reassign the root window 


VOID wReassignRootWindow(UINT wid); 


Reassign the window ID of zero to mean the window wid rather than the root window which covers the 
whole screen. 


The assignation applies only to the calling client. 
Passing a wid of zero resets the window ID of zero to mean the whole screen. 


Used for creating development environments on a large screen version of the window server which 
simulate a small screen environment. 


Not available in version 2 of the window server. 


Visible and invisible windows 


wMakelnvisible Make window invisible 
VOID wMakeInvisible(UINT wid); 
Mark window wid as invisible. 
When a window is marked as invisible it and all its descendants are made invisible. 
The window server treats windows which are invisible as follows: 
e if the window is backed-up, any drawing to it is drawn only to the backup bitmap(s) 
e invalidating a window using wInvalidateRect or wInvalidateWin has no effect 


e¢ windows behave as if they do not exist with respect to mouse input (this only applies when there 
is a pointing device) 


3-6 


3 WINDOWS 


wMakeVisible Make window visible 
VOID wMakeVisible(UINT wid); 
Mark window wid as visible. 


Unless wMakeInvisible has been applied to a descendant, calling wMakevisible makes all descendants 
visible. 


Sibling positions 


wWindowPosition Change position in sibling list 
VOID wWindowPosition(UINT wid, UINT pos); 
Move window wid to the position pos in its sibling list. 


If pos is greater than the number of siblings then window wia will go to the back of the sibling list, if pos 
is zero then it will go to the front of the sibling list. 


wGetWindowPosition Get position in sibling list 
INT wGetWindowPosition(UINT wid); 
Return the position of window wid in its sibling list. 


The function behaves as for wcheckPoint in that it flushes the client-side buffer and reports any uncleared 
error - either by calling p_ieave or by returning the error number. 


Not available in version 2 of the window server. 


Scrolling 


wScrollRect Copy a rectangle 
VOID wScrollRect (UINT wid, .i.P_RECT *prect, P_POINT *poffset); 

Copy the pixels in rectangle prect in window wid to the same sized rectangle, displaced by poffset. 

The structs p_pornt and p_rRect are defined as: 


typedef struct 
{ 
WORD x; 
WORD y; 
} P_POINT; 


typedef struct 
{ 
P_POINT tl; /* top left pixel (internal) */ 
P_POINT br; /* bottom right pixel (external) */ 
} P_RECT; 
The copy excludes the following from prect: 
e those parts which are in the update region (that is, those parts which are invalid) 
e those parts which are obscured or clipped by other windows 


e those parts which are beyond the boundaries of the window 


Although these parts are not copied, their existence causes the corresponding region of the displaced 
rectangle to be invalidated. 


3-7 


WINDOW SERVER REFERENCE 


In version 4 of the window server, if drawing is enabled to both the normal and the grey planes, then the 
copying activity described above is done to both planes. 


If the window is a backed-up window, the copy is also applied to the backup bitmap(s). For a backed-up 
window: the update region is always null; those parts which are obscured or clipped can be recovered from 
the backup bitmap(s); those parts which are beyond the boundaries of the window are cleared. 


Note that wScrol1Rect may also be applied to a bitmap where wid is a bitmap ID (but not in version 2 of 
the window server). 


wsScrollWin Scroll a window 
VOID wScrollWin(UINT wid, .i.P_POINT *poffset) ; 

Scroll the whole of window wid by displacement poffset. 

Entirely equivalent to wScrollRect with prect set to a rectangle covering the whole window. 


Note that wScrollwin may also be used to scroll a whole bitmap where wid is a bitmap ID (but not in 
version 2 of the window server). 


Redrawing 


There are six variants of wBeginRedraw which vary according to whether a temporary graphics context is 
created (and, if so, whether it is to be altered from its default settings) and whether a part or the whole of 
the window is being redrawn, as follows: 


wBeginRedraw to redraw a part of the window using an independently created temporary or 
permanent graphics context 


wBeginRedrawWin to redraw the whole of the window using an independently created temporary 
or permanent graphics context 


wBeginRedrawGC to redraw a part of the window using a temporary graphics context which is 
created and initialised with specified values 


wBeginRedrawGC0 to redraw a part of the window using a temporary graphics context which is 
created with default initial values 


wBeginRedrawWinGC to redraw the whole of the window using a temporary graphics context which is 
created and initialised with specified values 


wBeginRedrawWinGC0 to redraw the whole of the window using a temporary graphics context which is 
created with default initial values 


Note that the last character in both wBeginRedrawGco and wBeginRedrawwWincco is the digit zero (and not 
the letter 'o'). 


When a begin redraw function is used to simultaneously create a temporary graphics context, the 
corresponding call to wEndRedraw automatically frees it. 


All variants validate at least a part of a window and cause subsequent drawing to use the update region 
rather than the normal drawing region. If the background attribute of the window is w_wIN_BACK_CLR, 
validated pixels in the update region are cleared and if the background attribute is w_wIn_BACK_SET, the 
same pixels are set. 


In version 4 of the window server, the above two background attributes apply to validated pixels in the 
normal (black) plane in the update region. In addition, if the background attribute of the window is 
W_WIN_BACK_GREY_CLR Or W_WIN_BACK_GREY_SET, validated pixels in the grey plane in the update region 
are cleared or set respectively. 


A way of ensuring flicker-free redrawing, is to set the background attribute to w_wIN_BACK_NONE and cover 
every pixel in the redraw. 


In version 4 of the window server, W_WIN_BACK_NONE applies only to the normal (black) plane. To achieve 
the same effect when drawing to the grey plane, the corresponding attribute w_wIN_BACK_GREY_NONE 
should also be set. 


3-8 


3 WINDOWS 


wBeginRedraw Start a partial redraw 


VOID wBeginRedraw(UINT wid, .i.P_RECT *prect); 


Validate the rectangle prect in window wia and clip subsequent drawing to the intersection of prect and 
the window's update region (as it was before the validate). The normal drawing region is restored when 
wEndRedraw is called. 


The struct p_rect is defined as: 


typedef struct 
{ 
WORD x; 
WORD y; 
} P_POINT; 


typedef struct 
{ 
P_POINT tl; /* top left pixel (internal) */ 
P_POINT br; /* bottom right pixel (external) */ 
} P_RECT; 


wBeginRedrawWin Start a full redraw 


VOID wBeginRedrawWin(UINT wid); 


Validate the whole of window wia and clip subsequent drawing to the window's update region (as it was 
before the validate). The normal drawing region is restored when wEndRedraw is called. 


Equivalent to calling wBeginRedraw with a rectangle covering all of window wia. 


wBeginRedrawGC Start a partial redraw (GC) 


VOID wBeginRedrawGC (UINT wid, .i.P_RECT *prect, UINT field_set, G_GC *pgc); 


Validate the rectangle prect in window wia and clip subsequent drawing to the window's update region 
(as it was before the validate). 


In addition, create a temporary graphics context which is initialised with those fields from pgc which have 
their corresponding bit fields set in field_set. 


The c_cc struct is defined in wlib.h as: 


typedef struct 
{ 


UBYTE gmode; /* G_TRMODE_SET, CLR, INV (line) */ 

UBYTE textmode; /* G_TRMODE_SET, CLR, INV, REPL (text) */ 

UBYTE style; /* G_STY_NORMAL, _BOLD, _UNDERLINE, _INVERSE, _DOUBLE, _MONO, 
_ITALIC */ 

UBYTE flags; /* controls use of grey & double pixel mode */ 

WORD font; /* ID of font to use */ 

} G_GC; 


where the bit fields for field_set are: 


G_GC_MASK_GMODE corresponding to the gmode member 
G_GC_MASK_TEXTMODE corresponding to the textmode member 
G_GC_MASK_STYLE corresponding to the style member 
G_GC_MASK_FONT corresponding to the font member 

G_GC_MASK_GREY corresponding to the flags member (version 4 only) 
G_GC_MASK_DOUBLE corresponding to the £1ags member (version 4 only) 


The flags member is introduced in version 4 of the window server. Prior to version 4, the space occupied 
by this member was unused. 


See the Graphics Output chapter for a complete description of the fields in a c_cc struct. 


The graphics context is freed (and the normal drawing region is restored) when wendRedraw is called. 


3-9 


WINDOW SERVER REFERENCE 


wBeginRedrawGCOo Start a partial redraw (GCO) 


VOID wBeginRedrawGCO (UINT wid, .i.P_RECT *prect); 


Validate the rectangle prect in window wid and clip subsequent drawing to the window's update region 
(as it was before the validate). 


In addition, create a temporary graphics context with default initial values. 


The graphics context is freed (and the normal drawing region is restored) when wEndRedraw is called. 


wBeginRedrawWinGC Start a full redraw (GC) 


VOID wBeginRedrawWinGC(UINT wid, UINT field_set, .i.G_GC *pgc); 


Validate the whole window wid and clip subsequent drawing to the window's update region (as it was 
before the validate). 


In addition, create a temporary graphics context which is initialised with those fields from pge which have 
their corresponding bit fields set in field_set. 


The graphics context is freed (and the normal drawing region is restored) when wEndRedraw is called. 
The c_cc struct is defined in wlib.h as: 


typedef struct 
{ 


UBYTE gmode; /* G_TRMODE_SET, CLR, INV (line) */ 

UBYTE textmode; /* G_TRMODE_SET, CLR, INV, REPL (text) */ 

UBYTE style; /* G_STY_NORMAL, _BOLD, _UNDERLINE, _INVERSE, _DOUBLE, _MONO, 
_ITALIC */ 

UBYTE flags; /* controls use of grey & double pixel mode */ 

WORD font; /* ID of font to use */ 

} G_GC; 


where the bit fields for field_set are: 


G_GC_MASK_GMODE corresponding to the gmode member 
G_GC_MASK_TEXTMODE corresponding to the textmode member 
G_GC_MASK_STYLE corresponding to the style member 
G_GC_MASK_FONT corresponding to the font member 

G_GC_MASK_GREY corresponding to the flags member (version 4 only) 
G_GC_MASK_DOUBLE corresponding to the flags member (version 4 only) 


The flags member is introduced in version 4 of the window server. Prior to version 4, the space occupied 
by this member was unused. 


See the Graphics Output chapter for a complete description of the fields in a c_cc struct. 
Example 


LOCAL_C VOID BeginRedraw(INT wid, INT fid, INT style) 
{ 
G_GC gc; 


gc.font=fid; 
gc.style=style; 


wBeginRedrawWinGC (wid, G_GC_MASK FONT |G GC_MASK_STYLE, &gc) ; 
} 


wBeginRedrawWinGCo Start a full redraw (GCO) 


VOID wBeginRedrawWinGCO(UINT wid); 


Validate the whole of window wid and clip subsequent drawing to the window's update region (as it was 
before the validate). 


In addition, create a temporary graphics context with default initial values. 


The graphics context is freed (and the normal drawing region is restored) when wEndRedraw is called. 


3-10 


3 WINDOWS 


wEndRedraw End a redraw 
VOID wEndRedraw (VOID) ; 

End a redraw. 

Drawing is set back to use the normal drawing region (which clips to the visible region of a window). 


If a temporary graphics context was created by calling wBeginRedrawGC, wBeginRedrawWinGC, 
wBeginRedrawGCO OF wBeginRedrawwineco, the temporary graphics context is freed. 


Validating 


Validating a rectangle in a window removes that rectangle from the window's update region (if the 
window has an update region). Validating the whole window deletes the window's update region. 


When responding to the receipt of a wm_REDRAw event (see the Events chapter) it is essential to perform a 
validation: until a window's update region has been entirely validated, wm_rEDRaw events will continue to 
be received. 


The normal response to a wM_REDRAW event is to perform a validation and to draw all or part of the window 
(drawing will be clipped to the intersection with the window's update region). The rectangle that is 
validated should correspond exactly to the rectangle that is drawn, rather than to the rectangle specified by 
the wM_REDRAW event. 


Depending on the window's background attribute, validation may also set, clear or leave unchanged all the 
pixels in the rectangle. You should set the background attribute to select the action that is most 
appropriate for the particular situation. 


If the background attribute of the window is w_wIN_BAck_cLR, validated pixels in the drawing region are 
cleared and if the background attribute is w_wIN_BACK_sET, the same pixels are set. 


In version 4 of the window server, these attributes refer to validated pixels in the normal (black) plane of 
the update region. In addition, if the background attribute w_wIN_BACK_GREY_CLR is set, validated pixels in 
the grey plane of the drawing region are cleared and if the background attribute w_wIN_BACK_GREY_SET 1S 
set, the same pixels are set. 


A way of ensuring flicker-free redrawing of a window is to set the background attribute to 
W_WIN_BACK_NONE and cover every pixel in the draw. 


In version 4 of the window server, the w_wIN_BACK_NONE attribute refers to the normal (black) plane. If you 
are also drawing to the grey plane, then the same result can be achieved in this plane by setting the 
W_WIN_BACK_GREY_NONE attribute. 


wValidateRect Validate a rectangle of a window 
VOID wValidateRect (UINT wid, .i.P_RECT *prect); 

Validate the rectangle prect in window wid. 

The struct p_rect is defined as: 


typedef struct 
{ 
WORD x; 
WORD y; 
} P_POINT; 


typedef struct 
{ 
P_POINT tl; /* top left pixel (internal) */ 
P_POINT br; /* bottom right pixel (external) */ 
} P_RECT; 


wValidateWin Validate a whole window 


VOID wValidateWin(UINT wid); 
Validate the whole of window wid. 


Equivalent to calling wvalidateRect with a rectangle covering window wid. 


3-11 


WINDOW SERVER REFERENCE 


a 
Invalidating 


Invalidating a rectangle in a window adds that rectangle to the window's update region. Invalidating the 
whole window sets the window's update region to cover the whole window. 


When a client wishes to draw an area in one of its windows, there are two approaches: 
e to draw directly to the area (normally after calling wvalidateRect or wValidateWin) 


e to invalidate a rectangle and make use of the code which redraws its window in response to a 
WM_REDRAW event 


The advantages of invalidating are: 
e It makes use of the code which must in any case be provided to redraw the window. 


e An application can effectively use the window server's update region to accumulate disjoint 
invalid areas without having to worry about whether those areas overlap (since overlapping areas 
will generate a single redraw). 


e Because the areas invalidated are clipped to the visible areas of the window, responding to the 
WM_REDRAW events can require less work than drawing the whole window (since the whole 
window may be partially or totally obscured or it may be invisible). 


The main disadvantage of invalidating is the loss of performance resulting from the extra context 
switching from the client to the window server to process the invalidate command and then back to the 
client to process the redraw. 


winvalidateRect Invalidate a rectangle 
VOID wiInvalidateRect (UINT wid, .i.P_RECT *prect) ; 

Invalidate the rectangle prect in window wid. 

The struct p_RecT is defined as: 


typedef struct 
{ 
WORD x; 
WORD y; 
} P_POINT; 


typedef struct 
{ 
P_POINT tl; /* top left pixel (internal) */ 
P_POINT br; /* bottom right pixel (external) */ 
} P_RECT; 


winvalidateWin Invalidate a window 
VOID wiInvalidateWin(UINT wid); 
Invalidate the whole of window wid. 


Equivalent to calling wInvalidateRect with a rectangle covering the whole of window wid. 


————e—————————— EE eT) 
Text cursor 


wTextCursor Draw a text cursor 


VOID wTextCursor(UINT wid, .i.W_CURSOR *pcursor) ; 
Present a text cursor (which is optionally flashing) in window wid. 


There is only one text cursor per client. If a text cursor already exists, it is removed before the new cursor 
is positioned (you do not have to call wzEraseTextCursor if you are moving the cursor to another position 
in the same or a different window). 


Version 4 of the window server allows the text cursor to appear grey. This is achieved by setting 
W_CURSOR_GREY in the flags member of the w_cursor structure. 


3-12 


3 WINDOWS 


The w_cursor struct is defined in wlib.h as: 


typedef struct 
{ 
WORD x; 
WORD y; 
} P_POINT; 


typedef struct 
{ 
P_POINT pos; /* text cursor position */ 
UBYTE height; /* text cursor height */ 
BYTE ascent; /* text cursor ascent */ 
UBYTE width; /* text cursor width */ 
UBYTE flags; /* for obloid cursor and to disable flashing */ 
} W_CURSOR; 


The height, ascent and width members specify the height, ascent and width of the text cursor. The flags 
member may be zero or it may contain any combination of the following bit flags: 


W_CURSOR_OBLOID to round off the corners of the cursor 
W_CURSOR_NO_FLASH to disable the flashing of the cursor 
W_CURSOR_GREY to make the text cursor appear grey 


The position of the cursor is consistent with positioning conventions for text where the top left of the 
cursor is ascent above the position passed to wrextCursor. In fact, the x, y position for wrextcursor 
should be the same as for drawing a text string. See the description of gPrintText in the Graphics Output 
chapter. 


Applications which use a vertical line cursor to indicate a position between two characters should (by 
convention) place the cursor in the leftmost position of the character cell which is to the right of the 
cursor. In this case, width is set to 1 (or 2), and ascent and height are set according to the font currently 
in use. 


A block or underline cursor is sometimes appropriate when using a monospaced font where width should 
be set to the width of a characters in the font. 


For an underline cursor, height should be set to 1. To draw the underline along the baseline of the font, 
ascent Should be set to zero. To draw it along the bottom line of the characters, ascent should be set to 
(font.ascent—font.height+1). 


The window server controls the flashing of the cursor and makes sure that it does not interfere with any 
drawing. 


On large screen versions of the window server such as the MC, the window server automatically ensures 
that only the foreground text cursor is visible. 


wDrawTextCursor Draw a text cursor 


VOID wDrawTextCursor(UINT wid, .i.W_CURSOR *pcursor) ; 


A now defunct function to support older applications which leave pcursor->flags undefined (before 
version 3.5 of the window server, pcursor->flags was a filler for word alignment). 


This function is the same as wrextCursor except that it ignores pcursor->flags and consequently does 
not support w_CURSOR_OBLOID, W_CURSOR_NO_FLASH OF W_CURSOR_GREY. 


New applications should use wrextcursor. 


wEraseTextCursor Erase a text cursor 
VOID wEraseTextCursor (VOID); 
Remove the caller's text cursor. 


In programming terms, calling this function when there is no cursor is harmless. However, be aware that 
careless use of this function can cause problems. 


3-13 


WINDOW SERVER REFERENCE 


Only one cursor is ever visible on the screen at any one time and wEraseTextCursor erases the text cursor 
regardless of the window in which it appears. An application, therefore, must ensure that a text cursor is 
erased at the appropriate time. 


An inappropriately timed call to weraseText Cursor can "steal" the cursor from the currently emphasised 
window. 


EEE 
Bitmap sequences 


The window server has the ability to attach an animated sequence of bitmaps to a window. This sequence 
specifies the bitmap, position, bitmap source rectangle, blit mode and time to wait before advancing the 
sequence. The sequence is set up by the wSetWinBitmap call, modified by the wchangewWinBitmap call and 
freed with wrree. 


A bitmap is displayed as part of the window background, and a client can draw on top of the bitmap. 
Because of this the client will normally be sent a wM_REDRAW event telling it to redraw the window 
containing the bitmap every time the sequence advances. If you do not require to draw on top of the 
bitmap you should set the w_wIn_No_REDRaw flag for the window so that your application is not slowed 
down by unnecessary WM_REDRAW events. 


wSetWinBitmap Attach bitmap sequence to window 
INT wSetWinBitmap(UINT wid, UINT count, .i.WS_WIN_BITMAP *pdata) ; 


Attach a sequence of one to twelve bitmaps to window wid where pdata is the address of an array of count 
bitmap sequence records. 


The structure of a bitmap sequence record is described by the ws_wIn_BiTmap struct which is defined as: 


typedef struct 
{ 
WORD x; 
WORD y; 
} P_POINT; 


typedef struct 
{ 
P_POINT tl; /* top left pixel (internal) */ 
P_POINT br; /* bottom right pixel (external) */ 
} P_RECT; 


typedef struct 
{ 
WORD bitmap; /* Bitmap ID */ 
P_POINT pos; /* position of bitmap */ 
P_RECT rect; /* Source rectangle in bitmap */ 
UWORD mode; /* Blit mode */ 
ULONG time; /* Time till next bitmap in sequence */ 
} WS_WIN_BITMAP; 


where: 

bitmap is the bitmap ID. If any of the bitmaps in the sequence is freed before the 
bitmap sequence is freed, the window server will panic the calling client when 
it tries to display the freed bitmap. 

pos is the target position in the window wid of the top left of the bitmap 

rect is the rectangle within the bitmap to copy from 

mode is the graphics mode to use when copying the bitmap (one of G_TRMODE_REPL, 
G_TRMODE_SET Of G_TRMODE_CLR Or G_TRMODE_INV). In version 4 of the window 
server, a member of a bitmap sequence can be made to appear grey. This is 
achieved by OR'ing the flag ws_wIN_BITMAP_GREY into this member. 

time is the interval in tenths of a second after which the window server advances to 


the next bitmap (in a circular fashion). If this time is too short, the window 
server will hog the processor animating the bitmaps and the performance of the 
rest of the machine will be degraded. 


Returns the ID of the bitmap sequence. 


3-14 


3 WINDOWS 


wChangeWinBitmap Change a bitmap 
VOID wChangeWinBitmap(UINT bsid, UINT index, .i.WS_WIN_BITMAP *pdata) ; 
Replace bitmap sequence record index in the bitmap sequence with ID bsia with the contents of pdata. 


The whole of pdata must be set up even if only one of the elements of the structure is being changed. 


wFree Free a bitmap sequence 
VOID wFree(UINT bsid); 
Free bitmap sequence bsid. 


A bitmap sequence is automatically freed if the window it is attached to is destroyed. 


Sprites 
In version 4 of the window server, an animated sequence of bitmaps known as a 'sprite' can be created. 


While a sprite is 'connected' to a particular window, it differs from an animated bitmap sequence in that it 
is not displayed as part of the window background. The window server takes care of saving and restoring 
the contents of the underlying window display. This can give the impression of the sprite 'floating' above 
the underlying display. 


Each application (or client, in general) can have only one sprite at a time and each sprite consists of a 
sequence of up to thirteen bitmap sets. Each bitmap set consists of up to six bitmaps, three for the normal 
plane and three for the grey plane. 


wCreateSprite Create a sprite 


INT wCreateSprite (INT wid,P_POINT *pos,INT flags,INT count,.i.W_SPRITE *psprite); 


Available in version 4 of the window server, this function creates a sprite connected to the window with 
ID wia based at the position specified by the p_pornt struct pointed to by pos. 


The value of f1ags controls clipping of the sprite. If it contains the flag w_spRITE_CLIP_CHILDREN, the 
sprite will be clipped by any child windows of the window to which the sprite is connected. If this flag is 
not set, the sprite can only be clipped by other windows or by the limits of its own window. 


The use of the w_spRITE_CLIP_CHILDREN flag needs some care. If this flag is set, the sprite should not be 
connected to the root window. The application's top level window is always a child window of the root 
which would clip or overlay a sprite. 


Menus and dialog boxes are not child windows of any of the application's windows; therefore a sprite will 
always be clipped by menus and dialog boxes regardless of the setting of w_sPpRITE_CLIP_CHILDREN. 


The count parameter specifies how many bitmap sets the sprite has. 


The psprite parameter points to an array of w_spRITE structures, one for each bitmap set. Note, therefore, 
that there are count elements in the array. 


The structure of w_spRrteE is defined as follows: 


typedef struct 
{ 


WORD bit_set; /* (normal plane) bitmap for pixels to be set 1 A 
WORD bit_clr; /* (normal plane) bitmap for pixels to be cleared */ 
WORD bit_inv; /* (normal plane) bitmap for pixels to be inverted*/ 
WORD bit_gr_set; /*(grey plane) bitmap for pixels to be set ay: 
WORD bit_gr_clr; /* (grey plane) bitmap for pixels to be set */ 
WORD bit_gr_inv; /* (grey plane) bitmap for pixels to be set */ 


P_POINT offset; 
UWORD time; 
} W_SPRITE; 


3-15 


WINDOW SERVER REFERENCE 


The time parameter indicates the length of time in units of 1/10th of a second that the bitmap set is to be 
displayed. However, this field is ignored if the sprite consists of only one bitmap set (i.e. count is set to 
one). 


The members bit_set, bit_clr, and bit_inv contain the bitmap ids to be displayed in the normal plane 
using the modes G_TRMODE_SET, G_TRMODE_CLR and G_TRMODE_INV respectively (see the section on 
Graphics contexts in the chapter Graphics Output). 


Similarly, bit_gr_set, bit_gr_clr and bit_gr_inv contain the bitmap ids to be displayed in the grey 
plane. 


Note that setting a bitmap field to zero means that no bitmap will be used for the relevant plane and mode. 


The bitmap fields can be set in any combination as appropriate. Setting all of them to zero results in the 
sprite being left blank for the specified time. 


The offset parameter indicates the (x,y) offset of the top left-hand position of the bitmaps relative to the 
specified sprite position. 


All bitmaps within a bitmap set must be the same size or else E_GEN_aRG will be returned. 
If successful, the function returns the sprite id. 


If the application (or client, in general) already has a sprite, the function panics with panic 
W_PANIC_SPRITE_EXISTS. 


wSetSprite Change a sprite's bitmaps and position 


INT wSetSprite(INT id,P_POINT *pos, INT index,.i.W_SPRITE *psprite) ; 


Available in version 4 of the window server, this function allows the position and individual bitmap sets 
of an existing sprite to be changed. 


The parameter id must be a valid sprite handle as returned from a call to wcreateSprite, otherwise the 
function panics with a W_PANIC_SPRITE. 


If the parameter pos is not NULL, it is assumed to point to a P_POINT structure specifying the new position 
for the sprite. If the parameter is NULL, it is ignored and the sprite's position will be left unchanged. 


If the parameter psprite is not NULL, it is assumed to point to a W_SPRITE type structure specifying a new 
bitmap set. The index parameter indicates which of the original bitmap sets is to be replaced; a zero value 
refers to the first. If the psprite parameter is NULL, then both it and the index parameters are ignored and 
the sequence of the bitmap sets will be left unchanged. 


If the sprite is being enlarged, then this call can fail with an E_GEN_MEMory. Changing the position of the 
sprite cannot fail. 


wFree Free a sprite 
VOID wFree(UINT id); 


This function frees the sprite identified by the parameter ia. 


Clocks 


On the Series 3, the Series 3a and an HC that is running version 3.5 and upwards of the window server, 
the window server can maintain a date and time clock in a window. 


The various clock displays are influenced by the date and time related members of the E_conrie struct 
(see the description of p_getctd in the Time, Timers and Dates chapter of the PLIB Reference manual). 
On the S3 and S3a, the E_conFic struct is used to store system-wide user preferences. 


On the S3, the textual components of the clock displays use the $3 system font. 


On the HC, the font used for clock displays is determined by the sws_ir ("Internal Font") environment 
variable (as with all output that is not directed at a graphics context). The "factory" setting of this 
environment variable selects the same font as is used on the S3. 


3-16 


3 WINDOWS 


On the S3a, the clock displays depend on the function used to draw the clock. The description and 
discussion of the function wscreateClock (see below) applies equally to the S3 and the S3a. However, 
wsCreateClock was designed for the S3 with its 240 x 80 pixel screen. On the S3a with its 480 x 160 
pixel screen, a clock drawn using wsCreateClock will 'work' but will appear clumsy and ungainly. 


The enhanced version 4 function wscreateClock2 1s to be preferred for applications running on the S3a. 


wsCreateClock Create a clock 


INT wsCreateClock(UINT wid, UINT flags, INT xpos, INT ypos, INT offset); 


In version 4 of the window server, this function is superseded by wscreateClock2 which includes ALL of 
its functionality. wscreateClock should only be used if running earlier versions of the window server. 


Create and maintain a clock at pixel position (xpos,ypos) in window wid. The clock displays the system 
time offset by offset minutes. 


In all cases, (xpos,ypos) specifies the internal position of the top left corner of a rectangle containing the 
time display. 


The appearance of the clock is controlled by the f1ags parameter which should be one of: 


WS_CLOCK_SMALL_DIGITAL To present a small digital clock. Displayed in the system font on the S3. 
Displayed in the S3 system font on the S3a (in native and compatibility 
mode). Displayed in the ‘internal’ font on the HC (as used by wInfomsg and 
wSetBusyMsg). The coordinates (xpos,ypos) specify the top left corner of 
the rectangle containing the first character of the time display. 


WS_CLOCK_MEDIUM To display a medium sized clock in either digital (using double height 
characters) or analogue (using a 36x32 bitmap) form. Unless overridden by 
the flags described below, the selection between analogue and digital is 
controlled by the clockType member of the z_conFie struct (which should 
contain either E_ANALOGUE_CLOCK Of E_DIGITAL_CLOCK). Whether digital or 
analogue, the coordinates (xpos,ypos) specify the top left corner of a 36 
pixel wide by 32 pixel high rectangle containing the time display. 


WS_CLOCK_LARGE_ANALOG To display a large analogue clock using a 66x60 bitmap. The coordinates 
(xpos,ypos) specify the top left corner of the 66 pixel wide by 60 pixel high 
clock bitmap. 


The above values may be qualified by oring in combinations of the following flags: 


WS_CLOCK_WITH_DATE To also display the date. With ws_cLocK_SMALL_DIGITAL, the date is 
displayed to the left of the time. With ws_cLock_mEep1um, the date is 
displayed under the time. Not available with ws_cLocK_LARGE_ANALOG. 


WS_CLOCK_WITH_SECONDS To also display seconds. With ws_cLock_sMALL_DIGITAL, the seconds field 
is added to the end of the display. With ws_cLock_LARGE_ANALOG, a second 
hand is added. Not available with ws_cLock_mMEDIUM. 


WS_CLOCK_FORCE_ANALOG Valid only with ws_cLock_mep1vm to display an analogue clock regardless 
of the value of the clockType member of the z_conrie struct. 


WS_CLOCK_FORCE_DIGITAL Valid only with ws_cLock_mep1vm to display a digital clock regardless of 
the value of the clockType member of the =_conrFie struct. 


WS_CLOCK_AM_PM To also display an am/pm indicator when the timeType member of the 
E_CONFIG Struct is E_TIMEz_12 (although the relative positions may still be 
altered when timeType iS E_TIME_24). With ws_cLOCK_SMALL_DIGITAL, the 
am/pm indicator is displayed at the end of the time string. With a 
WS_CLOCK_MEDIuM analogue clock, the am/pm indicator is displayed to the 
right of the base of the clock face. With a ws_cLock_mep1Ivm digital clock, 
the time digits are moved up and the am/pm indicator is displayed between 
the time digits and the position of the date. Ignored if 
WS_CLOCK_LARGE_ANALOG is set. 


WS_CLOCK_CENTERED Only applies to ws_cLocK_SMALL_DIGITAL with ws_cLOcK_AM_pPM set. 
Causes the time string to be centred in the wider space that allows for the 
am/pm indicator when the timeType member of the E_conr1e struct is 
E_TIME_24. 


3-17 


WINDOW SERVER REFERENCE 


If successful, the function returns the ID to use when calling wsSetClock and wrree. Otherwise, the 
function can leave or return &_GEN_NOMEMORY. 


The following sample program: 


#include <plib.h> 
#include <wlib.h> 


LOCAL_D WSERV_SPEC wSpec; 
LOCAL_D UINT wid; 


LOCAL_C VOID MainEventLoop (VOID) 


WS_EV event; 


for (77) 

{ 

wGetEventWait (&event) ; 

if (event .type==WM_REDRAW) 
{ 
wBeginRedrawWinGCO (wid) ; 
gBorder (W_BORD_SHADOW. D|w BORD_SHADOW_ON) ; 
wEndRedraw (); 
} 


} 


GLDEF_C VOID main(VOID) 
{ 
wConnect (&wSpec, 0,W_CONNECT_PRIORITY) ; 
wid=wCreateWindow(0,0,0,1); 
wsCreateClock (wid, WS_CLOCK_LARGE_ANALOG|WS_CLOCK_WITH_SECONDS, 4, 4,0); 


wsCreateClock (wid, WS_CLOCK_MEDIUM|WS_CLOCK_FORCE_DIGITAL|WS_CLOCK_WITH_DATE, 4+66+6, 4,0 
i 


wsCreateClock (wid, WS_CLOCK_MEDIUM|WS_CLOCK_FORCE_ANALOG | WS_CLOCK_WITH_DATE, 4+66+6+36+6 
14,0); 


wsCreateClock (wid, WS_CLOCK_SMALL_DIGITAL|Wws CLOCK_WITH DATE |WS CLOCK_WITH_SECONDS, 104, 
66,0); 

wiInitialiseWindowTree (wid) ; 

MainEvent Loop () ; 


} 


when run on an HC, produces: 


1438 L-: 


fon 24 Mon 28 


Morn 28 Jan 14835812 


Note that the seconds field of the small digital clock is badly drawn because it changed from 11 to 12 
while the screen was being captured. 


The screen was in fact captured using the scapt program described in the Bitmaps section of the first 
chapter. It is left as an exercise for the reader to convert pcxsave.c (which is used by scapt) to take true 
snapshots of a changing screen?. 


3One strategy is to save the screen as a bitmap to a temporary local file using gsaveBit and then to 
convert the file. 


3-18 


3 WINDOWS 


wsCreateClock2 Create a clock - Enhanced version 


INT wsCreateClock2(.i.WS_CREATE_CLOCK *pclock,TEXT *pfmt) ; 


This function is introduced in version 4 of the window server and is an enhanced version of the 
wsCreateClock function. It is much preferred and should be used for applications designed to run on the 
Series 3a. 


Note that this function includes the functionality of wscreateClock. 


The clock it creates is based on the values in the ws_cREATE_CLOcK structure pointed to by the parameter 
pclock and the value in the second parameter pfmt. 


The structure ws_CREATE_cLocK can be found in wilib.h but is defined as follows: 


typedef struct 
{ 
UINT id; /* window ID */ 
UINT type; /* clock type */ 
P_POINT pos; /* position ey: 
INT offset; /*time offset */ 
INT flags; /*clock flags */ 
INT font; 
INT style; 
} WS_CREATE_CLOCK; 


The function creates a clock in window id at position pos of the specified type. The clock displays the 
system time offset by the number of minutes specified in the of fset member. 


The possible values for type and flags include those values which can be specified in the flags 
parameter in the old wscreateClock function. However, in wsCreateClock2, some values apply to type 
while the others apply to flags. 


The second parameter pfmt and the ws_cREATE_CLOCK members font and style are only relevant when 
the type of clock being created is ws_cLocK_FORMATTED. For all other types of clock pfmt must be set to 
NULL. 


To summarise, type should be one of the following: 


WS_CLOCK_SMALL_DIGITAL To present a small digital clock. This clock has the appearance as described 
in wsCreateClock and is designed for the Series 3 screen. On the Series 3a 
in non-compatibility mode it will appear small and is not recommended. 


WS_CLOCK_MEDIUM To present a medium sized clock. This clock has the appearance as 
described in wsCreateClock and is designed for the Series 3 screen. On the 
Series 3a in non-compatibility mode it will appear small and is not 
recommended. 


WS_CLOCK_MEDIUM2 To display a medium sized clock that is larger than the old medium sized 
clock. It behaves in a similar way to the old medium clock in that, unless 
overridden by the flags described below, the selection between analogue and 
digital is controlled by the clockType member of the E_conFIe struct. 


This clock is drawn using black/white and grey. The analog clock uses a 
58x51 bitmap. 


WS_CLOCK_LARGE_ANALOG To display a large analog clock. This clock has the appearance as described 
in wsCreateClock and is designed for the Series 3 screen. On the Series 3a 
in non-compatibility mode it will appear small and is not recommended. 


WS_CLOCK_XL_ANALOG To display an extra-large analog clock as used in alerts. 
This clock is drawn using black/white and grey. It uses a 99x99 bitmap. 


WS_CLOCK_FORMATTED To display a formatted digital clock/date. The display is controlled by the 
format string whose address is passed in the second parameter pfmt. The 
meaning of the format string is the same as for the PLIB function p_dt2str. 
See the PLIB manual for more detail on the syntax and meaning of this 
string. The font and style are specified by the font and style parameters in 
the ws_CREATE_CLOCK Structure. 


The clock types described above can be modified by setting combinations of the following flags in the 
flags member of the ws_cREATE_CLOcK Structure: 


3-19 


WINDOW SERVER REFERENCE 


WS_CLOCK_WITH_DATE 


WS_CLOCK_WITH_SECONDS 


WS_CLOCK_FORCE_ANALOG 


WS_CLOCK_FORCE_DIGITAL 


WS_CLOCK_AM_PM 


WS_CLOCK_CENTERED 


WS_CLOCK_BOX 


WS_CLOCK_GREY 


To also display the date. With ws_cLockK_SMALL_DIGITAL, the date is 
displayed to the left of the time. With ws_cLock_mMED1um and 
WS_CLOCK_MEDIUM2, the date is displayed under the time. Not available with 
WS_CLOCK_LARGE_ANALOG Or WS_CLOCK_XL_ANALOG. Not applicable to 
WS_CLOCK_FORMATTED. 


To also display seconds. With ws_cLocK_SMALL_DIGITAL, the seconds field 
is added to the end of the display. With ws_cLockK_LARGE_ANALOG, 
WS_CLOCK_XL_ANALOG and the analog version of WS_CLOCK_MEDIUM2, a 
second hand is added. Not available with ws_cLocK_Mep1Iv™ or the digital 
version of WS_CLOCK_MEDIuM2. Not applicable to ws_cLOcK_FORMATTED. 


Valid only with ws_cLock_MEDIUM and WS_CLOCK_MEDIUM2 to display an 
analogue clock regardless of the value of the clockType member of the 
E_CONFIG struct. Not applicable to ws_cLOCK_FORMATTED. 


Valid only with ws_cLock_MEDIUM and WS_CLOCK_MEDIUMz2 to display a 
digital clock regardless of the value of the clockType member of the 
E_CONFIG struct. Not applicable to ws_cLOCK_FORMATTED. 


Valid as for wsCreateClock. In addition, this is not available for 
WS_CLOCK_MEDIUM2 and is not applicable to ws_cLOCK_FORMATTED. 


Only applies to ws_cLOCK_SMALL_DIGITAL with ws_CLOCK_aAM_PM set. Causes 
the time string to be centred in the wider space that allows for the am/pm 
indicator when the timeType member of the E_CONFIG struct is E_TIME_24. 
Not applicable to ws_cLOCK_FORMATTED. 


Only applies to ws_cLocK_FORMATTED. Causes graphics to be drawn 
enclosing the formatted clock as shown in one of the examples. 


If set, it causes those clocks which are normally drawn in black & white 
only, to be drawn in grey. 


It has no effect on those clocks which are drawn in both black/white and 
grey. 


If successful, the function returns the ID to use when calling other 'clock' functions such as wsSet Clock 


and wFree. 


For example, when run on the S3a, the code: 


#include <plib.h> 
#include <wlib.h> 


GLREF_D WSERV_SPEC wSpec; 
GLREF_D UINT wMainWid; 


LOCAL_C VOID MainEventLoop (VOID) 


{ 
WS_EVENT event; 


for (77) 


{ 


wGetEventWait (&event) ; 
if (event .type==WM_KEY) 


{ 


if (event.p.key.keycode==W_KEY_RETURN) 


break; 


3-20 


3 WINDOWS 


GLDEF_C INT main (void) 
{ 
WS_CREATE_CLOCK clock; 


wConnect (&wSpec, 0,W_CONNECT_PRIORITY) ; 
wCompatibilityMode (0, &wSpec) ; 
wMainWid = wCreateWindow(0,0,0,1); 


winitialiseWindowTree (wMainWid) ; 
clock.id = wMainWid; 

clock.type = WS_CLOCK_XL_ANALOG; 
clock.pos.x = 200; 

clock.pos.y = 40; 

clock.offset = 0; 

clock.flags = WS_CLOCK_WITH_SECONDS; 


wsCreateClock2 (&clock, NULL) ; 
MainEventLoop() ; 
return (0); 


} 


displays the extra large analog clock with 
a seconds hand as shown opposite. 


An example of a formatted clock is given next. The digital clock/date is displayed in bold, with double 
height and surrounded by a neat box. The code used to display the clock is as follows: 


#include <plib.h> 
#include <wlib.h> 
#include <fonts.h> 


GLREF_D WSERV_SPEC wSpec; 
GLREF_D UINT wMainWid; 


LOCAL_C VOID MainEventLoop (VOID) 
{ 
WS_EVENT event; 


for (77) 
{ 
wGetEventWait (&event) ; 
if (event .type==WM_KEY) 
{ 
if (event.p.key.keycode==W_KEY_RETURN) 
break; 


GLDEF_C INT main (void) 
{ 
WS_CREATE_CLOCK clock; 


wConnect (&wSpec, 0,W_CONNECT_PRIORITY) ; 
wCompatibilityMode (0, &wSpec) ; 

wMainWid = wCreateWindow(0,0,0,1); 
wiInitialiseWindowTree (wMainWid) ; 


3-21 


WINDOW SERVER REFERENCE 


clock.id = wMainWid; 

clock.type = WS_CLOCK_FORMATTED; 

clock.pos.x = 150; 

clock.pos.y = 70; 

clock.offset = 0; 

clock.flags = WS_CLOCK_BOX; 

clock.font = FONT_ID_SWISS_8; 

clock.style = G_STY_DOUBLE|G_STY_BOLD; 
wsCreateClock2 (&éclock, "Sh%:%m%:%s Se %da%/Sm%s/Sy") ; 


MainEvent Loop (); 
return(0); 


} 


Take particular note of the text string 
forming the second parameter to 1 — 
wsCreateClock2. The format and structure | 17a Wednesday 18/88/1993 
of this text string governs the display of 
this clock. 


wsSetClock Set the clock offset 


VOID wsSetClock (INT clock_id, INT offset); 


Change the time offset (in minutes from the system time) of clock clock_id (where clock_id was 
returned from a call to wscreateClock). 


wFree Free a clock 
VOID wFree(INT clock_id); 
Free the clock clock_id (where clock_id was returned from a call to wscreateClock). 


A clock is automatically freed if the window it contains is closed as a result of a call to 
wCloseWindowTree. If a clock is freed by wcloseWindowTree, it must not be freed a second time by a call 
to wFree. 


Mouse icons 


On the large screen version of the window server (such as that on the MC), each window has an 
associated mouse icon - as specified by the mouse icon ID in the mouse_icon window attribute. The 
mouse_icon window attribute is set when you create the window by calling wcreateWindow and it may 
subsequently be changed by calling wset Window 


Mouse icons can be selected from one of three categories: 


e The two built-in icons, the default icon w_WwIN_MI_STANDARD and the invisible mouse icon 
W_WIN_MI_NULL. 


¢ ROM-based icons which are automatically loaded by the window server when it boots up. 


e External mouse icons which are loaded from a file by calling gopenMouseIcon (which returns the 
mouse icon ID). 


On MC machines, the following mouse icons are built into the ROM: 
W_WIN_MI_STANDARD standard mouse icon. 

W_WIN_MI_NULL invisible mouse icon. 

W_WIN_MI_PUSHER hollow standard mouse icon. 
W_WIN_MI_TEXT text window mouse icon. 

W_WIN_MI_CROSS cross. 


3-22 


W_WIN_MI_MARGIN text window margin icon. 
W_WIN_MI_PG_DOWN page down scroll bar icon. 
W_WIN_MI_PG_UP page up scroll bar icon. 
W_WIN_MI_VSLIDE scroll bar vertical slider icon. 
W_WIN_MI_HSLIDE scroll bar horizontal slider icon. 
W_WIN_MI_TO_BIG resize gadget expand window icon. 
W_WIN_MI_TO_SMALL resize gadget shrink window icon. 
W_WIN_MI_RESIZE resize gadget move-resize icon. 
W_WIN_MI_MOVE move window icon. 

W_WIN_MI_LEFT horizontal scroll bar move left icon. 
W_WIN_MI_RIGHT horizontal scroll bar move right icon. 
gOpenMouselcon 


INT gOpenMouselIcon(TEXT *filename, UINT index) ; 


Load mouse icon index from file filename. 


3 WINDOWS 


Load a mouse icon 


Returns the positive ID of the mouse icon to use in the w_winpata structure when calling wsetwindow or 


wCreateWindow. 


If an error with error number err occurs while loading the mouse icon, the function calls p_leave (err) or 


returns err, depending on whether wDisableLeaves has been called. 


If filename is not a full file specification, the unspecified components are taken from the window server's 


default path which, in practice, is always the internal drive M:\. 


See also gSetOpenAddress in the next chapter for loading a mouse icon file which is embedded in another 


file. 


wFree 


VOID wFree(UINT mouse_icon_id) ; 


Free a mouse icon. 


Any windows using the freed icon revert to using the default icon. 


Free a mouse icon 


3-23 


CHAPTER 4 


GRAPHICS OUTPUT 


Graphics contexts 


You must create a graphics context before performing any graphics output (apart from the screen and 
window directed graphics described in the previous two chapters). 


The use of a graphics context reduces the number of parameters required when calling graphics functions. 
A graphics context contains the following: 
e the ID of a drawable (a window or a bitmap) that is the ultimate recipient of the graphics output 


e whether to set, clear or invert pixels when drawing lines using gDrawLine, gDrawPolyLine, 
gDrawBox, gBorderRect, gBorder, gBorder2Rect Of gBorder2 


e the font, style and transfer mode to use when drawing text using gPrintText, gPrintClipText, 
gXPrintText, gPrintBoxText OF gShadowText. 


The drawable is set once and for all when the graphics context is created (using gcreateGc or a variant 
thereof). The rest of the content can be set up when the graphics context is created and it can also be 
altered subsequently (using gSetcc). 


A graphics context is set with the aid of a c_cc struct, which is defined in wlib.h as: 


typedef struct 
{ 


UBYTE gmode; /* mode for line drawing */ 

UBYTE textmode; /* mode for writing text */ 

UBYTE style; /* style of text: bold, underline etc. */ 
UBYTE flags; /* controls use of grey & double pixel mode */ 
WORD font; /* ID of font to use */ 

} G_GC; 


Note that the flags member is introduced in version 4 of the window server. Prior to version 4, the space 
occupied by this member was unused. 


Introduced in version 4, grey is available (in one shade only) on the S3a and Workabout. At a software 
level this is implemented by introducing the concept of a plane. 


There are two planes to which drawing can be directed. The normal plane can be thought of as being 
associated with the drawing of black while the grey plane, as its name implies, is associated with the 
display of grey. 


Drawing is normally done to one or both planes. However, they are not entirely independent; for example, 
to display grey, the normal plane should be clear and the grey plane set. If a pixel in the normal plane is 
set, it is displayed black regardless of the grey plane setting. This is best thought of as the normal plane 
‘overlaying’ the grey plane. 


Also introduced in version 4, all graphic commands can be set to perform all drawing with double sized 
pixels. This feature is motivated by the need to run Series 3 applications on the Series 3a; in other words, 
to use the S3a in S3 compatibility mode. 


4-1 


WINDOW SERVER REFERENCE 


gmode 


The gmode field is used by the line drawing functions gDrawLine, gDrawPolyLine, gDrawBox, 
gBorderRect, gBorder2Rect, gBorder, gBorder2, wDOrawButton and wDrawButton2 and may be one of: 


G_TRMODE_SET set pixels in the line. This is the default. 
G_TRMODE_CLR clear pixels in the line. 

G_TRMODE_INV invert pixels in the line. 

textmode 


The textmode field controls the method of writing text in gPrintText and gPrintClipText and may be 
any of: 


G_TRMODE_SET where Is in the font set bits in the destination and Os do not change bits in the 
destination (used to print on to a previously cleared area). This is the default. 


G_TRMODE_REPL where Is and Os in the font overwrite the destination (used to print over 
unprepared areas). 


G_TRMODE_CLR where Is in the font clear bits in the destination and Os do not change bits in 
the destination (used to print on to a previously set area). 


G_TRMODE_INV where Is in the font toggle corresponding bits in the destination and Os in the 
source pattern do not change bits in the destination (used to print over an 
existing image and may be reversed by a second application). 


style 


The style field controls the style of text in gPrintText, gPrintClipText, gXPrintText, gPrintBoxText, 
gShadowText, wDrawButton and wDrawButton2. The precise mechanism of applying a style depends on 
the version of the window server. Prior to version 4, styles may be any combination of: 


G_STY_NORMAL text is drawn as it is in the font. This is the default. 


G_STY_BOLD text is drawn bolded (generally bolded characters are one pixel wider than 
normal characters). 


G_STY_UNDERLINE text is drawn underlined where each character (including space) is drawn with 
a horizontal line beneath its graphic. 


G_STY_INVERSE text is drawn in inverse video (where the bits in the font are inverted before 
drawing). 
G_STY_DOUBLE text is drawn with double height characters where each row of pixels in the 


character graphic is doubled up before drawing. 


G_STY_MONO text is drawn with additional space around the characters of a proportional font 
to turn it into a monospaced font. For this to be effective, the proportional font 
should be designed with monospacing in mind (as is the built in font on the 


Series 3). 

G_STY_ITALIC text is drawn italicised by shifting the top half of each character across by one 
pixel. 

G_STY_SUPERSCRIPT indicates an intention to draw in superscript, not processed by the window 
server. 

G_STY_SUBSCRIPT indicates an intention to draw in subscript, not processed by the window server. 


Fast text printing of a fast font only works with normal style or with just c_sty_mono. The use of any other 
style will cause text drawing to fall back to the slower algorithm. 


In version 4 of the window server and upwards, the above styles still apply. However, in version 4, font 
groups are available as discussed in the section on ROM-based fonts in the Introduction chapter of this 
manual and in the description of gconfigureFonts later in this chapter. 


If the font to which the above styles (except G_sTY_SUPERSCRIPT and G_STY_SUBSCRIPT) are applied is a 
font group, then the window server will select the most appropriate font from within that group. 


4-2 


4 GRAPHICS OUTPUT 


Depending on how the font group is configured and the combination of styles to be applied, some further 
algorithmic styling, as described above, may be necessary. 


In version 4 of the window server and upwards, the following two styles are also available: 


G_STY_SUPERSCRIPT2 text is drawn in superscript. This style only has meaning when used in 
conjunction with a font group configured with a suitable superscript font. 


If this style is used with a single font (ie not a font group), then the style is 
ignored. 


G_STY_SUBSCRIPT2 text is drawn in subscript. This style only has meaning when used in 
conjunction with a font group configured with a suitable subscript font. 


If this style is used with a single font (ie not a font group), then the style is 
ignored. 


Note that when configuring a font group to include fonts for the c_sty_suPERSCRIPT2 and 
G_STY_SUBSCRIPT2 Styles, the AscentAdjust field in the c_ront_conrie data structure can be used to 
adjust the font's ascent when printing (see the gconfigureFonts function later in this chapter). 


The bits c_sty_SUPERSCRIPT and G_sTy_SUBSCRIPT are reserved for higher level software. For example: 


LOCAL_C VOID DrawTextBox(INT fid, INT style,TEXT *str,P_RECT *prect,INT ascent) 
{ 
G_GC gc; 


gc.font=fid; 
gc.style=style; 
gSetGC (0, G_GC_MASK. FONT |G GC_MASK_STYLE, &gc) ; 
if (style&G_STY_SUPERSCRIPT) 
ascent-—=1; 
if (style&G_STY_SUBSCRIPT) 
ascentt=1; 
gPrintBoxText (prect, ascent, G_TEXT_ALIGN_LEFT,0,str,p_slen(str)); 
} 


flags 


Introduced in version 4 of the window server, the flags member is used to indicate the plane to which 
drawing is to be directed. It is also used to indicate whether drawing should be done in double or single 
pixel mode. Possible values are: 


G_GC_FLAG_GREY_PLANE graphics drawing is directed to the grey plane only 
G_GC_FLAG_BOTH_PLANES — graphics drawing is directed to both the grey plane and the normal plane 


G_GC_FLAG_DOUBLE if set, all drawing is done in double pixel mode. Unsetting this puts the GC 
back into single pixel mode; this can be used to reverse a previous call to set 
double pixel mode or in windows that are in this mode by default either 
because the application is in compatibility mode or the window has the 
W_WIN_DOUBLE_PIxEL flag set. 


Note that this flag should not be set if drawing is done to a backed-up 
window. If the window needs to be restored from the backup, then the 
drawing will be displayed in single pixel mode. In this situation, it is best to 
set the whole window into double pixel mode. 


font 


The font field contains the ID of the font to be used in gPrint Text, gPrintClipText, gXPrintText, 
gPrintBoxText, gShadowText, wDrawButton and wDrawButton2. 


The font ID may be that of a ROM-based font or an ID of a font that was loaded from a file by calling 
gOpenFont. 


The ROM-based font IDs start at ws_ronT_BaAsE and you can use wS_FONT_BASE+1 etc for as many fonts as 
are built into the ROM. 


By default, a graphics context is initialised with the ID of the system font (as described in the section Text 
fonts in the first chapter). You can reset a graphics context back to the system font by specifying 
WS_FONT_SYSTEM. 


4-3 


WINDOW SERVER REFERENCE 


a —Ss 
Creating a permanent graphics context 


gCreateGC Create a permanent GC 
INT gCreateGC(UINT drawable_id, UINT field_set, G_GC *pgc); 


Create a permanent graphics context that is assigned to the drawable drawable_id (the ID of a previously 
created window or bitmap) and select the created graphics context as current. 


The c_cc struct is defined as: 


typedef struct 
{ 


UBYTE gmode; /* G_TRMODE_SET, _CLR, _INV (line) */ 

UBYTE textmode; /* G_TRMODE_SET, _CLR, _INV, _REPL (text) */ 

UBYTE style; /* G_STY_NORMAL, _BOLD, _UNDERLINE, _INVERSE, _DOUBLE, _MONO, 
_ITALIC */ 

UBYTE flags; /* G_GC_FLAG_DOUBLE, _GREY_PLANE, _BOTH_PLANES */ 

WORD font; /* ID of font to use */ 

} G_GC; 


Note that the flags member is introduced in version 4 of the window server. Prior to version 4, the space 
occupied by this member was unused. 


If field_set is Zero, pgc is ignored and the graphics context is created with default values (but, in this 
case, you should use gcreateGCco). 


If field_set is non-zero it should contain a bit mask to specify which fields in pgc are used to set the 
graphics context, as follows: 


G_GC_MASK_GMODE to use pgc->gmode 

G_GC_MASK_TEXTMODE to use pgc->textmode 

G_GC_MASK_STYLE to use pgc->style 

G_GC_MASK_FONT to use pgc->font 

G_GC_MASK_GREY to use pgc->flags (looks at G_GC_FLAG_GREY_PLANE and 


G_GC_FLAG_BOTH_PLANES only) (version 4 only) 
G_GC_MASK_DOUBLE to use pge->flags (looks at G_GC_FLAG_DOUBLE only) (version 4 only) 
Returns the ID of the graphics context if successful. 


If an error (with error number err) occurs, the function calls p_leave (err) or returns err, depending on 
whether wDisableLeaves has been called. Possible values for err are: 


E_GEN_NOMEMORY insufficient system memory 
E_GEN_ARG an invalid gmode, textmode, style or font was specified 
E_GEN_FAIL none of the grey background modes had been previously set for the window and 


an attempt was made to set G_GC_FLAG_GREY_PLANE. This error can only be 
returned in version 4 of the window server. 


In version 2 of the window server, the function calls p_panic if an invalid gmode, textmode, style or font 
is specified. 


In version 4 of the window server, setting the c_cc_MasK_GcREyY bit in field_set causes the window server 
to look at the two grey flags in the flags member; setting the G_cc_MASK_DOUBLE bit in field_set causes 
the window server to look at the double pixel flag in the flags member. 


Setting G_GC_FLAG_GREY_PLANE directs graphics to the grey plane only, while setting 
G_GC_FLAG_BOTH_PLANES directs graphics to both the normal and the grey planes. 


Setting G_GC_FLAG_DOUBLE causes all drawing to be done in double pixel mode. 


4 GRAPHICS OUTPUT 


gCreateGCO Create a permanent GC with default values 
INT gCreateGCO(UINT drawable_id); 
A code saving convenience routine, equivalent to: 


gCreateGC (drawable_id,0,0); 


wFree Free a permanent GC 
VOID wFree(UINT gc_id); 

Free the permanent graphics context with ID gc_ia. 

To free a temporary graphics context, use gFreeTempGc not wrree (WS_TEMPORARY_GC) . 


Because graphics contexts consume memory, they should be freed when they are no longer required. 


Creating a temporary graphics context 


gCreateTempGC Create a temporary GC 


VOID gCreateTempGC (UINT drawable_id, UINT field_set, G_GC *pgc); 


Create a temporary graphics context that is initialised with those fields from pgc which have their 
corresponding bit fields set in field_set. 


The c_cc struct is defined as: 


typedef struct 
{ 


UBYTE gmode; /* G_TRMODE_SET, _CLR, _INV (line) */ 

UBYTE textmode; /* G_TRMODE_SET, _CLR, _INV, _REPL (text) */ 

UBYTE style; /* G_STY_NORMAL, _BOLD, _UNDERLINE, _INVERSE, _DOUBLE, _MONO, 
_ITALIC */ 

UBYTE flags; /* G_GC_FLAG_DOUBLE, _GREY_PLANE, _BOTH_PLANES */ 

WORD font; /* ID of font to use */ 

} G_GC; 


where the bit fields for field_set are: 


G_GC_MASK_GMODE corresponding to gmode 
G_GC_MASK_TEXTMODE corresponding to textmode 
G_GC_MASK_STYLE corresponding to style 
G_GC_MASK_GREY corresponding to flags (version 4 only) 
G_GC_MASK_DOUBLE corresponding to flags (version 4 only) 
G_GC_MASK_FONT corresponding to font 


Note that the f1ags member is introduced in version 4 of the window server. Prior to version 4, the space 
occupied by this member was unused. 


The behaviour is as for gcreatecc, apart from the following: 


@ gCreateTempcc does not return an ID. This improves efficiency, because the window server does 
not have to reply to the gcreateTempGc. 


@ gCreateTempcc remembers the currently selected permanent graphics context (if any), and 
gFreeTempec reselects that same graphics context. 


4-5 


WINDOW SERVER REFERENCE 


While a temporary graphics context exists, you may not call: 
e gCreateGC 
e gCreateTempGC 
e gSetGCo 
@ gSetéc to set a graphics context other than ws_TEMPORARY_GC 
e wrree (for any graphics context) 


e wBeginRedrawGC, wBeginRedrawGC0, wBeginRedrawWinGC Or wBeginRedrawWinGCO 


gCreateTempGCOo Create a temporary GC with default values 
VOID gCreateTempGC0 (UINT drawable_id) ; 
A code saving convenience routine, equivalent to: 


gCreateTempGC (drawable_id,0,0); 


gFreeTempGC Free a temporary GC 
VOID gFreeTempGC (VOID) ; 
Free the temporary graphics context created by gcreateTempGc or gCreateTempGCo. 


If a permanent graphics context was current before the temporary graphics context was created, it is 
reselected. 


Setting a graphics context 


gSetGC Set a graphics context 


VOID gSetGC(UINT gc_id, UINT field_set, G_GC *pgc); 


Select gc_id as the current graphics context and alter those fields from pge which have their 
corresponding bit fields set in field_set. 


The c_cc struct is defined as: 


typedef struct 
{ 


UBYTE gmode; /* G_TRMODE_SET, _CLR, _INV (line) */ 

UBYTE textmode; /* G_TRMODE_SET, _CLR, _INV, _REPL (text) */ 

UBYTE style; /* G_STY_NORMAL, _BOLD, _UNDERLINE, _INVERSE, _DOUBLE, _MONO, 
_ITALIC */ 

UBYTE flags; /* G_GC_FLAG_DOUBLE, _GREY_PLANE, _BOTH_PLANES */ 

WORD font; /* ID of font to use */ 

} G_GC; 


where the bit fields for field_set are: 


G_GC_MASK_GMODE corresponding to gmode 
G_GC_MASK_TEXTMODE corresponding to textmode 
G_GC_MASK_STYLE corresponding to style 
G_GC_MASK_GREY corresponding to flags 
G_GC_MASK_DOUBLE corresponding to flags 
G_GC_MASK_FONT corresponding to font 


Note that the flags member is introduced in version 4 of the window server. Prior to version 4, the space 
occupied by this member was unused. 


4-6 


4 GRAPHICS OUTPUT 


To alter a temporary graphics context with gsetGc, pass gc_id aS WS_TEMPORARY_GC. 


In version 3 and upwards of the window server, passing gc_ia as zero will modify the current graphics 
context, be it temporary or permanent. In version 2, passing a gc_id of zero will panic the process with 
panic number 85 (illegal graphics context ID). 


gSetGCo Make a permanent GC current 
VOID gSetGCO(UINT gc_id); 

Make the permanent graphics context with ID gc_ia current. 

Equivalent to: 


gSetGC (gc_id,0,0); 


———EE— EE —————————————— ESS — Sy 
Line drawing 


The functions in this section are all directed at the drawable associated with the current graphics context 
and are subject to the gmode field of the current graphics context. 


gDrawLine Draw a line 
VOID gDrawLine(INT xl, INT yl, INT x2, INT y2); 
Draw a line between pixel (x1,y1) and pixel (x2, y2). 


When drawing a horizontal line with y1 equal to y2, the line includes the pixel with the lower x 
coordinate and excludes the pixel with the higher x coordinate. 


Similarly, when drawing a vertical line with x1 equal to x2 the line includes the pixel with the lower y 
coordinate and excludes the pixel with the higher y coordinate. 


When drawing a line in which both coordinates change, the window server turns the coordinates of the 
end pixels into a rectangle with a top-left internal pixel and a bottom-right external pixel. The line 
drawing algorithm then fills in those pixels that are intersected by a mathematical line between the 
corners of the mathematical rectangle on the boundary of those pixels that are in the rectangle. 


gDrawPolyLine Draw a sequence of lines 
VOID gDrawPolyLine(INT x, INT y, WORD *plist); 
Draw a sequence of lines as specified in the polyline piist, starting at the position (x,y). 


A polyline is a sequence of line drawing and movement commands. The drawing is self-relative in that 
each operation is relative to the end point of the last. 


The polyline 1ist has the following structure: 


UWORD n; /* number of word-pairs following */ 
WORD xl, /* flag and x displacement */ 
WORD yl; /* y displacement */ 


/* 
Bit Bo As S22 FAs OM 9 6B 6252-4 32-21 0 
$----------------------------- +--+ 
| X-displacement | | Move/draw flag 
$----------------------------- +--+ 
| Y-displacement | 
$------------------------------- + 
af 
WORD x2,y2; /* 2nd flag and x, y displacement */ 
WORD xn,yn; /* nth flag and x, y displacement */ 


WINDOW SERVER REFERENCE 


Each element of the polyline list consists of an x,y displacement, and a bit flag that is set to move and 
clear to draw. The move/draw flag is held in bit 0 of the x displacement word where bits 1..15 contain the 
actual x displacement!. The y displacement is stored as normal. 


In version 2 of the window server plist is limited to 61 move/draw operations. 


For example, the following polyline draws a button consisting of two concentric squares of dimensions 
50x50 and 30x30 as in the following diagram: 


static WORD button[]= 
{ 


95, /* 9 operations follow */ 
50*2, 0, /* draw right 50 */ 
0*2, 50, /* draw down 50 */ 
-50*2, 0, /* draw left 50 */ 


0*2, -50, /* draw up 50 */ 
(10*2) |1, 10, /* move right 10, down 10 */ 


30*2, 0, /* draw right 30 */ 
0*2, 30, /* draw down 30 */ 
=30%*2; 0; /* draw left 30 */ 


0*2, -30 /* draw up 30 */ 
hi 


gDrawPolyLine(0,0,&button[0]); 


gDrawBox Draw a box 
VOID gDrawBox(P_RECT *prect) ; 

Draw a box composed of the outermost pixels in the rectangular block of pixels specified by prect. 

The P_RECT struct is defined as: 


typedef struct 
{ 
WORD x; 
WORD y; 
} P_POINT; 


typedef struct 
{ 
P_POINT tl; /* top left pixel (internal) */ 
P_POINT br; /* bottom right pixel (external) */ 
} P_RECT; 


gBorderRect Border a rectangle 


VOID gBorderRect (P_RECT *prect, UINT flags); 
This function is not available in version 2 of the window server. 


Draw a border inside the rectangular block of pixels specified by prect, as controlled by flags where 
flags should be one of: 


Zero to use corner type 2 
W_BORD_CORNER_1 to use corner type | 
W_BORD_CORNER_4 to use corner type 4 
W_BORD_OPEN a special case used for menus on the S3 and the S3a 


'For example, you can get the x displacement into bits 1..15 by multiplying the required x displacement 
by 2 (which also clears bit zero). If you want to move rather than draw, you must then set bit zero. 


4-8 


4 GRAPHICS OUTPUT 


One of the three corner types may be qualified by oring in a combination of the following bit fields: 


W_BORD_CUSHION to leave a one pixel clear cushion all around 

W_BORD_SHADOW_S for a single shadow area (mutually exclusive with w_porD_SHADOW_D) 
W_BORD_SHADOW_D for a double shadow area (mutually exclusive with w_porD_SHADOW_S) 
W_BORD_SHADOW_ON the pixels in the shadow area are set - otherwise they are cleared (meaningless 


unless either the w_BoRD_SHADOW_S OF W_BORD_SHADOW_D flag is set) 


W_BORD_TOP_ON to draw an arrow in the top right corner 
W_BORD_TOP_OFF to clear an arrow in the top right corner 
W_BORD_BOT_ON to draw an arrow in the bottom right corner 
W_BORD_BOT_OFF to clear an arrow in the bottom right corner 


The meanings of the flags are illustrated by the following diagrams: 


W_BORD_CUSHION |W_BORD_CORNER_1 


W_BORD_CUSHION |W_BORD_CORNER_4 W_BORD_CUSHION|W_BORD_SHADOW_S 


W_BORD_CUSHION |W BORD_SHADOW s|w. BORD_SHADOW_ON 


W_BORD_CUSHION |W BORD_CORNER 4|w BORD_SHADOW s|w. BORD_SHADOW_ON 


W_BORD_CUSHION |W BORD_CORNER 4|w. BORD_SHADOW. D|w BORD_SHADOW_ON 


W_BORD_CUSHION |W BORD_SHADOW. D|w BORD_SHADOW_ON W_BORD_OPEN 


W_BORD_SHADOW. D|w BORD_SHADOW_ON 


Although some of the effects may look gross on the above diagrams, bear in mind they will typically be 
used on much larger windows. 


Some of the flag combinations presuppose a minimum size of rectangle. 


4-9 


WINDOW SERVER REFERENCE 


The w_Borp_opEN flag is a special case that overrides all the others. The top two corners are drawn as for 
W_BORD_CUSHION |W_BORD_SHADOW_S |W_BORD_SHADOW_ON, but the bottom two are laws unto themselves. 
Note also the non-appearance of lines along the bottom. This is used for the header of a Series 3 or 
Series 3a pull-down menu. 


Except for those combinations designed to change shadows and arrows, the borders are designed to be 
drawn over a clear background. For example, those pixels at the perimeter of the rectangle that are 
obtained with w_BoRD_CUSHION are not explicitly cleared. 


The above assumes that gmode in the graphics context is set to G_TRMODE_SET (its default value). 


Drawing shadows 


The first line of a shadow is inset by 2 pixels at the bottom left and at the top right, and a second line (for 
double shadowing) is inset a further one pixel. 


At the bottom right, the outside line matches the inside line, just being displaced either one or two pixels 
diagonally downwards and outwards. 


The pixels that are set for w_BORD_SHADOW_ON are explicitly cleared when this flag is absent, so that the 
call 


gBorderRect (prect, W_BORD_SHADOW_S) ; 
can be used to de-emphasise a window formerly emphasised using 


gBorderRect (prect, W_BORD_SHADOW s|w. BORD_SHADOW_ON) ; 


Arrows 


The following shows the use of W_BORD_BoOT_oN to draw an arrow in the bottom right corner on the S3 or 
the S3a: 


Process name Alloc bytes Alloc cells Let stack 
Sy SEMANGEAS 
SSE SRY EAS CFe 2356 
SyYSE/SRY64 1DFa 14C 


STSPSHLLFHS = 1518 300) 
TIME.$86 BF2 430 
DATAFer BE 463 


Remember, that when running version 4 of the window server on the Series 3a in Series 3 compatibility 
mode, the image will be drawn in double pixel mode! 


gBorder Border a drawable 
VOID gBorder(UINT flags); 
Equivalent to gBorderRect where the rectangle covers the entire drawable (bitmap or window). 


Not available in version 2 of the window server. 


gBorder2Rect Draw a 'shadowed' border 
VOID gBorder2Rect (INT type, P_RECT *prect,INT flags); 


Introduced in version 4 of the window server, this function is similar to gBorderRect but includes the 
ability to draw a 3-dimensional style border. 


This function can be regarded as a generalisation of gBorderRect as not only can it draw the 3D style 
borders but includes the functionality of gBorderRect itself. 


It draws a border inside the rectangular block of pixels specified by the parameter prect with a style 
specified by the parameter type. The flags parameter 'fine-tunes' the border display. 


The type can be one of: 
¢ W_BORDER_TYPE_0 - to draw a border in the old style as done by gBorderRect 


¢ W_BORDER_TYPE_1 - to draw a 3-dimensional grey and black border. 


4-10 


4 GRAPHICS OUTPUT 


Note that for w_BoRDER_TYPE_1 borders, the window must be enabled for drawing grey. 


The flags parameter can be used to fine-tune the border display. They are, to all intents and purposes, the 
same as those used in the function gBorderRect with some minor changes in meaning. 


Flags should be one of: 


W_BORD_CORNER_2 to draw a corner type 2, the same as that drawn by gBorderRect. This is the 
default corner and need not be explicitly coded. This flag applies to both border 
types. 

W_BORD_CORNER_1 to draw a corner type 1, the same as that drawn by gBorderrRect. This flag 
applies to both border types. 

W_BORD_CORNER_4 to draw a corner type 4, the same as that drawn by gBorderRect. This flag 
applies to both border types. 

W_BORD_OPEN to draw a special corner used for menus on the S3 and S3a and is the same as 
that drawn by gBorderRect. This flag applies to w_BorRDER_TyPE_o borders 
only. 

The corner types can be qualified by OR'ing a combination of the following bit fields: 

W_BORD_CUSHION to leave a | pixel clear cushion right around the border. This flag applies to 
both border types 

W_BORD_SHADOW_S to draw a single shadow area. This flag applies to a w_BoRDER_TYPE_o border 
only. 

W_BORD_SHADOW_D to draw a double shadow area for a w_BoRDER_TYPE_O border. 


to set the thickness of the grey and black areas, which give the 3-D effect, to 4 
pixels (compared to a default value of 2 pixels) for a w_BoRDER_TYPE_1 border. 


W_BORD_SHADOW_ON to set the pixels in the shadow area for a w_BoRDER_TYPE_0 border. One of 
W_BORD_SHADOW_S OF W_BORD_SHADOW_D must also be set. If this flag is not set, 
the pixels are cleared. 


to draw a rectangle with the shadowed effect in grey and black as shown in the 
diagrams below for a w_BoRDER_TYPE_1 border. In drawing, it draws only the 
grey and black parts of the border. It leaves the white parts untouched because 
it assumes a pre-cleared background. 


If this flag is not set, it draws the outline of the border as shown and clears the 
area between the two outlines. This allows the shadow effects to be turned off 
by simply calling gBorder2Rect again. 


The following diagrams show examples of the various 3-dimensional style borders introduced with this 
function. All are of type w_BORDER_TYPE_1. The caption below each diagram shows the flag combinations 
used to draw it. 


LJ OC 


W_BORD_CORNER_4 W_BORD_CORNER_4 | W_BORD_SHADOW_ON W_BORD_CORNER_4 | W_BORD. 


SHADOW_ON | W_BORD_SHADOW_D 


W_BORD_CORNER_1 | W_BORD_SHADOW_ON W_BORD_CORNER_2 | W_BORD_SHADOW_ON 


4-11 


WINDOW SERVER REFERENCE 


gBorder2 Draw a 'shadowed' border 
VOID gBorder2 (INT type, INT flags); 


Introduced in version 4 of the window server, this is equivalent to gBorder2Rect but the rectangle is set to 
be the whole drawable, either the whole window or a bitmap. 


gDrawObject Draw a graphics object 
VOID gDrawObject (INT type,P_RECT *prect,INT flags) ; 


Introduced in version 4 of the window server, this draws the scaleable graphics object specified by type. 
The object is scaled to fit inside the rectangle specified by the parameter prect. 


The type of objects currently available are: 


G_DRAW_OBJECT_TYPE_0 a 3-dimensional box 


The flags applicable to this type of object are as follows: 


W_BORD_CORNER_2 to draw the box with a corner type 2, the same as that drawn by gBorder. This 
is the default and need not be explicitly coded. 

W_BORD_CORNER_1 to draw the box with a corner type 1, the same as that drawn by gBorder. 

W_BORD_CORNER_4 to draw the box with a corner type 4, the same as that drawn by gBorder. 

W_BORD_SHADOW_D to draw the box with double the thickness of the dark and light edge effects. 


Area filling 


The functions in this section act upon the drawable associated with the current graphics context. 


gCirRect Change a rectangle 
VOID gClrRect (P_RECT *prect, UINT mode); 


Change all pixels within the rectangular block specified by prect where the change depends on mode as 
follows: 


G_TRMODE_SET set the pixels 
G_TRMODE_CLR clear the pixels 
G_TRMODE_INV invert the pixels (this is reversible by another invert) 


The P_RECT struct is defined as: 


typedef struct 
{ 
WORD x; 
WORD y; 
} P_POINT; 


typedef struct 
{ 
P_POINT tl; /* top left pixel (internal) */ 
P_POINT br; /* bottom right pixel (external) */ 
} P_RECT; 


4-12 


4 GRAPHICS OUTPUT 


gilnvObloid Invert an obloid 


VOID gInvObloid(P_EXTENT *pext) ; 
Invert all the pixels (except the four corner pixels) in the rectangular block specified by pext. 
The p_extEnT struct is defined as: 


typedef struct 
{ 
P_POINT tl; 
WORD width; 
WORD height; 
} P_EXTENT; 


Not available in version 2 of the window server. 


gFillPattern Fill a rectangle with a bitmap 


VOID gFillPattern(P_RECT *prect, UINT bitmap_id, UINT mode); 


Repeatedly copy the bitmap with ID bitmap_ia over the rectangular block of pixels specified by prect as 
many times as is necessary to fill the rectangle. 


The parameter mode should be one of: 
G_TRMODE_REPL where bits in the source pattern replace corresponding bits in the destination. 


G_TRMODE_SET where Is in the source pattern set corresponding bits in the destination (Os in 
the source do not change corresponding bits in the destination). 


G_TRMODE_CLR where Is in the source pattern clear corresponding bits in the destination (Os in 
the source pattern do not change corresponding bits in the destination). 


G_TRMODE_INV where Is in the source pattern toggle corresponding bits in the destination (Os 
in the source pattern do not change corresponding bits in the destination). 


A larger bitmap will give improved performance. If the pattern is all ones or all zeros, gFillPattern is 
equivalent to gclrRect, but less efficient. 


There is a built in grey bitmap with the handle ws_prTmap_crey and size ws_BITMAP_GREY_STzE_x by 
WS_BITMAP_GREY_SIzE_y. This is not true grey as found on the Series 3a but is a pseudo-grey, built up 
from a pattern of alternate black and white pixels (ie pixels alternately set on and off in the normal plane). 


The parameter bitmap_id can also be the ID of a backed-up window to refer to the backup bitmap (but not 
in version 2). 


For example to fill the current drawable with the grey cheque board pattern: 


LOCAL_C VOID GreyWin (VOID) 
{ 
P_RECT rect; 


rect.tl.x=0; 

rect.tl.y=0; 

rect.br.x=10000; 

rect.br.y=10000; 
gFillPattern(&rect,WS_BITMAP_GREY,G_TRMODE_REPL) ; 
} 


In version 4 of the window server, when bitmap_id refers to a backed-up window, the function has a 
special way of handling grey: 


e In normal mode, the black plane only is copied from the source to the destination. 


e In G_GC_FLAG_GREY_PLANE mode, the grey plane from the source is selected and copied to the 
grey plane of the destination. If the source only has one plane, then that is used as the source. 


e In G_GC_FLAG_BOTH_PLANES mode, and with a two plane source, both planes are copied to their 
respective destination planes. If only one plane exists, then it will be copied to both planes of the 
destination. 


Note that this does not apply when copying from any other form of bitmap - in all other cases the black 
and grey planes must be copied by two separate calls to gFillPattern. 


4-13 


WINDOW SERVER REFERENCE 


—EeE——E—E—————————————————————————— ee) 
Text fonts 


Fonts are generally described in terms of: 
e ascent, descent, and vertical leading 
e width and horizontal leading 
e low character and high character (the range of ASCII values covered). 


To clarify the meaning of some of these terms, refer to the following diagram: 


The string 'Specify' has been printed at a point (x, y) which is indicated in the diagram by a pair of 
partially drawn lines. The horizontal of the pair of lines is known as the baseline. 


The descent of a character is the number of pixels that it extends below the baseline. Thus in the font 
shown, 'S' has a zero descent whereas 'p' has a descent of 1. 


The ascent of a character is the number of pixels that it extends above the baseline. In the font shown, 'S' 
has an ascent of 7 whereas 'p' has an ascent of 5. The ascent quoted for a font is always the maximum 
ascent of all the characters in the font, and likewise for the descent. The sum of the ascent and the descent 
is the height of the font. 


Vertical leading is the number of additional pixels that separate adjacent lines of text, over and above the 
stated height of each line of text. This is usually at least one, to prevent the highest ascent of one line ever 
joining up with the lowest descent of the line above. On occasion, however, such joining up may actually 
be intended, for example to support box-drawing via the IBM graphics characters in the extended portion 
of a font. In any case, it should be noted that, strictly speaking, vertical leading is not a characteristic of a 
font as such; rather, it describes how a font is used on a particular occasion. To complicate matters, 
different uses of a font will in fact often have different vertical leading. 


Horizontal leading is the number of pixels that separate adjacent characters in a line of text. 


The term width is, unfortunately, possessed of two subtly different meanings. The more useful of the two 
meanings is that the width of some text is the number of pixels from the start of that text to where a piece 
of text following on from the first one would start. This is the value returned by window server inquiry 
functions such as gText Width. Thus the width of the character 'S' in the above font is the number of pixels 
from the start of the 'S' to the start of the following character (‘p'), namely 6. With this meaning, all the 
characters shown in the diagram have width 6, except for 'i' (4) and 'f' (5). 


The second of the two meanings of width discounts the horizontal leading, so that, by this reckoning, the 
width of 'S' is just 5 pixels. This latter meaning of width is sometimes referred to as basic width. 


There is an important difference between horizontal and vertical leading: horizontal leading is always 
supplied as part of the font; on the other hand the amount of vertical leading (if any) to be applied is up to 
the user of the font. Stated otherwise, applications have no choice about horizontal leading, but do have 
choice over vertical leading. For this reason, the simple term leading is commonly used to denote what is 
here being called vertical leading (since horizontal leading is usually just taken for granted). 


The width of the widest character in a font is called the maximum width, and the width of the numeric 
character '0' is called the numeric width, or sometimes the column width. (In any well designed font, all 
numeric characters will have the same width). 


Occasionally, a font is described in terms of its body cell. The font depicted has a basic body cell of 5 by 8 
(which excludes both vertical and horizontal leading), and a corresponding expanded body cell of 6 by 9. 


Not all the character codes within the range need have a representation within the font. When drawn, 
these characters will be represented by the last character in the font. 


4-14 


4 GRAPHICS OUTPUT 


An application can switch between many different fonts of varying sizes. Each Graphics Context may 
have a different font. The appearance of text can also be altered by various style options such as underline 
or bold (these are independent of the font). 


Fonts are generally proportional, ie the characters within the font can be of differing width. It is left to an 
application to determine the width of text and make decisions about layout accordingly. 


Information is provided to allow fonts of differing heights to be aligned vertically about a baseline. When 
characters are drawn, the y-coordinate given corresponds to the baseline of the character. If a line of text 
is drawn using characters from fonts of different height, this ensures that the text lines up vertically. 


gOpenFont Open a font 
INT gOpenFont (TEXT *filename) ; 
Load the font from filename and return the font ID. 


If an error (with error number err) occurs (for example, the file does not exist or if it is not a valid font 
file), the function calls p_leave (err) or returns err, depending on the wDisableLeaves State. 


To use the font for text drawing functions, the font ID must be assigned to a graphics context (using 
gSetGC). 


Note that the parameter filename is ultimately passed to p_open by the window server process - not the 
client process. If fi 1ename is not a full file specification, the unspecified components are taken from the 
window server's default path which, in practice, is always the internal drive M.\. This is unlikely to meet 
the requirements of a finished product so filename should specify the drive and directory as well as the 
file name. Typically, you might place a font file in the same location as the application file in which case 
you would use something like: 


GLREF_D TEXT *DatCommandPtr; 


LOCAL_C INT OpenFont (TEXT *name) 
{ 
TEXT full [P_FNAMESIZE]; 


f_fparse (name, DatCommandPtr, &full[0],NULL) ; 
gOpenFont (&full[0]); 
} 


See also gSetOpenAddress for loading a font file which is embedded in another file. 


gSetOpenAddress Set pos to open font/bitmap/mouse icon 
VOID gSetOpenAddress (UINT mode, ULONG pos); 


Set the file position for the next call to gopenFont, gOpenFont Index, gInitBit, gOpenBit or 
gOpenMouselcon as a function of mode and pos. 


The possible values of mode are defined by constants of the form c_opEN_MopE_xxx where xxx is one of: 


OFFSET to indicate that pos is the file position of the data 

WORD_PTR_OFFSET to indicate that pos is the file position of a uworp containing the file position of 
the data 

LONG_PTR_OFFSET to indicate that pos is the file position of a uLonc containing the file position of 
the data 

NORMAL to cancel the effect of any previous unused call to gsetopenaddress (pos iS 
ignored) 


The effect of the call only lasts until the next call to gopenFont, gopenFontIndex, gInitBit, gOpenBit OF 
gOpenMouseIcon So you wouldn't normally need c_opEN_MoODE_NoRMAL - especially as a call to 
gSetOpenAddress would normally occur immediately before the gopenxxx call it is intended to effect. 


The data at the effective file position should be the entire contents of the normal font, multiple font, 
bitmap or mouse icon file - including all headers. 


4-15 


WINDOW SERVER REFERENCE 


wFree Free a font 
VOID wFree(UINT font_id); 


Free a previously loaded font. 


gFontinfo Get font information 


INT gFontInfo(UINT font_id, UINT style, G_FONT_INFO *pinfo); 


Write information about the font with ID font_id as modified by the text style style to the G_FoNT_INFO 
struct at pinfo where the G_FONT_INFO struct is defined in wlib.h as: 


typedef struct 
{ 


UWORD low_ch; /* lowest character code in font */ 

UWORD high_ch; /* highest character code in font */ 

UWORD height; /* height of font */ 

UWORD descent; /* height of bottom part of a character */ 

UWORD ascent; /* height of top part of a character */ 

UWORD numeric_width; /* width of the '0' character */ 

UWORD max_width; /* width of widest character in the font */ 

UWORD flags; /* flags specifying information about the font */ 
TEXT name[16]; /* Text name of the font */ 


} G_FONT_INFO; 


The field numeric_width is actually the width of the '0' (zero) character, however any well designed font 
will have all its numeric characters the same width. If a font is monospaced, all characters are of width 


max_width. 


The field max_width is set by the font designer when the font is created. It is not necessarily the widest 
character in the font, since the font designer will normally exclude any special characters that are rarely 
used - max_width is normally the width of 'M' or 'W'. 


The fields numeric_width, max_width, height, descent and ascent can be modified from their base 
values by the style given. 


The flags field consists of the following bit fields: 

G_FONT_FLAG_ASCII the font contains the standard ASCII character set 
G_FONT_FLAG_CP850 the font contains the IBM code page 850 character set 
G_FONT_FLAG_BOLD the font is designed to look bolded 
G_FONT_FLAG_ITALIC the font is designed to look italic 

G_FONT_FLAG_SERIF the font character graphics have serifs 


Returns zero if successful or, if font_id is invalid, it calls p_leave (E_GEN_NOFONT) or returns 
E_GEN_NOFONT, depending on whether wDisableLeaves has been called. 


To get information on the system font, font_id may be set to WS_FONT_SYSTEM. 


On version 2 of the window server you should not call gFont Info with an invalid font_id (if you do, 
gFont Info writes garbage to pinfo). 


gTextWidth Get text width 


INT gTextWidth(UINT font_id, UINT style, TEXT *pbuf, UINT len); 
Return the width in pixels of the 1en characters at pbuf when drawn with font font_id and style style. 


Any character code in pbuf that does not have a corresponding character graphic in the font is taken to 
have the width of the last character in the font. 


Note that the style can affect the width returned because bolding, italicising, mono-spacing etc widens 
each character. 


To get the text width when using the system font, font_id may be set to WS_FONT_SYSTEM. 


If font_id is invalid, the function calls p_leave (E_GEN_NOFONT) or returns E_GEN_NOFONT, depending on 
whether wDisableLeaves has been called. 


4-16 


4 GRAPHICS OUTPUT 


gTextCount Clip text to pixel width 


INT gTextCount (UINT font_id, UINT style, TEXT *pbuf, UINT len,UINT *pwidth) ; 


Return the number of characters from pbuf (up to 1en) that will fit in their entirety in *pwidth pixels 
when drawn with font font_id and style style. Also overwrite *pwidth with the remaining width. 


Any character code in pbuf that does not have a corresponding character graphic in the font is taken to 
have the width of the last character in the font. 


Note that the style can affect the width returned because bolding, italicising, mono-spacing etc widens 
each character. 


When using the system font, font_id may be set to wS_FONT_SYSTEM. 


If font_ida 1s invalid, the function calls p_leave (E_GEN_NOFONT) or returns E_GEN_NOFoONT, depending on 
whether wDisableLeaves has been called. 


gGetWidthTable Get a font width table 


INT gGetWidthTable(UINT font_id, UINT style, UBYTE *ptab); 
Generate a usyTE array of character pixel widths in *ptab for font font_id and style style. 


The first byte in *ptab is the width of the character with code 1ow_ch and the length of the array written is 
high_ch-low_ch+1 (where low_ch and high_ch are from the font's c_rontT_inro struct). 


The function is provided to speed optimise calculations based on character widths - such as those 
performed by gTextwidth and gTextCount. 


Any character code that does not have a corresponding character graphic in the font is taken to have the 
width of the last character in the font. 


Note that the style can affect the width returned because bolding, italicising, mono-spacing etc widens 
each character. 


When using the system font, font_id may be set to ws_FONT_SYSTEM. 


Returns zero if successful or, if font_id is invalid, it calls p_leave (E_GEN_NOFONT) or returns 
E_GEN_NOFONT, depending on whether wDisableLeaves has been called. 


wSetSystemFont Set the system and internal fonts 


INT wSetSystemFont (INT mode, INT handle, UINT style); 


Available in version 4 of the window server, this function mat be used on the Series 3a and Workabout to 
set up the system and internal fonts. 


The mode parameter is used to indicate which font type is to be the target of the set up. This parameter can 
take one of the following values: 


W_SYSTEM_FONT_S3B sets up the native system font 
W_SYSTEM_FONT_S3 sets up the Series 3 compatibility mode system font 
W_SYSTEM_FONT_INTERNAL_S3B _ sets up the native internal font 
W_SYSTEM_FONT_INTERNAL_S3 __ sets up the Series 3 compatibility mode internal font 
The handle parameter references the font to be used as the source for the setup. This can be: 
e the handle returned for a loaded font 
e the handle of one of the built-in fonts 
e the handle of a font group created by gconfigureFonts 


The style parameter can be used to modify the style of text when setting up either of the two internal font 
types. This parameter is ignored if setting up any of the other font types. The style parameter adopts the 
same values as those applicable to the sty1e field in the graphics context. 


4-17 


WINDOW SERVER REFERENCE 


The function returns zero if successful, =_cEN_Noront if an invalid font handle is supplied or =_cEN_are if 
an invalid mode is supplied. Alternatively, it calls p_leave if wDisableLeaves has been called. 


Note that at the time of writing, there is no way of notifying applications that the system font has changed. 


gOpenFontindex Open a font from a multiple font file 


INT gOpenFontIndex(TEXT *fname,UINT index) 


Available in version 4 of the window server, this function is similar to gopenFont except that it allows a 
font to be loaded from a file containing more than one font. 


The index parameter is used to indicate which font within the file is to be loaded. The first font in the file 
corresponds to an index of zero, while the second font corresponds to an index value of one and so on. 


Single-font files can be opened by setting index to zero. 
Multiple-font files are invalid to older versions of the window server. 
If index refers to a font file beyond the final one in the file, error E_FILE_EOoF is reported. 


If an error (with error number err) occurs, the function calls p_leave (err) or returns err, depending on 
whether wDisableLeaves has been called. 


Multiple-font files can be created by versions 2.00 upwards of the font compiler WSFCOMP. 


gConfigureFonts Configure a font group 
INT gConfigureFonts (INT count,G_FONT_CONFIG *pfcfg[]) 
Available in version 4, this function is used to create a font group and return its id. 


A font group is a compromise solution to the problem of deciding whether to use the window server's 
algorithmic method of obtaining a style (see style subsection of the Graphics context section) or to use a 
font designed specifically for the purpose. This is even more important where the situation is ambiguous. 
For example, given a bold font and an italicised font, if the application wishes to print in bold and italics, 
does it choose to apply the bold style to the italicised font or apply the italic style to the bold font? 


Designing a font for every combination of style is impractical while the result of applying the window 
server's algorithmic method may not always give satisfactory results. 


Essentially, a font group is a list of font id's and style combinations. 


When an application wishes to print text, typically it will specify a (group) font ID and a combination of 
styles to be applied. In response, the window server scans down each entry in the list searching for the best 
match. It then uses the font in this entry for printing. 


The font group is specified by the parameter pfcfg which points to an array of G_FONT_CONFIG structures. 
The array has count elements. Each element in the array is, in effect, an entry in the list discussed above. 
The G_FonT_conF1IG structure is defined as follows: 


typedef struct 
{ 
UINT FontId; /*Replacement Font is 
UINT RepStyles; /*Styles needing to be replaced*/ 
UINT FontStyles; /*Styles used with this Font ay 
UI 
} 


NT AscentAdjust; /*Adjustment to Font's ascent */ 
G_FONT_CONFIG; 


The order of the elements in the array is important because of the way the search algorithm works. This 
proceeds as follows: 


1. The window server initially chooses the base font as the 'best'. In other words, the first entry 
in the array. 


2. Initially, each entry in the array is scanned, starting with the first, until one is found where 
the RepStyles field contains styles which are a subset of the styles to be printed. 


4-18 


4 GRAPHICS OUTPUT 


3. Subsequently, the scan continues, searching for entries whose RepStyles field contains 
styles which are a subset of the styles to be printed and which also (as a minimum) contain 
the styles of the current 'best' entry. Where such an entry is found, this becomes the 'best'. 


4. The process, numbered 3 above, is repeated until the array is exhausted, The window server 
uses the font corresponding to the Font1d of the ‘best’ entry in the array. 


Having found a suitable font, the window server then applies those styles which the application wants 
printed but which are not specified in the Repstyles field. For example, suppose the application wants 
bold and italic printed. Suppose also that the 'best’ entry in the array specifies only the bold style in the 
RepStyles field. The window server will use the Font 1d as the font to be used and will apply the italic 
style to this font. 


In addition, the rontstyles member of each entry in the array specifies styles which are also to be applied 
to the chosen font when it is drawn. 


The Ascentadjust field specifies an adjustment to be made (positive or negative) to the font's ascent when 
printing. This is primarily of use for superscript and subscript fonts. See the c_sty_suBscRIPT2 and 
G_STY_SUPERSCRIPT2 styles at the beginning of this chapter. 


gReadFontHeader Read a font header from a file 


INT gReadFontHeader (TEXT *fname, INT index,UBYTE *pbuffer) 


Available in version 4 of the window server, this function reads up to a maximum of 
FONT_MAX_HEADER_LEN bytes of font data from the font referenced by fname and index into the buffer 
pointed to by pbuffer. 


fname references the font file while the index parameter indicates the actual font within the file. For a 
single font file, index must be set to 0; for a multiple font file, an index value of zero refers to the first 
file, an index value of one refers to the second file and so on. 


If the call is successful, the function returns the length of data actually read. 


If an error (with error number err) occurs (for example, the file does not exist or it is not a valid font file), 
the function calls p_leave (err) or returns err, depending on the wDisableLeaves State. 


gReadFontGroupHeader Read a font group header from a file 


INT gReadFontGroupHeader (TEXT *fname,UBYTE *pbuffer) 


Available in version 4 of the window server, this function reads up toa maximum of 
FONT_MAX_HEADER_LEN bytes of font header data from the font file referenced by fname into the buffer 
pointed to by pbuffer. 


In the first word of the buffer, the function places the number of fonts contained in the file. This word is 
followed by the group header. This means that the actual maximum length of header data that can be 
stored in the file is FONT_MAX_HEADER_LEN - 2 bytes. 


If the call is successful, the function returns the length of data actually read. 


If an error (with error number err) occurs (for example, the file does not exist or it is not a valid font file), 
the function calls p_leave (err) or returns err, depending on the wDisableLeaves State. 


See the description of wsfcomp for information on how to add header data. 


Text output functions 


The functions in this section are all directed at the drawable associated with the current graphics context 
and are all subject to the style and font fields of the current graphics context. 


The functions gPrintText and gPrintClipText are also subject to the textmode field. The functions 
wDrawButton, and wDrawButton2 are also subject to the gmode field. 


In version 4 of the window server, the plane to which drawing is directed in the current graphics context 
will affect the 'colour' of the display. 


4-19 


WINDOW SERVER REFERENCE 


gPrintText Print text 
VOID gPrintText (INT x, INT y, TEXT *pbuf, UINT len); 


Print the len characters at pbuf horizontally from pixel position x, y where len must not be greater than 
WS_MAX_PRINT_TEXT_LEN. 


The first character graphic is positioned such that its leftmost pixel that is just above the baseline is over 
pixel (x,y) of the drawable. (The baseline is the mathematical line between the upper ascent pixels and 
the lower descent pixels that make up the height of the font.) 


The text is printed relative to the baseline so that the characters in a line of text that contains different 
fonts (with potentially different ascents and descents) line up correctly, as illustrated by the following 
diagram: 


Baseline 


Descent 


sil 


X is the printing position. 


The text is printed according to the textmode, style and font in the current graphics context. 


Any character code in pbuf that does not have a corresponding character graphic in the font is printed as 
the last character in the font. 


Note that gPrintText performs no special processing on control characters (ie characters with a code that 
is less than 32) and if they are not represented in the font then they will also be printed as the last 
character in the font. 


gPrintClipText Print clipped text 
INT gPrintClipText (INT x, INT y, TEXT *pbuf, UINT len, UINT clip_width) ;;; 
Similar to gprintText except that it only draws as many characters as will fit inside clip_width. 


Returns the number of characters actually printed. 


gPrintBoxText Print text in a box 


VOID gPrintBoxText (P_RECT *prect, UINT ascent, UINT align, INT margin, TEXT *pbuf, UINT 
len); 


Print the len characters at pbuf with a fixed textmode of G_TRMODE_REPL within the rectangular block of 
pixels specified by prect, clearing (or setting) those pixels that are not replaced by characters from the 
font (1en must not be greater than ws_Max_PRINT_BOX_TEXT_LEN). 


If necessary, the drawing is pixel-clipped to the rectangle defined by prect. 
The P_REcT struct is defined as: 


typedef struct 
{ 
WORD x; 
WORD y; 
} P_POINT; 


typedef struct 
{ 
P_POINT tl; /* top left pixel (internal) */ 
P_POINT br; /* bottom right pixel (external) */ 
} P_RECT; 


4-20 


4 GRAPHICS OUTPUT 


The characters are positioned vertically such that there are ascent pixels between the top of the rectangle 
and the base line of the characters (unless you intend to clip the top off the text, ascent should be greater 
than or equal to the current font's ascent) as illustrated by the following diagram: 


ascent ascent 
of 
font 


baseline of font 


The excess space around the text is cleared or set depending on the inverse bit in the style. 


The text may be left or right aligned, or centred within prect depending on whether align is 
G_TEXT_ALIGN_LEFT, G_TEXT_ALIGN_RIGHT Of G_TEXT_ALIGN_CENTRE. 


The parameter margin is used to clear extra space to the left or right of the text where margin is 
interpreted as follows: 


align = G_TEXT_ALIGN_LEFT 


left-aligned text 


align = G_TEXT_ALIGN_RIGHT 


right-aligned text 


For centred text, the margin can be placed either to the right or to the left of the text according to the sign 
of margin, as follows: 


align = G_TEXT_ALIGN_CENTRE, margin>=0 


centred text 


align = G_TEXT_ALIGN_CENTRE, margin<0O 


centred text 


The text is printed according to the style and font in the current graphics context (but not textmode). 


Using gPrintBoxText avoids the flicker that is generated between a separate clear and print. 


gXPrintText Print text with embellishment 


VOID gXPrintText (INT x, INT y, TEXT *pbuf, UINT len, UINT flags); 


Print the 1en characters at pbuf horizontally from pixel position x, y with highlighting in a style that 
depends on the value of f1ags (1en must not be greater than ws_MAx_PRINT_TEXT_LEN). 


4-21 


WINDOW SERVER REFERENCE 


The text is printed according to the style and font in the current graphics context (but not textmode). 


Equivalent to calling gPrintText with a fixed textmode of G_TRMODE_REPL followed by some 
embellishment depending on the value of f1ags. Possible flag values are illustrated below for the string 
‘Specify’, in each case printed with the same value of x and y. 


Zero (no embellishment). | 


rT TT : 8 
The partially drawn lines indicate H Sian: CMM. SUMMERS Ros CaGd Ce 
the point to which the coordinates x l ial laa fe i 
and y-apply; _ TTT "a1: iF sae _ 


G_XP_INV_BLOCK 


G_XP_INV_OBLOID 


G_XP_INV. BLOCK |G XP_REDUCED 


G_XP_INV_OBLOID|G_XP_REDUCED 


G_XP_UND_BLOCK nnnn a Be 
a nnnE ann EEE BB a ] | 
ann 6G _ Ho no One 66 ] 
| a HEREE 8 | f a | 
et | a ] a nnnE 
nnnE 6G EERE SEE Boe OU a 


G_XP_UND BLOCK |G XP_REDUCED 


All the reduced forms are intended for use on text strings with no characters having descenders, such as 
numbers and upper case letters. 


A zero flags is equivalent to gPrintText with a textmode of G_TRMODE_REPL and may be used to cancel an 
embellishment set up previously. 


Not available in version 2 of the window server. 


In version 4 of the window server, by setting the graphics context to draw to the grey plane and making 
sure that the window is enabled for drawing grey, all of the text and embellishments in the above 
examples will be drawn in grey. 


4-22 


4 GRAPHICS OUTPUT 


gShadowText Print shadowed text 


VOID gShadowText (INT posx,INT posy, G_SHADOW *pshadow, TEXT *ptxt,INT len); 


Introduced in version 4 of the window server, this function prints the 1en characters at ptxt with a 
shadowed effect from pixel position posx, posy where 1en must not be greater than 
WS_MAX_PRINT_TEXT_LEN. 


It uses the current font and style (ie the current graphics context) but ignores the current textmode. 
The pshadow parameter must point to a structure of type c_sHaDow which is defined as follows: 


typedef struct 
{ 
UBYTE BodyColour; 
UBYTE ShadowColour; 
UBYTE LightColour; 
UBYTE filler; 
UWORD Flags; 
WORD ShadowSizexX; 
WORD ShadowSizey; 
WORD LightSizex; 
WORD LightSizeyY; 
WORD Spacing; 
} G_SHADOW; 


The shadow is always placed at the bottom right of the text while the lighting effect is always placed at the 
top left of the text. 


The size of the shadow effect is specified by snadowSizex and ShadowSizey. The size of the lighting effect 
is specified by Lightsizex and LightSizey. 


The 'colours' for the body, shadow and light can be one of black, grey, white or none by setting the 
G_SHADOW Members BodyColour, ShadowColour and LightColour to one of G_COLOUR_BLACK, 
G_COLOUR_GREY, G_COLOUR_WHITE Of G_COLOUR_NONE. 


The display can consist of either a single copy of the text giving an impression of the text floating above 
the shadow or a solid block linking the text to the background. By default, the floating style shadow is 
used. The solid block effect is achieved by setting the riags member to G_SHADOW_SOLID. 


The gap between characters can be set by giving the spacing member a suitable value. This is useful if a 
character's shadow effects are not to overlap the following character. 


The following picture shows four examples of the effect of using gshadowText: 


t Ihe 


In all examples, shadowSizex was Set to 6, ShadowSizey was Set to 6, LightSizex was set to 2 and 
LightSizey was Set to 2. 


Spacing was Set to 6 to allow sufficient space between the characters so that the shadow effects could be 
seen. 


4-23 


WINDOW SERVER REFERENCE 


Looking at each example from left to right, the following values were used: 


1. BodyColour set to G_COLOUR_BLACK 
ShadowColour Set tO G_COLOUR_GREY 
LightColour set to G_COLOUR_NONE 


2. BodyColour set to G_COLOUR_BLACK 
ShadowColour Set tO G_COLOUR_GREY 
LightColour set to G_COLOUR_NONE 
Flags set to G_LSHADOW_SOLID 


3. BodyColour set to G_COLOUR_BLACK 
ShadowColour Set tO G_COLOUR_GREY 
LightColour set tO G_COLOUR_WHITE 
Flags set to G_LSHADOW_SOLID 


4. BodyColour set tO G_COLOUR_WHITE 
ShadowColour Set tO G_COLOUR_BLACK 
LightColour set to G_COLOUR_GREY 
Flags set to G_LSHADOW_SOLID 


wDrawButton Draw a text button 
VOID wDrawButton(P_RECT *prect, TEXT *pstr, UINT depressed); 


Draw a button within rectangle prect containing the zero terminated string pstr. If depressed 1s TRUE, 
draw the button with the text and the box displaced to give a 3D illusion of a depressed button. 


The length of pst r must not be greater than w_DRAW_BUTTON_MAX_LEN (240). 


The text is printed according to the style and font in the current graphics context. Both the box lines and 
the text string are drawn according to the gmode (the value of textmode is ignored). 


The P_REcT struct is defined as: 


typedef struct 
{ 
WORD x; 
WORD y; 
} P_POINT; 


typedef struct 
{ 
P_POINT tl; /* top left pixel (internal) */ 
P_POINT br; /* bottom right pixel (external) */ 
} P_RECT 


~ 


The intended use of worawButton is illustrated by the following example: 


include <plib.h> 
include <wlib.h> 


LOCAL_D WSERV_SPEC wSpec; 
LOCAL_D UINT wMainWid; 
LOCAL_D UINT FontID; 

LOCAL_D UINT FontStyle; 
LOCAL_D G_FONT_INFO FontInfo; 


LOCAL_C VOID SetFont (INT fid, INT style) 


gFont Info (Font ID=fid, FontStyle=style, &FontInfo) ; 


LOCAL_C VOID SetGC (VOID) 


G_GC gc; 


gc.font=FontID; 

gc.style=FontStyle; 

gSetGC (0, G_GC_MASK FONT |G GC_MASK_STYLE, &gc) ; 
} 


4-24 


4 GRAPHICS OUTPUT 


LOCAL_C VOID DrawButton(INT state) 


{ 
P_RECT rect; 


rect.tl.x=20; 

rect.tl.y=(40-2) -FontInfo.height; 
rect.br.x=140; 
rect.br.y=(40+2)+FontInfo.height; 
wDrawButton(&rect,"Press any key",state) ; 


} 


LOCAL_C VOID MainEventLoop (VOID) 


{ 
WS_EV event; 


for (77) 

{ 

wGetEventWait (&event) ; 

if (event .type==WM_REDRAW) 
{ 
wBeginRedrawWinGCO (wMainWid) ; 
gBorder (W_BORD_SHADOW. D|w BORD_SHADOW_ON) ; 
SetGC(); 
DrawButton (FALSE) ; 
wEndRedraw (); 
continue; 
} 

if (event .type==WM_KEY) 
{ 
gCreateTempGCO0 (wMainWid) ; 
SetGC (); 
DrawButton (TRUE) ; 
wF lush () ; 
p_sleep(51); 
DrawButton (FALSE) ; 
gFreeTempGC () ; 
} 


} 


GLDEF_C VOID main(VOID) 


{ 
wConnect (&wSpec, 0,W_CONNECT_PRIORITY) ; 


wMainWid=wCreateWindow(0,0,0,1); 
wiInitialiseWindowTree (wMainWid) ; 
SetFont (WS_FONT_SYSTEM, G_STY_BOLD) ; 
MainEvent Loop () ; 


} 


wDrawButton2 Draw a text button 


VOID wDrawButton2 (INT type, P_RECT *prect, TEXT *ptext, UINT state); 


Introduced in version 4 of the window server, this function not only draws the new style Series 3a buttons, 
but also the old style Series 3 types. 


The parameter prect points to a p_REcT structure that specifies a rectangle that fully encloses the button 
in all of its states. 


The ptext parameter specifies a zero terminated string to be drawn inside the button in the current font 
and style. It is the responsibility of the caller to make sure that the text will fit inside the button; there is 
no clipping of text. The maximum length of text is w_DRAW_BUTTON_MAX_TEXT. 


The parameter type indicates which style of button is to be drawn. This can have the following values and 
meanings: 


W_BUTTON_TYPE_1 draws the Series 3 style buttons 


W_BUTTON_TYPE_2 draws the Series 3a style buttons 


4-25 


WINDOW SERVER REFERENCE 


The state parameter has different meanings for the different types. 
For w_BUTTON_TYPE_1 buttons, 0 draws a raised button while | draws a depressed(flat) button. 


For w_BUTTON_TYPE_2 buttons, 0 draws a raised button, 1 draws a semi-depressed button while 2 draws a 
fully depressed(sunken) button. 


The following picture shows three examples of w_BUTTON_TYPE_2 buttons. From left to right, the 
examples show: a state O button (raised), a state | button (semi-depressed) and a state 2 button (fully 
depresses). 


raised Sen] depressed fully depressed 


For the purpose of comparison, the following picture shows examples of w_BUTTON_TYPE_1 buttons. From 
left to right, the examples show: a state 0 button (raised) and a state | button (fully depressed). 


raleed fully depressed 


It is important to note that before calling worawButton2 to draw W_BUTTON_TYPE_2 buttons, the window 
must be enabled for drawing grey. 


Bitmaps 


Although directed at the drawable associated with the current graphics context, the graphics output 
functions in this section do not depend on any of the settable fields in the graphics context. 


gCreateBit Create a bitmap 
INT gCreateBit (UINT flags, W_OPEN_BIT_SEG *pbitseg) ; 


Create an uninitialised bitmap where the size of the bitmap and its method of storage is controlled by 
flags and the W_OPEN_BIT_SEG struct at pbitseg. 


The W_OPEN_BIT_SEG Struct is defined as: 


typedef struct 
{ 
P_POINT size; 
TEXT seg_name[14]; 
} W_OPEN_BIT_SEG 


where pbitseg->size specifies the dimensions of the bitmap in pixels and pbitseg->seg_name is written 
to by gcreateBit when requested by the bit in flags (as described next). 


If f£1ags is zero, the bitmap may be stored in the window server's data space or in a named memory 
segment depending on the size of the bitmap. If the bitmap requires less than 2.5K bytes, it is stored in 
the window server's data space. 


The storage of the bitmap is controlled by setting the following bits in flags: 
WS_BIT_SEG to store the created bitmap in its own memory segment (regardless of its size) 


WS_BIT_SEG_ACCESS to create the bitmap in its own memory segment and to write the name of the 
segment as a zero terminated string to pbitseg->seg_name. The segment name 
can be used to access the bitmap directly using p_sgcopyfr and p_sgcopyto 
(described in the Memory Allocation chapter of the PLIB Reference manual) or 
otherwise. 


WS_BIT_SEG_ZERO_SIZE Used in conjunction with ws_BIT_SEG_ACcCcEss to create the bitmap's memory 
segment with zero size. You must subsequently increase the size at a later date. 
This is designed to be used in conjunction with graphics functions that are 
added using wLoadDYL. 


4-26 


4 GRAPHICS OUTPUT 


If flags is either zero or WS_BIT_SEG, pbitseg—>seg_name is not written to and, in this case, pbitseg may 
just be the address of a p_pornt struct. The prototype for gcreateBit actually declares pbitseg asa 
voIp * so that you can pass either a wS_BIT_SEG * Of a P_POINT *. 


You may use all the window server graphics functions to draw to a bitmap unless the 
WS_BIT_SEG_ZERO_S1ZE flag is set, in which case the graphics functions will have no effect. 


Returns the positive ID of the bitmap if successful. 


If the function fails because there is insufficient memory, it calls p_leave (E_GEN_NOMEMORY) or returns 
E_GEN_NOMEMoRY, depending on whether wDisableLeaves has been called. 


gOpenBit Load a bitmap 
INT gOpenBit (TEXT *filename, UINT index, UINT flags, W_OPEN_BIT_SEG *pbitseg) ; 


Load bitmap index from file filename where index is used to select a bitmap from a file that contains 
multiple bitmaps (a zero index selects the first bitmap). To load from a file containing a single bitmap, 
pass the index as zero. 


The function writes to the w_oPEN_BIT_sSEG Struct at pbitseg where w_opEN_BIT_SEG is defined as: 


typedef struct 
{ 
P_POINT size; 
TEXT seg_name[14]; 
} W_OPEN_BIT_SEG 


If the bitmap is successfully loaded, the dimensions of the bitmap in pixels is written to pbitseg->size 
and the ID of the bitmap is returned. 


If £1ags is zero, the bitmap may be stored in the window server's data space or in a named memory 
segment depending on the size of the bitmap. If the bitmap requires less than 2.5K bytes, it is stored in 
the window server's data space. 


The storage of the bitmap is controlled by setting the following bits in fags: 
WS_BIT_SEG to store the loaded bitmap in its own memory segment (regardless of its size) 


WS_BIT_SEG_ACCESS to store the loaded bitmap in its own memory segment and to write the name of 
the segment as a zero terminated string to pbitseg->seg_name. The segment 
name can be used to access the bitmap directly using p_sgcopyfr and 
p_sgcopyto (described in the Memory Allocation chapter of the PLIB 
Reference manual) or otherwise. 


WS_BIT_WRITE if set, you are given write access to the bitmap and a new bitmap is always 
created. If the flag is not set, the bitmap will only be created once and if any 
client calls gopenpit on the same bitmap, the loaded bitmap will be shared. 


Provided that the ws_B1T_wr1TE flag is set, you may use all the window server graphics functions to draw 
to a bitmap. If the ws_B1T_wr1te flag is not set, the graphics output functions will have no effect. 


If ws_BIT_SEG_ACCESS iS not set in flags, pbitseg->seg_name is not written to and, in this case, pbitseg 
may just be the address of a p_pornt struct. The prototype for gopenBit actually declares pbitseg as a 
voIp * so that you can pass either a wS_BIT_SEG * Of a P_POINT *. 


If an error (with error number err) occurs, the function calls p_leave (err) or returns err, depending on 
whether wDisableLeaves has been called. 


Note that the parameter filename is ultimately passed to p_open by the window server process - not the 
client process. If filename is not a full file specification, the unspecified components are taken from the 
window server's default path which, in practice, is always the internal drive M:\. This is unlikely to meet 
the requirements of a finished product so filename should specify the drive and directory. 


4-27 


WINDOW SERVER REFERENCE 


Typically, the bitmap file might be built into the application to create a .app file as described in the 
Building An Application chapter in the General Programming manual. In this situation you might have a 
code fragment that looks like: 


GLREF_D TEXT *DatCommandPtr; 


LOCAL_C INT OpenBit (TEXT *name) 


{ 
W_OPEN_BIT_SEG bseg; 
TEXT full [P_FNAMESIZE]; 


f_fparse (name, DatCommandPtr, &full[0],NULL); 
gOpenBit (&full[0],0,0, &bseg) ; 
} 


See also gSetOpenAddress for loading a bitmap file which is embedded in another file. 


wFree Free a bitmap 


VOID wFree(UINT bitmap_id); 
Free the bitmap with ID bitmap_ia. 


Any Graphics Contexts drawing to bitmap_id is automatically freed. 


gSaveBit Save a bitmap 


INT gSaveBit (TEXT *filename, UINT bitmap_id) ; 


Save the bitmap with ID bitmap_id to file filename or, if bitmap_id is zero, save the screen to file 


filename. 


The parameter bitmap_id can also be the ID of a backed-up window to refer to the backup bitmap (but not 
in version 2). 


Returns zero if successful. 


If an error (with error number err) occurs, the function calls p_leave (err) or returns err, depending on 
whether wDisableLeaves has been called. 


If filename is not a full file specification, the unspecified components are taken from the window server's 
default path which, in practice, is always the internal drive M:\. 


In version 4 of the window server, the function will save a double bitmap when saving the screen or a 
backed-up window with a grey plane. 


gSaveRect Save part of a bitmap 
INT gSaveRect (TEXT *filename, UINT bitmap_id, P_RECT *prect); 


Save the rectangular block of pixels specified by prect from the bitmap with ID bitmap_id to file 
filename or, if bitmap_id is zero, save the rectangular block of pixels specified by prect from the screen 
to file filename. 


The P_REcT struct is defined as: 


typedef struct 
{ 
WORD x; 
WORD y; 
} P_POINT; 


typedef struct 
{ 
P_POINT tl; /* top left pixel (internal) */ 
P_POINT br; /* bottom right pixel (external) */ 
} P_RECT; 


4-28 


4 GRAPHICS OUTPUT 


The parameter bitmap_id can also be the ID of a backed-up window to refer to the backup bitmap (but not 
in version 2). 


Returns zero if successful. 


If an error (with error number err) occurs, the function calls p_leave (err) or returns err, depending on 
whether wDisableLeaves has been called. 


If filename is not a full file specification, the unspecified components are taken from the window server's 
default path which, in practice, is always the internal drive M:\. 


Not available in version 2 of the window server. 


In version 4 of the window server, the function will save a double bitmap when saving the screen or a 
backed-up window with a grey plane. 


gCopyBit Copy a bitmap to a window 
VOID gCopyBit (P_POINT *pos, UINT bitmap_id, P_RECT *prect, UINT mode); 


Copy the rectangular block of pixels specified by prect in the bitmap with ID bitmap_ia to position pos 
in the destination. 


The parameter mode should be one of: 
G_TRMODE_REPL where bits in the source pattern replace corresponding bits in the destination. 


G_TRMODE_SET where Is in the source pattern set corresponding bits in the destination (Os in 
the source do not change corresponding bits in the destination). 


G_TRMODE_CLR where Is in the source pattern clear corresponding bits in the destination (Os in 
the source pattern do not change corresponding bits in the destination). 


G_TRMODE_INV where Is in the source pattern toggle corresponding bits in the destination (Os 
in the source pattern do not change corresponding bits in the destination). 


The p_point and p_rect structs are defined as: 


typedef struct 
{ 
WORD x; 
WORD y; 
} P_POINT; 


typedef struct 
{ 
P_POINT tl; /* top left pixel (internal) */ 
P_POINT br; /* bottom right pixel (external) */ 
} P_RECT; 


This function should not be used to copy from a bitmap onto itself, since it does not handle overlapping 
source and destination areas - gcopyRect should be used instead. 


The parameter bitmap_id can also be the ID of a backed-up window to refer to the backup bitmap (but not 
in version 2). 


In version 4 of the window server, when bitmap_ia refers to a backed-up window, the function has a 
special way of handling grey: 


e In normal mode, the black plane only is copied from the source to the destination. 


e In G_GC_FLAG_GREY_PLANE mode, the grey plane from the source is selected and copied to the 
grey plane of the destination. If the source only has one plane, then that is used as the source. 


e In G_GC_FLAG_BOTH_PLANES mode, and with a two plane source, both planes are copied to their 
respective destination planes. If only one plane exists, then it will be copied to both planes of the 
destination. 


Note that this does not apply when copying from any other form of bitmap - in all other cases the black 
and grey planes must be copied by two separate calls to gcopyBit. 


4-29 


WINDOW SERVER REFERENCE 


gCopyRect Copy a bitmap onto itself 
VOID gCopyRect (P_RECT *prect, P_POINT *pos, UINT mode); 

Copy the rectangular block of pixels specified by prect to position pos. 

The parameter mode is as for gcopyBit, described above. 


This function should only be used when the current graphics context is assigned to a bitmap. It should not 
be used to copy parts of windows since it does not handle invalid areas or possible obscuring windows - 
wScrollRect should be used instead. 


gPeekBit Read a bitmap 
INT gPeekBit (UINT bitmap_id, P_POINT *pstart, UINT len, UBYTE *presult) ; 


Copy a horizontal slice of 1en bits starting at (pstart->x, pstart->y) from bitmap_id to presult 
(which must be at least (((1en+15)/8) & (~1)) bytes long). 


To copy from the screen, set bitmap_id to zero. 
If the section specified by start and len extend outside the bitmap then gPeekBit will call p_panic. 
The parameter bitmap_id can also be the ID of a backed-up window to refer to the backup bitmap. 


On version 2 of the window server, 1en must be less than (8*MAX_WSERV_TO_CLIENT_BUFFER) bits long. 


In version 4 of the window server, if the most significant bit of the bitmap_id is set, then the function will 
‘peek' from the grey plane. For example, the following code fragment re-directs the function to ‘peek’ from 
the grey plane: 


bitmap_id |= 0x8000; 

gPeekBit (bitmap_id, ... ); 
gCheckBitmapID Check if a bitmap is valid 
INT gCheckBitmapID(UINT bitmap_id) ; 
Check if a bitmap is valid. 


Returns zero if it is valid. Otherwise the function calls p_leave(E_FILE_NxIST) or returns E_FILE_NXIST, 
depending on whether woisableLeaves has been called. 


Not available in version 2 of the window server. 


Multiple bitmaps 


In version 4 of the window server, a set of bitmap functions is available that allows a bitmap file to be 
opened so that bitmaps within the file can be loaded or drawn direct from the file. 


Loading multiple bitmaps from a file with this method is considerably quicker than repeated calls to 
gOpenBit as the file does not have to be opened and closed for every bitmap loaded. 


Drawing bitmaps direct from a file is advantageous when drawing part of a large bitmap; only the parts 
actually drawn are loaded, saving on access time and storage. 


When using this method to draw the whole bitmap, there is a trade-off between memory usage and the 
time taken to perform the draw. While loading the bitmap "bit by bit" as it is drawn makes it slower than 
loading the whole bitmap in one go and then drawing it, it needs less memory, as only that part of the 
bitmap to be drawn needs to be in memory at any one time. 


4-30 


4 GRAPHICS OUTPUT 


glnitBit Open a bitmap file 
INT gInitBit (TEXT *filename, INT *pcount) ; 


Available in version 4 of the window server, this function opens the bitmap file £i1ename ready for calls 
to gGet Bit OF gDrawBit. 


If the open is successful, the function returns the handle of the open file and the number of bitmaps held 
in the file is written to *pcount. 


If filename is not a full file specification, the unspecified components are taken from the window server's 
default path which, in practice, is always the internal drive M:\ 


If an error (with error number err) occurs, the function calls p_leave (err) or returns the (negative) error 
number, depending on whether woisableLeaves has been called. 


See also gSetOpenAddress for opening a bitmap file which is embedded within another file. 


gGetBit Load a bitmap from an open file 


INT gGetBit (UINT handle, UINT index,UINT flags, W_OPEN_BIT_SEG *pbitseg) ; 


Available in version 4 of the window server, this function loads a bitmap from the bitmap file referenced 
by handle (as returned from a previous call to ginitBit). 


index indicates the position of the bitmap within the file; zero indicates the first bitmap, one indicates the 
second and so on. 


The behaviour of the function and the meaning of the parameters flags and pbitseg are the same as for 
gOpenBit. 


Returns the ID of the bitmap if successful. 


If an error (with error number err) occurs, the function calls p_leave (err) or returns the (negative) error 
number, depending on whether woisableLeaves has been called. 


gDrawBit Draw a bitmap from an open file 
INT gDrawBit (P_POINT *pos, INT handle,P_RECT *prect, INT mode, INT index) ; 


Available in version 4 of the window server, this effectively performs a gGetBit, gCopyBit and wrree. 
The pos, prect and mode parameters are the same as for gcopyBit in that they specify what is drawn. The 
handle and index parameters are the same as for gcetBit in that they reference the open bitmap file and 
indicate the position of the source bitmap within the file (relative to zero). 


Only the relevant scan lines for the parts to be drawn are loaded; these are loaded one at a time. This 
means that no extra memory needs allocating. 


Returns zero if successful. 


If an error (with error number err) occurs, the function calls p_leave (err) or returns, depending on 
whether woisableLeaves has been called. 


gQueryBit Query the size of a bitmap 


INT gQueryBit (INT handle, INT index, P_POINT *psize); 


Available in version 4 of the window server, this function queries the size of a bitmap within a file opened 
by gInitBit. The open file is referenced by handle while index indicates the position of the bitmap 
within the file (relative to zero). The structure pointed to by psize is filled in with the size of the bitmap. 


Returns zero if successful. 


If an error (with error number err) occurs, the function calls p_leave (err) or returns, depending on 
whether woisableLeaves has been called. 


4-31 


WINDOW SERVER REFERENCE 


wFree Close an open bitmap 


VOID wFree(UINT handle) ; 


In version 4 of the window server, if passed the handle referencing an opened bitmap file (as returned 
from a call to ginitBit), the function closes the bitmap file but leaves loaded any bitmaps that came from 
that file. 


ginitMultiSave Initialise a multiple bitmap file 
INT gInitMultiSave (TEXT *fname, INT count) ; 


Available in version 4 of the window server, this function creates a file fname prepared to receive up to 
count bitmaps. 


The call returns a positive handle if the file was successfully opened and initialised. This handle should be 
used in subsequent calls to gSaveMultiBit, gSaveMultiRect and gEndMultiSave. 


Any errors generated by the filing system when creating the file will be returned (or leave called). In this 
event, any file created will be deleted. 


gSaveMultiBit Save a bitmap to a multi bitmap file 
INT gSaveMultiBit (INT handle, INT bitmap) ; 


Available in version 4 of the window server, this function attempts to save the bitmap with ID bitmap to 
the initialised multiple bitmap file referenced by hand1e. If bitmap is zero, the screen is saved to the file. 


The call returns zero if successful. 


Any error generated by the filing system when writing to the file will be returned (or leave called) in the 
same way as for gSaveBit. If an attempt is made to save more than the maximum permitted number of 
bitmaps (set by the parameter count in the call to ginitMultiSave) the function will return 
E_GEN_TOOMANY. 


If the call fails (for whatever reason), the multiple bitmap file will be left in good condition and any 
bitmaps already saved will still be accessible. However, any further attempts to save to the file will not be 
allowed and it must be closed by a call to gzEnaMultiSave. 


gSaveMultiRect Save part of bitmap to multi bitmap file 
INT gSaveMultiRect (INT handle, INT bitmap, P_RECT *prect); 


Available in version 4 of the window server, this function behaves in the same way as gSaveMultiBit. 
However, only that part of the bitmap specified by the rectangle defined by prect is saved. 


The call can fail for exactly the same reasons as gSaveMult iBit returning the same values. 


gEndMultiSave End multiple bitmap save and close file 
INT gEndMultiSave (INT handle) ; 


Available in version 4 of the window server, this function ends the saving of bitmaps to a multiple bitmap 
file referenced by handle and closes the file. 


The call returns zero if successful. 


Any error generated by the filing system when closing the file will be returned (or leave called). 


ginquireChecksum Inquire screen or bitmap checksum 
VOID gInquireChecksum(INT handle, UWORD *pchecksum) ; 


Available in version 4 of the window server, this function calculates a checksum and places the value in a 
UWORD pointed to by pchecksum. 


handle references the object of the checksum operation and can be the ID of a bitmap or a backed-up 
window. If handle is zero, the object of the checksum operation is the whole screen. 


4-32 


4 GRAPHICS OUTPUT 


Adding graphics output functions 


The window server can be extended by building additional low-level graphics output services, that write 
directly to the screen memory, into a dynamic link library (DYL). Such a DYL, when loaded using 
wLoadDYL, effectively becomes part of the window server. 


Note that the services described in this section are not suitable for loading and accessing any other type 
of DYL. 


Producing the window server extension DYL itself is an advanced topic and is not documented in this 
Software Development Kit. At the time of writing, no such DYL exists. 


A DYL that extends the window server must first be loaded by calling p_1oad1ib (described in the Object 
Oriented Programming chapter in the PLIB Reference manual). It must then be loaded by the window 
server using wLoadDYL. The services supplied by the DYL can then be accessed using wcalipyL and 
wCallDYLReply. 


wLoadDYL Load a DYL 


INT wLoadDYL(TEXT *name) ; 
Load the loaded window server extension DYL name into the window server. 
The DYL should already have already been loaded into memory by a call to p_loadlib. 


The parameter name is the DYL segment name (which is the same as the DYL file name, but does not 
include the directory or the device). 


Returns the ID of the DYL (to be used by wcalipyu and wcal1DyLReply). 


Example 


GLDEF_C UINT LoadWservDYL (VOID) 
{ 
f_leave(p_loadlib("C:\DYL\TEST.DYL", &test_dyl_handle, TRUE)); 
return (wLoadDYL("TEST.DYL") ); 
} 


wCallIDYL Call a DYL function 


VOID wCallDYL(UINT dyl_id, UINT class, UINT size_of_data, VOID *pdata); 


Call a graphic function within the DYL ay1_id where class specifies which function within the DYL to 
call (as specified by the builder of the DYL). 


pdata points to the parameters to be passed to the DYL. 


size_of_data 1s the number of bytes of data at paata. 


wCallDYLReply Call a DYL enquiry function 
INT wCallDYLReply(UINT dyl_id, UINT class, UINT size_of_data, VOID *pdata, VOID *presult) ; 
Call an enquiry function within the DYL where the function called should not do any graphics output. 
pdata points to the parameters to be passed to the DYL. 

size_of_data is the number of bytes of data at paata. 


Returns the value returned by the DYL function (negative return values cause p_leave to be called, 
positive values are returned normally). 


The DYL function may also return a buffer of data, if it does presult should point to a buffer large 
enough to hold the returned data. 


4-33 


CHAPTER 5 


EVENTS 


DS ew En a FS EF 
Getting the next event 


wGetEventWait Wait for an event 


VOID wGetEventWait (WS_EV *event) ; 


Wait for a window server event and return with the event type and parameters written to the ws_zv struct 
at address event where ws_Ev is defined as: 


typedef struct 
{ 
WORD type; 
UWORD handle; 
UWORD time; 
WS_EVENT_UNION p; 


} WS_EV; 

where: 

type is the positive event type of the form wu_xxxx 

handle For events that are directed at a window (eg wM_REDRAW, WM_MOUSBE), this is the 
handle that was specified to wcreateWindow. For events that are not directed at 
a window (eg WM_KEY, WM_FOREGROUND), it is set to the value specified to 
wConnect. 

time is set by key and mouse events. It gives the low order word of the system tick 
count (a tick is 1/32 of a second) when the event occurred. It may be used, for 
example, to detect double clicks. 

Pp is a union of event type-dependent parameters 


The ws_EVENT_UNION union is defined as: 


typedef union 
{ 
UWORD uword; 
UBYTE *dpoint; 
P_RECT rect; 
WMSG_KEY key; 
WMSG_MOUSE mouse; 
WMSG_RUBBER rubber; 
WMSG_CAPS caps; 
} WS_EVENT_UNION; 


These event-specific parts are described under the description of the associated event type, in the course of 
this chapter. 


5-1 


WINDOW SERVER REFERENCE 


wGetEvent Asynchronously request an event 
VOID wGetEvent (WS_EV *event) ; 


Request an event from the window server and return without waiting for the request to complete. This is 
the asynchronous version of wGetEventWait. For more information on asynchronous events, see the 
chapter Asynchronous Requests and Semaphores in the PLIB Reference manual. 


Calling wGetEvent initially sets event->type to E_FILE_PENDING to indicate that no event has yet arrived. 
When there is an event to deliver, the window server sets event->type to the event type and also sets the 
rest of event as appropriate for event->type. It then signals the caller's I/O semaphore. 


Only one wGetEvent may be outstanding at a time. The window server panics the process if a second 
wGetEvent is called when one is already pending. 


wGetEventSpecial Asynchronously request selected events 
VOID wGetEventSpecial (WS_EV *event,UINT flags); 


Introduced in version 4 of the window server, this is an enhanced version of the function wGetEvent, 
where the flags parameter is used to select which type of event(s) the window server is to deliver. 


There can only be one call outstanding to either wGetEvent or wGetEvent Special at any one time. 


To change the type of event(s) selected in an outstanding wGetEvent or wGetEvent Special, use the 
function wGetEventUpdate. 


The following flags can be used to select the corresponding events. They can be ored together: 


WE_KEY Selects key and task key events 

WE_REDRAW Selects wM_REDRAW events 

WE_STATUS Selects the WM_FOREGOUND, WM_BACKGROUND and WM_oN events 

WE_MOUSE Selects mouse and rubber band events 

WE_OTHERS Selects all events other than those listed above. 

WE_NORMAL Selects all of the above events 

WE_ESC This is only relevant when wE_KEy is not set. If the ESC key is pressed, the 
keyboard buffer is thrown away and a wM_EScaAPE event is delivered to the 
application. 


Note that calling weetEvent Special with the we_Normat flag set is equivalent to calling wGetEvent. 


wGetEventUpdate Change event types selected 
VOID wGetEventUpdate(UINT flags); 


Introduced in version 4 of the window server, this function modifies the type of event(s) that the window 
server is to deliver where there is an outstanding wGetEvent or wGetEvent Special call. 


The previously selected event type(s) are discarded and replaced with a new set as specified in the flags 
parameter. The possible values for f1ags are the same as those described in wGetEvent Special. 


Note that if there is no outstanding call to either wGetEvent or wGetEvent Special then calling 
wGetEventUpdate will have no effect. 


5-2 


5 EVENTS 


Event types 
This section describes event types that are common to more than one machine type. 
The following descriptions assume that event is declared as: 


WS_EV event; 


WM_KEY Key press event 


Sent when a key is pressed where the key press is described by the wasc_xey struct event.p.key where 
wMsG_kEy is defined as: 


typedef struct 
{ 


UWORD keycode; /* Code for the key pressed */ 
UBYTE modifiers; /* State of mouse button, shift keys etc */ 
UBYTE count; /* Used to accumulate auto-repeat counts */ 


} WMSG_KEY; 
Count 
For single key presses, event .p.key.count is l. 


If a key is held down, count will get to be greater than | when the client is unable to process keys at the 
rate at which the system generates repeated keys. 


As described in the Keyboard input section of the first chapter, application programmers are best advised 
just to ignore the repeat count. 


Modifiers 


event .p.key.modifiers is a Set of bit flags: 


W_SHIFT_MODIFIER SHIFT key down 
(0x02) 

W_CTRL_MODIFIER CTRL key down 
(0x04) 

W_PSION_MODIFIER PSION key down 
(0x08) 

W_CAPS_MODIFIER caps lock on 
(0x10) 


W_NUM_LOCK_MODIFIER num lock on (MC only) 
(0x20) 


Keycode 


When a "standard" key that represents a character from the SIBO character set! is pressed, 

event .p.key.keycode contains the character code of the corresponding character in the range 0x20 to 
(nominally) oxt£ but excluding ox7£. The actual upper limit on the code which can be directly produced 
from the keyboard is less than oxfr and depends on what language (eg French, German) the keyboard is 
produced for. 


The SHIFT and CAPS LOCK keys modify the keycode following the normal conventions and as suggested by 
the labelling of the key. 


In most cases on the HC and MC and for those keys that are used as accelerators on the S3 and S3a, the 
PSION shift key produces a keycode that is generated by adding 0x200 (w_spEcIAL_kEy) to the unshifted 
keycode with caps lock off. For example, pressing PSION+A with or without CTRL and SHIFT and regardless 
of the caps lock state produces a keycode of 0x261 (the code for lower case 'a' plus w_SPECIAL_KEY). 


'Similar to IBM's code page 850 - see the section Text Fonts in the first chapter. 


WINDOW SERVER REFERENCE 


On machines which have a CTRL key (that is, excluding the HC), you can generate any keycode from 0x00 
to 0xff indirectly by holding down the CTRL key and typing the required code as a 3-digit decimal number 
(using leading zeros as necessary). In this case, a single key event is generated after the third decimal 
number is pressed. Also, following normal conventions, pressing CTRL-A to CTRL-Z produces a keycode 


from 0x01 to Oxia. 


Many of the keys do not represent printable characters from the SIBO character set (these keys are 
sometimes called "special keys"). Such keys generate a keycode which is either less than 0x20, 0x7f or 


greater than Oxff. 


The following lists the key codes produced by the special keys: 


W_KEY_TAB (0x9 or 
"\t') 


W_KEY_DELETE_LEFT 
(0x08 or '\b') 


W_KEY_DELETE_RIGHT 
(Ox7£) 


W_KEY_RETURN (0x0d 


or ' Nx) 


W_KEY_ESCAPE (0x1b) 


W_KEY_UP (0x100) 


W_KEY_DOWN (0x101) 


W_KEY_RIGHT (0x102) 


W_KEY_LEFT (0x103) 


W_KEY_PAGE_UP 


(0x104) 


W_KEY_PAGE_DOWN 


(0x105) 


W_KEY_HOME (0x106) 


W_KEY_END (0x107) 


W_KEY_TASK (0x108) 


W_KEY_VOICE (0x109) 


5-4 


Produced by TAB, with or without SHIFT or CTRL. On the HC and MC only, the 
PSION key adds w_sPECIAL_KEY. On the Workabout, the PSION key (but not 
SHIFT+PSION) converts the keypress to W_KEY_TASK. 


Produced by DEL on the HC, DELETE with or without CTRL or PSION on the S3 
and $3a, BACKSPACE with or without SHIFT or CTRL on the MC, and DEL 
without SHIFT on the Workabout. On the HC and MC, the PSION key adds 
W_SPECIAL_KEY. 


Produced by SHIFT+DEL on the HC and Workabout, SHIFT+DELETE on the $3 
and S3a, DELETE with or without SHIFT or CTRL on the MC. On the MC only, 
the PSION key adds w_sPECIAL_KEY. 


Produced by ENTER, with or without SHIFT or CTRL. On the HC and MC only, 
the PSION key adds w_sPECIAL_KEY. 


Produced by ESC, without SHIFT or CTRL on the Workabout; with or without 
SHIFT or CTRL on all other machines. On the HC and MC only, the PSION key 
adds w_SPECIAL_KEY. 


Produced by UP ARROW, with or without SHIFT or CTRL. On the HC and MC 
only, the PSION key adds w_SPECIAL_KEY. 


Produced by DOWN ARROW, with or without SHIFT or CTRL. On the HC and MC 
only, the PSION key adds W_SPECIAL_KEY. 


Produced by RIGHT ARROW on the HC, RIGHT ARROW with or without SHIFT or 
CTRL on the $3, S3a, Workabout and MC. On the HC and MC only, the PSION 
key adds w_sPECIAL_KEY. 


Produced by LEFT ARROW on the HC, LEFT ARROW with or without SHIFT or 
CTRL on the $3, S3a, Workabout and MC. On the HC and MC only, the PSION 
key adds Ww_SPECIAL_KEY. 


Produced by PSION+UP ARROW on the $3, S3a and Workabout, PAGE UP with or 
without SHIFT or CTRL on the MC. On the MC only, the PSION key adds 
W_SPECIAL_KEY. 


Produced by PSION+DOWN ARROW on the $3, S3a and Workabout, PAGE DOWN 
with or without SHIFT or CTRL on the MC. On the MC only, the PSION key adds 
W_SPECIAL_KEY. 


Produced by PSION+LEFT ARROW on the $3, S3a and Workabout, HOME with or 
without SHIFT or CTRL on the MC. On the MC only, the PSION key adds 
W_SPECIAL_KEY. 


Produced by PSION+RIGHT ARROW on the $3, S3a and Workabout, END with or 
without SHIFT or CTRL on the MC. On the MC only, the PSION key adds 
W_SPECIAL_KEY. 


Produced by SHIFT+LEFT ARROW (TASK) on the HC, TASK with or without SHIFT 
or CTRL on the MC and PSION+TAB on the Workabout. On the MC only, the 
PSION key adds W_SPECIAL_KEY. 


Normally processed by the window server to switch the foreground task and not 
passed to clients. However, you can use wCaptureKey to capture the W_KEY_TASK 
key (as described under wcaptureKey). 


Produced by RECORD with or without SHIFT or CTRL on the MC only. The PSION 
key adds w_sPECIAL_KEY. 


W_KEY_CAPS_LOCK 
(0x10c) 


W_KEY_BACKLIGHT 
(0x120) 


W_KEY_INFO (0x121) 


W_KEY_MENU (0x122) 


W_KEY_HELP (0x123) 


W_KEY_DIAMOND 
(0x124) 


W_KEY_APP1 to 


W_KEY_APP8 (0x131 to 


0x138) 


W_KEY_MODE (0x130) 


W_KEY_LCD (0x2000) 
W_KEY_LCD_MINUS 
(0x2001) 


W_KEY_ON (0x2002) 


5 EVENTS 


Produced by CAPS LOCK on the $3 and MC, by PSION+DIAMOND on the S3a and 
by PSION+SPACE on the Workabout. 


This key press is processed by the operating system to set the caps lock state 
and passed to the window server on the $3, S3a and MC (but not on the HC). 
On the MC, the window server generates a wM_KEYBOARD_STATE_CHANGE event 
to the shell. The window server does not normally pass it on to the foreground 
client. You can use wcaptureKey to capture the w_KEY_cAPs_LOocK key. 


Produced by the BACKLIGHT key with or without SHIFT on the HC and the 
Workabout. On the HC only, the PSION key adds w_spECIAL_KEY. 


This key is normally processed by the operating system although you can 
disable it by calling p_setbacklight as described in the General System 
Services section of the PLIB Reference manual. The key is normally passed 
through to the foreground client (unless captured by a client using 
wCaptureKey). 


Produced by SHIFT+RIGHT ARROW (INFO) on the HC only. 


Produced by MENU with or without SHIFT on the HC and by MENU with or 
without SHIFT, CTRL or PSION on the S3, S3a and Workabout. On the HC only, 
the PSION key adds w_spEcIAL_KEY. 


If wsEnableTemp has been called, the window server processes PSION+MENU to 
present a temporary status window (in which case it does not pass the key press 
on to the client). By convention on the S3 and S3a, CTRL+MENU is processed by 
clients to present a permanent status window. 


Produced by HELP with or without SHIFT, CTRL or PSION on the S3 and S3a, and 
by ESC with either SHIFT or CTRL, but not PSION, on the Workabout. 


As suggested by the S3/S3a key labels, PSION+HELP on these machines should 
be interpreted as a DIAL key. 


Produced by DIAMOND on the S3a only. Used by applications to switch from one 
mode to another. 


Produced by the 8 membrane keys on the S3 from left to right (also called 
application keys). 


These are normally handled by the window server in co-operation with the 
system task. For more information, see the section on Clients and the Window 
Server in the Introduction chapter of this manual. 


Produced on the S3 only when the application key that is associated with the 
foreground application is pressed. Applications normally cycle through their 
display modes in response to this key event. 


Produced by DIAMOND on the S3a when running in S3 compatibility mode. 


Produced by the LCD BRIGHTER and LCD DIMMER keys on all machines except 
the Workabout. On the Workabout the single LCD BRIGHTER key produces 
W_KEY_Lcp only, and SHIFT+LCD BRIGHTER is used to dim the LCD. 


These keys are processed by the operating system rather than the window server 
so you can't use wCaptureKey to disable them. These keys are normally passed 
through to the foreground client. 


Produced on an HC with version 3.5 of the window server, and on the S3, S3a 
and Workabout when the ON key is pressed. 


Also, when the machine switches on for any reason (such as the expiry of an 
absolute timer) the operating system manufactures an w_KEyY_on event to the 
window server?. 


2On the HC, the window server is only informed of the machine being switched on after 
p_setonevent (TRUE) has been called. 


5-5 


WINDOW SERVER REFERENCE 


This event is normally processed by the window server to: 


1. pass a WM_ON event to the foreground client (provided it has called 
wiInformOn) or, in version 4 of the window server, pass a WM_ON event 
to a client whether it is in foreground or background (provided it has 
called wInformonAll (TRUE) ) 


2. present an info message to inform the user of any low battery state? 
3. to present the password alert if a password has been set. 


When processed by the window server, the w_KEY_on event is not passed to the 
foreground client. 


You can use wCaptureKey to capture the w_KEy_oNn key. This will disable all 
window server processing of this event. 


W_KEY_OFF (0x2003) Produced by the OFF key on the HC, $3, S3a and Workabout only. 


Normally processed by the window server to turn the machine off and not 
passed to clients. However, you can use wCaptureKey to capture the OFF key (as 
described under wcapturekey). The capturer can turn the machine off by 
calling p_off - as described in the General System Services section of the PLIB 
Reference manual. (The same section also describes p_setauto which can be 
used to stop the machine from automatically switching off.) You don't get a 
W_KEY_OFF event when the machine automatically switches off. 


WM_REDRAW Redraw event (WM 


Sent when the client's event queue is empty and one or more windows has an update region. 


The parameter event .p.rect describes a rectangular block of pixels from the update region (and which 
needs to be redrawn). 


The only event type that has a lower priority than wM_REDRAW is WM_USER_MSG. 


WM_BACKGROUND Background event 


Sent to a foreground client when it goes background. 
Only event.type is set. 


On all machines except the MC, you generally do not need to do anything when you receive a 
WM_BACKGROUND event. However, if you are doing anything that requires real-time input from the user (a 
game, for example) or you are doing an animated display, you should suspend the operation until you 
receive a WM_FOREGROUND event. 


WM_FOREGROUND Foreground event 


Sent to a background client when it becomes foreground. 


Only event.type is set. 


WM_CANCELLED Cancellation event 


Sent in response to a call to wcancelGetEvent command - see the description of wcancelGetEvent in this 
chapter. 


Only event.type is set. 


3See also the description of the wsERV_FLAG_LOW_BATTERY_WARNINGS flag in wsystem. 


5-6 


5 EVENTS 


WM_USER_MSG User message event 


Sent in response to a call to wusermsg. This event has the lowest priority of all and can be used to indicate 
that the window server has no more messages to send - see the description of wuserMsg in this chapter. 


Only event .type is set. 


WM_ON Machine switched on event 


Available in version 3.5 of the window server; if the client has called wrnformon, it is sent this event when 
the machine is switched on and it is in foreground. 


The event is designed to prompt the foreground client to update its display. 


On the HC, the window server is only informed of the machine being switched on after 
p_setonevent (TRUE) has been called. 


In version 4 of the window server, if the client has called winformonAll (TRUE), it is sent this event when 
the machine is switched on, whether it is in foreground or background. 


Only event .type is set. 


WM_COMMAND Command received from another client 


This is sent in response to a wSendCommana from another client to prompt the receiver of the event to call 
wGetCommand to get the command data. It is only available in version 3.5 of the window server. 


Only event .type is set. 


WM_TASK_UPDATE Inform shell of process termination 


Sent to the shell if it is foreground and any process terminates (not just clients of the window server). 


Available only on the $3, $3a and Workabout, and on an HC running version 3.5 upwards of the window 
server. Disabled by default on the HC - see the description of wsystem. 


Only event .type is set. 


WM_TASK_KEY Inform application key handler 


Sent to the application key handler when: 
e an application key is pressed and no process of that application exists 
e a PSION shifted application key is pressed 

Applies only to the S3, S3a and Workabout. 


The index of the application key in the range 0 to 15 is written to event.p.key. keycode. The window 
server handles 16 application keys, where a second set of 8 keys are accessed by holding down the 
CONTROL key. 


WM_DATE_CHANGED Change of date event 


Introduced in version 4 of the window server. Sent whenever the date changes, either because the date has 
en reset or the clock has gone past midnight. 


The message is sent to any Series 3a or Workabout application which is not in Series 3 compatibility 
mode and is in foreground at the time of the event 


Non compatibility mode applications which are in background will receive the message the next time they 
come into foreground. 


If the machine is off at the time of the event, the message is delivered when the machine is next turned on. 


WINDOW SERVER REFERENCE 


WM_ESCAPE Escape-key event 


In version 4 of the window server, this message is delivered to an application when the ESC key is pressed 
in the following circumstances: 


e  =The application must have asynchronously requested selected events by calling 
wGetEventSpecial. 


e Among the events selected for delivery, WZ_EVENT_ESC must be included but wE_EVENT_KEY must 
be excluded. 


In this situation, the content of the keyboard buffer is discarded. 


Large screen events 


The event types in this section are only generated on large screen versions of the window server, such as 
on the MC200 and MC400 machines. 


WM_DEICONISE Deiconisation event 


Sent to a client to tell it to deiconise. The client will have previously declared itself iconised with a 
wClientIconised call. 


Only event .type Is set. 
A client receives this message when another client calls wclientPosition to position it to the foreground. 


It is also sent to the system application (sys$shll.img) when it is iconised and selected by the PSION-TASK 
key press. 


WM_ATTACHED Attachment event 


Sent to a client to tell it another client has attached itself on top of it. The uword field of the 
WS_EVENT_UNION structure is set to the process ID of attached client. After receiving this message the 
client will not be able to receive wM_KEyY events until the attached client detaches, terminates or 
disconnects from the window server. 


Only event.type is set. 


A client will receive a WM_ATTACHED event when the notifier process (sys$nt fy) attaches itself to the 
foreground client when any process calls p_notify or p_notifyerr. 


WM_DETACHED Detachment event 


Sent to a client when a previously attached client detaches (either by a wDetachClient call, by terminating 
or by disconnecting from the window server). 


Only event .type is set. 


WM_KEYBOARD_STATE_CHANGE Keyboard state change event 


This event is only ever sent to the system application (sys$shll.img). It is sent when either the numlock or 
capslock state changes. The new states of these can be read from event .p.caps.modifiers. 


5 EVENTS 


a EEEEEEEEEOEOEOEeEeEeEeEeseseseeess 
Mouse events 


The event types in this section are only generated on machines with a pointing device, such as on the 
MC200 and MC400. 


WM_MOUSE Mouse event 


Sent when ever there is a change of state on the mouse (digitiser). 
The wmsc_mouse structure is defined as: 


typedef struct 
{ 
UBYTE event; /* type of mouse event */ 
UBYTE state; /* state of mouse button, shift keys etc */ 
P_POINT pos; /* mouse position (relative to window) */ 
} WMSG_MOUSE; 


event .p.mouse.event gives the type of the mouse event that occurred and is one of: 


WM_MOUSE_MOVE mouse movement event (this is filtered out by default) 
WM_MOUSE_PRESS mouse press event 
WM_MOUSE_RELEASE mouse release event 


Mouse movement events (wmM_MousE_move) are filtered out unless explicitly enabled, on a per-window 
basis. See wcreateWindow and wSetWindow for details. 


event .p.mouse.state gives the state of the mouse and the key modifiers when the event occurred, it may 
be tested using the bit masks: 


W_MOUSE_DOWN mouse button down 

W_MOUSE_OUTSIDE mouse event occurred outside window 
W_SHIFT_MODIFIER SHIFT key down 

W_CTRL_MODIFIER CTRL key down 

W_PSION_MODIFIER PSION key down 

W_CAPS_MODIFIER Caps lock on 


W_NUM_LOCK_MODIFIER Num lock on 


The w_mMousE_ouUTSIDE bit is set when a mouse event occurs outside the visible portion of the given 
window. This can happen when either: 


a window has grabbed the mouse, by specifying the w_wIN_mMousE_GRAB bit, WM_MOUSE_RELEASE 
events are sent to the same window that received the wm_MousE_PRESS event, even if the mouse 
has subsequently moved outside the visible portion of the window. 


or: 
a window has captured the mouse by calling wcaptureMouse. 


Testing the w_mousk_ouTSIDE bit is not equivalent to checking the mouse position against the extent of the 
window, because a client can never know if part of the window has been obscured. 


WM_RUBBER_BAND INIT Start rubber band 


This is a special version of the wu_mousE message, it also uses the wmsc_mouseE Structure. It is sent instead 
of a wM_MousE event when a mouse press occurs inside a window with the w_wIN_RUBBER_BAND_CAPTURE 
flag set. 


See the Rubber Band section for details. 


WINDOW SERVER REFERENCE 


WM_RUBBER Complete rubber band 


Sent on completion of a rubber band. 


See the Rubber Band section for details. 


WM_ ACTIVE Activation event 


Sent to a window that has previously set the w_wIN_INacTIVE bit (in a call to wcreat eWindow or 
wSetWindow) whenever a WM_MOUSE event of type WM_MOUSE_PRESS is sent to the window or any of its 
descendants. 


Only event .type is set. 


WM_ACTIVE notifies a parent that the mouse has clicked somewhere in its window tree. The wm_mousE event 
is then sent straight to the window where the click occurred (unless that window has the w_wIN_No_MoUSE 
bit set). 


If a window and its descendant both have the w_w1n_1NacTIVE bit set, they both receive a WM_ACTIVE event 
if there is a click in a descendant of the descendant window. 


SSS SSS SS — SS ——————————e 
Event functions 


wCancelGetEvent Request a cancel event 
VOID wCancelGetEvent (VOID) ; 
Instruct the window server to send the caller a WM_CANCELLED event. 


After a call to wcancelGetEvent, the window server delivers the w4_CANCELLED event at the highest 
priority - any other events waiting in the window server client event queue are overtaken. 


wUserMsg Request a user event 
VOID wUserMsg (VOID) ; 
Instruct the window server to send the client a w“_USER_MsG as soon as it has no other event to report. 


A second call to this function before the first w1_usER_msc is delivered will have no effect. 


wSendCommand Send a command to another client 
INT wSendCommand(HANDLE pid, VOID *pbuf, UINT len); 
Send the 1en bytes of data at pbuf to the window server client with process ID pia. 


If the call is successful, the function returns zero and client pid will receive a wM_COMMAND event to which 
it should respond by calling wGet command (as described below). 


If no client with process ID pid exists, the function leaves or returns with the error number E_FILE_NXIST. 


The function can be used to send up to 127 bytes. If 1en is | or 2, the function does not allocate any 
memory. If 1en is greater than 2, the function could leave or return with the error number 
E_GEN_NOMEMORY. 


Only available in version 3.5 and upwards of the window server. 


5-10 


5 EVENTS 


wGetCommand Get a command from another client 


INT wGetCommand (VOID *pbuf) ; 

Write to pbuf, the command data that was last sent to this process (with a call to wsendcommand). 
This function should be called in response to the receipt of a wa_commanp event. 

There should be at least 127 bytes of memory at pbuf. 


If another command is sent to the client before it has read the old command, the old command is 
overwritten with the new data. 


The function behaves as for wcheckPoint in that it flushes the client-side buffer and reports any uncleared 
error - either by calling p_ieave or by returning the error number. 


Only available in version 3.5 and upwards of the window server. 


winformOn Enable the reception of WM_ON events 
VOID wInformOn (VOID) ; 

Enable the reception of a wu_on event when the machine is switched on. 

The window server only sends a wy_on event to the foreground client. 


On the HC, the window server is only informed of the machine being switched on after 
p_setonevent (TRUE) has been called (normally by the shell). 


Only available in version 3.5 and upwards of the window server. 


winformOnAll Enable/disable the reception of WM_ON events 


VOID wInformOnAll(UINT state); 


Available in version 4 of the window server, this function is similar to wInformon. However, there are 
some subtle differences. 


If state is TRUE, it enables the reception of wu_on events; on the other hand, if state 1s FALSE, it disables 
the reception of wm_on events. 


When enabled by this call, wu_on events are delivered whenever the machine is switched on, regardless of 
whether the calling client is in foreground or in background. 


Disabling wu_on events with this call disables the reception of wu_on events regardless of whether they 
were originally enabled by a call to wInformonall Or wInformon. 


Capturing keys 


wCaptureKey Capture a key 
INT wCaptureKey(UINT keycode, UINT modifiers, UINT modifier_mask) ; 
Send the specified key press(es) to the calling client, whether it is foreground or not. 
Every time a key is pressed the window server evaluates 
(key_pressed_code==keycode) && ((key_pressed_modifiersé&émodifier_mask) ==modifiers) 
and if the result is TrRuz then the keyboard event is sent to the client that specified the capture. 
For example: 
wCaptureKey (W_SPECIAL_KEY|'a',W_PSION_MODIFIER, W_PSION_MODIFIER) ; 
captures PSION+A, PSION+SHIFT+A, PSION+SHIFT+CTRL+A, and PSION+CTRL+A. Whereas: 
wCaptureKey (W_SPECIAL_KEY| 'a',W_PSION_MODIFIER, W_PSION_MODIFIER|W_SHIFT_MODIFIER) ; 


captures PSION+A and PSION+CTRL+A. 


5-11 


WINDOW SERVER REFERENCE 


Note from the above that it is possible for two different but similar key/modifier combinations to capture 
the same key presses. This is significant if the two calls to wcapturekey came from different clients. 
Where two key capture records select the same key press, the key event is delivered to the first client to 
call wCaptureKey. 


The function is useful for implementing "hotkeys" which select a particular task. However, you should 
only capture relatively obscure key combinations which are not normally used by the tasks themselves 
(capturing the unmodified A key, for example, would be disastrous). 


The function returns zero if successful. Errors include E_GEN_NomeEmory and, if there is already a capture 
record with a matching keycode, modifiers and modifier_mask (even as a result of a wcaptureKey from 
another client), E_FILE_Ex1stT. The function either leaves or returns the error, depending on whether 
wDisableLeaves has been called. 


The window server automatically cancels any calls a client has made to wcaptureKey when that client 
disconnects or terminates. 


On an HC, an application can disable the window server's processing of the TASK key by capturing it with: 
wCaptureKey (W_KEY_TASK,0,0); 


Not available in version 2 of the window server. 


wCancelCaptureKey Cancel key capture 
INT wCancelCaptureKey(UINT keycode, UINT modifiers, UINT modifier_mask) ; 


Cancel a key capture set up by wcapturekey, the keycode and masks must exactly match those used to 
initiate the capture. 


The function returns zero if successful. If the keycode/modifier combination is not marked as captured 
then the function will leave or return E_FILE_NxIST. 


Not available in version 2 of the window server. 


Setting task switch keys 


wSetTaskKey Set a task switch key 
INT wSetTaskKey(UINT keycode, UINT modifiers, UINT modifier_mask) ; 


Set the specified keypress(es) to move the foreground client to the end of the task list and bring the client 
previously at position | (where the foreground process has position zero) to the foreground. 


As for captured keys, every time a key is pressed the window server evaluates 
(key_pressed_code==keycode) && ((key_pressed_modifiersémodifier_mask) ==modifiers) 
and if the result is TRUE, the tasks are cycled. 


The effect of setting the task key does not cease when the calling client disconnects or terminates. The 
only way to stop the key press from being a task key is to call wcancelTaskKey. 


Any number of task switch keys may be set. On the HC and MC, these operate in addition to the 
W_KEY_TASK key (unless the w_KEy_TAs«K key has been captured). 


The function returns zero if successful. If there is already a set task key record with a matching keycode, 
modifiers and modifier_mask, the function leaves or returns E_FILE_EXIST. It can also fail with 
E_GEN_NoMEmoRY. If there is already a capture record with a matching keycode, modifiers and 
modifier_mask, the capture key record is cancelled and replaced by the task key record. 


The shell on the S3 and S3a calls wSet TaskKey to assign SHIFT+SYSTEM as a task key. 


Only available in version 3.5 upwards of the window server. 


5-12 


5 EVENTS 


wCancelTaskKey Cancel a task switch key 
INT wCancelTaskKey(UINT keycode, UINT modifiers, UINT modifier_mask) ; 
Cancel a task key setting, set up with wset TaskKey. 


The function returns zero if successful. If the keycode/modifier combination is not marked as a task key 
then the function will leave or return £_FILE_NXIST. 


wSetBackTaskKey Set a back task switch key 
INT wSetBackTaskKey(UINT keycode, UINT modifiers, UINT modifier_mask) ; 

Set the specified keypress(es) to bring the client furthest from the front to the foreground. 

Except that it cycles tasks in the opposite direction, wSetBackTaskKey is identical to wset TaskKey. 


The shell on the S3 and S3a calls wsetBackTaskKey to assign SHIFT+PSION+SYSTEM to the "back-task" key 
which brings the task furthest from the front to the foreground. 


wCancelBackTaskKey Cancel a back task switch key 
INT wCancelBackTaskKey (UINT keycode, UINT modifiers, UINT modifier_mask) ; 
Cancel a back task key setting, set up with wSetBackTaskKey. 


The function returns zero if successful. If the keycode/modifier combination is not marked as a back task 
key then the function will leave or return E_FILE_NXIST. 


Capturing the mouse 


wCaptureMouse Capture the mouse 


VOID wCaptureMouse(UINT wid); 


Capture the mouse within window wid and all its descendants. This function does not capture with 
respect to other clients' windows. 


It is used, for example, by the dialog box that allows the user to click on it or any of its constituent 
windows, but ignores clicks to other windows in the application (ie the menu bar and the application's 
client window). 


If mouse capture is already active in another window then the previous capture will be cancelled before 
the new capture is activated. 


If a window with capture is destroyed the mouse is automatically released. 


wReleaseMouse Release the mouse 


VOID wReleaseMouse (VOID) ; 


Cancel the mouse capture, does nothing if there was no capture active. 


WINDOW SERVER REFERENCE 


The rubber band 


The rubber band is only implemented on machines with a pointing device, such as on the MC200 and 
MC400. 


wRubberBand Rubber banding 


VOID wRubberBand(UINT msg_window, UINT band_window, W_RUBBER_BAND *prubber) ; 


Start the rubber band and return immediately where the result is returned later as a WA_RUBBER event 
(which might just indicate that the parameters are illegal). 


msg_window is the ID of the window to which the wM_RUBBER event will be sent. 


band_window is the ID of the window in which the rubber band will be drawn, it is usually set to zero (the 
whole screen). 


The rubber band is displayed as specified by the w_RUBBER_BAND struct at address prubber where 
W_RUBBER_BAND is defined as: 


typedef struct 
{ 


P_EXTENT start; /* initial size and position */ 
P_EXTENT outer; /* outer bounding rectangle */ 
P_EXTENT inner; /* inner bounding rectangle */ 
UWORD flags; 

UWORD minx; /* max and min size limits */ 


UWORD miny; 

UWORD maxx; 

UWORD maxy; 

P_POINT grid_snap; /* x and y grid snap values */ 
} W_RUBBER_BAND; 


If flags is set to zero then the following default values will be used: 


resizing Disabled. 

minx Not applicable when resizing disabled. 
miny 

maxx 

maxy 

start The extent of msg_window. 

outer No outer bounds. 

inner The visible extent of band_window. 
grid_snap (1,1) in the x and y directions. 
complete on release Disabled. 


Each of these defaults may be overridden by setting the following bits in flags: 


W_BAND_RESIZE enables resizing of the rubber band, if this is selected the rubber band will 
appear on screen with its resize triangles, if resizing is disabled the rubber 
band appears as a rectangle. When resizing is enabled then minx, miny, maxx 
and maxy (which determine the maximum and minimum sizes of the rubber 
band) must be set. 


W_BAND_START sets the start position and size to start. If this conflicts with inner, outer or 
the maximum or minimum size limits then it will be modified appropriately. 


W_BAND_INNER sets the inner rectangle to inner. The movement of the rubber band is 
restricted such that part of the rubber band stays within this rectangle. 


W_BAND_OUTER sets the outer rectangle to outer. The movement of the rubber band is 
restricted such that no part of the rubber band extends outside this rectangle. 


5-14 


5 EVENTS 


W_BAND_GRID_SNAP sets the grid snap values to grid_snap. The rubber band will move/resize in 
steps of grid_snap. 


W_BAND_GRID_SNAP_SIZE aS for W_BAND_GRID_SNap except that only the size of the rubber band (and not 
its position) is grid snapped. 


W_BAND_COMPLETE_ON_UP causes the rubber band to complete on the first mouse up event. 
The values in start, outer and inner are all relative to band_window. 


If there is no legal position for the rubber band then the rubber band completes immediately with a 
WM_RUBBER message with the state set to ww_BAND_ERROR. This could happen (say) if minx is greater than 
maxx Or if inner does not intersect with outer. 


WM_RUBBER events 


The window server sends a wM_RUBBER message when the rubber banding completes. The format of the 
WM_RUBBER message is: 


typedef struct 
{ 
UWORD state; /* completion state */ 
P_EXTENT extent; /* the selected extent */ 
} WMSG_RUBBER; 


Sstate is set to one of the following: 


WM_BAND_NOMOVE the band position was selected without any moving or resizing, extent is the 
same as set in wRubberBand. 


WM_BAND_MOVE the rubber band moved but did not change size. extent is set to the new 
position and the old height and width. 


WM_BAND_RESIZE the rubber band has been resized (and perhaps also moved). extent contains 
the new position and size. 


WM_BAND_CANCEL the rubber band was cancelled. extent is undefined. 
WM_BAND_ERROR the rubber band was not displayed because of illegal parameters in 
wRubberBand. 


Capturing mouse and keyboard events 


The flag w_wIN_RUBBER_BAND_CAPTURE USed in the wSetWindow and wcreateWindow commands can be 
used to capture all mouse and keyboard events to the rubber band from the moment the mouse was pressed 
in the specified window. The first click in the window will be sent to the window as a 
WM_RUBBER_BAND_INIT event and held in a buffer as a wu_mouse event (of type wM_MOoUSE_PRESS). 
Subsequent mouse and keyboard events will also be buffered. When the rubber band becomes active it will 
receive all the buffered events. The capture is cancelled on completion of the rubber band. 


When a client receives a WM_RUBBER_BAND_INIT event it MUST call wRubberBand immediately. This is 
because all clients will have all their mouse events and keys blocked. If the client decides that it does not 
want to launch a rubber band then it should set the w_sanp_KILL_capTurE flag in flags and call 
wRubberBand, this will cancel the mouse capture without actually launching a rubber band (all parameters 
in the w_RUBBER_BAND Structure are ignored except that msg_window must be a valid window ID). 


5-15 


CHAPTER 6 


WINDOW SERVER REFERENCE UPDATE 


This document is a beta version and may be subject to change. 


This chapter describes the changes and additions that have been made to the Window server as a result of 
the introduction of the Siena and Series 3c machines into the SIBO range. 


Note: Siena was codenamed Vine by Psion during development, hence the naming of some of the 
constants given below. 


Screen sizes 


The true screen and pixel dimensions of the various LCD screens on all SIBO machines are as follows: 


Machine type Screen Pixel pitch Pixel size Screen size Screen size 
(pixels) (mm) (mm) (cm) (in) 
HC 160x80 0.34x0.43 0.31x0.40 5.44x3.44 2.14x1.35 
S3 240x80 0.385x0.43 0.355x0.40 9.24x3.44 3.64x1.35 
Workabout 240x100 0.26x0.30 0.23x0.27 6.24x3.00 2.45x1.18 
Siena 240x160 0.25x0.25 0.23x0.23 6.00x4.00 2.36x1.57 
S3a 480x160 0.259x0.259 0.20x0.20 12.477x4.156 4.915x1.637 
S3c 480x160 0.26x0.26 0.20x0.20 12.478x4.158 4.915x1.637 
MC200 640x200 0.33x0.33 0.30x0.30 21.12x6.60 8.31x2.60 
MC400 640x400 0.33x0.33 0.30x0.30 21.12x13.20 8.31x5.20 


In the above table, the horizontal measure is shown before the vertical measure. The pixel pitch measures 
the horizontal and vertical distance between the same points on adjacent pixels. The difference between 
the pixel size and the pixel pitch gives the gap between pixels. 


The Series 3c and the Siena screens support the use of grey in exactly the same way as for the Series 3a. 


Keyboard 


Except where stated below, the keycodes produced on the Series 3c and the Siena are identical to those 
produced on the Series 3a. 


The following table lists the additional and/or modified key codes produced by the special keys on the 
Siena and the Series 3c, as listed in wskeys.h: 


W_KEY_TAB (0x9 or Produced by TAB, with or without SHIFT or CTRL. On the HC and MC only, the 
"\t') PSION key adds w_spEcIaL_kEy. On the Workabout, the PSION key (but not 
SHIFT+PSION) converts the keypress to Ww_KEY_TASK. 


On the Series 3c, the PSION key (including SHIFT+PSION) converts the keypress 
tO W_KEY_IR_LINK (0x142). 


6-1 


WINDOW SERVER REFERENCE 


W_FUNC_MODIFIER 
(0x80) 


W_KEY_APP1 to 
W_KEY_APP9 (0x131 to 
0x139) 


W_KEY_IR_BRING 
(0x140) 


W_KEY_IR_SEND 
(0x141) 


W_KEY_IR_LINK 
(0x142) 


W_KEY_CALC_CLEAR 
(0x01b) 


W_KEY_CALC_MEM_CLEAR 
(0x150) 


W_KEY_CALC_MEM_RECAL 
L (0x151) 


W_KEY_CALC_MEM_ MINUS 
(0x152) 


W_KEY_CALC_MEM_ PLUS 
(0x153) 


W_KEY_CALC_CHNG_SIGN 
(0x154) 


W_KEY_CALC_PERCENT 
(0x155) 


W_KEY_CALC_DECIMAL 
(0x156) 


W_KEY_CALC_MEM_INPUT 
(0x158) 


W_RUSSIAN_MODIFIER 
(0x1000) 


6-2 


On the Siena only, an FN modifier key is provided that produces this additional 
modifier code. 


Note that the same value is used for Mouse Down (w_mousE pown) on the Psion 
MC range of machines. 


On the Series 3 and Series 3a, key codes w_kEY_APP1 tO W_KEY_APP8 are 
produced by the eight membrane keys (also called application keys) in order, 
from left to right. 


The Series 3c has a ninth membrane key, on the extreme right, that produces 
W_KEY_APP9. 


On the Siena only, this key code is produced by the IR receive key. 


On the Siena only, this key code is produced by the IR send key. 


On the S3c only, this key code is produced by the PSION + TAB key combination. 


On the Siena only, this key code is produced by the ON/CE key. 


On the Siena only, this key code is produced by FN + the ‘3’ key on the numeric 
keypad. 


On the Siena only, this key code is produced by FN + the ‘2’ key on the numeric 
keypad. 


On the Siena only, this key code is produced by FN + the ‘-’ key on the numeric 
keypad. 


On the Siena only, this key code is produced by FN + the ‘+’ key on the numeric 
keypad. 


On the Siena only, this key code is produced by FN + the ‘.’ key on the numeric 
keypad. 


On the Siena only, this key code is produced by FN + the ‘=’ key on the numeric 
keypad. 


On the Siena only, this key code is produced by the ‘.’ key on the numeric 
keypad. 


On the Siena only, this key code is produced by FN + the ‘1’ key on the numeric 
keypad. 


On the Russian variant Series 3a and Series 3c only, (for Psion internal use 
only). 


6 WINDOW SERVER REFERENCE UPDATE 


Status windows 
Series 3c 


Status windows on the Series 3c are functionally identical to those on the Series 3a. Some minor cosmetic 
changes have been made, including a new analog clock design for the wide status window. 


Siena 


Only a narrow status window is available on the Siena. A smaller font is used and the diamond list has 
been reorganised, compared with that of the Series 3a, to maximise the space for displaying text. Despite 


these changes, only four characters of the application name and up to five characters of each diamond list 
item can be displayed. 


Diamond list text items that contain more than five characters are automatically truncated. Since such 
truncation may occur at an unsuitable point in the text, you should consider supplying truncated versions 


of the diamond text for use in the status window, such as the four-character abbreviations for ‘Normal’ 
and ‘Outline’ shown in the above illustration. 


The following constants are defined in wlib.h: 


WS_WIDTH_V4c 51 Normal status window width on Series 3c, in pixels; 
this is not a new constant - it also exists on the Series 3a 


WS_WIDTH_SMALL_V4c 32 Narrow status window width on Series 3c, in pixels; 
this is not a new constant - it also exists on the Series 3a 


WS_WIDTH_VINE 36 Narrow status window width on Siena, in pixels 


6-3 


WINDOW SERVER REFERENCE 


Clocks 


The clock creation functions, for example, wscreateClock2, on the Siena and Series 3c support additional 
clock styles. The new styles and their appearances and dimensions are given below. The associated 
symbolic constants are defined in wlib.h. 


Siena 


The Siena supports one additional clock, of type ws_cLocK_VINE: 


WS_CLOCK_VINE 0x06 

WS_BITMAP_VINE_CLOCK_SIZE_X 70 Width of Siena analogue clock, in pixels 
WS_BITMAP_VINE_CLOCK_SIZE_Y 69 Height of Siena analogue clock, in pixels 
Series 3c 


The Series 3c supports two additional clock types, ws_cLock_MEDIUM3 and ws_CLOCK_XL2_ANALOG: 


WS_CLOCK_MEDIUM3 0x06 

WS_BITMAP_MEDIUM3_CLOCK_SIZE_X 58 Width of Series 3c medium analogue clock, in pixels 

WS_BITMAP_MEDIUM3_CLOCK_SIZE_Y 51 Height of Series 3c medium analogue clock, in pixels 

WS_CLOCK_XL2_ANALOG 0x07 

WS_BITMAP_XL2_CLOCK_SIZE_X 111 Width of Series 3c extra large analogue clock, in 
pixels 

WS_BITMAP_XL2_CLOCK_SIZE_Y 110 Height of Series 3c extra large analogue clock, in 
pixels 


Window Server versions 


The following values are contained in the version_id member of the w_sERVER_INFo Struct. The constants 
and the struct are defined in wilib.h: 


WS_TYPE_S3C 0x60 Series 3c window server 


WS_TYPE_VINE 0x70 Siena window server 


6-4 


INDEX 


$WS_FL 


environment variable, 1-2, 1-55, 1-56, 2-25 


$WS_FNTS 

environment variable, 1-2, 1-38, 2-10 
$WS_IF 

environment variable, 2-10, 3-16 
$WS_SD 

environment variable, 1-32 
$WS_SF 

environment variable, 1-38 
$WS_SF2 

environment variable, 1-39 
$WS_SF4 

environment variable, 1-39 
.pcex files 

from screen capture, 1-33 

to bitmap PIC files, 1-31 
.ph files 

multi bitmap header file, 1-31 
.pic files 

checksum, 1-37 

from a PCX file, 1-31 
.plk files 

multi bitmap files, 1-31 
activation 

event, 5-10 
add files 

embedded bitmap files, 1-37 
alert flag 

WS_ALERT_B, 1-3 
alerts 

asynchronous, 2-18 

message display, 2-12 

synchronous, 2-14 

updating, 2-19 

wsAlertW, 1-3 
animation 

bitmap sequences, 1-21, 3-14 

sprites, 1-3, 1-23, 3-15 
application keys 

handler, 1-15 


W_KEY_APPn, 5-5 
wAppKeyHandler, 1-15 


area fill pattern 

gFillPattern, 4-13 
area filling 

modes, 4-12, 4-13 

WLIB functions, 4-12 
arrow keys 

rubber band mode, 1-54 
arrows 

drawing, 4-10 
ascent 

fonts, 4-14 
asynchronous 

events, 5-2 
attached clients 

WLIB functions, 2-25 
attachment 

event, 5-8 
backed up windows 

bitmaps, 1-19 
background 

client, 1-14 

client switch task order, 2-8 

event, 5-6 
background modes 

window, 1-3 
backlight 

key code, 5-5 
baseline 

fonts, 4-14 
bitmaps 

capture screen to, 1-32 


converting from pcx with wspcx.exe, 1-31 


copying, 4-29, 4-30 

creation of, 1-30, 4-26 

drawables, 1-18 

drawing from, 1-30, 4-31 

drawing to, 1-31 

embedded files, 1-37 

files creating, 1-31 

files creating with grey, 1-31 

find in file gSetOpenAddress, 1-30 
freeing, 4-28, 4-32 

freeing sequences, 3-15 

from PCX files, 1-31 
G_TRMODE_CLR, 1-30 
G_TRMODE_INV, 1-30 
G_TRMODE_REPL, 1-30 
G_TRMODE_SET, 1-30 

gCopyBit, 1-30 

gDrawBit, 1-30 

gFillPattern, 1-30 

grey, 1-22 

gSetOpenAddress, 1-30 

header file for multi bitmap files, 1-31 
horizontal slice, 4-30 

joining multiple from PLK file, 1-31 
loading, 4-27, 4-31 

multiple, 4-30 

open multiple bitmap file gInitBit, 1-30 
opening, 4-31 
overview, 1-30 

pixel coordinates, 1-47 
reading, 4-30 

redraws avoiding, 1-22 


WINDOW SERVER REFERENCE 


redraws avoiding example code, 1-22 

ROM-based grey, 1-30 

saving, 4-28 

screen capture, 1-31 

sequences, 1-21, 3-14 

storage of, 1-30 

structure, 1-36 

validating, 4-30 

wFree, 1-30 

WLIB functions, 1-2, 4-26 

wsetWinBitmap, 1-30 
bitmaps copying 

gCopyBit, 4-29 

gCopyRect, 4-30 
bitmaps create 

gCreateBit, 4-26 
bitmaps drawing from 

gDrawBit, 4-31 
bitmaps freeing 

wFree, 4-32 
bitmaps function 

wChangeWinBitmap, 3-15 

wFree, 3-15 

wsetWinBitmap, 3-14 
bitmaps loading 

gGetBit, 4-31 

gOpenBit, 4-27 
bitmaps multi save end 

gEndMultiSave, 4-32 
bitmaps multiple initialise 

gInitMultiSave, 4-32 
bitmaps multiple saving 

gSaveMultiBit, 4-32 
bitmaps open 

embedded, 4-28 

structure, 4-26, 4-27 
bitmaps opening 

gInitBit, 4-31 
bitmaps partial save 

gSaveMultiRect, 4-32 
bitmaps position 

gSetOpenAddress, 4-15 
bitmaps reading 

gPeekBit, 4-30 
bitmaps saving 

gSaveBit, 4-28 

gSaveRect, 4-28 

multiple, 4-32 
bitmaps sequences 

wChangeWinBitmap, 1-21 

wFree, 1-21 

wsetWinBitmap, 1-21 
bitmaps size get 

gQueryBit, 4-31 
bitmaps validating 

gCheckBitmapID, 4-30 
black 

plane, 1-3, 1-19, 3-8, 4-1, 4-13 
blind operations 

window server, 1-11 
body cell 

fonts, 4-14 
border 

WLIB function, 4-8 


ii 


WLIB functions, 4-10 
border attribute 
W_BORD_CORNER_1, 4-11 
W_BORD_CORNER_2, 4-11 
W_BORD_CORNER_4, 4-11 
W_BORD_CUSHION, 4-11 
W_BORD_OPEN, 4-11 
W_BORD_SHADOW_D, 4-11 
W_BORD_SHADOW_ON, 4-11 
W_BORD_SHADOW_S, 4-11 
border drawing 
gBorder, 4-10 
gBorder2, 4-12 
gBorder2Rect, 4-10 
gBorderRect, 4-8 
types, 4-10 
box 
WLIB function, 4-8 
buffered commands 
window server, 1-11, 1-13, 2-5 
busy 
message cancel, 2-12 
message display, 2-11 
busy message 
window server option, 1-6 
button drawing 
example code, 4-24 
button text 
wDrawButton, 4-24 
wDrawButton2, 4-25 
cancelled 
event, 5-6, 5-10 
capturing 
keyboard events, 5-15 
keys, 1-51, 5-11 
mouse, 1-53, 5-13 
mouse events, 5-15 
screen to a bitmap file, 1-32 
checksum 
font files, 1-46 
pic files, 1-37 
WLIB function, 4-32 
checksum get 
gInquireChecksum, 4-32 
child 
window, 1-18 
clear area 
gClrRect, 4-12 
CLIB 
library, 1-8 
startup module, 1-8, 2-1 
startup module MC, 1-10 
client 
attach caller, 2-26 
attach caller to foreground, 2-26 
attached, 2-25, 5-8 
background, 1-14 
command event, 5-7 
command get, 5-10 
command send, 5-10 
de-iconised event, 5-8 
detach caller, 2-26 
detached, 2-26, 5-8 
foreground, 1-14 


INDEX 


going deaf, 1-26 
iconised, 1-16 
iconised mark as, 2-9 
information get, 2-8 
list get, 2-10 
management, 1-17 
pause disable, 2-10 
pausing, 1-52 
pausing enable, 2-9 
priority, 1-16, 2-7 
system-modal, 1-17, 2-9 
task order, 2-8 
wCancelSystemModal, 2-9 
client commands 
between window server clients, 1-6 
client window 
background drawing, 1-18 
clients 
window server, 1-13 
clients terminating 
window server, 1-6 
client-side buffer 
flushing, 1-13 
clipping 
redrawing, 3-9 
windows, 1-25 
windows child, 1-18 
clock 
creating, 3-17, 3-19 
example code, 3-18, 3-20, 3-21 
freeing, 3-22 
offset, 3-22 
Series 3c and Siena update, 6-4 
Series 3c update, 6-4 
Siena update, 6-4 
structure, 3-19 
WLIB functions, 3-16 
clock attribute 
WS_CLOCK_AM_PM, 3-17, 3-20 
WS_CLOCK_BOX, 3-20 
WS_CLOCK_CENTERED, 3-17, 3-20 
WS_CLOCK_FORCE_ANALOG, 3-17, 
3-20 
WS_CLOCK_FORCE_DIGITAL, 3-17, 
3-20 
WS_CLOCK_FORMATTED, 3-19 
WS_CLOCK_GREY, 3-20 
WS_CLOCK_LARGE_ANALOG, 3-17, 
3-19 
WS_CLOCK_MEDIUM, 3-17, 3-19 
WS_CLOCK_MEDIUM2, 3-19 
WS_CLOCK_SMALL_DIGITAL, 3-17, 
3-19 
WS_CLOCK_WITH_DATE, 3-17, 3-20 
WS_CLOCK_WITH_SECONDS, 3-17, 
3-20 
WS_CLOCK_XL_ANALOG, 3-19 
clock drawing 
automatic, 1-6 
clock function 
wFree, 3-22 
wsCreateClock, 3-17 
wsCreateClock2, 3-19 
wsSetClock, 3-22 


code 
key, 1-51 
keys, 5-3 


command data get 

wGetCommand, 5-10 
compatibility mode 

S3 display mode, 2-6 

Series 3, 1-12 

status windows, 2-21 

W_CTBY_S3, 2-6 

W_CTBY_S3_SCR, 2-6 

wInquireCompatibility, 2-7 
compute mode 

ending wEndCompute, 2-8 

priority setting wStartCompute, 2-8 
configure 

font group, 4-18 

window server, 2-24 
connect to 

window server, 2-1, 2-3 
CONNECT_INFO 

structure, 2-3 
console device 

channel to, 1-8 
coordinates 

pixel, 1-47 
copying bitmaps 

WLIB function, 4-29, 4-30 
corner type 

border attribute, 4-8 

border attributes, 4-11 
count 

key repeat, 1-51 

keys repeat, 5-3 
cursor 

flashing, 1-29 

grey, 1-29 

text, 3-12 

text window, 1-29 

wTextCursor, 1-29 
cursor attribute 

W_CURSOR_GREY, 3-12 
cursor function 

wDrawTextCursor, 3-13 

wEraseTextCursor, 3-13 

wTextCursor, 3-12 
cursor remove 

wEraseTextCursor, 1-29 
date changed 

event, 5-7 
DatStatusNamePtr 

magic static, 2-13 
deaf clients 

multi-tasking, 1-26 

window server flag, 1-56 
de-iconise 

event, 5-8 
descent 

fonts, 4-14 
destroying 

windows, 1-27 
detachment 

event, 5-8 


iii 


WINDOW SERVER REFERENCE 


diamond key 

key code, 5-5 

key press, 1-15 

mode display, 2-20 
disable 

status window, 2-22 

status window temporary, 2-22 
disconnect from 

window server, 2-5 
display 

brief message, 2-11 
display process 

SYS$CONS on MC, 1-7 
double pixel mode 

window, 1-12 
doubled sized pixels 

mode, 4-1 

S3 display mode, 2-6 
drawable 

graphics context, 4-1 

windows and bitmaps, 1-18, 1-50 
drawing 

arrows, 4-10 

background client, 1-18 

lines, 4-7 

polygon, 4-7 

shadowed text, 4-23 

shadows, 4-10 

text, 1-44 

to bitmaps, 1-31 

windows, 1-25 
drawing mode 

G_GC_FLAG_BOTH_PLANES, 4-3 

G_GC_FLAG_DOUBLE, 4-3 

G_GC_FLAG_GREY_PLANE, 4-3 
drawing region 

window, 1-19 
DYL graphics 

WLIB function, 4-33 
E_CONFIG 

structure, 3-16 
E_PRIORITY_BACK 

window server flag, 2-7 
E_PRIORITY_FORE 

window server flag, 2-7 
embedded 

font files, 1-47 
embedded bitmap files 

add file lists, 1-37 
enable 

status window temporary, 2-22 
end rubber band 

event, 5-10 
environment variable 

$WS_FL, 1-2, 1-55, 1-56, 2-25 

$WS_FNTS, 1-2, 1-38, 2-10 

$WS_IF, 2-10, 3-16 

$WS_SD, 1-32 

$WS_SF, 1-38 

$WS_SF2, 1-39 

$WS_SF4, 1-39 
EPOC 

operating system, 1-1 

PC version, 1-59 


iv 


error 


cleaning up, 1-11 
handling window server, 2-7 
panic numbers window server, 1-12 


error handling 


window server, 1-11 


escape-key 


event, 5-8 


event 


W_KEY_MODE, 1-2 
W_MOUSE_DOWN, 5-9 
W_MOUSE_OUTSIDE, 5-9 
WM_ACTIVE, 1-53, 5-10 
WM_ATTACHED, 2-25, 5-8 
WM_BACKGROUND, 5-6 
WM_CANCELLED, 1-28, 5-6, 5-10 
WM_COMMAND, 5-7 
WM_DATE_CHANGED, 1-3, 5-7 
WM_DEICONISE, 1-16, 2-8, 5-8 
WM_DETACHED, 2-25, 5-8 
WM_ESCAPE, 5-8 
WM_FOREGROUND, 2-25, 5-6 
WM_KEY, 1-15, 1-51, 5-3 
WM_KEYBOARD_STATE_CHANGE, 
5-8 
WM_MOUSE, 1-52, 5-9 
WM_MOUSE_MOVE, 5-9 
WM_MOUSE PRESS, 5-9 
WM_MOUSE_RELEASE, 1-53, 5-9 
WM_ON, 5-7, 5-11 

WM_REDRAW, 3-12, 5-6 
WM_RUBBER, 1-53, 5-10, 5-14 
WM_RUBBER_BAND_INIT, 1-54, 5-9 
WM_TASK_KEY, 1-15, 5-7 
WM_TASK_UPDATE, 5-7 
WM_USER_MSG, 5-7, 5-10 
WS_EVENT_UNION, 5-1 


event function 


wCancelGetEvent, 5-10 
wGetEvent, 1-51 

wGetEvent get async, 1-14 
wGetEventSpecial, 1-51 
wGetEventSpecial get async, 1-14 
wGetEventWait, 1-51 
wGetEventWait event get, 1-14 
wSendCommand, 5-10 
wUserMsg, 5-10 


event selected 


WE_ESC, 5-2 
WE_KEY, 5-2 
WE_MOUSE, 5-2 
WE_NORMAL, 5-2 
WE_OTHERS, 5-2 
WE_REDRAW, 5-2 
WE_STATUS, 5-2 


event selected update 


wGetEventUpdate, 5-2 


event types 


described, 5-3 


events 


activation, 5-10 
asynchronous, 1-28, 5-2 
attachment, 5-8 
background, 5-6 


cancelled, 5-6, 5-10 
client command, 5-7, 5-10 
date changed, 5-7 
de-iconise, 5-8 
detachment, 5-8 
end rubber band, 5-10 
escape-key, 5-8 
foreground, 5-6 
getting next, 5-1 
inform key handler, 5-7 
key, 1-14 
key presses, 1-51 
keyboard capturing, 5-15 
keyboard state change, 5-8 
large screen, 5-8 
machine on, 5-7 
mouse, 1-14, 1-52, 5-9 
non window server, 1-28 
other sources, 1-28 
process termination, 5-7 
redraw, 1-24, 5-6 
rubber, 5-15 
selected, 5-2 
start rubber band, 5-9 
synchronous, 5-1 
time-stamping, 1-14 
types, 5-3 
update selected, 5-2 
user, 5-10 
user message, 5-7 
waiting, 5-1 
wGetEvent async, 5-2 
wGetEventWait sync, 5-1 
window server clients, 1-14 
WLIB functions, 5-10 
events selected async 
wGetEventSpecial, 5-2 
fast fonts 
described, 1-38 
file format 
bitmaps, 1-36 
fonts, 1-46 
files 
bitmaps creating, 1-31 
font, 1-42 
fill area 
gClrRect, 4-12 
filling areas 
modes, 4-12, 4-13 
WLIB functions, 4-12 
flashing 
cursor, 1-29 
FLK 
font source file list file, 1-44 
flushing 
client-side buffer, 1-13 
commands window server, 2-5 
window server, 1-11 
flushing commands 
window server, 2-7 
FON 
file, 1-42 
font group configure 
gConfigureFonts, 4-18 


INDEX 


font group header read 
gReadFontGroupHeader, 4-19 
font header read 
gReadFontHeader, 4-19 
font information 
structure, 4-16 
font internal 
wSetSystemFont, 4-17 
font loading 
gOpenFont, 4-15 
font open index 
gOpenFontIndex, 4-18 
font position 
gSetOpenAddress, 4-15 
font style 
G_FONT_FLAG_ASCII, 4-16 
G_FONT_FLAG_BOLD, 4-16 
G_FONT_FLAG_CP850, 4-16 
G_FONT_FLAG_ITALIC, 4-16 
G_FONT_FLAG_SERIF, 4-16 
G_STY_BOLD, 4-2 
G_STY_DOUBLE, 4-2 
G_STY_INVERSE, 4-2 
G_STY_ITALIC, 4-2 
G_STY_MONO, 4-2 
G_STY_NORMAL, 4-2 
G_STY_SUBSCRIPT, 4-2 
G_STY_SUBSCRIPT2, 4-3 
G_STY_SUPERSCRIPT, 4-2 
G_STY_SUPERSCRIPT2, 4-3 
G_STY_UNDERLINE, 4-2 
font system 
wSetSystemFont, 4-17 
font type system 
W_SYSTEM_FONT_INTERNAL_S3, 4-17 
W_SYSTEM_FONT_INTERNAL_S3B, 
4-17 
W_SYSTEM_FONT_S3, 4-17 
W_SYSTEM_FONT_S3B, 4-17 
font width table 
gGetWidthTable, 4-17 
fonts 
ascent, 4-14 
baseline, 4-14 
bitmaps, 1-38 
body cell, 4-14 
compiler wsfcomp.exe, 1-43 
configure group, 4-18 
descent, 4-14 
fast, 1-38 
file structure, 1-46 
files, 1-42 
files checksum, 1-46 
files embedded, 1-47 
files p_cre, 1-46 
finding in file gSetOpenAddress, 1-42 
FON files, 1-42 
freeing, 4-16 
group, 4-18 
group header, 4-19 
HC, 1-39 
header, 4-19 
high character, 4-14 
horizontal leading, 4-14 


WINDOW SERVER REFERENCE 


ID field, 4-3 
ID start WS_FONT_BASE, 1-38 
ID system WS_FONT_SYSTEM, 1-38 
information, 1-44, 4-16 
internal IDs, 4-17 
loading gOpenFont, 1-42 
loading gOpenFontIndex, 1-42 
low character, 4-14 
MC, 1-41 
monospaced, 1-38 
multiple, 4-18 
opening, 4-15, 4-18 
proportional, 1-38 
roman, 1-41 
ROM-based, 1-38, 4-3 
S3, 1-40 
S3a, 1-41 
source file list FLK file, 1-44 
source FSC file, 1-43 
structure, 1-46 
style, 1-45, 4-2 
style G_STY_BOLD, 1-45 
style G_LSTY_DOUBLE, 1-45 
style G_STY_INVERSE, 1-45 
style G_STY_ITALIC, 1-45 
style G_LSTY_MONO, 1-45 
style G_STY_NORMAL, 1-45 
style G_LSTY_UNDERLINE, 1-45 
swiss, 1-42 
system IDs, 4-17 
text, 1-38, 4-14 
vertical leading, 4-14 
width, 4-14 
width table, 4-17 
Workabout, 1-41 

Fonts 


ID system from W_SERVER_INFO, 1-38 


ID system S3/HC from $WS_SF, 1-38 


ID system S3a from $WS_SFNTS, 1-38 


information gFontInfo, 1-44 
fonts.h 

header file, 1-39, 1-41 
foreground 

client, 1-14 

client switch task order, 2-8 

event, 5-6 
freeing 

bitmap sequences, 3-15 

bitmaps, 4-28, 4-32 

clocks, 3-22 

fonts, 4-16 

mouse icon, 3-23 

permanent graphics contexts, 4-5 

sprites, 3-16 

temporary graphics contexts, 4-6 
FSC file 

font source file, 1-43 
G_FONT_CONFIG 

structure, 4-18 
G_FONT_FLAG_ASCTI 

font style, 4-16 
G_FONT_FLAG_BOLD 

font style, 4-16 


vi 


G_FONT_FLAG_CP850 

font style, 4-16 
G_FONT_FLAG_ITALIC 

font style, 4-16 
G_FONT_FLAG_SERIF 

font style, 4-16 
G_FONT_INFO 

font information structure, 4-16 

structure, 1-46 
G_GC 

plane flag, 1-3 

structure, 3-9, 4-1 
G_GC_FLAG_BOTH_PLANES 

drawing mode, 4-3 
G_GC_FLAG_DOUBLE 

drawing mode, 4-3 

graphics flag, 1-2 
G_GC_FLAG_GREY_PLANE 

drawing mode, 4-3 
G_SHADOW 

structure, 4-23 
G_STY_BOLD 

font style, 1-45, 4-2 
G_STY_DOUBLE 

font style, 1-45, 4-2 
G_STY_INVERSE 

font style, 1-45, 4-2 
G_STY_ITALIC 

font style, 1-45, 4-2 
G_STY_MONO 

font style, 1-45, 4-2 
G_STY_NORMAL 

font style, 1-45, 4-2 
G_STY_SUBSCRIPT 

font style, 4-2 
G_STY_SUBSCRIPT2 

font style, 4-3 
G_STY_SUPERSCRIPT 

font style, 4-2 
G_STY_SUPERSCRIPT2 

font style, 4-3 
G_STY_UNDERLINE 

font style, 1-45, 4-2 
G_TRMODE_CLR 

bitmap transfer mode, 1-30 

text mode, 4-2 

text transfer mode, 1-45 
G_TRMODE_INV 

bitmap transfer mode, 1-30 

text mode, 4-2 

text transfer mode, 1-45 
G_TRMODE_REPL 

bitmap transfer mode, 1-30 

text mode, 4-2 

text transfer mode, 1-45 
G_TRMODE_SET 

bitmap transfer mode, 1-30 

text mode, 4-2 

text transfer mode, 1-45 
gBorder 

graphics output, 1-49 

WLIB function, 4-10 
gBorder2 

graphics output, 1-49 


WLIB function, 4-12 
gBorder2Rect 

graphics output, 1-49 

WLIB function, 4-10 
gBorderRect 

graphics output, 1-49 

WLIB function, 4-8 
gCheckBitmapID 

WLIB function, 4-30 
gClrRect 

graphics output, 1-49 

WLIB function, 4-12 
gConfigureFonts 

WLIB function, 4-18 
gCopyBit 

bitmap WLIB function, 1-30 

graphics output, 1-49 

WLIB function, 4-29 
gCopyRect 

graphics output, 1-49 

WLIB function, 4-30 
gCreateBit 

bitmap WLIB function, 1-30 

WLIB function, 4-26 
gCreateGC 

graphics context permanent, 1-50 

WLIB function, 4-4 
gCreateGCO 

graphics context permanent, 1-50 

WLIB function, 4-5 
gCreateTempGC 

graphics context temporary, 1-51 

WLIB function, 4-5 
gCreateTempGCO 

graphics context temporary, 1-51 

WLIB function, 4-6 
gDrawBit 

bitmap WLIB function, 1-30 

graphics output, 1-49 

WLIB function, 4-31 
gDrawBox 

graphics output, 1-49 

WLIB function, 4-8 
gDrawLine 

graphics output, 1-49 

WLIB function, 4-7 
gDrawObject 

graphics output, 1-49 

WLIB function, 4-12 
gDrawPolyLine 

graphics output, 1-49 

WLIB function, 4-7 
gEndMultiSave 

WLIB function, 4-32 
gFillPattern 

bitmap WLIB function, 1-30 

graphics output, 1-49 

WLIB function, 4-13 
gFontInfo 

fonts WLIB function, 1-44 

WLIB function, 4-16 
gFreeTempGC 

graphics context free, 1-51 

WLIB function, 4-6 


INDEX 


gGetBit 

bitmap WLIB function, 1-30 

WLIB function, 4-31 
gGetWidthTable 

WLIB function, 4-17 
gInitBit 

bitmap WLIB function, 1-30 

WLIB function, 4-31 
gInitMultiSave 

WLIB function, 4-32 
gInquireChecksum 

WLIB function, 4-32 
gInvObloid 

graphics output, 1-49 

WLIB function, 4-13 
gmode 

graphics modes, 4-2 
gOpenBit 

bitmap WLIB function, 1-30 

WLIB function, 4-27 
gOpenFont 

fonts WLIB function, 1-42 

WLIB function, 4-15 
gOpenFontIndex 

fonts WLIB function, 1-42 

WLIB function, 4-18 
gOpenMouselcon 

WLIB function, 3-23 
gPeekBit, 1-35 

WLIB function, 4-30 
gPrintBoxText 

graphics output, 1-49 

text drawing WLIB function, 1-44 

WLIB function, 4-20 
gPrintClipText 

graphics output, 1-49 

text drawing WLIB function, 1-44 

WLIB function, 4-20 
gPrintText 

graphics output, 1-49 

text drawing WLIB function, 1-44 

WLIB function, 4-20 
gQueryBit 

WLIB function, 4-31 
graphics 

adding output functions, 4-33 

DYL, 4-33 

G_GC_FLAG_DOUBLE flag, 1-2 

output, 2-10 

structures, 1-48 

WLIB functions, 1-47 
graphics contexts 

current, 1-50 

free gFreeTempGC, 1-51 

free wEndRedraw, 1-51 

gCreateGC, 4-4 

gCreateGCO, 4-5 

gCreateTempGC, 4-5 

gCreateTempGCO0, 4-6 

gFreeTempGC, 4-6 

gSetGC, 4-6 

gSetGCO, 4-7 

overview, 1-50, 4-1 

permanent, 1-50, 4-4 


WINDOW SERVER REFERENCE 


permanent freeing, 4-5 
permanent gCreateGC, 1-50 
permanent gCreateGCO, 1-50 
set specific gSetGC, 1-50 
set specific gSetGCO, 1-50 
setting, 4-6 
temporary, 1-51, 4-5 
temporary & permanent, 1-50 
temporary freeing, 4-6 
temporary gCreateTempGC, 1-51 
temporary gCreateTempGCO, 1-51 
temporary wBeginRedrawGC, 1-51 
temporary wBeginRedrawGCo, 1-51 
temporary wBeginRedrawWinGC, 1-51 
temporary wBeginRedrawWinGCO, 1-51 
wFree, 4-5 
windows, 1-18 
graphics DYL call 
wCallDYL, 4-33 
graphics DYL enquiry call 
wCallDYLReply, 4-33 
graphics DYL load 
wLoadDYL, 4-33 
graphics functions 
not to current graphics context, 1-49 
to current graphics context, 1-49 
graphics modes 
gmode, 4-2 
graphics objects 
gDrawObject, 4-12 
type attributes, 4-12 
types, 4-12 
graphics output 
gBorder, 1-49 
gBorder2, 1-49 
gBorder2Rect, 1-49 
gBorderRect, 1-49 
gClrRect, 1-49 
gCopyBit, 1-49 
gCopyRect, 1-49 
gDrawBit, 1-49 
gDrawBox, 1-49 
gDrawLine, 1-49 
gDrawObject, 1-49 
gDrawPolyLine, 1-49 
gFillPattern, 1-49 
gInvObloid, 1-49 
gPrintBoxText, 1-49 
gPrintClipText, 1-49 
gPrintText, 1-49 
gShadowText, 1-49 
gXPrintText, 1-49 
not to current graphics context, 1-49 
to current graphics context, 1-49 
wCancelBusyMsg, 1-49 
wDrawButton, 1-49 
wDrawButton2, 1-49 
wDrawTextCursor, 1-49 
wEraseTextCursor, 1-49 
wInfoMsg, 1-49 
winfoMsgCorner, 1-49 
wsAlertA, 1-50 
wsAlertCancel, 1-50 
wsAlertUpdate, 1-50 


viii 


wsAlertW, 1-50 
wsCreateClock, 1-49 
wsCreateClock2, 1-49 
wscrollRect, 1-49 
wScrollWin, 1-49 
wsDisable, 1-50 
wsDisableTemp, 1-50 
wsEnable, 1-50 
wsEnableTemp, 1-50 
wsSetBusyMsg, 1-49 
wsSelectList, 1-50 
wsSetClock, 1-49 
wsSetList, 1-50 
wsStatusWindow, 1-50 
wsUpdate, 1-50 
wTextCursor, 1-49 
gReadFontGroupHeader 
WLIB function, 4-19 
gReadFontHeader 
WLIB function, 4-19 
grey 
cursor, 1-29 
plane, 1-3, 1-19, 3-8, 4-1, 4-13 
gSaveBit 
bitmap WLIB function, 1-31 
WLIB function, 4-28 
gSaveMultiBit 
bitmap WLIB function, 1-31 
WLIB function, 4-32 
gSaveMultiRect 
bitmap WLIB function, 1-31 
WLIB function, 4-32 
gSaveRect 
bitmap WLIB function, 1-31 
WLIB function, 4-28 
gSetGC 
graphics context specific, 1-50 
WLIB function, 4-6 
gSetGCO 
graphics context specific, 1-50 
WLIB function, 4-7 
gSetOpenAddress 
bitmap WLIB function, 1-30 
fonts WLIB function, 1-42 
WLIB function, 4-15 
gShadowText 
graphics output, 1-49 
text drawing WLIB function, 1-44 
WLIB function, 4-23 
gTextCount 
text layout WLIB function, 1-44 
WLIB function, 4-17 
gTextWidth 
text layout WLIB function, 1-44 
WLIB function, 4-16 
gXPrintText 
graphics output, 1-49 
text drawing WLIB function, 1-44 
WLIB function, 4-21 
HC 
fonts, 1-39 
replacing the shell, 1-56 
shell example code, 1-56 
task switching, 1-15 


header file 
for multi bitmap files, 1-31 
wlib.h, 1-8 
header files 
fonts.h, 1-39, 1-41 
high character 
fonts, 4-14 
hook notifier 
process, 1-55 
window server option, 1-5 
horizontal leading 
fonts, 4-14 
hotkeys 
capturing, 5-12 
implementing, 5-12 
hot-spot 
mouse icon, 1-52 
hung-up 
redrawing delays, 1-26 
window server flag, 1-56 
icon ID 
WS_DEFAULT_ICON, 1-3 
icon ID grey 
WS_DEFAULT_ICON+1, 1-3 
iconised 
client, 1-16 
client mark as, 2-9 
icons 
mouse, 1-52, 3-22 
include file 
key code wskeys.h, 6-1 
inform key handler 
event, 5-7 
input 
rubber band mode, 1-53 
internal fonts 
IDs, 4-17 
invalidate function 
wlInvalidateRect, 3-12 
wlInvalidateWin, 3-12 
invalidating 
windows, 1-24 
WLIB function, 3-12 
invert obloid 
gInvObloid, 4-13 
invisible window 
wMakelnvisible, 1-28 
key 
pause disable wDisablePauseKey, 1-52 
pause enable wEnablePauseKey, 1-52 
specific cancel wCancelCaptureKey, 1-51 
specific wCaptureKey, 1-51 
tasks setting, 1-52 
key capture 
wCaptureKey, 5-11 
key capture off 
wCancelCaptureKey, 5-12 
key code 
diamond, 5-5 
Series 3c and Siena update, 6-1 
W_FUNC_MODIFIER, 6-2 
W_KEY_BACKLIGHT, 5-5 
W_KEY_CALC_CHNG_SIGN, 6-2 
W_KEY_CALC_CLEAR, 6-2 


INDEX 


_CALC_DECIMAL, 6-2 
_CALC_MEM_CLEAR, 6-2 
_CALC_MEM_INPUT, 6-2 
_CALC_MEM_MINUS, 6-2 
_CALC_MEM_PLUS, 6-2 
_CALC_MEM_RECALL, 6-2 
_CALC_PERCENT, 6-2 
_CAPS_LOCK, 5-5 
_DELETE_LEFT, 5-4 


_HELP, 5-5 


MENU, 5-5 


qeidddddddddedeedeeeeeeeeeas 


Sebi bie eb bii ibis bts bist tts 


Me 
Y_ 
Y_ 
Y_ 
NX 
Y_ 
Y_LEFT, 5-4 
Mes 
Y_ 
Y 
Y_' 
Y_ 
Y_PAGE_UP, 5-4 
Y 


agceead 


W_KEY_VOICE, 5-4 
W_RUSSIAN_MODIFIER, 6-2 
wskeys.h, 6-1 
key code applications 
W_KEY_APPn, 5-5 
key modifier 
W_CAPS_MODIFIER, 5-3, 5-9 
W_CTRL_MODIFIER, 5-3, 5-9 
W_NUM_LOCK_MODIFIER, 5-3, 5-9 
W_PSION_MODIFIER, 5-3, 5-9 
W_SHIFT_MODIFIER, 5-3, 5-9 
key press 
diamond, 1-15 
keyboard 
events capturing, 5-15 
input, 1-14, 1-51 
key press events, 1-51 
rubber band, 5-15 
Series 3c and Siena update, 6-1 
state change event, 5-8 
update for Series 3c and Siena, 6-1 
key-click 
disable, 2-26 
enable, 2-26 
keys 
application handler, 1-15 
cancel back task switch keys, 5-13 
cancel task switch keys, 5-12 
capturing, 1-51, 5-11 
code, 1-51, 5-3 


WINDOW SERVER REFERENCE 


code - Series 3c and Siena update, 6-1 
code wskeys.h, 6-1 
count, 1-51, 5-3 
events, 1-14 
key press events, 1-51 
modifier, 5-3 
repeat count, 1-51, 5-3 
set back task switch keys, 5-13 
set task switch keys, 5-12 
large screen 
event, 5-8 
LCD display resolution 
by machine, 2-5 
leading horizontal 
fonts, 4-14 
leading vertical 
fonts, 4-14 
leaving 
disable, 2-7 
enable, 2-7 
libraries 
WLIB using, 1-8 
line drawing 
gDrawBox, 4-8 
gDrawLine, 4-7 
gDrawPolyLine, 4-7 
WLIB functions, 4-7 
link paste 
window server services, 1-6 
low character 
fonts, 4-14 
machine on 
event, 5-7 
machine type 
from wConnect, 1-2 
magic static 
DatStatusNamePtr, 2-13 
MC 
fonts, 1-41 
task switching, 1-16 
wAttachToClient, 1-16 
wAttachToForegroundClient, 1-16 
MC200 
Fonts system ID, 1-39 
mouse, 5-9 
MC400 
Fonts system ID, 1-39 
mouse, 5-9 
message 
cancel busy, 2-12 
display alerts, 2-12 
display brief, 2-11 
display busy, 2-11 
message constant 
W_INFO_MSG_MAX_LEN, 2-11 
message flag 
W_CORNER_BOTTOM_LEFT, 2-11 
W_CORNER_BOTTOM_RIGHT, 2-11 
W_CORNER_TOP_LEFT, 2-11 
W_CORNER_TOP_RIGHT, 2-11 
mode display 
diamond key, 2-20 
mode list 
status window, 2-23 


modifier 
keys, 5-3 
monospaced fonts 
sets, 1-38 
mouse 
capturing, 1-53, 5-13 
event, 5-9 
events, 1-14, 1-52, 5-9 
freeing icon, 3-23 
grabbing, 1-53 
icons, 1-52, 3-22 
input, 1-52 
releasing, 5-13 
rubber band, 5-15 
mouse capture 
wCaptureMouse, 5-13 
mouse icon 
gOpenMouselcon, 3-23 
hot-spot, 1-52 
W_WIN_MI_STANDARD, 1-52 
wFree, 3-23 
mouse icon attribute 
W_WIN_MI_CROSS, 3-22 


_MI_MARGIN, 3-23 
I_MOVE, 3-23 
_ NULL, 1-52, 3-22 
_PG_DOWN, 3-23 
_PG_UP, 3-23 
_PUSHER, 3-22 
_RESIZE, 3-23 
_RIGHT, 3-23 
_STANDARD, 3-22 
_TEXT, 3-22 
MI_TO_BIG, 3-23 
_MI_TO_SMALL, 3-23 
N_MI_VSLIDE, 3-23 
mouse icon position 

gSetOpenAddress, 4-15 
mouse release 

wReleaseMouse, 5-13 
multiple 

bitmaps, 4-30 

fonts, 4-18 
multi-tasking 

redraw response, 1-26 

window destroying and, 3-6 
normal 

plane, 1-3, 1-19, 3-8, 4-1, 4-13 
notifier 

hook the process, 1-55 

window server option, 1-5 
notify 

process SYS$NTFY, 1-54 
obloid invert 

gInvObloid, 4-13 
on event enable 

winformOn, 5-11 

winformOnAll, 5-11 
opening 

bitmaps, 4-31 

fonts, 4-15, 4-18 


z 
z 


— 


— 


— 


— 


z'z'z'czzzzzz 


— 


— 


— 


eececccece 
Ssscccaces 


ZAZZAZLZAZLZAZLZLAZLZZ 


z= 
=i 


F 


p_cre 
font files, 1-46 
function, 1-37 


p_enter 

window server, 1-11 
p_execc 

sub-process create, 1-26 
P_EXTENT 

structure, 1-48, 3-1 
P_FSIG 

structure, 1-37, 1-46 
p_iowait 

and window server events, 1-28 
p_leave 

window server, 1-11 
p_panic 

window server, 1-12 
P_POINT 

structure, 1-48, 3-1, 4-30 
P_RECT 

structure, 1-48, 4-29 
p_resume 

function, 1-14 
panic 


W_PANIC_SPRITE, 3-16 

W_PANIC_SPRITE_EXISTS, 3-16 
panic numbers 

window server, 1-12 
parent 

window, 1-18 
password support 

window server option, 1-6 
pause 

client disable, 2-10 

client enable, 2-9 


pausing 

client, 1-52 
PC 

EPOC, 1-59 
PCX file 


from screen capture, 1-33 

to bitmap file, 1-31 
pcxsave.c 

example program screen capture, 1-33 
pcxScreenSave 

screen capture, 1-33 
permanent 

status window, 2-19 
PH file 

multi bitmap header file, 1-31 
PIC file 

from a PCX file, 1-31 
PIC_HEAD 

structure, 1-36 
pixel 

coordinates, 1-47 

double sized mode, 4-1 

screen resolutions, 2-5 
pixel coordinates 

bitmaps, 1-47 
plane 

black, 1-3, 1-19, 4-1 

grey, 1-3, 1-19, 3-8, 4-1, 4-13 

normal, 1-3, 1-19, 4-1, 4-13 


INDEX 


plane flag 

in G_GC, 1-3 
PLIB 

library, 1-8 

startup module, 1-9, 2-1 

startup module MC, 1-10 
PLK file 

multi bitmap files, 1-31 
polygon drawing 

WLIB function, 4-7 


priority 
changing clients, 2-7 
client, 1-16 


compute mode end wEndCompute, 2-8 
compute mode setting wStartCompute, 2-8 
redraw events, 1-27 
wEndCompute, 1-17 
wSetPriorityControl, 2-8 
wsStartCompute, 1-17 
process 
SYS$FSRV, 1-54 
SYS$MANG, 1-54 
SYS$NTFY, 1-54 
SYS$NULL, 1-54 
SYS$SHLL, 1-15, 1-54 
SYS$WSRYV, 1-54 
wsystem, 1-55 
process termination 
event, 5-7 
proportional fonts 
sets, 1-38 
reading bitmaps 
WLIB function, 4-30 


redraw 
event, 5-6 
events, 1-24 


priority, 1-27 
priority bit W_WIN_PRIORITY, 1-27 
responsively, 1-26 
update region, 1-24 
validating before, 1-25 
redraw function 
wBeginRedraw, 3-9 
wBeginRedrawGC, 3-9 
wBeginRedrawGC0, 3-10 
wBeginRedrawWin, 3-9 
wBeginRedrawWinGC, 3-10 
wBeginRedrawWinGC0O, 3-10 
wEndRedraw, 3-11 
redrawing 
wBeginRedraw WLIB functions, 1-26 
windows, 1-24, 1-25 
windows variants, 3-8 
redraws 
avoiding using bitmaps, 1-22 
avoiding using bitmaps example code, 1-22 
releasing mouse 
WLIB function, 5-13 
repeat count 
key, 1-51 
keys, 5-3 
reserved static 
see magic static, 2-4 


WINDOW SERVER REFERENCE 


ROM 
built in grey bitmap, 1-30 
roman 
fonts, 1-41 
ROM-based fonts 
IDs, 4-3 
sets, 1-38 
root 
window, 1-18 
rubber band 
arrow keys, 1-54 
enter mode wRubberBand, 1-54 
input mode, 1-53 
keyboard events, 5-15 
mouse events, 5-15 
WLIB functions, 5-14 
rubber band attribute 
W_BAND_COMPLETE_ON_UP, 5-15 
W_BAND_GRID_SNAP, 5-15 
W_BAND_GRID_SNAP_ SIZE, 5-15 
W_BAND_INNER, 5-14 
W_BAND_OUTER, 5-14 
W_BAND_RESIZE, 5-14 
W_BAND_START, 5-14 
rubber band flag 
WM_BAND_CANCEL, 5-15 
WM_BAND_ERROR, 5-15 
WM_BAND_MOVE, 5-15 
WM_BAND_NOMOVE, 5-15 
WM_BAND_RESIZE, 5-15 
rubber band start 
wRubberBand, 5-14 
83 
fonts, 1-40 
S3a 
fonts, 1-41 
saving bitmaps 
WLIB function, 4-28 
saving multiple bitmaps 
WLIB function, 4-32 
scapt 
screen capture example program, 1-36 
screen 
coordinates, 1-18 
double pixel mode, 1-2 
event, 5-8 
screen capture 
disabling, 1-32 
example code, 1-33 
HC, 1-33 
pexScreenSave function, 1-33 
scapt example program, 1-36 
to a bitmap, 1-31 
to bitmap file, 1-32 
to PCX file pexsave.c, 1-33 
screen resolution 
by machine, 2-5 
by machine update, 6-1 
Series 3c and Siena update, 6-1 
screen sizes 
by machine update, 6-1 
scrolling 
rectangle, 3-7 
window, 3-7, 3-8 


xii 


windows, 1-28 
windows continuous, 1-29 
selected events 
WLIB function, 5-2 
Series 3 
compatibility mode, 1-12 
task switching, 1-15 
Series 3a 
task switching, 1-15 
server 
window server connecting to, 1-8 
setting graphics contexts 
WLIB functions, 4-6 
shadowed text 
WLIB functions, 4-23 
shadows 
drawing, 4-10 
shell 
event, 5-7 
HC replacing the shell, 1-56 
HC shell example code, 1-56 
process, 1-15, 1-54 
sibling 
window, 1-18, 3-7 
sprite 
structure, 3-15 
sprite attribute 
W_SPRITE_CLIP_CHILDREN, 3-15 
sprite function 
wCreateSprite, 3-15 
wFree, 3-16 
wsetSprite, 3-16 
sprites 
animated bitmaps, 1-3 
animated graphics, 1-23 
animation, 3-15 
black plane, 1-23 
changing, 3-16 
creating, 3-15 
freeing, 3-16 
grey plane, 1-23 
normal plane, 1-23 
plane grey, 1-23 
W_SPRITE_CLIP_CHILDREN, 1-23 
wCreateSprite, 1-23 
wFree, 1-23 
wsetSprite, 1-23 
start rubber band 
event, 5-9 
startup module 


PLIB MC, 1-10 
start-up system 
process, 1-54 
status window 
compatibility mode, 2-21 
disable, 2-22 
drawing, 1-6 
extent get, 2-21 
mode list, 2-23 
overview, 2-19 
permanent, 2-19 


permanent enable, 2-21 

permanent set state, 2-21 

select position set, 2-23 

Series 3c and Siena update, 6-3 

Series 3c update, 6-3 

Siena update, 6-3 

state get, 2-23 

temporary, 2-19 

temporary disable, 2-22 

temporary enable, 2-22 

update displayed, 2-22 

wsStatusWindow permanent, 2-21 
status window flag 


W_STATUS_WIN_NO_DIAMOND, 2-23 


W_STATUS_WINDOW_BIG, 2-21 


W_STATUS_WINDOW_CTBY, 2-21 
W_STATUS_WINDOW_ICON, 2-23 


W_STATUS_WINDOW_OFF, 2-21 


W_STATUS_WINDOW_SMALL, 2-21 


structures 
bitmap open, 4-26, 4-27 
clock, 3-19 
CONNECT_INFO, 2-3 
E_CONHIG, 3-16 
G_FONT_CONHIG, 4-18 
G_FONT_INFO, 1-46, 4-16 
G_GC, 3-9, 4-1 
G_SHADOW, 4-23 
graphics, 1-48 
P_EXTENT, 1-48, 3-1 
P_FSIG, 1-37 
P_POINT, 1-48, 3-1, 4-30 
P_RECT, 1-48, 4-29 
PIC_HEAD, 1-36 
sprite, 3-15 
W_SERVER_INFO, 1-38, 2-3 
W_SUPPORT_INFO, 2-26 
W_WINDATA, 3-1 
wMainGc, 2-2 
wMainWid, 2-2 
WMSG_KEY, 5-3 
WMSG_MOUSE, 5-9 
WMSG_RUBBER, 5-15 
WS_EV, 5-1 
WS_PIC_HEADER, 1-37 
WSERV_SPEC, 2-3 
wSpec, 2-2 
Structures 
WS_FONT_FILE_HEADER, 1-46 
style 
fonts, 1-45, 4-2 
sub-process 
create p_execc, 1-26 
Swiss 
fonts, 1-42 
synchronous 
events, 5-1 
SYS$CONS 
display process on MC, 1-7 
SYS$FSRV 
process, 1-54 
SYS$MANG 
process, 1-54 


INDEX 


SYS$NTFY 


process, 1-54 


SYS$NULL 


process, 1-54 


sys$shll, 2-9 
SYS$SHLL 


process, 1-54 


SYS$WSRV 


process, 1-54 
window server process, 1-1 


system fonts 


IDs, 4-17 


system modal 


wCancelSystemModal, 1-17 
wsystemModal, 1-17 


system start-up 


process, 1-54 


system type 


from wConnect, 1-2 


system-modal 


client, 1-17, 2-9 


task key 


back set wSetBackTaskKey, 1-52 
cancel wCancelTaskKey, 1-52 
set wSetTaskKey, 1-52 


Task key 


$3 and 3a, 1-52 


task key back cancel 


wCancelBackTaskKey, 1-52 


task keys 


setting, 1-52 


task order 


client position, 2-8 


task switching 


cancel back task switch keys, 5-13 
cancel task switch keys, 5-12 

HC, 1-15 

MC, 1-16 

Series 3, 1-15 

Series 3a, 1-15 

set back task switch keys, 5-13 

set task switch keys, 5-12 

window server, 1-14 


task switching back cancel 


wCancelBackTaskKey, 5-13 


task switching key cancel 


wCancelTaskKey, 5-12 


task switching key set 


wsetTaskKey, 5-12 


task switching set back 


wsetBackTaskKey, 5-13 


temporary 


text 


status window, 2-19 


button, 4-24, 4-25 

cursor, 1-29, 3-12 

drawing, 1-44 

fonts, 1-38, 4-14 

transfer mode, 1-45, 4-2 

transfer mode G_TRMODE_CLR, 1-45 
transfer mode G_TRMODE_INV, 1-45 
transfer mode G_TRMODE_REPL, 1-45 
transfer mode G_TRMODE_ SET, 1-45 
width, 4-16 


xiii 


WINDOW SERVER REFERENCE 


text count 
gTextCount, 4-17 
text drawing 
gPrintBoxText, 1-44 
gPrintClipText, 1-44 
gPrintText, 1-44 
gShadowText, 1-44 
gXPrintText, 1-44 
text mode 
G_TRMODE_CLR, 4-2 
G_TRMODE_INV, 4-2 
G_TRMODE_REPL, 4-2 
G_TRMODE_SET, 4-2 
text output 
WLIB functions, 4-19 
text print 
boxed, 4-20 
clipped, 4-20 
embellishment, 4-21 
gPrintText, 4-20 
shadowed, 4-23 
text print boxed 
gPrintBoxText, 4-20 
text print clipped 
gPrintClipText, 4-20 
text print embellished 
gXPrintText, 4-21 
text print shadowed 
gShadowText, 4-23 
text width 
gTextCount, 1-44 
gTextWidth, 1-44 
wGetWidthTable, 1-44 
text width get 
gTextWidth, 4-16 
textmode 
transfer mode, 1-45, 4-2 
time-stamp 
events, 1-14 
top-level 
window, 1-18 
transfer mode 
text, 1-45, 4-2 
update event selection 
WLIB function, 5-2 
update region 
redrawing, 1-24 
user 
event, 5-10 
user message 
event, 5-7 
validate function 
wValidateRect, 3-11 
wValidateWin, 3-11, 3-12 
validating 
before drawing, 1-25 
WLIB function, 3-11 
version_id 
window server, 2-4 
versions 
window server, 1-1 
vertical leading 
fonts, 4-14 


Xiv 


visibility 
window, 3-6 
visibility of 
windows, 1-28 
visible window 
wMakeVisible, 1-28 
W_BAND_COMPLETE_ON_UP 
rubber band attribute, 5-15 
W_BAND_GRID_SNAP 
rubber band attribute, 5-15 
W_BAND_GRID_SNAP_SIZE 
rubber band attribute, 5-15 
W_BAND_INNER 
rubber band attribute, 5-14 
W_BAND_OUTER 
rubber band attribute, 5-14 
W_BAND_ RESIZE 
rubber band attribute, 5-14 
W_BAND_START 
rubber band attribute, 5-14 
W_BORD_CORNER_1 
border attribute, 4-11 
W_BORD_CORNER_2 
border attribute, 4-11 
W_BORD_CORNER_4 
border attribute, 4-11 
W_BORD_CUSHION 
border attribute, 4-11 
W_BORD_OPEN 
border attribute, 4-11 
W_BORD_SHADOW_D 
border attribute, 4-11 
W_BORD_SHADOW_ON 
border attribute, 4-11 
W_BORD_SHADOW_S 
border attribute, 4-11 
W_CAPS_MODIFIER 
key modifier, 5-3, 5-9 
W_CONNECT_AT_BACK 
window server flag, 2-3 
W_CONNECT_CONNECTED 
window server flag, 2-8 
W_CONNECT_DISABLE_LEAVES 
window server flag, 2-3 
window server option, 1-11 
W_CONNECT_PRIORITY 
window server flag, 2-3, 2-7, 2-8 
W_CONNECT_SYSTEM_MODAL 
window server flag, 2-3, 2-8 
W_CONNECT_USER_FLAG 
window server flag, 2-3, 2-8 
W_CORNER_BOTTOM_LEFT 
message flag, 2-11 
W_CORNER_BOTTOM_RIGHT 
message flag, 2-11 
W_CORNER_TOP_LEFT 
message flag, 2-11 
W_CORNER_TOP_RIGHT 
message flag, 2-11 
W_CTBY_S3 
compatibility mode, 2-6 
W_CTBY_S3_SCR 
compatibility mode, 2-6 


W_CTRL_MODIFIER 

key modifier, 5-3, 5-9 
W_CURSOR_GREY 

cursor attribute, 3-12 
W_FUNC_MODIFIER 

key code, 6-2 
W_INFO_MSG_MAX_LEN 

message constant, 2-11 
W_KEY_APP1 

application keys, 5-5, 6-2 
W_KEY_APP2 

application keys, 5-5, 6-2 
W_KEY_APP3 

application keys, 5-5, 6-2 
W_KEY_APP4 

application keys, 5-5, 6-2 
W_KEY_APP5 

application keys, 5-5, 6-2 
W_KEY_APP6 

application keys, 5-5, 6-2 
W_KEY_APP7 

application keys, 5-5, 6-2 
W_KEY_APP8 

application keys, 5-5, 6-2 
W_KEY_APP9 

application keys, 6-2 
W_KEY_APPn 

application keys, 5-5 
W_KEY_BACKLIGHT 

key code, 5-5 
W_KEY_CALC_CHNG_SIGN 

key code, 6-2 
W_KEY_CALC_CLEAR 

key code, 6-2 
W_KEY_CALC_DECIMAL 

key code, 6-2 
W_KEY_CALC_MEM_CLEAR 

key code, 6-2 
W_KEY_CALC_MEM_INPUT 

key code, 6-2 
W_KEY_CALC_MEM_MINUS 

key code, 6-2 
W_KEY_CALC_MEM_PLUS 

key code, 6-2 
W_KEY_CALC_MEM_RECALL 

key code, 6-2 
W_KEY_CALC_PERCENT 

key code, 6-2 
W_KEY_CAPS_LOCK 

key code, 5-5 
W_KEY_DELETE_LEFT 

key code, 5-4 
W_KEY_DELETE_RIGHT 

key code, 5-4 
W_KEY_DIAMOND 

key code, 5-5 
W_KEY_DOWN 

key code, 5-4 
W_KEY_END 

key code, 5-4 
W_KEY_ESCAPE 

key code, 5-4 
W_KEY_HELP 

key code, 5-5 


INDEX 


W_KEY_HOME 

key code, 5-4 
W_KEY_INFO 

key code, 5-5 
W_KEY_IR_BRING 

key code, 6-2 
W_KEY_IR_LINK 

key code, 6-2 
W_KEY_IR_SEND 

key code, 6-2 
W_KEY_LCD 

key code, 5-5 
W_KEY_LCD_MINUS 

key code, 5-5 
W_KEY_LEFT 

key code, 5-4 
W_KEY_MENU 

key code, 5-5 
W_KEY_MODE 

event, 1-2 

key code, 1-15, 5-5 
W_KEY_OFF 

key code, 5-6 
W_KEY_ON 

key code, 5-5 
W_KEY_PAGE_DOWN 

key code, 5-4 
W_KEY_PAGE_UP 

key code, 5-4 
W_KEY_RETURN 

key code, 5-4 
W_KEY_RIGHT 

key code, 5-4 
W_KEY_TAB 

key code, 5-4, 6-1 
W_KEY_TASK 

key code, 5-4 
W_KEY_UP 

key code, 5-4 
W_KEY_VOICE 

key code, 5-4 
W_MOUSE_DOWN 

events, 5-9 
W_MOUSE_OUTSIDE 

events, 5-9 
W_NUM_LOCK_MODIFIER 

key modifier, 5-3, 5-9 
W_PANIC_SPRITE 

panic, 3-16 
W_PANIC_SPRITE_EXISTS 

panic, 3-16 
W_PSION_MODIFIER 

key modifier, 5-3, 5-9 
W_RUSSIAN_MODIFIER 

key code, 6-2 
W_SERVER_INFO 

for system font ID, 1-38 

structure, 1-38, 2-3 
W_SHIFT_MODIFIER 

key modifier, 5-3, 5-9 
W_SPRITE_CLIP_CHILDREN 

sprite attribute, 3-15 

sprites, 1-23 


WINDOW SERVER REFERENCE 


W_STATUS_WIN_NO_DIAMOND 

status window flag, 2-23 

window status flag, 2-23 
W_STATUS_WINDOW_BIG 

status window flag, 2-21 
W_STATUS_WINDOW_CTBY 

status window flag, 2-21 
W_STATUS_WINDOW_ICON 

status window flag, 2-23 
W_STATUS_WINDOW_OFF 

status window flag, 2-21 
W_STATUS_WINDOW_SMALL 

status window flag, 2-21 
W_SUPPORT_CTBY_S3 

window server flag, 2-26 
W_SUPPORT_GREY 

window server flag, 2-26 
W_SUPPORT_INFO 

structure, 2-26 
W_SYSTEM_FONT_INTERNAL_S3 

font type system, 4-17 
W_SYSTEM_FONT_INTERNAL_S3B 

font type system, 4-17 
W_SYSTEM_FONT_S3 

font type system, 4-17 
W_SYSTEM_FONT_S3B 

font type system, 4-17 
W_WIN_BACK_BITMAP 

window attribute, 1-19, 3-2 
W_WIN_BACK_CLR 

window attribute, 1-20, 1-25, 3-2 
W_WIN_BACK_CLR_NO_REDRAW 

window attribute, 1-21, 3-2 
W_WIN_BACK_GREY_BITMAP 

window attribute, 1-19, 3-2 
W_WIN_BACK_GREY_CLR 

window attribute, 1-20, 1-25, 3-2 


REDRAW 
window attribute, 1-21 


window attribute, 1-21, 3-2 
W_WIN_DOUBLE_PIXEL 
window attribute, 1-2, 3-3 


window attribute, 1-53, 3-3 
W_WIN_INPUT_ONLY 
window attribute, 1-53, 3-3 


Xvi 


W_WIN_MI_CROSS 

mouse icon attribute, 3-22 
W_WIN_MI_HSLIDE 

mouse icon attribute, 3-23 
W_WIN_MI_LEFT 

mouse icon attribute, 3-23 
W_WIN_MI_ MARGIN 

mouse icon attribute, 3-23 
W_WIN_MI_ MOVE 

mouse icon attribute, 3-23 
W_WIN_MI_ NULL 

mouse icon attribute, 1-52, 3-22 
W_WIN_MI PG_DOWN 

mouse icon attribute, 3-23 
W_WIN_MI_PG_UP 

mouse icon attribute, 3-23 
W_WIN_MI PUSHER 

mouse icon attribute, 3-22 
W_WIN_ML RESIZE 

mouse icon attribute, 3-23 
W_WIN_MIL RIGHT 

mouse icon attribute, 3-23 
W_WIN_MI STANDARD 

mouse icon, 1-52 

mouse icon attribute, 3-22 
W_WIN_MI_ TEXT 

mouse icon attribute, 3-22 
W_WIN_MIL TO _BIG 

mouse icon attribute, 3-23 
W_WIN_MI_TO_SMALL 

mouse icon attribute, 3-23 
W_WIN_ML_ VSLIDE 

mouse icon attribute, 3-23 
W_WIN_MOUSE_DRAG 
window attribute, 1-52, 3-3 
W_WIN_MOUSE_GRAB, 1-53 

window attribute, 3-4 
W_WIN_MOUSE_MOVE 
window attribute, 1-52, 3-3 
W_WIN_NO_MOUSE 
window attribute, 1-52, 3-3 
W_WIN_NO_REDRAW 

window attribute, 1-20, 3-3 
W_WIN_PRIORITY 

redraw priority, 1-27 

window attribute, 3-3 
W_WIN_RUBBER_ BAND 
indow attribute, 3-4 

window attribute_, 3-4 
W_WIN_RUBBER_BAND_ CAPTURE 

window attribute, 1-54 


iS 
5 


W_WIN_RUBBER_BAND_COMPLETE_ON_ 


RELEASE 

window attribute, 1-54 
W_WINDATA 

structure, 3-1 
wAppKeyHandler 

application keys, 1-15 
wAttachToClient 

MC, 1-16 

WLIB function, 2-26 
wAttachToForegroundClient 

MC, 1-16 

WLIB function, 2-26 


wBeginRedraw 


redrawing WLIB functions, 1-25, 1-26 


WLIB function, 3-9 
wBeginRedrawGC 

graphics context temporary, 1-51 

WLIB function, 3-9 
wBeginRedrawGCO 

graphics context temporary, 1-51 

WLIB function, 3-10 
wBeginRedrawWin 

WLIB function, 3-9 
wBeginRedrawWinGC 

graphics context temporary, 1-51 

WLIB function, 3-10 
wBeginRedrawWinGCO 

graphics context temporary, 1-51 

WLIB function, 3-10 
wCallDYL 

WLIB function, 4-33 
wCallDYLReply 

WLIB function, 4-33 
wCancelBackTaskKey 

task key back cancel, 1-52 

WLIB function, 5-13 
wCancelBusyMsg 

graphics output, 1-49 

WLIB function, 2-12 
wCancelCaptureKey 

key specific cancel, 1-51 

WLIB function, 5-12 
wCancelGetEvent 

and window server events, 1-28 

WLIB function, 5-10 
wCancelSystemModal 

system modal cancel, 1-17 

WLIB function, 2-9 
wCancelTaskKey 

task key cancel, 1-52 

WLIB function, 5-12 
wCaptureKey 

specific key, 1-51 

WLIB function, 5-11 
wCaptureMouse 

WLIB function, 5-13 
wChangeWinBitmap 

bitmap sequences, 1-21 

WLIB function, 3-15 
wCheckPoint 

WLIB function, 2-7 
wCleanUp 

WLIB function, 2-7 
wClientIconised 

WLIB function, 2-9 
wClientInfo 

WLIB function, 2-8 
wClientPosition 

WLIB function, 2-8 
wCloseWindowTree 

windows destroying, 1-27 

WLIB function, 3-6 
wCompatibilityMode 

S3 display mode, 2-6 
wConnect 

WLIB function, 1-8, 2-1, 2-3 


wCreateSprite 

sprites, 1-23 

WLIB function, 3-15 
wCreateWindow 

window create, 1-18, 1-27 

WLIB function, 3-1, 3-4 
wDetachClient 

WLIB function, 2-26 
wDisableKeyClick 

WLIB function, 2-26 
wDisableLeaves 

WLIB function, 2-7 
wDisablePauseKey 

pause key disable, 1-52 

WLIB function, 2-10 
wDisconnect 

WLIB function, 2-5 
wDrawButton 

graphics output, 1-49 

WLIB function, 4-24 
wDrawButton2 

graphics output, 1-49 

WLIB function, 4-25 
wDrawTextCursor 

graphics output, 1-49 

WLIB function, 3-13 
WE_ESC 

event selected, 5-2 
WE_KEY 

event selected, 5-2 
WE_MOUSE 

event selected, 5-2 
WE_NORMAL 

event selected, 5-2 
WE_OTHERS 

event selected, 5-2 
WE_REDRAW 

event selected, 5-2 
WE_STATUS 

event selected, 5-2 
wEnablePauseKey 

pause key enable, 1-52 

WLIB function, 2-9 
wEndCompute 

priority, 1-17 

WLIB function, 2-8 
wEndRedraw 

graphics context free, 1-51 

WLIB function, 3-11 
wEraseTextCursor 

cursor remove, 1-29 

graphics output, 1-49 

WLIB function, 3-13 
wFlush 

WLIB function, 2-5 
wFree 

bitmap free, 1-30 

bitmap sequences, 1-21 

sprites, 1-23 


WLIB function, 3-15, 3-16, 3-22, 3-23, 4-5, 


4-16, 4-28, 4-32 
wGetCommand 
WLIB function, 5-10 


WINDOW SERVER REFERENCE 


wGetEvent 

event, 1-28, 1-51 

event get async, 1-14 

WLIB function, 5-2 
wGetEventSpecial 

event, 1-28, 1-51 

event get async, 1-14 

WLIB function, 5-2 
wGetEventUpdate 

WLIB function, 5-2 
wGetEventWait 

event, 1-51 

event get, 1-14 

WLIB function, 5-1 
wGetProcessList 

WLIB function, 2-10 
wGetWidthTable 

text layout WLIB function, 1-44 
wGetWindowPosition 

window position get, 1-27 

WLIB function, 3-7 
width 

fonts, 4-14 
window 

attributes, 3-1 

attributes get, 3-5 

attributes set, 3-5 

back up bitmaps, 1-19 

back up bitmaps advantages, 1-19 

back up bitmaps disadvantages, 1-19 

back up bitmaps memory, 1-20 

background field, 3-2 

background modes, 1-3 

child, 1-18 

clipping, 1-25 

creating, 1-27, 3-1, 3-4 

destroying, 1-27, 3-6 

drawing, 1-25 

drawing region, 1-19 

flicker free drawing, 1-25 

flicker free redrawing, 1-25 

inactive, 1-53 

initialising, 1-27, 3-1 

invisible function, 3-6 

mouse only input, 1-53 

no-redraw, 1-20 

ownership, 1-18 

parent, 1-18 

position get wGetWindowPosition, 1-27 

position set wWindowPosition, 1-27 

root, 1-18 

scrolling, 1-28, 3-7 

scrolling optimised, 1-3 

sibling, 1-18, 3-7 

sibling position get, 3-7 

sibling position set, 3-7 

status, 2-19 

top-level, 1-18 

trees, 1-18, 3-5 

visibility, 1-28, 3-6 

visible function, 3-7 

W_WIN_DOUBLE_PIXEL flag, 1-2 

wInvalidateWin, 1-24 


XViii 


Window 
offset get, 3-6 
root reassign, 3-6 

window attribute 
W_WIN_BACK_BITMAP, 1-19, 3-2 
W_WIN_BACK_CLR, 1-20, 1-25, 3-2 
W_WIN_BACK_CLR_NO_REDRAW, 


1-21, 3-2 
W_WIN_BACK_GREY_BITMAP, 1-19, 
3-2 
W_WIN_BACK_ GREY _CLR, 1-20, 1-25, 
3-2 


W_WIN_BACK_GREY_CLR_, 3-2 
W_WIN_BACK_GREY_CLR_NO_ 
REDRAW, 1-21 
W_WIN_BACK_GREY_NONE, 1-25, 3-2 
W_WIN_BACK_GREY_NONE_, 3-2 
W_WIN_BACK_GREY_NONE_NO_ 
REDRAW, 1-21 
W_WIN_BACK_GREY_SET, 1-20, 1-25, 
3-2 
W_WIN_BACK_GREY_SET_, 3-2 
W_WIN_BACK_GREY_SET_NO_ 
REDRAW, 1-21 
W_WIN_BACK_NONE, 1-25, 3-2 


1-21, 3-2 
W_WIN_DOUBLE_PIXEL, 3-3 


W_WIN_INACTIVE, 1-53, 3-3 
N_INPUT_ONLY, 1-53, 3-3 
IN_MOUSE_DRAG, 1-52, 3-3 
IN_MOUSE_GRAB, 3-4 
IN_MOUSE_MOVE, 1-52, 3-3 
IN_NO_MOUSE, 1-52, 3-3 
IN_NO_REDRAW,, 1-20, 3-3 
IN_PRIORITY, 3-3 
IN_RUBBER_BAND_, 3-4 
IN_RUBBER_BAND_CAPTURE, 


Z 


geececace 
geeeeeez 


25 
af 


_WIN_RUBBER BAND_COMPLETE_ 
ON_RELEASE, 1-54 
WS_WIN_BITMAP_GREY, 1-22 

window create 
wCreateWindow, 1-18, 1-27 

window destroying 
multi-tasking and, 3-6 

window function 
wCreateWindow, 3-1 
wInquireWindow, 3-1 
wSetWindow, 3-1 

window invisible 
wMakelInvisible, 1-28 

window offset 
wInquireWindowOffset, 1-18 

window rectangle 
wlInvalidateRect, 1-24 

window scrolling 
continuous, 1-29 


wscrollRect, 1-28 
wScrollWin, 1-28 
window server 
buffered commands, 2-7 
changes, 1-1 
client information by process id, 2-8 
client list get, 2-10 
clients, 1-13 
configure, 2-24 
connect to, 1-8, 2-1, 2-3 
connecting to example code, 2-4 
disconnect from, 2-5 
error handling, 1-11, 2-7 
events and p_iowait, 1-28 
events and wCancelGetEvent, 1-28 
events and WM_CANCELLED, 1-28 
flag WSERV_FLAG_HOOK_NOTIFIER, 
1-55 
flag WSERV_FLAG_HUNG_UP, 1-56 
flag WSERV_FLAG_LOW_BATTERY_ 
WARNINGS, 1-56 
flag WSERV_FLAG_NO_NOTIFIER_ 
REBOOT, 1-55 
flag 
WSERV_FLAG_NO_PANIC_NOTIFY, 
1-55 
introduction, 1-1 
process SYS$WSRYV, 1-1 
Series 3c and Siena update, 6-1 
supported features get, 2-26 
task switching, 1-14 
version 3, 1-7 
version 3.5, 1-5 
version 4, 1-2 
version from wConnect, 1-2 
version_id, 2-4 
versions, 1-1 
versions Series 3c and Siena update, 6-4 
versions Series 3c update, 6-4 
versions Siena update, 6-4 
W_CONNECT_DISABLE_LEAVES flag, 
1-11 
wConnect WLIB function, 1-8 
WLIB functions, 2-1 
window server configuration 
see WSERV_FLAG, 2-24 
window server constant 
WS_LAST_CLIENT_POSITION, 2-8 
window server flag 
E_PRIORITY_BACK, 2-7 
E_PRIORITY_FORE, 2-7 
W_CONNECT_AT_BACK, 2-3 
W_CONNECT_CONNECTED, 2-8 
W_CONNECT_DISABLE_LEAVES, 2-3 
W_CONNECT_PRIORITY, 2-3, 2-7, 2-8 
W_CONNECT_SYSTEM_MODAL, 2-3, 
2-8 
W_CONNECT_USER_FLAG, 2-3, 2-8 
W_SUPPORT_CTBY_S3, 2-26 
W_SUPPORT_GREY, 2-26 
window server flags 
see also WSERV_FLAG, 2-24 
window status flag 
W_STATUS_WIN_NO_DIAMOND, 2-23 


INDEX 


window tree 
wlnitialiseWindowTree, 1-27 
window visible 
wMakeVisible, 1-28 
windows 
clipping child, 1-18 
drawables, 1-18 
graphics contexts, 1-18 
invalidating, 1-24 
overview, 1-18 
overview additional info, 1-27 
redrawing, 1-24, 1-25 
redrawing variants, 3-8 
windows and bitmaps 
drawables, 1-18 
windows destroying 
wCloseWindowTree, 1-27 
winfoMsg 
graphics output, 1-49 
WLIB function, 2-11 
winfoMsgCorner 
graphics output, 1-49 
WLIB function, 2-11 
winformOn 
WLIB function, 5-11 
winformOnAll 
WLIB function, 5-11 
wlnitialiseWindowTree 
window tree, 1-27 
WLIB function, 3-5 
wInquireCompatibility 
compatibility mode get, 2-7 
wInquireStatusWindow 
WLIB function, 2-23 
wlInquireWindow 
WLIB function, 3-1, 3-5 
wInquireWindowOffset 
window offset, 1-18 
WLIB function, 3-6 
winvalidateRect 
and invisible windows, 1-28 
window rectangle, 1-24 
WLIB function, 3-12 
winvalidateWin 
and invisible windows, 1-28 
window, 1-24 
WLIB function, 3-12 
WLIB 
header file, 1-8 
library with CLIB and PLIB, 1-8 
wLoadDYL 
WLIB function, 4-33 
WM_ACTIVE 
event, 1-53, 5-10 
WM_ATTACHED 
event, 2-25, 5-8 
WM_BACKGROUND 
event, 5-6 
WM_BAND_CANCEL 
rubber band flag, 5-15 
WM_BAND_ERROR 
rubber band flag, 5-15 
WM_BAND_ MOVE 
rubber band flag, 5-15 


WINDOW SERVER REFERENCE 


WM_BAND_NOMOVE 
rubber band flag, 5-15 
WM_BAND_RESIZE 
rubber band flag, 5-15 
WM_CANCELLED 
and window server events, 1-28 
event, 1-28, 5-6, 5-10 
WM_COMMAND 
event, 5-7 
WM_DATE_CHANGED 
event, 1-3, 5-7 
WM_DEICONISE 
event, 1-16, 2-8, 5-8 
WM_DETACHED 
event, 2-25, 5-8 
WM_ESCAPE 
event, 5-8 
WM_FOREGROUND 
event, 2-25, 5-6 
WM_KEY 
event, 1-15, 1-51, 5-3 
WM_KEYBOARD_STATE_ CHANGE 
event, 5-8 
WM_MOUSE 
event, 1-52, 5-9 
WM_MOUSE_MOVE 
event, 5-9 
WM_MOUSE_PRESS 
event, 5-9 
WM_MOUSE_RELEASE 
event, 1-53, 5-9 
WM_ON 
event, 5-7, 5-11 
WM_REDRAW 
event, 3-12, 5-6 
WM_RUBBER 
event, 1-53, 5-10, 5-14, 5-15 
WM_RUBBER_BAND_INIT 
event, 1-54, 5-9 
WM_TASK_ KEY 
event, 1-15, 5-7 
WM_TASK_UPDATE 
event, 5-7 
WM_USER_MSG 
event, 5-7, 5-10 
wMainGc 
structure, 2-2 
wMain Wid 
structure, 2-2 
wMakelnvisible 
window WLIB function, 1-28 
WLIB function, 3-6 
wMake Visible 
window WLIB function, 1-28 
WLIB function, 3-7 
WMSG_KEY 
structure, 5-3 
WMSG_MOUSE 
structure, 5-9 
WMSG_RUBBER 
structure, 5-15 
Workabout 
fonts, 1-41 
task switching, 1-15 


». ©. ¢ 


wReassignRootWindow 

WLIB function, 3-6 
wReleaseMouse 

WLIB function, 5-13 
wRubberBand 

enter rubber band mode, 1-54 

WLIB function, 5-14 
WS_ALERT_B 

alert flag, 1-3 
WS_CLOCK_AM_PM 

clock attribute, 3-17, 3-20 
WS_CLOCK_BOX 

clock attribute, 3-20 
WS_CLOCK_CENTERED 

clock attribute, 3-17, 3-20 
WS_CLOCK_FORCE_ANALOG 

clock attribute, 3-17, 3-20 
WS_CLOCK_FORCE_DIGITAL 

clock attribute, 3-17, 3-20 
WS_CLOCK_FORMATTED 

clock attribute, 3-19 
WS_CLOCK_GREY 

clock attribute, 3-20 
WS_CLOCK_LARGE_ANALOG 

clock attribute, 3-17, 3-19 
WS_CLOCK_MEDIUM 

clock attribute, 3-17, 3-19 
WS_CLOCK_MEDIUM2 

clock attribute, 3-19 
WS_CLOCK_SMALL_DIGITAL 

clock attribute, 3-17, 3-19 
WS_CLOCK_WITH_DATE 

clock attribute, 3-17, 3-20 
WS_CLOCK_WITH_SECONDS 

clock attribute, 3-17, 3-20 
WS_CLOCK_XL_ANALOG 

clock attribute, 3-19 
WS_DEFAULT_ICON 

icon ID, 1-3 
WS_DEFAULT_ICON+1 

icon grey ID, 1-3 
WS_EV 

structure, 5-1 
WS_EVENT_UNION 

events, 5-1 
WS_FONT_BASE 

define, 1-38 
WS_FONT_FILE_HEADERS 

structure, 1-46 
WS_FONT_SYSTEM 

define, 1-38 
WS_LAST_CLIENT_POSITION 

window server constant, 2-8 
WS_PIC_HEADER 

structure, 1-37 
WS_WIN_BITMAP_GREY 

window attribute, 1-22 
wsAlertA 

graphics output, 1-50 

WLIB function, 2-18 
wsAlertCancel 

graphics output, 1-50 
wsAlertUpdate 

graphics output, 1-50 


WLIB function, 2-19 
wsAlertW 

alerts, 1-3 

graphics output, 1-50 

WLIB function, 2-14 
wsCreateClock 

graphics output, 1-49 

WLIB function, 3-17 
wsCreateClock2 

graphics output, 1-49 

WLIB function, 3-19 
wscrollRect 

graphics output, 1-49 

window scrolling, 1-28 

WLIB function, 3-7 
wscrollWin 

graphics output, 1-49 

window scrolling, 1-28 

WLIB function, 3-8 
wsDisable 

graphics output, 1-50 

WLIB function, 2-22 
wsDisableTemp 

graphics output, 1-50 

WLIB function, 2-22 
wsEnable 

graphics output, 1-50 

WLIB function, 2-21 
wsEnableTemp 

graphics output, 1-50 

WLIB function, 2-22 
wsendCommand 

WLIB function, 5-10 
WSERV_FLAG 

HOOK_NOTIFIER, 2-24 

HUNG_UP_SW, 2-25 

LOW_BATTERY_WARNINGS, 2-25 

NO_NOTIFIER_REBOOT, 2-24 

NO_PANIC_NOTIFY, 2-24 

NO_SHELL_REBOOT, 2-24 

SW_NO_CAPS, 2-25 

SW_NO_LINK, 2-25 

SW_NO_LOW_BATTERY, 2-25 

SW_NO_PACKS, 2-25 

UPDATE_MSGS, 2-24 
WSERV_FLAG_HOOK_NOTIFIER 

window server flag, 1-55 
WSERV_FLAG_HUNG_UP 

window server flag, 1-56 
WSERV_FLAG_LOW_BATTERY_ 
WARNINGS 

window server flag, 1-56 
WSERV_FLAG_NO_NOTIFIER_REBOOT 

window server flag, 1-55 
WSERV_FLAG_NO_PANIC_NOTIFY 

window server flag, 1-55 
WSERV_SPEC 

structure, 2-3 
wsetBackTaskKey 

task key back set, 1-52 

WLIB function, 5-13 
wSetBusyMsg 

graphics output, 1-49 

WLIB function, 2-11 


INDEX 


wsetPriorityControl 

WLIB function, 2-8 
wsetSprite 

sprites, 1-23 

WLIB function, 3-16 
wsSetSystemFont 

WLIB function, 4-17 
wsetTaskKey 

task key set, 1-52 

WLIB function, 5-12 
wsetWinBitmap 

bitmap sequences, 1-21 

bitmap WLIB function, 1-30 

WLIB function, 3-14 
wsetWindow 

WLIB function, 3-1, 3-5 
wsfcomp.exe 

font file compiler, 1-43 
WSpcx.exe 

bitmap converter, 1-31 

bitmap file converter, 1-31 
wSpec 

structure, 2-2 
wsScreenExt 

WLIB function, 2-21 
wsSelectList 

graphics output, 1-50 

WLIB function, 2-23 
wsSetClock 

graphics output, 1-49 

WLIB function, 3-22 
wsSetList 

graphics output, 1-50 

WLIB function, 2-23 
wsStatus Window 

graphics output, 1-50 
wStartCompute 

priority, 1-17 

WLIB function, 2-8 
wStartup 

WLIB function, 2-1 
wStatus Window 

status window permanent set, 2-21 
wsUpdate 

graphics output, 1-50 

WLIB function, 2-22 
wsupportInfo 

WLIB function, 2-26 
wsystem 

process, 1-55 

WLIB function, 2-24 
wsystemModal 

system modal, 1-17 

WLIB function, 2-9 
wTextCursor 

cursor WLIB function, 1-29 

graphics output, 1-49 

WLIB function, 3-12 
wUserMsg 

WLIB function, 5-10 
wValidateRect 

WLIB function, 1-25, 3-11, 3-12 
wValidateWin 

WLIB function, 1-25, 3-11 


WINDOW SERVER REFERENCE 


wWindowPosition 
window position set, 1-27 
WLIB function, 3-7 


xxii