SIBO 'C' Software Development Kit 


HWIM REFERENCE 


Version 2.11 


February 3, 1995 


(C) Copyright Psion PLC 1990-95 


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, PsionMC, Psion HC, Psion Series 3, Psion 
Series 3a and Psion Workabout are trademarks of Psion PLC. 


TopSpeed is a registered trademark of Clarion Software Corporation. Intel 8086 and 80286 are registered 
trademarks of Intel 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 


DIMtroductiOns ccsccccisesssesnsssccscicaconsectssssasutusnresesnesctesdiainavessisnssibuscecseedl omiotios com ee ces 1-1 
Using: WIM classes. ts... % uss tesee. Be citich a eeatennsee haeercee eee ie 1-] 
INOCALION 335, c tices ceccratsyloreecosctaeecstueaecvasdi casi seueesSeltorss ssa coht ovacacivsss REO RS eR OM 1-2 
IN@MICS ore ec arbcaaletict lees rsbaceee cos ethane to el anode sist eat aes ces es R= RE 8 1-2 
Method Rimchion prototypes -..-.ccsciosercsesciedacsbccsat2estosisesseovsatcasvoiouieiisieoee wotsiblaas-c2aece 1-2 
The: novleave: Symbol 5.2, Ystceeevetssaceeutiacvsclisssesteidees hasteves en eeecod toon oe tie eis 1-2 
CLASS CIA SEIS ci stccesnssin! cael oboe gees epacsaieneduacraiaheews a6thataacMecciea Meee leas ae lanes leeeNM ct 1-3 
Class:Hierarchy.. 25 <::,.ciscaceeaatvitetersth, cysvatesraseies estes asians ccsstaedthty Sea aM Tide, Chee ee? 1-3 
Structured Error: Recovery sch. cztiasccteterii acdsee eee olnece er ses 1-4 
Use of. the:p. leave mechanisins..:si:sssssisasnsed cctissssssitaceestaserds cnc en se osc 1-4 
PAC MUMNOETS os etic cteatiey nd aie dyce te sae tenleaveliiu rai licss eA MIRE ae ee et eee 1-4 
2 The HWIMMAN Application Manager ..........ssssssssssssssresssscssoserossssssssasssosoresscecosecentacesesssssereseees 2-1 
PHECUDSOLS <3: 52.5 css SeiscidsVassebsaakieasarctacedscsitestataesescates retecteeraceat oie tvs delets ones aeeteectte sceieee 2-1 
Class :diactanimeenrmercteecert ert ee eet ee ee 2-2 
CLASS CORI OIG tresses tadieSython eerea lect loeestadocas ocmarnasetten reese Co meet etait 2-2 
PROPGIt ites atts, cated eRe A ACA cote hectiinast ale hscce eh tutsessdediec ce ate ihe heaton 2-3 
HIWIMMAN methods. .1..3:s0s2isccai ashe ales rees teats uecsitenscoledteesel on SNe ne ee 2-3 
PaO AMS Grasses cuca cain sbata tenga snucitevctveassascucodiagaln soa mart AO os ORE cs 2-3 
Generate resource: file Mame ...:5s:::ci:ssc.sctiasesacstevedact vides SE osc eee esas 2-5 
MW alt fOr ATICCVENE i. scccsieacotaaccu geal vassensvoueecoveshestacacck shea: Meissen ED 2-6 
Clean up resources and report aM €rT Or .........cccssssssssesscsesssssesssssessscsseesscsecearececeeseceenenenes 2-6 
Recordia new: filename... ..ccessexectsci ons capuvecueets caeadestascanesevicsstevtelaresadsecdeih ataclinadivette 2-7 
IREPOteAM errr ec. sevcasceethoca secs etousvnueles eb atadevtveneatuedbucasccdos teSt Mibelassiei bet stéesetavet seus Metiae 2-7 
Wait for all activity to Cease..........sessssesssesscsssssecssscseecssscsssessscsccecsearscserersacnencassecacesees 2-7 
PEAY aI OIY LRA Eilers. goer careasaansensstousycaacseecctesscerdavisrseesa dre nv ines ioesen at eaicaeee 2-7 
Guarantee existence Of IPCS 00... eecescsssssssesssesecssesnenesesersnesssesussvscerseeveessecsesecesscacneess 2-8 
3 THE WSERV., Class «5. ssceasctisiscassssinccecsanvasesiendtcesstessossbcons tos ieodedeuvastastetedeaasieacsséssteieosonce hese hia teccse 3-1 
PE CUTSOIS oi3sscsisecsassissateescsbbastecveatt fe caucn  Stvedadean cisasisedeagectesavicsiievaesedeatd ote ie tes 3-2 
Class ia orarm ' cses cake cccsdsevenstseysiys osetesbigantededsaeveiSesaasdasts g Gia ecseeies ea Hee 3-2 
Class definition: fais ccssciseuzésscssenacsevaraa vi covetdatastecatteasagvecdsavacasdiaios Sessexics theo bale wenonte 3-2 
PROperey, 2s Sccrs ssvssco cate, cssevevccustscesssnsassecss oubwivutskapasdesevadontcusatesdatadhosgtsceidedes ee ea 3-6 
WSERV methods acrc0 08 ie: facies ihe cal eceshens es toit te eR Eas ha slvtahnenuebin esac haves erases 3-9 
Application imitialisation 0.0.0... ccseesessscesessseseseseessseseessessssesssesssessssenececsecetensscaseesece 3-9 
Dra TtrAl AS © 52.22.05 scttcnssccasca os sstevsqpsousstedelactavacd sales caesa sieschaatstesbedteldosaesiec en ol ee 3-9 
Queue:a message from the Server: :...::.ssis.ssessececsesersecttsociaracecseacsasscassesieedeabe aati 3-10 
Cam ce 5 oo scsca cee Sh Soca sh ozs catieba ousted voaceva aud dnetsdetch cancdecioadecteasSics loos aera 3-10 
Cancel any pending window Server read.............cccssssssscssseseecsssessssceresecseseerseeeccetseesnenes 3-10 
Process a message from the Server ..........c.ccsccessssssesesesssnsnsesssesseesscsssssssecsssensneneseeceeeece 3-11 
Log anew: client Window 3.213.220; -S.ccslesdbsacitevesetvansisicsasddseeesidecudidieciaeuoreie eee oe eses 3-14 
Runa dialogns 2st 208 ett) 08 aes vente capa ce tascedssliecie etc tees sstote come een eas 3-15 
Add-a'dialogto the: dialog lists... ciseFaetepulsven dei dnadteiskeS decode isweee aces ks 3-15 
Remove a dialog from the dialog list ............:.sccesssssssssssssessssesssesesssssssessessececeesseeseseenes 3-16 
Paragraph word" wraptsnrk creme ena tect erste eee ee: 3-16 
Runehelp:sy Stem eee temcccez cree aeccrs, Sirgere: ne corre ari eth we Oe el aL 3-16 


Get'choicedist:resource:text::. 2a ere er ee a eer 3-16 


Ruin the free-form dialling Aialog s.o.3scccsasidccssasassnseseassusddasxassssedesdsbsvosuiticereenndiovevnsave 3-17 


Process a Switchfiles message ...........scsssscssecssssssesesescscsssvsssesssssecscecsercacscecesssesecvsvscesesess 3-17 
ALIER Me OGK COUN ea tistic sos Saausedwsktneateasccebers ines Sewssid dvi nentcavasi scsies dese RES, GM 3-17 
Del altermative mene DAT 27, ois. 2.25¢zcesnuythesareccessasasace iS iaeenavaadennasascaveccartrn ian teat 3-17 
Reset:the menu’ Dan -ts.ste.sccccictvacccScccastiassettesttotateclitans tus gesdovtessaiss Res cceavetousseoea llouissatheet 3-17 
RUM -AsSUDMEMI ses ce ccsvcovsleaccarutselcisieet ect tetl ta wlvanatt sige jo adh eubavaeaedes cniadeantiec te oees 3-18 
BRUM FAT AAD aes nsec spats yeu canegh setae den sup rnecdnalves caution scalar neaasuivios abu tbOde sa 3-18 
Runnjanterror: dialog ois. ce.ccsistic.covecusadiiev sid siecssehess stacecssviaSadtuloatensavasessuedvestvesenteceynecasteks 3-19 
Evaluate an expression scicii.as03sisr.;6cesantecelatactaisseoes estat sibaiaostvseats Sas stSeeusahe oslones dees: 3-19 
Set or get evaluator environment Variable..............ccsscssscesesssssssssesscsessscscscscetsseesseeceres 3-19 
Set or get dial environment variable .............cscccsessssssssssssssssssssssesssscssssseecerssensseececsesees 3-20 
RAI ENE. Set LOrmae Ig OG iced csencceastsaotesceaevesanbstte teditasevetoaveurieritaisioacseMivecpdliaieiause 3-20 
BPE TACE tO wy SALE EE se Acceso shac 9 cul aio hnis ston vane drusracenta os sneles caph Sits sana ves aa see sedte hans 3-21 
Runicountry selector, dialog -....3:..-:.ssscsscenedsessetatessacivesetsescetusevsvvesdvetesdravdsesinvioese eRe 3-21 
Smart dial of a NUM Der sf h. 2. l ea cécceadencensteseasttsddiaesessdasissdeusleaetesvc eae ee 3-21 
Ensure print context data exists... cesccsessssssssccsssssssssscsesssssssessscssssscstasssssossareveeees 3-22 
Run:iprint:sétup:dialog Serres: ss elas ae canals cstesss tiv tha ovtaosasariiv Siationseenetties See 3-22 
Rusmprintencon figuration dialog gat sysiacncredirietcess pla oases eet cco meesceesactansaes 3-22 
Sense text for current printer device ........cececssssscssssessssssescecssssessesesssusssseavscsescscensnseceres 3-22 
Add a:tilelist-tosthe listens: eActe tc ccetesteacsetacetaiissestsshccscontnes isto oh eee tesnlel 3-22 
Removelathilelist:trom the tlists0 cc cisarae cet ssehivids. ena nace ecto eth eees 3-23 
Anudator lias ticked Overy ss, oMees wetter teh claccoast oth ys hati eaadeec seen ae Roa nase 3-23 
Unrecognised WSERV€Venit ...22:..cs..:c¢estsesiahevencatistassvesovetdenrsint mentee athe wae as 3-23 
Ore TOUNG MESSAGE es. ccveasasstcauavistead ustiensvonsasueesed wih wacker te oe athe tos 3-23 
Backeround Message... ciz.ce.scccvessscocassesscucsarvsveavaslesesnsradevessvasacesscastMeesvisaviene i aeenes 3-23 
Request date change motification.............csscecssessssssesesesssssssssscccssssececssssssacsrsssssesscavecaeers 3-23 
Process WM_DATE_CHANGED .000....eceseesesssssssecsssesesesencesetsssensessasssssescasasscacceaneesees 3-24 
Launch: aD Vile arvameem. senmrrsrres oie tore tossh tence t res ss sess t isstes ere esate ees 3-24 
Set up a status window ‘diamond! list..............cccccsececsscessssessesscessscssscssssssacesscecesectssneneece 3-24 
Display dllocator statistics 3x, nse:sonnnssuatadedtysehseceussasodeesoesedenseloivsvaslsueseabecnterss 3-25 
Copy print context from @ Process ...........ssesessssssssssesessessssscssseesscevesscssassasssssssssasscersssvees 3-25 
Performintermal' data CHECK 5. i.:.ccesccccusdethedecic¥etsactgcesvcisdees lonels anctstsceaeeisteebseupeiee catel 3-26 
Hide application from System Screem...........sccssscsssssssesessscsssssscscnsessseesessesessnscsavsossauesere 3-26 
Set attachedistate -, c-.....hesirescsiserisesseycsdesndesarensvanevsatintienr visi gssucainhe RA ee 3-26 
Display, a file-related message, s,s, <ssssssstersescsssecessvsucsandecresrevensouevasviaacergrcit eet eeseses 3-27 
RunyA genda memo: editor 2... ecadeessccsactieed ne Givsses caste cee hea eens 3-27 
Run, digloe inian other process i.16o3,jsseasseteieiematianeter paces amet eee ead 3-27 
Exitapplication-with valet :i/ss.c.s.c cseccscavceu santas iesdle. Settee rn eee 3-28 
SHUTTER ssc. cassacecivece nes hsesvespcvnwvatsancveseseuesscdearstiassea elise dateradhcassacevtacle teuteedebea tiation 3-28 
Processing a Switchfiles message ............ccssssssssscssessseresssesesesesestecceesesssesstacscscassessseeseass 3-28 
Glass. de fin ition ssccscceccwscsesewswacnoaeroseccecssev es soav so 3090 BUT RESTSOT SESE NTE TSU SUTOG FOSS TUS OT OUTST STU T PUNO TUTTO 3-29 
PLOPerty ic: 402. 2s ochv. tediees shares esaheuseseeveveaatets caseanachastuideseegecaststor test seevsvaceaaceson see erecesttens 3-29 
SHUTTER: methods... 4isesat eevhucis cdi aren elven as tssina Beale anectebetincestatvateaadh 3-29 
Trt AHS sus ysteseess-acezssscusgaetsscssocetussesdseecadusvaisesSaeteatticoossaane esaa buen oiatotatoanc so abu caees 3-29 
Do, or prepare for, the file SWitch .........cccccscscscccccsssccsceresccecsscesseccecessesesessesesssssensesseess 3-30 
PRAMAS CEO scsi taes esa van dda dineeiet saan ifeaearan Sate cue Acad ddvacss Se ala OMEN 3-30 
4-The Gommniand Manager c:c.ccsicscsesctsssscatessssunssnsus uscd sascatucesnttvcnssvocestavavicsieusbautaybdseaaeciedpoovetaomresies 4-1 
PROCURSOTS) 2043 ssecocsctucceatesSe.g dectaecaneshetaaiiheee aciesseea ves leabesvan andere avhitechs ida mus inee eee 4-1] 
ClaSS Ata or ann. fe ses sstees ovis cesnn valance repeledaseussbaltecltiad ve ocacdeans tdvacueal hoor iracesidceied Bie 4-2 
COMMAN 8 failed Brinda otredeaearntllr sattenaniide sana Ab nediu cane tee ees 4-2 
GT aSE Ge riety ese ess shactesins Sah amaan ccutsan eco ae es dats es 4-2 
PYOPOrty oibsc secs Be Aeseek bess ctieditusc ds adentia cette avsacistautescssnantsedtsiosiadon dae aariistalestetetes er ass 4-2 
COMMAN methods sirs.oia.cice Mecsechiinevtiseivautecnscssorses osu hearea in eae ea RN 4-3 
Anitial ise s2esc2 2st. seits. sh tetetfocee enetcts coe ak steStsccsressvstaraciaas cissels eM aces ia RIN, Bao, 4-3 
Toggle permanent status WiNdOW............-ccscssssssssesessssessecsessssssscseeseesesssssasevacsessessesssnsees 4-3 
Validate: a COmMANd::-cs2t..:.ahcretshiassratetorcaatelisacsin cardi Manin tesserae RT Ae 4-3 
A. pull-down meni is about to appear ..ic.:..c.cceusnissssiaccieavteccannscccssravsorcoueissievceedocdscnnsdoes 4-3 
Process a WoKEY..MODE: Key sini .tisatetieas.casensaititaeiscstudes eee waar 4-4 
Open or create as tiles. i215, 2225, cote van cua Batvencecchocievtuslovsesvavicecel PANO Oe oe Rts AM or 4-4 
Exit the applications. ssccaresuser siete cassneues chacasstahs038t cuca astth aera cue eo ee th santas 4-5 


EL OPOLEY 22 secsccblavesseesteacessssevtl soaseesieisetel tra ess (oes ETE Bey OR, Reet RO 5-4 


WINGO Wsflaps.is.sevessteees satires ek havea Nae, co aattece ru en ore titans otc ie, a 2 5-4 
WIN methods: i203 ncidenan Shel nennd dnd nee et 5-4 
DeStrOY:scccsieassesstesctavecosedes ssectusietes ci cosine enecasisia ti tee ioe ee oh nec ces 5-4 
Create the window's window Server data ........ccccssssssssscsscsesssesssssssscssscsssctaccecesecsssacecsees 5-5 
System =mitiated redraws rs.sr. ere. dttic es ssevaresdarns atest ita del eccsdl eee ee 5-5 
Application-imnitiated we draw: 6. it.25.catoeco seals... ec eeeathesibadashs Foote OO aces 5-5 
St VISIDIUIt Ys sshd edeogtoscsherte esses siaustaeeRevarsen mab ata nea acinar aan ees 5-6 
Set window. highlight 503. dssi.; scsi cecsteatevscuessevssvervevesaavtastesuctistanss eon aces he eens 5-6 
Sense startlD for helps .ccstseieadt coissecssatensstecvetasedis lonctatanvevevsstacneus ieee Seen eee 5-6 
Calculate a window position ..........sscsssssssecssssssecesescssstsnsacacsessevevsnsesessuscsreceseseeraccees 5-6 
DEL WINGOW POSITION #.5<cc4;sses..ecerctseavagycaeeda eventos cattecsssnestucacestadisicedeee oe Ue RSs 5-7 
PLOGESS ct KEV NSS 5s ctawcyessvaaseatosoc enstnesctienasseveradSonciee tes videeeactnsceikan set eaten Mes 5-7 
Deferred WIN methods 3..s..cissssececcdecnsnecsestuesasaccssazehalted hiss cavsdegliessdiseaiattelielsaagn SRR a 5-7 
Wnt al SOs. 2o esos esas tse cs cevesscesssestssasnshsietsivcasedswiaiahvcases cucesdévasecsoasiSobeedscte eae neem cars 5-7 
SEC LOD EMMY tos deistascansstannstarstdiee stcsitusatsSeestonde'ssueaiacceetecdbaydercetuesiMea cate ee ee Sine met 5-8 
SENSE; PIOPCMty, (07. haa sees stevenivteatssoestasduceacivevsents ahs catstatadlcciin secintartie Ni Uertecrcens MRE one 5-8 
Draw. to'existing: GG. 0.22. Siessiesiceiatasscid desstltectacdeceecsdestisaanvocatieess ds everett cee ote 5-8 
The BWIN bordered window Class ..........:.sssssssesssssssesseesesssessensescsssesssssscsvsesavsentcetarevaceasees 5-9 
Class denim ition: 33.ctsveaseliissavti tees devtestaliedledvavdecdesstaiicth dohestinsessvasua eee ee es 5-9 
ETOP OLY sscd 23 tates ices veatecciveaceelonsat slau tida,hsansaeteaaavcthsarsats lattaten saat ease Resa dee antaess een ee 5-9 
BWIN Methods 3: 2 oo. cccvsicsscashaesd ati cactssenssdeasdaisrevabvatstouscten ca saassostobiva Bias terse ete 5-9 
Draw, DOrder “ack siste. cs aatete caressa tatiaatic ncnnee ete ee tine eae Se 5-9 
Update: Border. iiss eccccstssvcscevsiextces athesstseaithasiatien as Moiese teste sevises sees aoe ee ea es 5-10 
The LODGER Class =. ivccecsessvisssdtvioge She ineaslgiua cae sethesasedan act Bisa hai hori ae ee ede 5-10 
Class, definitions. fc. cass scststscteatiactc cues Cangdescaase Shovassaesssacaesicssisdater asian so ctiea aces hate 5-11 
PROPOMty sce tsi desis ccssetbscststanehseadicssasedecednsivigegs soetatttevstesssvasiveates cecievedeor devenees ee toes 5-1] 
LODGER: methods 'szs..:.2scsasesiecdivet.oaeesincces teat eesutiaadaasdi eaatdasn. deteezaull tecestatadecdnee eee as 5-12 
Trnttral ise sesssc.sshocats si sesetesesssunisietcepscactvt vada iteadstcdeavesstevee chante asshast «sistas wees teem dere ae 5-12 
DICSEROY: 522 Sen cStesaa sess cite bbutaSesanhedacvasvossascsic peas belecataka giet Soca vucatasducabacvas os deueaTesrgesttes ae 5-12 
SOU VISIDENIEY Sosscea ccvsvhocavsdovsteycavetaceet cnqucauesenes v14cteadiius Sencttsdusissseatcstessdieebiemin siete uate ah 5-12 
Greate: and Craw 'vicaisclesssescessicecctschasaievs seseiehiss nics scarei peace. destatssesnesstssiuerestaslasessedeueaeso 5-12 
CHECK’COMPSNE IS Valid Ty crstacsitecetetcnctnecsccsstaceacittseteeinitrenneannsinicscmeeie: 5-13 
Deferred LODGER methods ............cccsessssssessssssesssessseessssseassossvscsverscsssssassanecevsnesceesenenseeaeas 5-13 
Sensé required widths. tscyss.cciss4caiesdesratenssdasant on taerstaieeiat dle descaspeaveleteve ee eet en. 5-13 
Uh ate SUNS hayes cxcati rsa dovasaw caapiloun toca svzetetaradatbacsonessasantineticaredaseMebe tesa Gok ere 5-13 
6 List Boxes amd MeMus...........csssscssssssscssssescesssssesosassncsssssesacesorecssasaceocecsenscscsssrssesssseesrscacacasseenssease 6-1 
PI CCUISOMS 5 0c. Mice tiSss Siesvasdsstebaxbestistepetvadinectessdeesactasccctsahaasisnn giaabuabieathasavavtdee alent sees 6-1 
TeASt DONES 32325csech csc tdeyeh ovabevsiessecetcesveeredouteidaciestdsavcsessuctasbog. sie tatvstastahiscnicvoveralontee eID 6-2 
Class. deri ttionie sis c.cocis. caste neeiew Gtiiaaes verso de Teaadeceesezsdaeeb eile once dentro ratarc Meera: 6-3 
PROPOIUY 550s csss tecoveds cance vss oeteasvavauannesbewsteus caratevashden uideagtaasetneatcaesslabigcdelens eateste ts eoeiaeee 6-4 
TENSE DOME TAGES cocci: Mcatsssacyassasuits cach waceeh oeqaty ase cavc ua nanan eendiaslaeuatd ucstusastaiquamoen meietee as 6-5 
LISTBOXemethods:cciciSiswennelncianevncaiwagn et ea he EN 6-6 
Die@StrOyeicsitescstisegeriatiaivelescead Geseibtaibuschaaniscsargsuiesisdei iin aiatt creo eee ease aoa acne 6-6 
Tritt eal ISO 3 oo5 tts oi stra acacia Seo, das esha toueatavnsovoze tata ue cola) Ghiseaotitel aie, heat ke AAI, 6-6 
Handle:key inputisii.5.fesie.tescsaseveltt ssiatassueataQiaatvacisieteinnisiaeions cade icaaeeteo ee. 6-7 
DAW Ris 58 2he Becetsiarsattsessesaedevdvranattescra. ate, olvrenentvieas arse ceetiousaeutianesleast cearta, meee Raat, 6-8 
SOP EMPNASIS ssc. c.53 soschovestensssesuatas tececal asus ssads cece sasaaens derassoisehethoehacacv eaaiveesnaihcseabe oe 6-8 
Set the window size and position ...........cccsscssssssessesseseseseseseeescessssssesseesscsecessnsssssvesseeere 6-9 
DOrAW AN CCI Niesere ttre nsttettes rekcte = eceetasttftcc trader actos esse acelin oat era een ee 6-9 
Logeleremphasis:for antitem y -ii:scascvhsaccstaveesiie Sivetsractiic eee in eas 6-10 
Sense required width for an item ..0...0..e.ceeescssssessssessssssesssssncscssseseseecassescensssususssssnanes 6-10 


iti 


Sense, thesitem with fOCus 2. c-fos: sSesssirshetesSescscsadsesesasescvedsesatonsveuscanehev vette aa cks 6-10 
Get pointerto tem itext o.:, ccec.csisssstacesveststeetsdsseeisdes saris cssvoluseecetesuas eee i eek 6-10 
GEC IIGEXGON last (emis 22h h ceiynenurisaiadtrinanctuesh oh Wed PAD auscnidudh expan ogee 6-11 
PTC SIVN IAN PRAY ss da ss 2h aah avs csahalisacete nda bonacueseossasceat di csbeannead lps aguns als RANMA ec access 6-11 
Class CePINitiOM fesse. cds sssscoscescosansescunstavaes de. ensvsestocnuscocteatse st sesediesestasstonsba ge Peo cscs 6-12 
IPPOPCLLY esa. daten Sone cates vecuseussiarssscepey Sissies beatsnive oldie than ashetscdsssteeses vtssbecceto te eee ALES 6-13 
MENUBAR metnods:.¢. ciiccncusouvisnateng hagaatacadunts. ohase sb danathadnie eee 6-13 
Displaying. pull-down men « ..;..d..c5tcsstecu ces donsziedy-ase.yonasdsiNvhatbotesoedans npagntstetaees asc 6-13 
DCS OY i sets csiecsts uae tones iueses tus scvsxansssbee teaeseesiBier trees We Nobel See, Te a nam acd 6-14 
TPIREI ISG. © Fosse sas sco hada gt acura: eds acaiedanesnte Mea tas tinsh punt ness Dery me ene aN ER nen i: 6-14 
SOE: VISIDUN EY cfc: c sieste cs couse cvsszetesscks sted haters ticsiacaT OR arn Med eee ars 6-14 
Draw Fi ei cca asceutcns se tuacuene ih boy ids bth ond vandy sa avue es ad cSeeeth cote clceseSoe tras Tc! 6-15 
Handle Key sanput ss. s..ecceesenceesonssseceschesvescavaea Rass hestenccagites freee eek es EN we 6-15 
ACC ay MOM cc.c,-cassessnsnevensecvevnsvsdhsdecoaastansrvesceSeitea aceeves ocean eer aes Mee A 6-16 
PULLDOWN pull-down menu ou... .esesecsesssssesesssssscsessssssesenesessssrenessssssserecsessescsececuceesenes 6-16 
Class:definition.:.c0s25- PRs Ss cove, Aono eeacteieetatastencsrstesai ites oecsss estes crete eaten tee 6-17 
PLOPOIty M52 srscice Sedvectes ces sbe evens Des ecnedy eer ta seit scea hove castovasteiseac ott aetibores cle nee seins 6-17 
PUEE DOWN: methOds 225004. ie2t cateactescnstesteensiieilesiosclescicevsrertee ote: taameasecersrertee 6-17 
landlé Key input <i iectstss eect h casas do vsosbsiettevadicosteucewares hrs etn iaitesetean aaa otewtocaeaceodl 6-17 
Draw am item 5.35 e.cceosaneteuveualoae hake Gildacaseee ed ouiai siete et adaantacevedeoieediuerser sessoene cit vinic: 6-17 
SOL MSMR DIA SIS ict ¥osistpacscossietiaate tetera eicaett aihhaeve tia ata ne tee ewe 6-18 
SENSE PEQUITe Width for: at 1M. eco.tt-asctecaf cade tvaneveakvcwccstabadsstveiee asciabsuesacusdee awe 6-18 
XPULLDWN pull-down Menu ..........c.eccsscsscsceessssessssssssesssscaserscsssseeesesssusssessnssosssssereceserecnes 6-18 
OZTASS “Me RUMEN seas 5s ibaa ces Sainss pgenys agen beedSnes onto usvoncac as avsseoes ekeea bus stat eoandeeyern epagitecte 6-19 
PROPGDty satetsscscrsceesserstetessaetteraisciatariaisiesiestarsassiitcettes cose ai shit ine easton oeeeeeerememearits 6-19 
APULLDWNemethods wi. 2oscc0.. cides. cee RR 6-19 
Connect to the window Server... .ssssescssssesssssscsssesssesesessesersecsecsssssscessssessssassseeseneess 6-19 
DTW cass otetie coed ove sigobcvbecbudesaasdvsdssasetbsaccastateatiaansteleietexsniaubcatuviodveestvsstevasetasiv ince acs 6-19 
Settem emphasis. as: .2sc 001 ee acca betivea tee cesess se vescaced anshosstagsotessces ssteaieeOoee teedns  e 6-19 
MIBNUSIA Bites Sis, ri cusettes oa ae Nae oo ae tote, tied en RS hb hd i ofl ee ae 6-20 
Class Ge finiti on. 5.0.5. eee eiel as ewe cees décaestaathcnscatet test lasciStakse th ees oaot eee ane 6-20 
PIOPEMEY: ssc cvccsesshsougs causcosaseasedsavsnthosid’ce Sa dgunutnedéscarasdeveseoscdedsucbecboteisve tboceearwidll ere 6-20 
MENU PAB methods :.s.90u, Fatih eeccl Se ceecetatacs hi teidve uestdezncdeliehsesterersoeusealainaey Beate 6-20 
PAMAGN ADS ess Pavesi se xcs peated eased ovina de tute ae don a unlacest uae atu tart es 1, Sate hts 6-20 
DAW PES esi apensnsth Sees Secs Sescseeteaieda hs lilecsaes sc 5 shee tne Tec dcsavans dh stan aot aae wlan eke 6-20 
1 MNANOB: BOXES aes cs nsesasnazcayas sazdsvessgussccassoemeanuoidustssckauaassavastssisessess ova tgscvoemoaroeoret oct eneuasam ea eesed oan 7-1 
PRECUISONS 3 ctosssec¥ octsesevcouececaiceeNedeaeaaudasssiselaeiedicenidetosessseueecoriot olveniovenieces tts Stes 7-1 
CUS S CLA AAD  saece sans a asin soateaegeact taba tos cto neat cee meses Teas aecada asain wee cetera: 7-1 
DEG CHAIN 6 aiicesciieten Hass aeons at iailel alec ha leseinied ane Wi aac seen 7-2 
(Class CORIO .. asec -sutte ice ticpe iol vasece testes Ctoctic sas. us nssnoco ashy mee aiuto teens 7-2 
PROPErt ysis, s,ietectcda ese tsanctesesetesccetueetuecuuedataivtntres tect tiene foe Seseeieds Sec ovsincsavavsiiorseadnntutoncs 7-2 
POG FASTIN BLAS ails ctacissetties sechaatpnu ds caesdsdetaelhtas Gaabesscabsaa es sas tebrea tial asda el eee we saaseose 7-2 
DEGBOX 550s soca cbicabien set Bieabea athlete sess eae GL EB eat toca ssiuctecade So sesbeann nena oh ooo 7-3 
CASS eT n ith OMe a esccesest ofan teciev ecg devansic dos doce seued seskcecsteeeb on Suestodbodecqatacdeonevsotastevnedes evel 7-4 
PPROPGIOY ost isscsee ectanesossset sans ctisses cep sasesexidecra cesta easaccst cases ieas tees sttanr ase Mucosa eta 7-7 
DEGBOX fags acs 208s ecccuceseiliisectiaeseensctadsavbsccelasotasslatasdevcsuricesatbeaunioe ines 7-8 
Small font dialogs for the Workabout.............cecesscssssssssessssessessseseseesssscscsesesucarscsssseenens 7-9 
DL GBOX TUE Mi. Bap a5. scuaxtsz 9 Sosa eartuebashciaiwasacumsben besoin seaseasttiadsian sans eieateontiaes 7-9 
DEGBOX. methods... fscsiasa atin eieeattaei ds lis isa Ba eestaatersspea dase asada honed 7-10 
GomsistenGy CHECKS ‘ssssccca.cc2ecdesdesseavceacccscehcrovscavedei costsuctvaeeee ib dented tose. catia coedeeoeeds 7-10 
MT Gra Ses ists ote ta ces see te ra Nate yeety trae vessasg dilcaxtas dhs SoM cele. cops tasscibip senusantae ewerers nee 7-11 
DOStHOY *oossssheseccursssssseused haskl A retibuaes aieetinl acd boleriicecadtioses i eveduntoaeseaiteicastin Greet ccbasaereve: 7-11 
AGO POT iscsi ek Sekt oer absat aude cei: eee ea nee ae aor 7-12 
Add an item: by TéSOurce ID ......cscs.csssctesascveussesacosetssucveuavesscedeicessadiaibatelaveoceshecsoucuescuees 7-13 
PRE DIACE AN CxISTUAP ECT 2. 2.522, dace soeesatnsnaha rebate cisu last ctese vc eaaco eure Mantes mee le 7-13 


A 


Et MEM DY INGOKS .2.cPaicsstetears tua cetan Roscaaousouil weneciatiianuuaeie ee ORE 7-14 


Change the prompt Toran -Ttenivs.: 22.050 sdsaessauxasissnccassssosioervandvusecoteau Mus eee See as deae 7-14 
SEriS CHEM DY IMI ON too acssh hscsanetevwreecenteg addin sake ietiaasedystodinaaue at amet iedate oe 7-14 
WP are EY DT crass case. tesco neck acta cng hve dinsol eb acs hea an dagida esate tra testis vateda ham cede hina 7-15 
PAA e rl ey Aa alors asa crters trvcecescatscaanveasvabets <coukasdeesau tuivonnd dtaceeiWaenas eon eeteiocee bac ecte: 7-16 
Move Tacus:t6 specihed Aten 0.0. .c05 ct .50.0fercae-sgansaneavsuszavverances ss cssdoverissaveseavidhaanivansaneeae 7-17 
Draw wholedialog etc ified sc ccecvasedecetcealt Tesdestavscsasdovevtisseigeesceesntsiosauiteusecse asiee 7-17 
SetsizeOr- dialog eek; sv cecctivevcacsssrthiecsiuet orstastoueen eee aetna ricd. Lech ea 7-18 
MAG ANA MUG DM aceasta oats tes sac evn enssdepeamnsnstssansesnes ls didad nd ia dee 7-19 
ASOCK aM Meri ee syste cette esas & You vbaai tr bcecth Savin sein tock ieee ae ITER Roe toccs 7-19 
Display dirmim Ed Message 6 ok, Nios a yavgevaseds ages eels os Ouse sncueowranca armada eds. 7-19 
SeMSe stem INAS Xe eee, aces ae azee Syn basdeteteteccasdca Scr Svcs plasesdSovigesteuees ged Geena R en os 7-19 
SEMIS HEIN I AIM CS a sacastace sags oaad ovsvaie se igsnse dvveg eh td Meuse caaowt nvccdbo ners uedacdy nec ymtec secede thcs 7-20 
Del emitla sy veh u/., eaten eae ema cae acs ths an emer 7-20 
Sense'start 1D: for He lpise. cs) svecteta.i5.: licscss cries does (decteve caveveovorusacsse/ dies eterncecccsestee auc stactueses 7-20 
Set Cale Hox eras Seg. cM sashes a: asc vo esa cccaye eal ceaaesedessesscavcsesee essat enccsvedapavessetaasseadete 7-20 
SPectby min UMUMD- WIGS 5. essere 5 onc vied ew ocsceccoaavasuersuaveederseaiudesutieeeosstien acon ceceeelew: 7-20 
Dyyriaing (Can trai Satl ones eta. ess deasnccatgaisesatreen aoe naskaneedevesvlubetarde rac styedvectien aaem eens 7-21 
Deferred DEGBOX methods) .:.j<cscssarceois sasessbivavsccaves nies eon SM eae oe Ne 7-21 
Wtetichaneed messages, sic: cacsiacts, caaptoloxcovarexausisaenychecssstieave Daten OTM cece 7-21 
POCUS Changed Message .cssvssantnnscschsdodasesasn stems snsascasnscviosnsaseuiassloasto hha Mie eee 7-21 
Wauinel SUB-dialoe 1f Te qUined a2) os. 05.2) <edeccanecsviiatia oo aces desss cn eet austiareibhearaveete oe 7-21 
Create non-system dialog item oo... ecessesssssssssecssnsessesesssssssssesscsesvecssscecassecesecensssseees 7-22 
AST SDEA Dears: Gos sucka oon ovetss sonsbvciyesouss gevvpbee uaaesssdlovasdeathsiassiss iss cathe dicted ere 7-22 
Cass Ae Fin ith on zins iawscieescsstest iss gue devas acataeuedstecsenndevasesovactadsvigois sdioudesediauanl beaches 7-23 
VOOPIG TY std seta cet cu dour crt eashivoasetsiapest ges ces ts Mose sana data Souwttadacarcin Vercors ease cousartichad 7-23 
AT SIDIA lomethodsotasseattata maces tome ee ee 7-24 
DOS TOY 2. 2yivessiadewesisedea vost settoader thus selec iStstodl sie mectisseeatealisiadia leet tian edi cdesdsoscuse ied eosaiela 7-24 
AOUMMIEM ecstatic none mate eicAt ee te ari eee 7-24 
Dynamic initialisation svez. scccicestvqnrvedssseccnesesastcs cot cactvovdtets sed psuSoaeeteesevsdesuassese sestonk 7-24 
Handle keysmputs, 2.cteot.tcsec0. aitsapads cast ivasevatieeensiitscgessdicessesuesesueecce evils aacasoea ees 7-25 

8 Labels, Buttons and Choice Lists .........sscscscssssssosssssssssssasseesescesosevesesesssesssrasatassesesezacssareresssoesenere 8-1 

PLO CUIS OTS iss 36035, ess evauctsestuies saa etn ctbnddtenseatdessedngas taccastiOlcdics teeaca asec 8-1 

CCAS Ge NN ica toss och aa dase veons laa iodvecananraivastacsceigtecla MORRO A, atm RL Oe se 8-1 

TGS TW UN Chas. he Secs e tec hcreneian sein ccpsraasoatea raed babs case ROE Waeitiadd ewe aria ciaubcerssee eens 8-2 

Class enn ccstasstt cs, sanlicndcaps gaasituttiesgedeucstats chine dof iserinnareveaeritae aot dete 8-3 

EOI TY ns ces eaccs hil cash dna dics acenedaus ol audvanti Gian dertanenans acldrdeheociap hu emiriteibeeenent 8-4 

TEX DI WIN Bags coca of esvsnteteeaulasdecpeasetacanieds Peewans destavtads Deddsevecattaestavtssobian beeen eeeot 8-4 

SPE TWIN TECH OS 2 3253s2cc.5seasdesttazieatusnetetelaanth albasazscesneletceaseseioisnasect oaterteesateae aes 8-5 

MIMO ASG tet ten upset uartatanrecscen gana taceunat east a taaaanesdenan cas aban chataedmaots gepbavedie oecteaaes 8-5 

Dr awilext.c,dcaries.ciovssseinist es coestesh oysttaalesav ovens toeaeedeceipestanlasentee cactoartr weedeat 8-5 

Set Property’ sites. de. chic beissasehiies canst nam arcane ates aenette cee See ea 8-5 

SEIS MERE cco denise tansgnatutea td sd dur bea tanrghovbdeesSosuaededs dee es 15 dedeawegeedavnabestan et een 8-6 

Handle ikey:ipilt .2,.cccesssccithovevsesasdsiveasastessaasiesstinacsisvevaareye athe ee ens. 8-6 

Return required control Width 0.0... csesesssecesessececseseseescsessssssssscsescsvevsesececsseessasacnes 8-7 

EM phasise «32623. Seet shstsdivi te basaace ans ceteons deareavadss lente odstasgeses ecsesubeediaiea otied cat bea eee 8-7 

THE SMA CIIST Clase siccct.ccasavsssapoaced <ligayovsas otal avoohpanmtsvemsare, treats dicerstaetenieM eerie 8-7 

Glass Ce RnitiOM, Bivsnss clear a mad eet tat cy eo le, cae ay AsO ee 8-9 

PrOPEICY. 2-3 5.28:02s cucu schists shasta ctyeteathete catesvesteaded aio one Matte Aha EON, LE ce 8-9 
SMACHIST methods, ioc iicss.d.2.dossidicttaiecsstiait eset bbotsreessbeds Sates ne aereettacen he 8-10 
OSCR OY Fs 3555 seetienyesie? os sonarebabltete devon asta etvtscene basasceteat todetdisesteesosdide iets Ue 8-10 
Dnt fas 2 Pea cytes cae tenes td nentudteaenaslavatinaasianessins eat elaad ater eo ees 8-10 
Handle: keysmput'sesis.jcscsd! Yicausuvt aa diaceiensters So tabictetlssesushis Suaweisveaselohsees Teens 8-11 
Dra Wie, ae b 8 sd7, Sisk atta Taide ics astensvedhbeanubiet eet PONG Mette arate ee 8-11 
SENSE ates. ssc Sescastsscwsascaelevestisrvenscsves de ecteaniaaude ss sssssitesienueiossctescete de emens bin Re 8-11 
Set id, width and button positions ..0.0.......ccccssssssessessesesssssersesesssscecscssesececscersesensstsessass 8-11 
SENSE TEQUITED: WACK s. casscscnsseacennspsensake casconserrvetnasnacaansaisatiiauidinvicransan cleaves orks 8-12 


Class CE fiN iti OM cies. ssscceSseveaderecatecanivsuaccbersiecsdececctees ROR ee Na 8-14 
POEL cect nbs sii at ccs acs alespn duu dv asiteuls devon totus adeasdesd tcaadielan ame ee Re eee ess 8-14 
ACES Timethods ooesctectestceSeccces assez cressttesaesetoceid ts cceacalestusen ee evs. Sameer 8-15 
Tnitialise ees. ees eee ccioeilecdtas cde oii ceca he ae code te a RN ee te 8-15 
|B) Fh eaves AOI EE A re OR ae ee iar ME I bts SP fy DO Soe 8-15 
SCNSE HE que WIE ro c8 3 ucts ction aes tae teateueuse aut nectasa Nore nasene ear seat ee nla ht 8-15 
Phe: CHETS Ti class r.ticssscctsvtesyacccesteas ees Best to ec 8-16 
Class definition: 225.200 cesatsh aitasraeteeeee cee Oa ee Ree Pee te eM aha ns 8-18 
POP CUE Y cos seats nasshin a tckban Yatetsaswslan did aelasecusak ee eas Me ee eR eee Mee ema 8-18 
PUTS Tea oa ticcrsnnsl costes enctunusaaylavecatiadeeuisehiacocctevciss) WERE da, 8-19 
CHETS Tometh ods 2. c5<-sacsaets dessus aveesiietoestsok stese. Tarsabivee chester teste ei ow Bee 8-19 
MOST OY. sratsrnes ca ccunisnacvsactsatoxissacedeeasdo vat csericativearckilarc thy, amr ehen eee Mera tints 28 8-19 
Tmtialise ss... Sree oec see as rcacs as gevedevstodi sigeccuss stpuidiscandocsscccizys eae ee ss RN od 8-19 
Handle: key, input srs :s.ti.ciscciseecvugetsesacsastecadtestscssesa steadied so BOM Sheers sak tess aE chess 8-19 
|B £4 debe pre peers oe peri eee eet oan TT ry este Pe A Te SPIER 2, Ak’ ccna ca eee 8-20 
Set current item and/or data ............cccsscssssssesscccssccsssesccscesccsessessensessescsccscesscsessessesscsasees 8-21 
Sense data and selected item ..............c.ccccssssssssecscssssserccnscecesececesesesecstcscsacsseassestvsareveseass 8-2] 
SENSE TEU eT WIE 52 ss ceevs cana sct cans dius tacecassesacetupusenawsside Mander AE ee oe ct eceial 8-21 
SOU CMIPH ASS tsi ccictstecsacsssicdese costae vi uvitarteileosstiare <Aelsectxtuel A spate mete oc OM ci can ays dt 8-21 
The NCHLIST numeric choice list class ............ccccsscscccssscccssccescscescsscssssesssessescesvsscesesecsscees 8-22 
Class CEFN It OM 25! sscsetsscsc acaahscassseatezevesvasdeesblvs lack ovstectsentailioie soa bbe vc deba lin cs Bedlouen besos 8-22 
PLOPOMby 025: ceases cvesds ssstosasseaceeusisunervatossativeabel ohc aan dade eel tesenans eoehiation ce geichne Pea 8-22 
NCHLIST methods ies 5..20. 535. cacdiscsssvesteatvsdbavcodsussvasssiedasenscttaneaieeeadlatiaicivstiasadeotetuvawve SEaads 8-22 
Set current item and/or maximum value ..........ccc cc ccssssscecccescecsesesccsessessessessensesssevencess 8-23 
Sensesselectedtitent vient seectacnaniletacte ii ee ee 8-23 
‘The:V ARES -resource array-Class asiiecnninartiese nanerotrreeeree 8-23 
ClaSS! GET IMItIOM og ocos cess de cscesandteesvsescitzaues sabes taapiccieate Reovsselian oiucsee Paes ciate eee 8-24 
PERO CTU at sesso ssacstenerestecunivesavis Docu cusosedlaiode gases accieaaea vise Meh eines Mice isan ealiaa eh 8-24 
WARES Oth ods st. o2. es FexcecPe chive cei cetecsesteiieote ace sisen tests vlaidcddeta si Abel ot Aatis Tle fovea oseeeacee te 8-24 
COD TOC ORG om sist cies a eerates aera ea acne ascents sauce ane Panels oicaateatelathege aaa 8-24 
Getrecord Teme. cscs. .t3.453s oc vheiwratsceisedessoessh tslicecentcstvesderss arte dos ae es Meee 8-24 
Unita iSO or tciexe cts Societe tease a Et hen eter tee arts San a kts cues, ete 2 2 SMM 8-24 
Delete sequence Of records ssa. 5 cscxsscce viv caceecanngecdecdavnienevadssacsnssleaniecss Medea giv teans 8-24 
InSert: SEQUENCE: OT RECON S ios Sasso svat avesizeaavcenspassi ros toasts OiRepsases gesinadsetevcapsanonnevenedd 8-25 
POUL TOME CONG 5595.52. 288s Acs csathsdadhces cvacecbetucesctoceccceleiassdet ecco toh stesoe asics 8-25 
Point:to:record data ts. scscissicsstcitescctevessatctva couistacdeeen tee lk tii ceascoeestecess eset sede oan cctss 8-25 
gS) 0 1 |) 0 21a TE rep PERRIER ETO? 8-25 
The VANUMBER numeric array Clas ..........cssssessscsecsescssesesscsessessssssassessesvsssacseeseseeseeaceeeees 8-26 
CG FETE (5) 1 (0) We Pe 8-26 
BO DEIEY Mattel at coronene a0 watasada vis seen isuadesevcasene lees otesauccesalhgecisteckaa ta tionieavetange ose 8-26 
MANUMBER: meth odSiv. sisccxs ceccvecessvisvsaxdegeas cedevc cla Segeste ee wean S5tatsotds ces WASP ed we ces 8-26 
DESTROY ch von chs nse Rot lode cco ates ex Soat wagd cal aan Paces aaaey edateaa a peop aaa bes aanemeee 8-26 
Point to record dataycivsisszts 2a scoccsttetad zoe adex caccdvataxonscactetatia ties! sewers ove es 8-27 
SELMAXIMUM Valle sss csccccésscssseMeess daces cytes case ava ehedin Me Mbesacesi AO ws Me eiee 8-27 
OUNUMEPIC EGitONS.. .aiécc.vsacecscecastonssessceosecsuacsccbacaeiossdosses oastuiessoeasicucusisavuvdenccnsecoisGiaceom ageecticaziom Lavscas 9-] 
PE CUPS OTS, ct sesssest Ss cic shes Soects webs bois cases asvectat ee Soave toaaneeaa iets ice ie ieee 9-1 
CVSS ASP eee Santen Sadist cant ants cbiaoasdawsuedtneuirn ceca as aicnctettatinelesraetelasaaa tak 9-1 
IPE NE ics ai h08 2206, boa, coz ares ca beveussteasaasaeuciuee eu cd ts aa ast at oan OT 8 a ent 9-2 
CE) FTaK () 01 01 0 (6) 0 Enna eo 9-2 
PRO DMEY sts en siderosis ct usc ase Sicha gas dara, tos calou eeayutieatie bala aes aia eal meal wisn Tama 9-3 
MENE methods: ser, iisisiee cies Od st cageneccsrowss see etviescatesabieasveinn a dbsadidosedl eed ete eesti 9-5 
PLAN Ge REY: PCS cei 3s ii caas As dance cceaats coarse oun sdescedeearssearcersneasioowea avant ew 9-5 
Draw CUIEMT STEIN Gs sc staodarinsreeee cust pocndeasl eee oe reste Me et gee 9-6 
RSTSL Ce Ry i es Se rane eee 9-6 
ETON S IGE Cas siaerecc tua as ts tesserae west pengu dein agus acs seandnccag tele tssuinte named eects 9-6 


vi 


Validate;the:current:num ber.cv-03..0 000 scistsediness heeietes ss ocedbcacseidts st eR 9-6 
Show range information message .............ccsssscssssscsssscscesescesesessesesssssssssesossesesesosenececeeees 9-7 
WIPE SUDClass EXSUNplESs. -caasyycsdtaacanuctsarecasst avert saemssgo trauees cesar hati ure meee ol neteel ees 9-8 
AnDASIC SUDCIASS Mere ctaycscst celta craks sei orrisssssactertvedee Neeser ome itech Ae a ee 9-8 
Extended range date editor Control 00.0.0... .scssesesesssessesssssssssccscsscsssrscecerersessesecsesesessseses 9-9 
TEN GE DID S200 vs sce saves vevezeissadvecaszeccosdntoote aoe ceric RUA te Macon, Oa eet OT 9-13 
Class: definitions: steve thsec2888 cesccsc.cesctcstessencsget dS aaici PA casein cl cleo OO 9-14 
COBOL cxareccteesc es tattoos ocssy) eaueh oeisscsscPesaune BUrasdec ousnnsiudebnetave cue rename 9-14 
LNCEDIT-methods:h..:. aiid eee eect ae Le Se ee 9-14 
Initialise: eq itor ic: 2.61. scecchiessasstct edi Glas sfesd hee geastviee Bn Oe 9-14 
Set Gata hte latcdnecestvecasler testes cicada. Goer tana: se RU 9-15 
SENSCEVALUCS -cissct is covevszvonsnaceccsvengobeecsoncuineneusbeuca Stud tear copes Se tre 9-15 
INGE DIT eos, corres gosta sts caeaeasigescodesaiSestels accept baste aec casts (addres cabs ati ek nce al 9-16 
GC] aSS GOL itaom oss sis oie cces fan cetgteasesSsticnc teovssdresidulastes Paves eit, Shs ocledst Mec Mem am 9-17 
PLO PEREY 2238506: c9 crt Seadbs edasonsttcestlacenzaes lous cancestadse eee actos ase eimai 9-17 
INCEDI Timethods ts: ccc.21:ideemostisediaciete dt Sa aie ee 9-17 
ANitialise’s, sic: csascnie avs ceeeatietiec ite eet ie ee 9-17 
SEUNEW:VAlUES 3s. gescese avez osiedvecteatssatectedkosdthscvves ete 9-18 
Sense New: Values: as.t2ccie As Gadscs cddcioas ovelevess scene ee ee Ee 9-18 
IWINGCE DID ooccccactescatsensetistiastavesevevcsec si tslecdl-asculers acta tuesevadeie ie os acti RE a ee 9-19 
GE VaSS\ eT TIOM sa ciednac5s csi Reksecscs cass ee beis i wcavcduadiad epose pate syle Dts Ee Pee oa 9-20 
PUOPEUEY 20305 s0353 casos tanmuntevasuidedesecehepecadind Moussa teincbiciGs manned ne tem a am) 9-20 
WNCEDITimethdss-secisiit ii chs asvtinanichen Gen hen BU ee 9-20 
Mita liS@ tesssteracssce ccc seasasaeseescvacaecagvusacassscsn ies esladde One ee See EE cots 9-20 
SERMEW ValUES a 2iceiciiteet acee eh eticocgce acest elie hance Mee ca ads ote Pe os. 9-21 
SENSE NEWaValUle sc Heiiesen eisai ede Mect te ntocn iodo , ee, OCT 9-21 
DV EDU riccha sete tos Sesthes SOG Geiss adeseuciceoce acid aod ee eee Np BAM Les 9-22 
CLASS TACLIN GION sarc. 2 cee eevee sssatadeacdasxpeeuss bats eb lore ecle teed Set shecnee ice be IN 9-24 
PODER EY ys crores statues teas hes acai astatgnaiademedopeateeccesseea tetant es eu udearoe a cats cs hae Aa eo 9-25 
DIEDID: methods 2e2iiiet 135 ci55 fos at ocsctvccuse dele susedassea ee aN oe aa 9-25 
Wnitialisetjssc8 aves Ait tin ia, oO ken erm eid Mr ee oO Men» 9-25 
DEE MEW ValUCS 550 ce85.c23 sis dec Seadosths dees ieseveddibts oka athasabats oie Meets cites 9-26 
DENSE. VAIUC Pessecciei i ctles tea Saas oat eetcages te eos eabin Go tacesldai ie hee ee ee 9-26 
Flanidleva REV Press si cinsecscivacs ssevesssiecgeansivaagnaniviaPacstvasgvivantonaetiuuinvdne tence eee 9-27 
BETA ASISE acces ates isden cose tee td alguns stares aden icastie Rhara iia ule as Se gn AIT AM 9-27 
Validate values and fields .........c.cccssccsscsccsssectscessscscsecscsesssecesssssesesscssesseceecesccececceceee 9-27 
LEED UD 3:isce2recsansseizs citi viaSbhets tov tavdvatl aseeiba nial hele uck te scedd pouch cceec Be, ace 9-28 
Class definition ess: s2iih2ce.2;ccerctstonssticsccdeuneetteteatwhowen sare eee Acer hen BO 9-29 
PROPER Oss oe cctestdrn. cuneate: Saaracaase aectvnntetdasdey Adastueiag cts data leaseahes cad teu sdebeea tosis 9-30 
LE EDIT methods 9:2). ccs.csccasssctcosse lh sssd od essacsei nase ehioeics ak ieee hes Nossa ach etdacaii Tuite on 9-30 
[mnt abies sces tu ctih sos sas cesbect esdscaesdacitvcssesbececsestsnddebieexatvathsosio lace AAG ccks cchncatmats aRe 9-30 
DEL NEW Valles scsi seciiesteseesscags Mizcssazatestgssel stones toda es Serbo eeskdseees toettoe tye eel bee 9-30 
Sense Current Value. cio. csseiccsosccinees eels cassethceans de madasvessaceabedeesseeciede ee ee 9-31 
PRG DID soso ct scrsctes etc s5 cs Set a vanda tea caucus eet a dead cat desea oo enced ie ea ie ER ete! 9-31 
Class Cerin ition. .eecsccecsvacdesvesasdoccss side fucaS Secs beau operates elec oad yt NE Pe 9-32 
BPD cass sstc crus vidioutcavcsasualacacs sc vault tasucen ain tune a etwvasttncse oreoaua neayeall MLSE eet ose elec 9-33 
RGEDIT. methods ie52s. occ 252, loededadseat Eteacdsdeteton a ie Dek Rete ocactatehete SON es 9-33 
UMIMALISE 22s tects ec heh kai, Sle ted cate et ME 2, tee uit aie ile NS, caf 9-33 
SEt NEW: ValUCS 325.55: 5 5s sects, iia ade sth de 1725, a, Jeu Seto vest atacsts tae eNOS 9-33 
SENSE MEW. VANES 2 Secccscstsccssestazbsiedacscdissdsdecael aucuet daw aveaseeniaeselloveeds ss seactteoeecug tthe nn 9-33 


—_—_—:.: nes ee eee 


BO !TEXt ECU OFS cossces soc ccccconstcctessesssuacasasavsvisticisenssiesoosesnctsccocsscssessusnecsiasesseedlidisasdeasachnn, coe enc seasiacieacs 10-1 
PRECUISOIS 2222. ctet creer ee eet i Pe aay ci 8 Nn a ee en aR ANE Be ae Bee tes 10-1 
S97 LF 23:1 | pe eee fence era er eee Se Wa eee cee 10-1 


Viii 


THE Sit: WHO W 0: 5 sc.vncussnvnndoschserioninsenasncayessavesdoh seca Bet Re RM, eke 10-2 
PERG IMES cissiccsSoudiavcons che nggts asks ssestassbonsneisi dst ade AR eo RE oe 10-2 
ACUNSOT POSTEO sxx sc cess cancasitevecedta tally rac teat sie estat ae en meee ne eee 10-3 
I MCICUTS OR nat ty tN Oe Gee ee nae ci ea ae SUM eee le eee 10-3 
PARI ast Pe i as a SE ater Ae AMM EO Ret ane Pee Ln ee aa Pate i 10-3 
Eg Foe (0111 (5 (0) 1 Ree ond ero RLS Rede hs Stet ate RN 7 ARR ace Aa 10-3 
PROPEICYy 205, c.ntacsduvssccssavinestesusectnavesotvvesyeravenaerdetaiisa Stace Mtbaths ceverethee ie et 10-5 
ED WIN iets 25st Pee L AOE, ocaescest anit rakcstatseds wu via lateeud ai Meevs ten estatttraea eco at: 10-6 
Destroy res sisnti a int SAPNA creat a An stelea tigre oath che oe 10-6 
Create components and imitialise..<acssicccsscbeates aadaeesiabetthas..tlstavcisn SE. ee 10-6 
Pang lesKey tip ut i oac toe. os s2c2 a sang Ob uded ina ltwvuseen Cairn lacks Lessee ee te oe 10-10 
DDPAW VIC Ws 23ca cose. esas ustensdesesniesavesesastbcduacavestteasesstiatseyianidiassestiecaidteenscis eae Nave 10-15 
SCM Se MeN WN eric ta eet cyste cioceast ee rexancsue es neve, heen ougealedasuareatl yaa ore mee ei: 10-15 
CGO Rec tens coches ua etch tote hut aia t cate enacetitlaaas atta, Cltah di scaddunestali di Maceteeecy ee Sisegtn cues 10-15 
SGLISCHLE Xacyertert caps salts atcia ase snatende tye ectan te Gitar alin aren soon ee ec eae es 10-15 
SeMemP Asis ecccctise Masi aias sede weno er ss tevin cedoene tialecaascn tame ee tastes 10-16 
Det window. LD :and position v2, scs,tevalaah Mcayassccteedocenasiascisen dade sal SR ese 10-16 
SCUSE WIG Succ tecsieis eae seracaneisecadcasatasaces te tu sieaitt anihandsengenasaied Be em 10-16 
SEMSE/SCTEEN AMARE SIZE: sus22. 23cs<vccvbesendcaesbiees csi cesescssscscsthabsddod svadcccstesvease cee 10-16 
DEC SCKEEN MALE SIZE: Mata 5. wi, esses necevsteliisasceshsbeces stoieecdcdigeusssublscaridtee eee coc 10-16 
Set Content:and CuUrsOPsscicz-sscsisces tess eanesdacassties.seaiacdistasnsjariedslolalscadrees co en. 10-17 
SENSE CUISGr and SClECE ata 625s dalacecsssusd exsnweundeesBbcssaenelncelsc8s/siedsusecs Boy tererumvinde oe: 10-18 
ATISENG AUSCUT SOW firsts cola Soe trhavstaha ease Rt Me cast riast nt oehaed Measptsssd Ri acae Saami deen 10-19 
Replace select and add: surround. ....:,.ccs.scssecaccicsetcdessnashscosscesocssscovessssescoeqveceoneseedensesz 10-19 
Ol Oh and NMS Spaci G .svrscctasesssiblats ainceninsesentaasacaatal vam anatasealerae meet ee Roe 10-19 
Pave Mamie iissict. ssa oatsonsgesindoas taupe vedo vieasesausittd.pelaissens teeee eee ee aera 10-20 
Search for.text and'show cursOPrss.tec.cacsutitenit scatter 10-20 
Replace Select, .c.tccace. tesbivsesjatevenees bacsgattviatesiaccchsedeiesdofiit-dhsvetineabactatene roan aan vies. 10-20 
Evaluateam expression cc -.eceternte ate nal cee irate ie wearers 10-21 
Copy Select toclipboard: s.<c5.;resasesevsesassckst O50 saci dues vesinsdeilasvasssiiveckedesets iiultesscesaitouteeiaee 10-22 
Paste att: clipboard comtents 2: cis sccsccsnc.-qaseasvansehscnanziiedecs say gusvdosassmsleSaesonslapeRepwiaeeere 10-22 
BRS tRORINY DIL Se ayo cts oidiv hacxcnves oneness: uetttcenccertoutheorcese Mecsas hon ane Ae sea og 10-22 
INSert teXtesir 2. seater yee sceceesd sates aps toe pet edageeiBe ea stiesi ait csvateandaech icatarseonersvondcaa ee ra Me 10-23 
RGRAY KEY plese MAM GUIN B. 3.20) usasets secon incesdeaan wus idedenirederitactssaissustccasteeer Bye mia uae 10-23 
Hab RE y press HANG 8 sc occacciacs seipussess2ssewsasdabuscuiascanidexnvsactionteboretantelisintenieeleean: ssace 10-24 
MEUISCOMNI ZS SEY Lorian dec occa ch ads tual nls den sli tsk ae bade seiuenicesnaesaue ols A deeb 10-24 
Retupin read-only State seca ecessads ezce rage vhupuastunealanuhicssecveyndonsievsesieveuteeeicsaricnaltberntiliau 10-24 
TIN GTI Dy ject bea asi ah epee nia sBae Able tes S ha Doahva nada risen usa cee Eee 10-24 
MCVASS COTM TON 5 sect tei elds aie sone ea OM sce, 10-25 
ASE OB ET EY si iocugshs ies lstc gsc aaa tune Neat Sy Sha Aha MACE autos ea eR AE SO ear yc 10-25 
PUNC TUBB sine tia bs ass as usitoes co 0 es cot aoe aasreteee cam ete eee aM Oe ec 10-25 
Pande key In pit vscasscvcss cscxnssvescoeovsteceesient ti saas RereteneGrnnee atta Meare Pacman. 10-25 
BLD sr cpe ces ascstca Hdandnccens cua cous cnas aussie es annentabtnpdceubcaieenccerd beet nies te oisliaal elu deo 10-26 
Class CELINIHON 5.2009 ici ccecessedeaetassssesdteaaseteatedstesbecit Seaesvdsodtvteo si eae es 10-26 
PPO POM y os sicieanaits aie ota sensei a Sec las cis cn diacetate ba deanna ats Wave Gece ee ee rea vee! 10-27 
PIETER, Mite @as.s.sc88 eter cesta acca ceed tah stiri eet Nas Gilat ene tak fed 10-27 
TSAI TS 2 cestcncacps acces Saude aaa dlacd ess naa eceseet gape esta ulated aN eat Wane ota theces cay weet 10-27 
EE VANES oc alscsauargataatseanbesteca sine eaeasicteyishnianldeacauosaays tienes oalon isiueey ieee ern ee 10-28 
GNSE CUETO E VaINE 5,0. c..5tovses <panstd cde rcesneiel ua uaaseoantahdvehansasiecmernce aetna ees ti eaces 10-28 
Walaa elds ic. essst cass toed asectectst Wceuccactauleain ea ensue cenacmapaenten Gai ise 10-29 
BA) 1) 0 set re er ct rd Re One nC 10-29 
CTASS COM ION rasa as cacti is to ately Ce Nanackam see ial Casas de aud Gags abygilt 10-30 
PrOPerty «<fictisesaiv eves creceusdt caniids atect sctaseubeataneereasteal eau tu aaiahes coe stance Seems 10-30 
AEDIE methods’... s2vt. sc. stucicseshivesatspretiessaenieitbati sad cx. sceth ecxil octet ave eens 10-30 
GGCUTEG MIRE WIN es scacecs ees jes cstaed as peceecsascas outed ea entedeveloniesouciataaetiancac enticed hanya 10-30 
Fianidie Key in pull cacsr teste reats o.tuciast etree ar eaeatrn aie ccttres Mev avssaeinisoossie toine neeaaeete 10-30 
DAW AETE, sstrens Srsseacseeetcsttsves foc r oeas Ses eesarapetustoos otter. or tastier cael iseenas amen Met eee cM 10-31 
SENSE Gata Sirrwecteccresetrtisiecoctcusser reves tered ent ertrenusacn since: tome onseriiecieer nici inet cr tes 10-31 
Clear password data tcc nee eetenrs trees caonsttien on araet es aes 10-31 
Selemplasis te: eres sate eevee te eerste et sania, Ese aE 0 ae, ge 10-31 


MA GAUGE CASS OSs foe cesncnacchcecsiassscetunseosyedbeysarasascioaschosibioesiteuestestedelousat MaseAtacrivisacai eee OE voeeeas 


Precursors 
Class diagram 
ATI GE sea a ations ts sens ned Sc tiapaneseionizusaco nn eealaie tea ocean ee eraan tee cts i 
Class definition 
PYOPOMLY 23.5 fc50c st svecsvseieasssusiasscovestangosrssiebess os botieesie a ee Se A 
GAUGE: methods is: cis. ccacet se cieceectatevottscovavades Saas ativeas ced seis oes watts wdc IN SRN 11-2 
ATES 8 Fee n cocoa soe Seas tata eases ee evtercata naon spor vc tenes vnal ouch WANE etek Re 11-2 
Set Characteristics Of Saugse SECHONS -....se.scsconsaicsrorasvucaduanscssssosdevdsapesandapeblocacduanccecctaseess 11-3 
Return minimum Width for PAUSE 2, scpectcesceverscssdinesosvss2sioacaseactescabsioh ne ¥iagh ce Be solo hos 11-3 
Draw: the) gauge’ 1S ecctiscses Gratster. cc cctsaaniate tiv esencalniaheseacadceneeeh e ice Aeae neanat A 11-3 
DONE WN Ssiticnetslcneni a Mirae ate oct eee 2 eee eee. 11-3 
Class Gehnition ici: cient he eee nes ens MN Oe 11-4 
GO DIEEEY. cattle cy Stayt od sganucns stu brchtucest est thiastatee Os aan deuatack Recwass duseisetuger ne tata raaatel 11-5 
DONEWN. methods:s:seecsene see colmererrcseres eo ce et es art ee ee 11-5 
CHPAUL SS hr Mare te ctetete eter cer mee ceerecisteciet suathestcrestetseiereet seat toitee daiaaee tees ee. 11-5 
MOST NGT AUIS uns cascns cnatecits acai cena deep has eahvpaesndasucaAagl MtcacesavephasctesuvGrysseMtle Me oes. 11-5 
PG AUIGE Class Cx ata ss hice Uecal a cihitaies sath alles ace sege a teaita south coe hbase: 11-5 
ASDONEWN'Class-exaimple es. cti. ta. caagrscustevenccdtiscusssocceioh isons mecastitiettes eae 11-6 
AVdymamicigauge: fcc: St Bsc cl eececatadis. heewsessssscssld dics toll cseeinuthcuelectecste ae neeietres atte ss 11-7 
PAMINOLALIFIE  BAUIBE eects cette cseecetecsirscadinsl isl ot Saud otbecas duacscane Metsu sine at ce pet cies 11-10 
12: Fil€: Sel@Ctors ssc cccevicscazasvacctssovsostasosscosaissp oases deroeesoies oseucasensiduoves evenscabasuicvdecsoutestasnessecottvelcoe Seah 12-] 
PReCUrsOns 2520 so.cessssecsresssasseione Stree eweteetutissstesetstiscatest veel steaesciveatens eos atm anes oben coe: 12-1 
VATE Vers cisscrcszescosteseveasanvsdostosurcesstnsitiweisdatacaotit associ. ths soi tectvadd wh aca sttenrers | eee ce: 12-1 
Clasvdiacran= ne ae nem ee 12-2 
Class de fim ith oni, 525.0. cescssorss feccoesycacsentes cucascareseevecveidavezsdacssboaeseeevaucheowseys o stereebias bowie: 12-2 
PLOPEMCY, £02.22 Scn2as cust iovbvncocdicavecsculudyevstedlaeateavedh soacsvuswéatoasciedanttiedenasests ous bate Secs aioe 12-2 
VADEWVimethods osc s.cc6. cae sctucetesavqt Sets chatae has odvsrsehesesed puatbosns eR cae tas 12-2 
TOMTOM Ss tea Sa eiteadeencuteustoustsgwethcere Si ce Rocce ies ONS. clock ee ee OG 12-2 
Search; fora CEvice sce. sis:d sss Seka vapanseatanascaatess Bscvsdencecessossdthoedatia ctevissasssponssscsvestoes 12-2 
Return public: device specification ssicsccc.ccssicpssssnessscearnnsiascsseedsnsecoceadevesssvbxs secdayooeseatvancets 12-2 
PACKSEI ceitttecccatstccresteesorettccttecterdtusertucsnertintaes eceohesare alercohosst Svled vost seat tuetove: sete seh 12-3 
MCTASS, CRA TAD SS ens oes scan dae anus sawn stint ott aaa becbatscpaeateacoat sas assoaatons laueettalgeraceuneetsestiaakesze 12-4 
COT AS SAS PUN ION i. sates chsh oaoeoeet ava joes Gpekc evant ashscaedssatercecvearacctarstg aaacayetee Gee 12-4 
PLOD Cit) een 12-4 
PACKSEU methods si. 220.0ii iectlteat Secsstaezsensiadintab osciact pustbee sate tiuee te adaecrsstucdsdivietealoecures: 12-4 
MEWETA MESES seit, ataata, dat dst\ wehnasaieeNsersdavoues elas iwidee aaattinsietesde ta otnantaale me ce 12-4 
Setipack from file tates: /2:2.-..,cssdeoatstaseshesvescasoscvnedhcdesidesestasesdencevs Seiwel hhc seers 12-5 
Handle key imput 2. coq icnonyscsntlaehissnzanchvetacbelee ss Sattans gusvastbnncsassestbbaealesdedgancatacd eat Meeca. 12-5 
MUNG AVE sac 2s sca deciaibies Seuseabated cack ava dd-vetsauia satonssritese decane tant uatiMech ab MOR A 12-5 
PINE arias Sreicaeite i Poracinseenslis pact eeaitn Maite conic aa tore ue ue eats» 12-6 
0) Ts TET ne eC Ec En a 12-7 
ASTASS Me MOA OM iat gua asacsa Beaty jers oiacris sgMS Obi eede NOE tas 0: ona lash tyc te me auc eee 12-7 
OPO ry cect hsb oes sale Pet bak Be Risaaea gues tats nose delved Cavsc used covse alan, Mean eros 12-7 
BINED EE MOU OS ci cichtai cikcicnns coi yaatedsvoausleets Wosncumansbicitacelaantaread ares eeun tue eu eer 12-8 
AYU DIS Oe cease tatiiacstsib seed Steet eget peat usa aVAIRY a eagle eon pe Saspen canis Sa ned et desaesdes ek 12-8 
DE Td IM cs catssec sh wor ata neavn aes ssesn tae a splash tegslaetaait cece do iid eagentSalktovadione 12-9 
GUS HUNT TC ARIE si cocece cans ccavansce cevscg- seated deanehderiiclahssei eset reatunehuateer anit ee ee 12-9 
Handle Key inputt :..3s5i:.ceciescues scarsiacsce tase ovbesecdseaeveees eat iadaletes ube snus a RO oes 12-9 
BID AS 1S OMe 5 inasahacuababiods soe Sncatansd luteaacacdsatschaceaniasess ces ahs sa mndewban lesa utd Ch eeneuncts 12-10 
Wee LAG BING MAMNS 5 50sec wiusicuieg sda lires is cahasciecs dee Sus bites Bhd cdooes ceclgedad esas acdiaaveeh Geodesaoebies 12-10 
RI Pa ahe Withee we iat 2. sessarsiinoxcdicsualectontasnatoe det cgsassystiagundiondencc ei celica tng eet ees 12-11 
FINS WINS ass cote Al eee saepeasche vin Nagao setl a anette euitala on mahs aht ea ceeleaimn mee! 12-11 
MON ASS HIRT AMY se coates vcore ct ivere rt vinai ne oesttiseng etuiaenmteed onic tae ete oc ee 12-12 
Classi TRIO Me tetccs- con resities ca, ax ceh ee Eel eee anu a Uber NY ite 12-12 
EYQDERCY seecervenerctiiecs coated sists tein aaeoth ns WGN aga hha eR Ee eM Ce ae 12-13 


FNSEGWNimethods:tscisccis ein el ee ee ct et Be Re 12-13 
MD ESTEOY. Steeirenasanier Min are ce ittaecasann, Sete reeves pete cet ciate ioe 12-13 
Una lise fee ecosetes 32 228 3, ss cses ead Sears tector bdaaicescee ese oa Utgeetdigt i it 12-14 
Change directory and/or Selection 1... cisccscnecspsrcanecosoverstrvessecritas oe AON Accists 12-14 
Get filename ct 2c... 7 tite ct ecg tiles ce eos ee MN eat a a. Ne et 12-16 
Handle key sn put cry stocspentees cshseuseaveettes Sveescepeyiauas vedinw cae sesivaeheccied a nsec ordvsiacnes 12-16 
Validate file name setrc8. sooo eee ee ee ee ge 12-17 
Sensewwidth?.». eect his etn ese ie eee Se APSO eg 12-17 
Update Tilemamiceme.. cutis sicker see alam IR Sk IR ach acon, eee kere 12-17 
IDSOnt tap Seite oe ei eeceese, aus eas nM tees sclera, 12-18 
EEX UP AC IAC Saree coor Mtn ta Eisner WOR lc cnctae SR eeeee  C 12-18 
Non-standard work on file list...........ccccccssssscscssssessessscseessstsssecscscseseessscsavececcessesceseseeeee 12-18 
Validate fileslist:::<.f.us scoi-) fencers as atesudase oa cas ste Seceice ite ea 12-18 

13: File*oist. Generator: Classes. sic sacsosssccscoescxisescsesesne soe sce eek sc 13-1 
PRECUISOTS fei ovi 0s sessles. coucccaecssttvinss is ev tnasesstttoctaskt atecscavee aah ie ec OM eae 13-] 
TASS Oia STAM 3. savccscccycacuasussstevcaxescnoncidecgesasosvenswialdeetaasesdeuctoedd nts o.oo 13-1 

NONODE reece resi tettostais cosiss eee Berese ON eaten acct Ste cen ta eet oa AR RRL 13-1 
Glass’definition 8: ar sector iss ke eee eee es Ee De Mee hs 13-2 
I RODE LLY! Po rsie lac taditeacca oe egeanratcnkavasaseaiunantvecsseuver anetes rw ivad gael eonak neste fa el ese ee eT hese 13-2 

NONODE methods ..)7 22 %esnh sities ancesestenees St tedeceeen aes acen aevate den tol Maotn testa Mck eo cath 13-2 
Anitialise*. J. 3. cossecccssasi chs lass? cacaeB vecdovssdeeeva ethos ie See ee aed 13-2 

INP SE recent oilers: etree 5,8, ee eh ren ae sa eet ign hore coe eet rr, ee 13-3 
Class definition ssissvesscccsen ssaaessvvavececvvcescavssavadsaaetsan sooo 0oew sean guna NOE) 13-3 
POPC DEY. ctu cchsttcstcqauinsiesdesisigusishecusngstevasnscsandehsncnta eaescden gsbaratensiaeialUaaarSietetvae a 13-3 

PSE methods: ten cesta tech eee ee oes in ks 13-3 
ANIPIALISC S29 52220 css So Mesos ccitays attics Pe stelaccd Mets miss cerereks tec eel sey tte Oe ce 13-3 
MCG eer cde Saas sai tia sac tunsan lua tet eect cies ota a ae Bree TE ne a 13-4 
StaKtSCAN aie. cisecivnetaseFA RS savoll vcecdecacdee ween hte A 13-4 
Diatta PeDUi) t s.sci3 savas vares cesses ess veasnseassadbes es tasveassnoon deradea ea dees Stes tsokteac cee 13-4 

14 The FILELIST Window Class........:cosesssosesssssesssssssssssssnsssssssessserscarceseesarcesesssaratatazansesaseesseceseseee 14-1 
PIOCULS OFS S22. 6) sh crsccls sth css scart cut icsleeievsedtatve Atesalideadoscs ees iteccutous doa des tutb ral ecasittoes ceegtaae. foce 14-1 

PIED Soon eect edat ise tibels he fons ist astel les teesitess coenestvedin do Levey occa te, ee Meh eo 14-1] 
Classdideidil ct a ee 14-2 
Classe fimitt ont 2c. sc2.cci casnssSs sees cscizvececcQeesee toate dedtaded een ashore game 14-3 
PR ODEDLY coeeessciaticttves MND ets Cem aSasc cota tets cea Sea tieeeies SRN vlaaundeare Aasuasacanenerte Oe 14-4 

FILEGIST, methods (ess. ccste taiticcevestecssetiss sedate ccttivel oe ee ee 14-6 
PESO Ysa seariutucnits ss Suis tacls yet nectdacereh Mg ewsienada sth tauacuiendn mesa ee ees 14-6 
Initialise Tile ‘ists. :..sss.ce.cc.vscedstedicdeesesd deeaovediisecataieinesdise ae iis aN 14-6 
Flare Mey Wap ut 5. cd san sachescettuetace® eadieal, wohidapscasaaiduastiaadtr nated esheea oaks ete scthls 14-7 
Return current Selection ..............cecscescsssssssssssssssececsesesssssssssssssescacscsssssscssesonsvecsesssesececee 14-10 
Draw ‘ante mm =. isc cccs testes decectic Seco seeee ete ae tases sds Rae ota csdk soe ed eens en ie 14-10 
GEE OTT text sets sictsedelics axes tae itactesacaeicedesssceetaeal a Ghaslse ovis tees coos bs Boeeusesste/ eee 14-11 
Vist Has Deer BEM RACE cccasscicsseenesseuseieacasesvavircundiadeane oveveeacswdiaosaheaiiestacs unde eceicas 14-12 
Check for chance tls Q Cs sss ciess cstnswnn easy cinoviseaeestlvaduart hasietbenccdbdanrra ene eee 14-12 

US General Sy stent Dialogs sssaisesssccscscccesssoceousadescecdesesveanionstsaiossasseStesciessqciecseststtalanltactaa Ot os 15-1 
PFECUTSOFS st sststsacs eeehetscsiiass a hate eke oes teaud cee 15-1 
CTS Set reaIMN esac tess iat ca sc Seca Menietaww ash davsiess Rad acon ia ates ee es 15-2 

ERRORDIOG 'sissttsotsecscttvauseslt tical duc dieltt abe eitcadiee ee Ala ea toca aceemmire Mes | 15-2 
STASS Ge FMT OM 80. os sieavsentzeasiashanexeyabas Waveete eobuesanscsnereascdicom outset: nash eee coco 15-3 
RESOUICE 25225 01Fs Saused Ba cries ties reat ee sca PN a: eg EEN MS TE 15-3 
POO IY thie case sie Dc hatin eg enact ete coca or aed stas clon ee haat ae BAER aE 15-4 


Dynamic initialisation v5.2. fc.0 %2esss esses take saves ie Seapebesrsiaadeadestiaeetsosdac te ee cout 15-4 
QUERY DEG retest scsssngssceseceetencvtelgeucrepeestralsucveseiseers caste eotacset tssacert thes eek Seen Meee? 15-4 
Cassie fimition:ssscsitscisscesde azote. cities sestetisiveeteaiasecssvs saastes oie tec toe ee ee 15-5 
PLOPr ly, fesc,.sotesc fe cerechutvec Step ssaecees tescsstert ee gusset chit sl onesie eae aoe ee 15-5 
IRESOUTCE shit viscattycocccselsscheivasdietihcasnacttsastartteeazsids tecttin vs ee ee 15-5 
QUEER VIDEG sme nO sa tcrnrearsuasesicsece snecerat eas ne ssitusnatas ca dcattecsscacdias et vetee regenera ient 15-6 
PY iaIn IG. MtlalISAMON 1225, cab, oececsdserateth al dears BRIA eae Sli eee 15-6 
Addiitemito'endiof lists... isis esesssissecestessansesthiesidvesciesisovsseetecvsd eM ER ees, 15-6 
ICTS TDD EG ao overs vcsttes crn teas atede toecpeeascevsosete thes eiebecceet a stesiavedsteseetie ties Ronse ece oe 15-6 
Class: de fimition.t.c2.2cessaiecerscescssssustn es ros uctessentancececerersactbeten tn sevectavechnes rtessemntetiestecs 15-7 
PROPERLY, 32 Seessu tutes sbsie ceded evesseghei gnats tases acess cisscasussesstouS tae ee ee 15-7 
RESOULCES i. ciss2e5 ea cintsuesing ehatiasbiebe chases Bae abt teiiaa Meio nat 15-7 
ELIS TDG methods 2245 ss sicsleeansctneacssseecss.. rastoutecdscovprasssevissnasote Moe eee es 15-7 
Dynamic: initialisation s...:.1.-1.cefasia.d-a.cceessedesuseecs Servesearsioreve hessocsinutste sinister eee: 15-7 
PlanGle key input! c.f ce scacsessdheass2tcatuet auneacentssccoasuvetoal uaa cena ee ee 15-8 
FONTSEL, aatint citciotied tis. Sia alts lautiiaae eee ea ee ee 2 15-8 
Glass: definition so. cscesssideaiterk sssstscasass Te densssscstaa te ctu ede cae acts batheuactove ate foes eoua oat 15-9 
PrQpenty taro setter cach snare hace ache inceticaten dere eee ane 15-9 
IRESOUICES ox. cacensscssserseaeteltsiesiiinsiscviitaca stavecsteressntedevstieh aid feacevocdevees Messisus 15-10 
FONTSEL methods. ossccscsscoycisosguacatedan dedeissuatsgiarsisvaigsseviiesibeve aes tcedaei via ca ae eases 15-11 
Dynamic imittali sation: sczivssiccrvesacseststvevessbeecae ceed easevouseasactie ia Senseecosbee anes ee aaa 15-11 
Prana Wee y imp it rst aircin i seh as 28 tes lten ee touav cx eaneoss ate lanes aah gen aca ons eevee? 15-11 
Handle item changed messages ...............c:cscscssssssssssssesessecstsstssssncessssuscsssssesacsessarersececese 15-12 
EVALDING To cirsnctinriitoticain: nent erie iain ee 15-12 
CASS EFINITION wists evscactiascavecarsvasneesatastetatalesdassssnintesasas lausieivasaciuees sesamiae oot y 15-13 
315) 5 PEER AE RB RE TY BS NPD ST IED EYI ISERIES br cf le OA 15-13 
RESOURCE Aro F.T. 2. peated at aceeteacsd ce fetes eeea sane tai si Dan Sects Bats eec he cols ee eee Oe 15-14 
EVALDLG methods sisescsits ncn ici a wen vasdlscsndeacaestncsestesdveausraact iis ee usec aes 15-14 
Dynamic: initialisation 3: 5.5 visvsesecctedscsnssecsesssossaosvecedeassadetsacdsoossoveterss geen onusvereeensaie: 15-14 
Pama sey AM Ut ocsegeiata cast at wesentg Csotesoaidna taaatense a eeabeeaeerates agree oe eee eee es 15-15 
Handle item changed messages.............ccssssssssscscecsssssescssesssssssusnscsssussseseveracavecscsecessseeeas 15-16 
Set minimum default sizes ...........cccsssssessscscesesssssescscsessesesssssesessscsescssscseacnsesesensseseseases 15-16 
SETPORUIDUG arc tieoi lettaveevctiadivecss cee oid ecek(ilicda cases desdaceusuuwdeovbvvsaus lsendsads ass bteteodddc tis 15-17 
Glass: defn thn ests tesie tteesdiede wer ooavievee bc iesane tt ystare ooactvetasseceoetacetanualee, wemtec ns tees 15-17 
POPE essere oaan estas tectia Se sce gate cCaa eaters tad nee kc aed esmsaoastedba tee ne ae eneacare tN 15-17 
RESOURCES teeter ttt tt te mi ee 15-18 
SE POR PDB G Mies 055 i sscturasinysl edad ound gnasisuesezadsh uns tsaei Macias dior testa uloadvacass arta ayaeeeetes 15-20 
Unntttalise Aig hee! ETS: jvssesseecueusvescssanccwasinbubnact asgusensduessacindadtsiucatiaeasciter sectee cae cncetioes 15-20 
Pele ey ni oUt tain sascha codeisuases oataaeiacarotescctacvpusstosgnctansceedlensmeeuarem f ooeteeeas 15-20 
SE THSEK DUG ws. soicaisstan ceasicrerteieleas Hee eee: Sears ewes nade Ba ieee 15-21 
Class de HMitOM: 4.2idau,ctiattiuiec uc cie mite daialtct Matsa t lik A Adare aber aan 15-21 
PHOPEMEY ss sesy eth tecs cvesipucusnksscesoaattietad cuss avetShase tussee aeseesscl Geiavsveutiee suevbadsdec ea lads sincere ee 15-22 
RESOURCES fc dic5t ics. ceatsc casted whscutearecucasercteles hs ceurstsees taiat sch OvsTieas goose ete ee eee 15-22 
SETHSHRDLG methods .000......ceesessesssssscsessescsessssescscesscsvscsssssessssssesesscesecsesescatacasavatavaneecens 15-23 
ArpiGia MSe EMIS So asis tees Coan sais aeacetioms Atrio sinzetaseibe Atenas igs Me Gee ative ee 15-23 
Flere Gy: prt cata. scocag scan iatety tyne atasspaotaadbniiocs footer tasters acta cates 15-23 
DG PHAN CVASSOS sce: cssitsceuseposetsobsactosschentuchsesascavesshutecdvsvaibes cbeiiesssiacslve nisi awesome 16-1 
PRE CUITSOFS ssi. 2.525s00eese shes enategedcanc se iesesezs satnes bevesiio ial giSins a OSE ee 16-3 
CVSS: iG SrA isis coaches cesses ns Seana caer cvnadvacansa beige ue aa Siento 16-3 
IEPRIN TER Si o22 foes esere.ite tz tien heater daice nei hae eA ee 16-4 
YUE CLSMNC MS wiiicnsit ids osce-csntaatuvenedltinieehaiubeiehielohaates Baya ee ee ee eR 16-4 
Cl aS5 Ge FIOM as ass. ciescres agvanstenterse etenecaneeariGgueeenueueona ea 16-5 
PLO DOUEY spshscengalsituste vosach cucniann 20 at rens astern aaneh alanis din cae a tee Kee ete 16-6 


Xl 


xii 


DGStr Oita she ce socecstsue abana tetzcssctcdt Loceacthacauseescuceteb leva cease sat Nvan eee Tac oad RT NRE dave 16-6 
Start printing. dialog iscsi es ccs cssce: Saco cet cretssaceaesacecs decevctsesdesususewsueesseresisteangad ote eaetis 16-7 
Readicall*back tis sent. tics tehicnsrsccres ti cuesecsstas ave tiene ecte tek ssaecdass neti h aaeasiaseiotaubizeriieasints 16-7 
Get prantertext Width sc0st cose stele geizateste beste rborersclevesacebeleovesdssheadedsestinees eta aeasatabees 16-8 
Déferred. PRINTER methods iv. cxiicts ices. fetches ac getessivatesacsevieusesotaitae sential eee aeas 16-8 
GEL tEXE LO! Print fecccscescsesssscsscssauceshserouvsseecuersvestevayssuesesd Sas acsssesacdeceens: Natsloevetsdeplesl esters 16-8 
PDEWVDUG Fite il lessee cde ect sccueteensteieutestas siae i carasacetats as SE MO ree oe 16-9 
Class Cet inition ys: in..cjccctesssssecsdsccsvercensbiscatiniseiecdienesaeeasicss sete ee lane 16-10 
BLOPGIty Sree; essiectscuahtsteatusenvaysduetesavesvensbtasuersrassascsvastiaatactduartessg:Si ows teecdisnvagh saison eres 16-11 
FRESOUTCES® Savtrscssccecssstctastears cecesiesnusutsossosecsceansitaesdsacanteetvederetsucssstiuevcencaatet atsibeaetaei teers 16-11 
POENV DUE; GimethOdss ss. Se -crtesacsicitenenicecpadastsvsenlecdiecs iescaceatacseguoseee ds ie no voor deesde ae ts 16-12 
DOS OY nos seiecccccrest re csascvcutzvssnpaten sssusceapeusecaRcouececevassvaeassrcs cvensvavse sditistonsecte tes sees re aties 16-12 
Latinch Sub-dialog cc evscts.cssescacticaeancasel ate Sicdhesttias ccsadevaasdesarshedia all Povsarsecasietsie ee 16-12 
Dynamic initialisation’: si: ciceccvevs coseecassncsveeesafectas ok scassenes foasasslidstovk dees lea cies sgaaseedstares 16-13 
Handle*Key iimpitt 2.0 os. ci- tease oc cccsscgntacosteat suesien aesetettevtrsssallabanctaes oateghinssinsavoeseastenes 16-14 
Readjin string resources’ <:0cc.sccceib:censeccissnstedansdisoveiscsesdncingiesescesteeasisdencessieratoseaveaceseanel 16-14 
Handle item changed messages............csscssssssssssssecsessssesssssssssceessesesssesssseceretessevscetseres 16-14 
PRIN PRE Vor sitestecscstesissasticsetnesssesatestseaescsuestotivectsbetncventsaesiu cevevex tectreas Geasececeisvarsosesvache ettOoks 16-15 
bass: Ae fim iti ond 2. e staves ccaccoduetguatat ectents aca seit a cvutsosssdssansgeveasasaesecuoshedvaavovouseebcatewtecedaties 16-15 
PLOPeT ey tid cuccrsscccscssttssccosessstousnintoisniiteseatinacecelsscecedewicusdueserteeatacds saree casuigecnvatenfssdetueecoueet 16-15 
RESOUTCES fo128, setesileaattedasstovlessst boca stecd cdghael Ghdvautese ed eettearadedenvachcs tee oO 16-15 
PRNPREV8methods 52.0.Fes.ccesiotistttascitessstesaceceeeuduaih nebediastetaresecte een acta usste este oeessies 16-16 
Dynamic initialisation ....6c. sseics.-cc-ceessecaececnisenee¥ensgsckpnictetesfessccrtessastraccssteseestisFaasesosatecess 16-16 
Handle: key tnputiss.sesssscccssecss25s ccgvasecess ices cusacansatiaceodz est veccvesdeud buecedueveasucsucesssevicacereseaseese 16-17 
BRIN GURU o0 2 iocccne srossticaccssnueue rae s essai isevedean stutedsvav seatetcabeseiadastoats sousiedtothe ve usectadarssTentasseet haters 16-17 
Class definition siscscccssccsussncsies cusssncasizscusesunccresc uses ass casa eeanevecarecierre cae TITRE TTT TE 16-19 
IPFOPEILY .ssisetcasccstevicsstssecacvatsssarsedvasasvitedibsdusasiicessis cuss Menion Seales GMS coaa tears ear neeeheatetors 16-19 
RESOUICES 25 accsccecsececvescecesetasescevevessuvsvuccucveviovecectuacsuonbes¥eiisrverndassnchscbsebedsecsieanecensadznecesehs 16-19 
PRNC URI MOth ods 2. c. cc. cstsctutesestecduonsteacedeoscyesdensssatedenensstuveeayesaseasl cueetescdusserestaesavaeescersursts 16-21 
Dynamicinitialtsation ':: 325 2550. 7oss carss cites, cov oaceseet csstateayereieteseesensaashs Maeutesbeat Wale seset 16-21 
Baunch sub=dialog cieic.cicits ccscses cicecsnes ses taacacavvsteectucdessbiastcvuescohsccestdeestaiadaicasssserecseaeronents 16-21 
Change default minimum SiZeS 00.0.0... ees eeeeeeescececececsssececcnenessscesssseasacseseaeensssesneesss 16-22 
Handle key inputs isc. iitsccsseeconssseebytes cus eceatcussterctecas avuastucviatet nucevauestaanseecttseatbvesedentee 16-22 
PA GE GTR oc soevescores sands caus saguonsstoot sauces suvoassasapstivoastetestsaeccussentusiaetlatentecedesietirobsaeveavetenties 16-23 
Classe fim ition. cs: 0. sss sfeoscs ssh 4a caters- ade dtecs sels secasceeteatervena caves rot Sheedy any seivbsecestes coeoetesdeoaseues 16-24 
IBEODET EY jc svcvcasscetes cletvesecevs avecevsestucestuscosevesiettsasdovisisveecnsedeedeasssde ostusuec tassios tebaate eetwabunaastt 16-24 
IR@SOUTCES cir: ssvsscs iersasaceaboaisnsatasadstesnntssrovncsvsuesbeesbeparecusutdSeveadiveseatvedanadec0ssaveatessibeeslseisoee 16-24 
PAGEGURIL methods: iss. (Prsstecics steus Sucuclvundbcsctsstaatdvacteesaeivaesdaaieas sozetaiact obeustaset testers 16-24 
Dynamic; initial Satin s..652.5 ses ec tetech cl ocetackescasccceatsstueseusseadaiveavaebiosdeueadvassaatetmacbea toute’ 16-24 
Handle key inputs. Jiscrevccicesvetestegetasuste vies tatdsestelacslenstaceadheutsondeistbuchestecsesseseescviciess ebusaes 16-25 
MARGINS 2 otis lo test ea cecsssacsraceusieseacucuestuncacvdsecasastavseucees tobesduasesaecteaacttve getier vce oeete shuren 16-25 
Glass Ge finiti ons. ci:.cesce.sesescacsacstunseivatvescudhcatdzie sesededvecs<inesvatcapidecveer ica ctives cache atsac tes 16-26 
POPOICY ococcreavscced.tocesuscaediecdunsescostiteeg seadecstarssvesscastesssaatdteeatéusousedioouevheetialavaedieeavedadhs 16-26 
RESOUN CES o.2csoic incest sassnnecsuasstotenadesa coer vel cgusece soecue ee buecs esesdex oss due ssvauabiseianamaniosiaes 16-26 
IMAIRGINS methods 23.2320. 5.2003 idsess tedsesavctsiss coeateveinabecat aaa sts det case ainsste cadena sthebate 16-27 
Dynamic :initialiSatOn:. voccceccesccsczsccs cesetesestasdlovcacactchsvsiasesivotedi lgsacislone treed souscGiavunereaaetestse 16-27 
Handle: key input, foiciesstostes.ci 5. assures es etebtevseacivsepieeinsocsie Mevsisneks davesesseusgniuensciacerbloies 16-27 
HEADFOO Piicsssssistecdi snes aiccessecuite lactis nasa, Uestagenesd Min detiies ivan pin atodiciee Ae eas 16-28 
CASS GET HON excseccscccrcess ccnscsrvessad tdevsl pssbeiesndiees<ctaessianeseosepoibnssnvvessetectankoascvseussestateades 16-29 
PT OPGUCY, 2205 so; sc acsez ened ios isiesextnesvsenestsontnntative cuaturteassesseusicavendscniat ieetcsesiah tons Messiaen esses 16-29 
RESOUTCES 2c c. 22 cscougusacdvedass avcesegiseacncuseussdinsfenetlsed exit cataci hose desscdehoce ae ee ae eat ated 16-29 
HEADFOOT. methods 3.2. zeiscvcsscdecsrese Mada castes stesnestchisesiadiniesterseesetendt Sidiacvie ee 16-30 
Dymamic:initialisation:.siis scsscspdaschst.cadssents ince dearsaecvwivessvasscvsceisvensuseeseencdiee lt oped estteaes 16-30 
Han dleskey impute sescicsseiecccs.ccasecoasiysetiiesnatvsncstsanstessessnaecesgussivissseasse sss eee sieve aiieeiobaccs 16-31 
Launch sub-ial og iscsi. csc aecteansacn nia sae saceed seceSrovieesdivcc ies ike seoadvadbedosouedentssusaccteestes teas ces 16-31 


LASS AE TMNIMOM ssn, tor tcca Bcisihat vactaeca sensi irs tasssbseeaensencunteeial ee A ama tine, 8 16-32 
PrOPEnty A rose o iss cratttenscet acres tr teanccrie sais cees toe seeders oe ere 16-33 
FRESOUICES 5.0022 ccc2 ie Subs. gsadie-aetoeeraetas oeteasn toca eee ereee ce ee cre dio ES: 16-33 
PRNMODEL methods. 5 scsi. .cs .isnscivcstas slevunescsissnsactietlacecarer ai Nests Ts tae 16-34 
DYMAMIC IMAL SACION 0 sesh ssescs ies aahcebcccas sas cutesecbsecvengcovsascsedis estes sR dea MMS oc 16-34 
HAAN NEA ey AN OU a cess tact casey ose actaseestsavcdneaaivigtchcatecsacasehuce me ese eee tees evsead 16-35 
Watinch:Sub=dialo gs. stareseatavash Bescccsteceinssabeidsvedsaiodectersasivet o Martas til ctescatieneteeo 16-35 
Handle ntemmchanged messages 205 525.¢.csoscs0c ss fias) pollicis arcesasaccicsebegteicqeus betevcoieee siaetiac 16-35 
PAGESIZ EF re ester csase aust scca end n seule bey otycedcriueanvseie ts hiscssS Mes facsdiaand POM cena 16-36 
TASS Ce FUME ashy i ce cha erph BSc Sreapidasvmnes ataliaepnadleal dns oa slaga tee cd 16-36 
IRESOUICES 2. o.o5utcfisesccaihs cca tisseesnyadssavatnteaapestastshsialocnsvoacitebivcs hacteaasl se eases 16-36 
PAGE SIZE teens 20 cs 2d. cscesdtuncasccisvveranpivtendanlinvdsendcsiiaimiw sia: Ban eM ees 16-37 
Dynamic! nitialiSation sess, .o..doscegdcsescatsecteatveeseavecossasiicesessisascscenseveotsessahe inet Stee aries 16-37 
Fran dle rey nut (3352 Shiaasscaiticssenlcnaa thapesnascestingnssaltevseasdeussdenrcarvaaveie mines eta 16-38 
Handle stem -chaeed MesSazes <<; i.e.snasec.ocsssthiets os hssasveavodacee soos ssachotavsegurtoeresncaconean 16-38 
PRINTING pete etesGts Ait) 4 a aah creel betes shaavdl das Bie el Mess eve ae ee a 16-39 
ACTS S AC TIMI 252 casks pus Valncce te vctendiceque Mis anieiaul tera denosdod ainsi mens 16-40 
PLOPELLY 2ossec8 erat os ntsesesssoensuss vas yosdesde hans arventedenascarsrsesediyastetoraestaciede us aamehton seca 16-40 
RRESOUPCOS 023555 28S asea bade cecss sales Dudes thoss eh diva Gucaaenctararue tanevivarciarSoadlogtslosesdba wise send 16-41 
BRIN-FING methods 252.005 issis0 steciteesadscaevesas Savsardtsesnstitds alotseat Soacssecepe dard azede ee ee 16-41 
Dynamic initialisation ...........:.ccccscesesssesscsesssesssessssssscsccsessssssssecessacsesessacsesssatacaracsaacers 16-41 
BEE SIZE OE tad 8 i cls iesencaeteacanngisbaaeu hee aids seeatealwedeacleaguael uabastecacd Mace ch odneieconaces 16-42 
Set title siren mtr ioih. ocches tasaaveesesssasinsccterscacat shies aieotevnacteiss cacatae re ee ee rete: 16-42 
POUNDERS darters ass sca vines ga eog ct nen ov ese denctieidctee ebcenazabsv iuseacee old Sdublac oyceant ews 16-42 
Completion’Call* bach rirteccecscssecceseccectanesteticsssssvcovsersststivegess x secrteseavs cuverssederumesentices 16-42 
Dds 10) B) BF 0 Os Sa ee ent ete caer rererererenecorerercerecttreececerrcrirt 16-43 
Class! diaeram 23255232: Setsans ec iesvecencdecscds avi Haat as eats acetate Danse ee Mors oe 16-43 
Class de fim thom seit. cis syvasssevseveadssdsce cussettesiasiosdbasiecneestveiesnsones thet ueteoestieeeve eee hee 16-44 
PIOPOrty ti ci ehtosn22c.d cencupanivasasacvie: Janstvvethcoasseassteddotanssevsdasesvashtss ses sotcpuces tices custeie oct 16-44 
PMODEOGS methods ss.:205.sc0idevescsatanieccgreiceriesch scion ccaaddssavesticaseect petunia neato sited 16-44 
Process matching filename... tsesecssesssssesssssssnssesesessssssesesssesssesssssescacscassvacsseeeers 16-44 
D7 Poialling DATOS sscsaciaockcsessencvosssosustaurtcavenesensat assess tos sisal cies ere Kevetecierasiesvivecidiaatanevsnien ne 17-1 
EC CUISOIS 2005.5 esvssea seus soc szcpscvsxsseeasdats Cuusia uu ebaseacvsdevevedesiceizetSaseacaesta ican tnueetelseee cai ars 17-1 
HAIG weverererececrecere ce rerese rere e rae eS Eee 17-1 
CTS ALATA i scsccaDi ncaa Dsnesntatocodl pap aVEeshcussncagtentss nad cobeacey assipigia aatarss ENON Magia 17-2 
GSTASS He BURNIN OM sis. ctayesocledSaliezanatte pices anata ate w'evapuisasifadracts icretlansisue aise ieleelosasetesamcis 17-2 
PROPOrty cet sasisisth naeset tie secu taaceeraaten terriers sasha eased eae aatieme ersten nes 17-2 
PEATDICE Methods iiesisiisteiisiaen sts cena taradie ie Wiatngutnadi nine aol ad Moola RN so 17-2 
DEA A tea ata us csa SS Sain SLs aaee nba cca carte ieatadietaauee ait, vmware 17-3 
ACTS: GL Ye EAM sg ssh ceduceiras cus ssheeaecueveeacsscaasan have be soiviastesiui uals dueciace avlobis caus th eateeies 17-3 
Teas Ae EU ILO sats eascofeg ps ierdas etc eh Bonntantneseccentalvackalaclects ganic tenth tats a ea tadies 17-3 
POPOL ty 2555055 Siccih cat cass Sess tev iys dh datas vavsetaashiastscoadeseebiertevtnsoecd atses eased ones ada avanecthdtabc 17-3 
DEAWAO- methods i... cisve:sdasesteiterscadies lain date aces sede ie anche eee lenditiemacie feo 17-4 
SPAN IC Ia DIRE ii 8hco ton css risa scat tad edt ites ek ss ietvenieis amie acicumbn nt aseen deren e 17-4 
Handle filters Keys ccc. cesses cs tatsseetatiesesschdravadiacteovesibiavitiavsauseeuoenbetee eitere.teseus 17-4 
DIAL DULG oi sec8 oso aed eset atcs dobsasdau tues Haeaeanatines sec dbs dectetactietouv a eee A oe ede: 17-5 
Class dia eran c.:2/c5 sess cle scasieesesiaszswns souctasaestasasdonscaccaselcvodasaceeai tie eee Oks oth hchunes etincoens 17-5 
EV ASS LS FUN Tt OTN ces yg zsh eee se vaatecseuteda asia ans tesnpctuati nba, egeqeec aattedee eancoles ete tintin 17-5 
PROPGMty srons.2-. cove sdabscbsancunstucatitadauevey ctl atssvses sodbtalacasevbeadevesussiteedtaswecsoaseceatetetaee cB scevde 17-5 
DEAE DUG in StS css satires docnss ape astenbeon tuba teudside cudea aie ualaie cnet, ane ities Meas 17-6 
(Teate: 3: Cial ACtive: GUO sacaj.-znsisccasdeseserceswsancernieyig Bias esate ROO cack 17-6 
PEA eres evas eleva cee 22 ee tacs eateat aoa ei caasenataa Ce iat esas cash a ate wdee tae thane te 17-6 
,G) Ergo FET a 1 4 cp a RS REPT os ere Ee 408 Ne a OT WERE eet TOE 17-6 
Glassidefinition!s: 2. Seat hese thee Bern en ee Moh A A caine A re 17-7 


xiii 


FREEDIAT Amcth ods cies ae: ats ssencxcdesesstast sean sestgnsovesseseseduovencacirasavsedvessiciacie assis enes 17-7 
IDESUOW. uit iccccesccecetassest ses tos snes sacle a stirs Seetcevsaa deassedasush iaocesoereva Tocca ces ee Ree ee 17-7 
Unitialise: freeform: Gialling :.2h.c ccc tesventveve tie isso scsecslavivanset cee tenes ee ae 17-7 
Drawidial string si<. ccc. pases cif. ee deeb cladeses eS 17-7 
AGG tpi ard Mia ooo sss cack dat cascet sacs eravecneenteencaiactace sonia ee OO co 17-8 
Sense LOGS er: Width vise Jccccikesesassssediscsezestsecssatecotstarss scotsense sts ee a NE casts 17-8 

PIDIATE DIL Grete ieateeiinsccetus ized tastiest teciserstesc cies su esstes sguicatart diester ere rse due ate oes 17-9 
Class dia grain \sicreic.ot .ssocecssccosticuesavent series ba cee nso see oo ets oie tc eee eR ee 17-9 
Ml aSSs Ae FILO TS 55x cs ctsstl Bese ccna ys aavacts aastivuecsiiaeadengeaesti ioneicad ho a a 17-9 
PROPOIY 2:5 cs-.tyesesecgsecsansnestscetencdvscecteanschnnsccsasestsenriees soi Reeizeus cebbe Sea et ae oa 17-9 
RESOUTCES ci cscsciies sserscesss2.cgerdasdszecs shin isteavenssesacva sce aeacssoc bend cas csadi oe eos, 17-10 

FDIALDLGimethods sisi iiaiaearih ai te decrevt itiecaedec een Se ee 17-10 
Handle: Key: vs.essciensscessccasareeyoacetenctestatactios cients ses teeasaste ee oe LE: 17-10 

ENTRY DEG Orit iss ckitessnctataiciesadceatoestatessracieartiase ss cuetasdethec sc ccucastecee RE oe) ea LAS 17-11 
Glass dia eran sevacotsielctstassrtestestsseestercs poseel cc tate toset ici one a out eee le oe ee 17-12 
Glass:definttions.:i22sces pester ors secatecveseg feereccivsacetssxcesasee-tiansseebie chorea ae eee 17-12 
PROPOLty f23.ceiessccicasiesvdsssesiecsagntueste citusave gasses tvecaceneebetaiocsevestels Azim hte eee 17-12 
RESQUICES is soi ciciaa.scsvdieZbtlt Sietlssdashncosadeabeaeatei tatatvevtacoes sbesltcavsisaasevche eee ees 17-12 

CN TRY DEG ‘methods iiss iii ecsvteantasstiasg-vacstssisesecorslsvesdoeelicacatdacssscteucvsussorgeatevesrvevnlccuensseles 17-12 
Handles keyite. srs. tas ccesttitt i ieaieasittest se adactensst Sek aude hccnt eee 17-12 

SDIATDU Goose iecsiaceatss sets dtinas deaensiianiivehvadiits caaGoesttin sceeastiasesored ei etoee neat hae 17-13 
Glass! dia Staite cic. sccscazgevsanvteiccsvstastasees east itasaaae Seasnd tbs thaoeansestuerneeie Seto tare eet 17-13 
CASS AEH TOM 5. asi ec tezescccssseoscseencceceaetscssstaS teria oesews tesaxesBouslanedscusucte Recreate es 17-13 
PLOPOIty :.sc..cecsceessevcsereucviSeucootesovtetavnteteertivi vdetareses cede va0eeeeSeeotae ee eaa sooo gue va TUS ESTES 17-14 
RESOUTCES 2.22.50. Ssieesarenawnecalstaceasvelecets segticassausts osesevesuenepouseices evel ths stonsh satelite cant es 17-14 

SDIAL DEG Methods .:, .istectcutisscsdssecestaessaileueresstassietscstslivbadestesthalsasetevecheSb near 17-15 
Add one or more items to the dialog ........cessesesesssessssesssssesesssesssssscsssessstsnsesecsesteneeees 17-15 
Initialise: dialogs. secs c.svecsatneseseasvesat totes loecvsaratactebselcssicen ctdsuevarvedeeanods ics icsanceneetevtvcion 17-16 
Phar he Gy ouca secs S22 acesaecuesstsbenasdacevertstetcacscsttostastenisesasaversscoevtelncioomesione oud as sheines 17-16 

WS ELC CNS SS OSs sisi czcoxscazssccsusstanesssusoes uasavacpbaavadgasnessposcaiva ceusuiucussusces dia tunel eslacavsecehteessaztabrnctaetnseaati 18-1 
PROCUISOLS 2252-515. scos4-ncsahcquscesteetuosrundeten es sepdeciicdesova dns soudSoosdMcvayl divtcesa sev iotbsetaeveecaadtoloes 18-3 

HEL PICIS Tes oie cite toe tate cases tosen ent be te neasicn bcs taa tetas uh tad etree Sts eee ee 18-4 
GEASS ATE aoc tk pasa h awed ciya sca isan Pioaua tonalea cosa ausideacee Medea tue Sy 18-5 
Classtdefin iti on sesame 18-5 
RIOpert ys. tses.cesusesccccvacesat heats ch oveslvaseeiehesdhgestetaststaa seostestsassseaies testator See 18-6 

HEL PIGIST methods’. ir .issisisecsacetas, sce deasdesdsbcesdeins teva scustactdSiontystsdesesstelnudebiouvaeess 5 Biosios 18-6 
Initialise help st .2..5.2stcseectestemcteestesnt skier seotvsasdn Adelante acres rah ae 18-6 
FRANCE KEYS 2 ersosit, Hiss. adsstee sta hacenassssaasectut ss vciwisaratatocauaciecis paaveo ebb tee 18-7 
GOLEM LENG soca senses tyes Deaes Seucaseres lav besacss acide slosutdeaSeiccsstessdeds de cabdeenyseasuaene aavaceioeteeee 18-7 
Get width OF item iisics.. 2s i.sc.cveses ec chseesatied fecsessteialasinsdsracsiaecesatecsed eomaa natn nae 18-7 
Format and draw air items c../..2822: 5. eecccelssiesesesevweccursaeets sists opiearadecetesdiocnseseos assstys uaitts 18-8 
Draw or remove emphasis On item ............ccceessessssesssessssssscssssssssssssesstccscesnseseseseesensers 18-8 

FRED PDE Gres 55:28, has deacSeavas asa atc seecvage ds tinsasdss cles csttavvas eens tenasti sted ton thse anita eee 18-8 
CLASS NRT AN aan Mask eases acxaueattaas Sandencssisbaciasin mul den ewcaaata oes GONG DA chutes 18-9 
Class: de timiti ot :sr.25. $220: scPecscatel Sveas soda de tude sovsseaocasdhccucaasusedvs teen sosoet es SEES aoe lao 18-9 
POPOL Uy 2osescscasvtesasvisesdeacavacestosdbessll sevedtedcacetgcast.2sde;slevekpocdesipevevratatsiacss Soteeteessbeacunadereete 18-9 

HEEL PDiLG methods ccscctscccsasetesvad suse tcecsadtesenvaicesteissnsassisuesdusacnvonsussvevevtelaboresdasesonetecarsectaneats 18-9 
Destroy dialogs. ihsscees cstescecttets lathe disses sats laasveses anecelazatarsabaeaeasva oeesctoeustbescesesobecne 18-9 
Initialise help dialog... :csssossccssscssscsctadacstlesaceosdszsczvcvacksandeseteveve sa diadisetienctvieree baaeuies 18-10 
Handlékeysoic, sctiv tesco chin Siectets a ldeevsidevas vdevishnacteetaa idee mths teats 18-10 
EM phasise fs -.2224..isvacresivavh sasesntiads veadessarsesiats adisitasneqese sted avaeseeiees len ea to fect Be 18-10 
Make the help dialog visible .................csesesssssssssssssssssvsssscsessscsssvsrseceenscseceeeeseeesssnceceas 18-10 


Xiv 


19 Opkand Commis:Script Support ..sc..cccsccsecssssorssentiacducossovesseseoanushanssioveseiseeialSeskveattdoreeciareac eee 19-1 


PIEGUISORS = :.S320: eocvtckscseghsc reese ht ssost onvad dvix tection ioe We eae eae 19-1 
PROG TIRIAN ort cccevevcsesiesvcs-csvevsoxbasesvs isnssssuceset uevssasnsnvacutecasteus raven dees dice oii Hed hasnt so 19-] 
GLASS AST AIM centage Seascsexccrsunsusenzeneciiica vans Se stis ect ists aiwveds once teceh oneal eee Peo 19-1 
Classe timition tes: 22:00 5.3 Betescsceustes state asthe elo PO  ee 19-2 
BODEN ee eerereccess ravi tas ivinu Stacey eeneny ai Rute cin it Medi nek A i Ue 19-2 
PROG TRAN meth ods 2:: 200s: sessesheiostescaccacdceetee essscdiecteousts sosdesseoeasRceseees rce teri eo 19-3 
Urn ithal S62 ess os ree secs acsecandecedtviecs ss Sassssvis care coven occasion ace PO Re cen Gs 19-3 
PNOCESSMCS SAO ps crelusdaacr dines: aan ssonvlnelersartesshan Me eae cecal heat eh a neceete eiocia 19-3 
Start translation of a MOdUMe ............ ce cecssssesesescsseceecsecscseectsrecsscscsscsessseesussessssseveceeeses 19-3 
Deferred PROGTRAN methods ........c.cccccsssssscsscecsccccecececcscsscscesssescessacssscsessessesevavacsesecteeccess 19-3 
GETING OL SOUL CE cs: a3: ccecases tia sedstecnccoeatt iva Tes bnecteSo dere tse eset co nhs seeynee ee ean 19-3 

BC DOMt COMM CULO TD ess. coc5s sts pete vesn carciusneeeiaverdetaducsd-nceslesdetesasta crits aathtcan a ae east Mcen: 19-4 
PROG EXE Ca scceavt za cesdebenidaseylabeqartstassaeoinsiasevab aac esate nex saeesdBADloniec teh a IRR, DAME 19-4 
CLASS, CACTI cae ish sus ielavean cas cetenicecteseanliamedeh nis cousin sia ean, lela Rem kere 19-4 
@lass definition excesses ccacsscertek ath ecco es octets eee dex tvss otk bashes Gea evo eae 19-4 
BOPED Ly 2. os. ecs. z. snosnustans cccursotssi tia cos cedcnsesduars cua tants tdcsathsetti tuts Movavi svete caetaoeite dae eke 19-5 
PROGEXEG methods & si. 2.025:c)cnnctetr oe cena acetal et se, ee Forte 19-5 
Mra ERA TS ABU UNG cost wekaatcd as ian sta teaeebemasns Ha cee taiinsdciniore ae ecko et ss 19-5 
Ensure process terminated :..::...s:.cseviiecetsnieetenextsti idesavesseeds cen hoki beeesivns 19-6 
PROGEIND) ove se cast cc. cerusendes Sanestocutores actceieasvea acluaerscostes iatee ext eee Ec ee as 19-6 
COTA Cl Fes CAIN 228 ai Aira ents seen SP catatonia vdeteaw wsvsialeaadiioce MMe ae ene 19-6 
Class Ge tin iti mss. 2250-275 eis fanstvkioseactagsvie abet ea caa acca alates to eases ee eco 19-6 

PEO PCY ea cscchdMunsvger ver el tustillaue yy cet cect oes ec aecaahea idee ad Nott ta Galen eels ov tuantaa 19-6 
PROGFIND Methods (io. secstasavesscatssisnsussessnvacttontviesioreséstareaaetsendisel SE Le ee, 19-7 
Startithe! SCan wisi. cevsdee sess To chesvac Sens dua ded elecat olbsent whee ses ele wide Seca doo 19-7 

File system mame found ..............ccccssccsssssssssssscsessssesesceccscscescsesssesscsecaesacsesccssecsuvecsecesones 19-7 

20 Imcremenital Matcher’s v.2...:..:.c.ccsccssiscscssscacsoscesdecoseasseseosesesrscvassceeceaculsccscevsedacdeizcdbcebssesccesstedctosses 20-1 
IO CUPSOIS% faiecenceacecesse os seaietst ties States bcdasaehiterue oe ates ects oovee ale cisco es Le ee 20-1 
MAT CHER 10x, os secretions eitueds Soeicsatsiactu stains Masse tenon tee Moe tebe ee a I 20-1 
KO) F-13137 (27 31204 (0) s eee ae RO a TR een IO 20-2 
BVO TEY soto ade eibicet than cee conte teen cv yobah bedeana ni cekig'sladvd A Ovcceas tein cd omtenecn see nteeuere ta: 20-2 
MAT CHER methods ia: ic5.55¢3.ccasthcseic as wnsut say aconesaxlar eavavasevicvdevepativaccii natin: ised tsdiads westeccle 20-2 
bs C-1a (aU EN Aes 51 || Rr rere eR ant tetera Tere EN e, tei rena Mey.) Jot 20-2 
Deferred MATCHER methods...........cccccscsssessscsscecssesesssceseccsscssscsasscssssssesessesssecssessesecseees 20-3 
Tmt lise evs sccise ss caa i Sicateias yuauiher a iteheaovhetctiiossciecd. BUSINES ovate ete eee 20-3 

Set current record by match ............ccesssssssesssssescesessscsecescsssvsssscecsvscsusececsseseceersasasssacesens 20-3 
Sense current record data ..........ccccsccssssssssssscsssssscscosscecessencssscsssacsssscssescassecsesesssacssseseaces 20-3 

MEL CUPTERETCCOR 22: tictt ot scat title cece eae etal strc uae eke Laer OM aN os 20-3 
Sense current record index ..........ccssscssssscssscssscesssecsssecsssecersasscsessescsssecsesessevecerecseseeseces 20-3 

Pry Clever mate scir.cteherte th asheslatutasstiasnsfceeeen ti diwties hoeeenect See cease ie itunes. 20-3 
Flan le: transition ws sists: vA sve adeds caves ca besrsvszecsecncc theta ace ean clot eee as es 20-3 
NMA TCHER oie iets Seach Mate tetas pest lets cance neds tote et ee 20-4 
CTS io Ned ANTD ac ec eess tenho viens seed dcsdica cata pns chav ndaestuavanoaineecana eR eI whee 20-4 
Glass definitions: 3.é2. 2:63 vtec cessveted csi be actbsasveesdasesdssauseecets Gosiielbecooctdvecdtbmicecssedeces 20-4 
PLOPEN by ihe Scie: sods aeadie aamsareanvenses otaatiot nd artes tatesnacalioeseid Minis toes Lal Siein Wasaizietcee 20-4 
VMATCHER methods: se. frems 22.5311, ete ole Be ait ae ee ee 20-5 
DES OY so ors eins seas crv ieaaet a. ani cecay cuaqeypeinaaaaveainiad atid vss ainsi Gea nae eeu 20-5 
Initialise vreccs asset ree ot ates, BR coec sadhsdoucaracBe cerita aS otin a 20-5 

Set current record by match ...........cccccsssssssssesesessssssssscscssssssssscesseassesessacacsesesesacseseseeeess 20-5 
Sense current record data w:....::.cccéssescecsdcbcatocentensscecteateysoveusbessbaceeusdstetedibaseeeleseceiconce. 20-5 

Set current records by Index cccvevctssnccaseeczasesdesdessasaeiaesigeacesarsvecdsensuietancsca hee eh Ae OP os 20-5 
SENSE} CUITENE TEGO: 3.65 2ccsscehsestssavencavesenes cates scaastbecevescuesteie Se Mlvelevisieec ances 20-5 

ry mnteliveent match ts siete sea ieNs seuntte ee secereasdicd hentieiese a atatita neato eee 20-6 
Handle:transition stats ieee tae Satie ee etch Sek tN Kcr re tw, eames oot 20-6 

DEL TaN Severs Mie, rere os he ceeses Aiba cote teves teste aes eee eed pgs Bene a 20-6 


XV 


WMA T.CHERS 22 icvccscasescsstessslecstesdetdisanes ottsos ct tnatadeeuivs fecachc shee aR a Renee ios 20-7 
TASS AT ANN ag hh ccs setts ascerdeaes Mins diag chante wonenisbraseeealoud esseids eineaauestbee ED cael 20-7 
CIS GOP Tt GIN 2c cscs35cas oes 5c doteessu cio Bases bsce tetas esttnciczcbesoeM vac 20-7 
PLODEMY ce wetting GUN Aa OR tera ot cass Meares erat os 20-7 

WMA TCHER: methods 2.2: cles ie2. 3. i. Sick ieesfasdivheed aes hides ous oc: ee Bo 20-8 
DCSt OY 23 ise Seas voce coanssuctsentetutanatiatvtbesbi. crate eoeesoes Se teieubd wvcepiass tga ie Ss 20-8 
TATRA ISO fe oe; coe sacs seca hehe dan d8c5 Pe Seogh ecto tes Beastie cteueae bathe en ee eal sbosh te Rin ee 20-8 
Seticurrent records stx.:20e At eee on ee Ble en ee es 20-8 
AryiiMteligent MAteh ss. cosicsan stints ieusaetesssiaebetvests ncrhccsrsalcraaateaeatceanes dec acter oes 20-9 
Handle: transitions 62.245 2cseht Peat eee, eee a a Oa Soke) BI EM te 20-9 

WIG DISET WIN 35522 ces seccastectisct led Lteuy iaeatns oss ave susan bodadee sev nawtewse ah oveateaenhet sac Boistee vas De 20-10 
AST R SSAA AUIN Sa Hick cA stave t ass tuneenvcecteoeratenecanaircatent ie teste tester aackain Taeoscease oe ee 20-10 
Glass: definitions. :s.teesct heal res et on, asatesdegtee ces hehe Se es, 20-10 
POP EDU y acess st ureatatlareticasscnttts Pipettes Mecsas Metra aa Ie cea Ae Na eee eter eens 20-11 

WIEDSEL-WNimethods's.css20::3 eeu cey Rae ets Oe A neha ee ee 20-12 
DDOSHOY cece seis reascesteteacistosertacssyece eter tet yia tack ccusc heats sctaccoe aes ait cees Men atari 20-12 
Initialise sectescicasdte eta. ts Nacvacensstsssssceesscsieeeetee ee ee Donne 20-12 
Draw Current record a2. sees secs spdctecedsSecsoe Seabee os Sebo eabstaddc Ore eee ee 20-12 
SO CUTE TE COT sec sco eisescit de scssttk. hecassaccce aedeesbiagh Seociscardare eee 20-12 
Handleikey input sitscs%ieisseccsevsrsticlscevins ods cvtacensidetiacssasicvsvites cheese ene te a 20-13 
SOnSe. ata foi cve.z ens sciveccavasceacnieeegenesgix Re cuetba tev oe ae ae neta do Md AN te 20-13 
BETAS ISG soe. ora, tsnciloniednacitaiscsesssin cca vac tds co avant ehujisnehatanatindied tocar euisaiba sass naeeataeke 20-14 
Returns required widths. 22... tsist. atti Se RE Hite cdevsen sea alee eet 20-14 
SEG TESHICHION ieesc ers ceseigs sree sais ete toe atec sah saaee seas ess ead ak hs esse ees 20-14 

ZL LIM PBSte SUPPOKt .ccsesaccesatuacsassssocossseuaivncsvonorscaenssersussiesazsasinasdoicseaiiescasccassuaseitttaesbea tetinsiaioke 21-1 
PRE CUPSOLS vecscccsiccnncazsaesetiasesswcssssosssssvecsgescessscecuaceoeasSertby Weabibbeesducssetiucth toe oees SOUS BE 21-1 

E-WEINKS V Sich foicsasscsacces tice iac ccsabisas oasebee ete ak iudee asada bd cceeasudSinon had re ROOD 21-1 
TASS CA OWA sasdec's ss dh sostiets oboe 8 cre geaipiwte ands avai dies sh chanssipsinarinlendccstaears Weuenalaiaatte 21-1 
Classiderinittionis.cectcsc:iictedfscdoetystss svsex 2 cievs coe cowatsesede, daa teetee dl cai See ieeesereienl aioctor 21-2 
Sc) 019 9 PEC ME ry ERI sO a Se ET Fy ee aE re ht Ma EN der 21-2 

EWLINKS V methods? iiccss..05025 55655. ictcinlos cobs czstedees pecuvcuahece colvancliloans dog see ce eae Ateeiaiak 21-2 
TDG ALS Oc 8 5.22 octtes cz cazdevccess su colsossce sees vcle to wish sustivs sabe eobs iit dbs avectect hide Ae 21-2 
Extractisome: data ti s.2.03.3 sch cost vest ccs sctcesettevecorseditnel deste de Se oes 21-2 

22 Representations of Time and Date ...........ssssssossssssosssscesesosssesrersssceseonsarsseesosessssccnanacacasansssacores 22-1 
PIOCUISONS s2s58o 5 sieieasedcdecivas hans e aise letecaaa dota ceubeen PR Gates atin Gaatan iv bia livai ee ietioion 22-1 

FVTIMEE hth cc Fives secs cashes cd ctactate ducts th tadansdd Ateiccatgel cece ood tostaa aatasn geile ee ee 22-1 
CLASS Ue OAM sco. os icsces tus hsv wate auc thasstmnasee eta ORL Ales ae eh aoc 22-1 
Class; Ae fin ition soi cevess .céessceves czoea sade ccxdsws hie feicSebs rose bs asaccs ac sad ECTS ee oe ce 22-2 
PLOPeOrty’¢. 2..c.sssv.tscuciteegns boseuesstcesCeransdeadgtecsesatenadausatesdstianioceevsiGesodt Meee eae ok oetsblas Ss, 22-2 

FLTIME methods iscscfalteve fess cise Seccas dh sece forth cb iaevetshantodu lanl ede rast eee ec 22-2 
SOU CITC Se 5 5. 23s 36 cee cks saes tecnechescaSuscte See tat a taeacace ots Sobacbetc sath Aosta catuncbins Mivaten Bi ees tne b lc 22-2 
SEE time FORMAL fevers, fs eessss se Sesciel edi ec oasciscuns even tee AAT Pee oto eds Bevel gue weed 22-2 
Get system, datas. i... j.dcccstessvesesecesesessesiosthnsues anasdestitasies Sebotedosvens Sia soe ideas ee ok dass 22-3 
Set: abbreviations ..6.c.sceasescecssuceetscsiea ceecuDoevedvidecddovelecdedaddaclata kone ENE eh 22-4 

ZB THE. GATE: GIaSS ccosssscssctasstisssnicdosnstecasesdcosacucusdazesecacetsecssscsussssvsveat tosestsccvbesavseeattin oaks a 23-1 
Cl aSs; CEFN ON feet casesees sep toscecdecsae eS scbevucee sin seee atev lis Coane badeub hees oi save bores code: 23-2 
PLOPOLty os.cocii i ck2 ashe cecias stueddesepseseasg setorsdessadbuanctencce uarituye as Meenas auich Sheet dacs cs 23-3 

Gate Methods tees? cieak ihe baste Tica vee aia eset hetero ee oosebhe 23-5 
CHECKIATS :Stattis ss: A ccsesscsscpee tater Gav ies haa betacaeassd dee 23-5 
SENSE WE Mast REY POSS si. iai..des ss ccee stpesktmttansteane eset et eae ences 23-5 


Gremeral tities 5552555 Nos 2hecsasi cos cesees Soo SBesstasiat ug caved évencte. dtetiasdnaceckehitiaecteed cease lat eesiet ow ats 24-2 
Return SER Bid scsl xaztiasecieastocvesvan cesttenscdtesvesensadbeneas Bei hssacdsbepzascaiaterde soeuithans Gaaeeikseiet. 24-2 
Returny FALSE sss is ccateusd cevsssssyascobess asd alata tapes cusuaacvecce occa da atiaivcsvcte sucicerva'issietdectgeeusies 24-2 
Destroy.an Object 2245), ac svesesescssicetasiertcceresotsts sues teastdvestiteeys adits vives ate eeveaunanstalienas 24-2 
Make sa window: Visible i..2 035.00: st.csesssvarieeshsoeentoahas ct dasedadieewiusassnsoncrdeccadeanboadieieierteasoss 24-2 
Send command to command manaGer ............ccsssssescsssssessrscssssesssssessovsvssscsecestsececacaeeseas 24-2 
Ensue: path CxiSts: 2.5: eipevs sched teach cadeseivesds hse Qa Sestvashincheliencsca ouialethitisatasateetees 24-3 

Text management 20s sse. cscs vet becactedocsdescsvsievsssadiscasstiaaseidtanguadesntsdulusecssuclvcdvoeviveats leletagens 24-3 
Allocate cell and load resource ............scccscsssssesssssscecssssosssesssssescscsssssecsvavecsnseceroreceeneaees 24-3 
Load resource imto: DUPER sis s.cicivescetcsscseseseanisanseed2ictetshesausstueslaavtledevesovebsascsseosbiscbvisesoeses 24-4 
Load choice listen into: DUEREL occ congsseedalesesosdsnaarcenseaie acabassaccpencbusdsiveneStisegaheaededaass 24-4 
Generate error texte seats ead casa astavasboaes dines asslgecontealedtas scvastve asedavdieatehceacecet 24-4 
Generate formatted String... cecscescesecessesessssescesceensseseceseensensesscecssessssvacseveueseeeees 24-5 
Generate formatted string, variable argument COUNL...........ccsccsssssessesessssscsescsesscsceseceees 24-6 
Append ellipsis; to: texts. sccst..cccteccsssececterssscapidivessscticceashilvssaniesessssuebivesetedlsetesioete Ns Bile 24-6 
SEU TEXT MODS esos t cde tant cocs sd ass avaah edondscandvanvacSvsalaseca veces savsscuiseacacddsviaseectang ean 24-6 
SOUTOME Sot ccecialsri tastes ca fics catvesnecvansusudsvesieuebetenuelécsciscastisasocssvaveisOosardars atdvacueasseul sadveseacs 24-7 
DELITEXL SLY IER iiss eet eth at ne eee orth ain cab tec sstenei tate Meee oles os ee Ag 24-7 
Get normal text width for buffer 0.0... ccsecsssssssescscseseccessssessssesesesssecssavsesesssstscacecseeees 24-7 
Get normal text width for string ..........cscssssessssssessssseseccsesesssssscessssecssssaresueseersccencaenees 24-8 
Getibold text widtlt for Outer 55: ce ssccsusnccevasuaivdstacssuatuaLasavsvnctsiieesdbcdastehuehervblecsswetesiorss 24-8 

User:notifications. csvssontecscetisiisis cas sets svn crate ses tcitvssansglanens bvdiesesseibvavesd huastenss cate 24-8 
Display an information message .............ccscsecsssssssssesesesesesesessssesesesesesseessseecesessccseseasrens 24-8 
Display an error informationemessage: 30... 5.5:5),2eccysherdgvesennaduanouastacaddeatddassdiveeedsctvasasies 24-9 
Display: a DUSY MeSSAge cs. .vscecscvsversnsdubees saseveae_{5cislec' sesetsieesnin sordeasesdecdiuewssenseeieecac dee 24-9 
Maketa'beep Sakata catatnasdtetnc cena mith tenet otc 24-9 

Rania ial gis sccstscctavesvsevadsviactss.Gectayhadeaseveacaateciareie dea bes sesticvestsraediel eves oBontes anleeeounede 24-10 
Maunich: a; dialog ve.tis.2325 sith eestuiabshcatvers cues dees sdavnsovsadaacphavavucastesecizcseseeovensoncposextdbecs2oes 24-10 
Ruma Confirm dialogs. .:5:ss.sctsassccastoascsincidedecesssisasedtbatsesiaeevecesteeevdl oopacceasisbealser cstsbvec dds 24-10 
Run a two-line confirm dialog 0.00... c.ccsesssssssssssssescsssesessesssssssssssessescsssssereceressacseneneeees 24-10 
Runean* error dialogs 3.525. scot se. dessiauecbecacancreressersrecebnovid Westies Aicsbat ds eoassen te eects 24-11 

Dialog DO xsi Mees 5. its ois A aod Geren nyorn asuadal awed Aleta gh aah 24-11 
SOL AM TEEN ooo d ces ant cvs! acsas sede savenausten cht cdeincteveacas dois stassevoenestsrdtevas den lodeauveet enerreewea dhe 24-11 
Ola LERCALOMN vsises iestsci tse suds becuse whats Cuvebasasenseeadhceuveneisstrstaisiaeen tisk seul ies cveselevs ivaauateodowtees 24-12 
Set text Im dit WINdOW seicssscssvesdusssnctsttandd zseataseseatajuise.soecdedeer desis, Seca bes Sdsntsaectach 24-12 
Set text in prompt WindOW ...0.....esesececcesessesesessssssceesssescscseseseeesserasescsacsesvevausessessacseees 24-12 
Set choice in: choice lists... i scscecessccatecscosesalanzeheacecaeceutseacesosrscosssoiaeas se cvovsbussdusneledsoncvses 24-13 
SetrOn/O@fichoice'listto’ On errr 24-13 
Set value of numeric editor... eceescssesssessssssessccsesesesesesssvevsassssassessscsesrecevesensececeeece 24-14 
Setdatitude/lomp tude: edi OF oc. oc. iesstjesnentevnuaneeetiaeeantusbadsa cat decnnansdecaiusiecsaavianses havea ice 24-14 
SEt Punctuation’ CMUOR s... cos seas ests sxes seven ecewhes cases ccaeusZe ase aarsosdesi ah. fuesial otaeveuaeeaten Mateos 24-15 
Set floating point editor... ecescsessssssssssessesssesssssecessssssssescesscssscsesescesssseavenceceeseaens 24-15 
Set ate! CAtOn cscs csctaiscedeucasins anscedh vives benstadiceasicig asnivessvasisesssibararsecgoniseteeusbaewatateds 24-15 
Set range Sditor shock oecsvsete task ate acatea aca taevelesdsiesande disses ie vosees adeedbeseveaticdeentcthe 24-16 
Set dialog title cosva. cscs dececavarevtotves cuseteivathuavthadianseacotosietaaseoseanaatienai hued tie 24-16 
SVONSE SAM TEM, 32) ses scvtcasescacwdescheueddes tre oduets ends Fedesazassvedsdsoctisyedeoatuscensoe tess edits sapboewl 24-17 
Sense edit: windows !2c.. ie. iseceedatevesteeadesnsathosssactdientgusosttsvvisteeotelodee Helasateiteeteavherele 24-17 
SENSE ia CHOICE Mist 22 so) sos aces este sdea ts aca hesobes oes ates As cs shateturetvieediabcaxtett ool 24-18 
SenSe:a NUMETIC CCIUOF a 22.25.45. 24ocaveenas dtatensanededaxtocsesesturaddesdeodeats leenensbegd ade uausecs 24-18 
SENSE A PAN GE CQHON ss ssesc5i sos cuctescdestycunensnzes cand cueedeadgens sack isi Peaeaacs seth gloyecdeaysedaatetebeedes 24-19 
Sense a floating point editor... eeecesessesesesenssessecsssscsesesessecscsesesssessscevevavacseeesees 24-19 
Sense a latitude/longitude editor ...........ccccssssssssssereceecscssssssssessscsescsssscscssvscctecseesaessensass 24-19 
Sense a punctuation editor oes ccccesccscssssesssssesecesssnsecsseseseecssersvsssessssucssarscseaeeeecaees 24-20 
Sense,a date editor sss ieia.censnascesecgecivste bess bevenssseedtaeseiet asbhnentiecutlodislsstiaeeiewiieeveedieale 24-20 
Dim /andim an itm o. 2 de cc ccsssavycenseeteacstineddetasaitvacacsredeverdlocasveauverautedtsceusieseuinusdavevhenc 24-21 
EQCIO UOC We am TECHN 25 acs eh ceta ed cus sh dean cna tdaasedabnnab labs ised as sideaiish apdsnauellancauoEaams 24-2] 
LB) 191212 2061 | Be ne ee a err NTO Oe ne aR Te on nC On 24-21 
Set floating point editor from twips ValUue..........c.ccccccscscssesssssesecsessscssesscnscsesssseseeeeecesens 24-22 
Sense twips value from floating point editor ..0........cccscssssssesessssessssessssssscscsssaresssseeeace 24-22 


xvii 


CHAPTER 1 


INTRODUCTION 


This manual is a reference document for Psion's HWIM library. It provides a comprehensive guide to the 
library and documents the classes, methods, properties, inheritance hierarchies and other information 
essential for understanding and using the library. 


It assumes familiarity with the concepts of Object Oriented Programming. 


The Object Oriented Programming Guide is a useful pre-requisite as it provides the necessary background 
to Object Oriented Programming as implemented at Psion. It can, of course, be read in conjunction with the 
HWIM Reference manual. 


The HWIM library is supplied as the hwim.dyl dynamic link library in the ROM of the Series 3 range of 
machines. It contains a rich set of classes that provide the application management environment and a 
sophisticated user interface for Series 3 applications. 


Access to a subset of the functionality of the HWIM classes is supplied by the non-object oriented HWIF 
library, described in the Programming in Hwif manual. Note that the HWIM and HWIF libraries are 
mutually exclusive; an application may not use a mixture of the facilities of these two libraries. 


The Series 3, Series 3a and Workabout machines contain slightly differing versions of the HWIM library. 
This is largely caused by the different screen size and the additional support for the use of grey pixels, but 
there have also been a number of enhancements. In addition to changes to the internal operation of some 
methods, the Series 3a version contains additional classes, and some classes that are present on the Series 3 
support additional methods on the Series 3a. 


The changes, however, are such that code written for the Series 3 will also run on the Series 3a and 
Workabout. Conversely, provided some care is taken not to use the enhanced features, code can be written 
for the Series 3a and Workabout that will also run on Series 3 machines. 


The HWIM software that is supplied with this version of the SIBO 'C' Software Development Kit 
corresponds to the Workabout version. The content of this manual is also primarily written to describe the 
Series 3a and Workabout versions, but differences between the versions for the various machines are 
noted. In the vast majority of cases, apart from the enhancements, the differences - even where mentioned - 
are concerned with internal details of implementation and are not significant to application programmers. 
Note that, except where explicitly mentioned, all changes that are specified for the Series 3a will also apply 
to the Workabout. 


Many of the HWIM classes contain features that are intended only to be used by system code. Any feature 
that is not explicitly documented as being usable by application programmers should be considered to be 
for system use and should not be accessed by application code. 


Using HWIM classes 


An application (or DYL) that either subclasses or creates an instance of an HWIM class must declare an 
external reference to the HWIM library (and the OLIB library) in its category file. If, for example, an 
application's category file has the name myprog.cat, the content of this category file must start with the 
following lines: 


IMAGE myprog 


EXTERNAL olib 
EXTERNAL hwim 


HWIM REFERENCE 


This ensures that, amongst other things, the defined constants representing the external category numbers 
for the HWIM and OLIB categories (in this case, cat_myapP_Hwim and cAT_MYAPP_OLIB, respectively) are 
available to application code. 


In the source code of the MYPROG application, an instance of an HWIM class - say, of Epwrn - would be 
created with p_new (or £_new) as follows: 


p_new(CAT_MYPROG_HWIM,C_EDWIN) ; 


.If myprog.cat defines a subclass of an HWIM class (say, the class susEDwrN) this would exist in the local 
category. An instance is created using the local category number cat_myproc_myproe, as follows: 


P_new(CAT_MYPROG_MYPROG, C_SUBEDWIN) ; 


Similar consideratons apply to instances created by means of £_newsend. 


SS SS ee a a ee ee ae 
Notation 


Names 


Except in class diagrams, a class name is always given in upper case, for example wsERv. 


The method name in the title line of the description of each method is the defined symbol for the method 
number, without its leading o_. In the body of the text this name, in lower case letters, is used to refer to the 
method function (or more simply, the method) whereas the upper case name refers to the corresponding 
message. Thus, an object's destroy method is executed when the object receives a pesTRoy message. 


Method function prototypes 


The description of each method contains a function prototype that specifies the nature of any return value 
and the parameters with which the method is called. The parameters exclude the object handle and the 
method number. 


For example, a method for the class wserv with the title line: 


and prototyped as: 


VOID ws_do_help(INT start_id); 
would be invoked by, for example: 
p_send3 (hand,O_ WS_DO_ HELP, 4); 
where hand is the handle of an object of the class in question. 
This corresponds to a method function declared in C source code as: 


METHOD VOID wserv_ws_do_help(PR_WSERV *self,INT start_id) 


{ 


The & symbol 


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


Some methods (the vast majority of destroy methods, for example) can never fail and will therefore never 
call p_leave. The title line of a number of the more significant methods of this type are marked with a 
leading © symbol. 


With the enter and leave mechanism, a call to p_leave should only occur within the protection of a 
p_enter harness. If p_leave is called outside a p_enter harness, the process will be panicked with panic 
number 47. 


The p_leave mechanism and its use in method functions is discussed briefly in the section on Structured 
Error Recovery later in this chapter. 


1-2 


1 INTRODUCTION 
-__ OS INTRODUCTION 


Class diagrams 


To illustrate the inheritance and using relationships between classes, most chapters will contain at least one 
class diagram. 


The notation is a subset of that used by Grady Booch and described in his book Object-oriented Analysis 
and Design with applications (2nd edition) with two minor changes; 


e classes which are referenced, but not described, within a chapter (i.e. classes whose full 
description lies in other chapters of this manual or in a different manual), are underlined, 


e — the diagrams do not distinguish between ‘has' (aggregation) and ‘using’ (client/supplier) 
relationships. 


Also note that ultimate inheritance from the root class is assumed and is not shown. 


Class hierarchy 


In understanding the structure of a specific class, remember that methods and property are often inherited 
from a superclass (or superclasses). 


While a class may contain new methods and property, it may also re-define methods inherited from a 
superclass (or superclasses). Note that methods in a superclass can be what are known as deferred methods. 


To help illustrate these relationships, each class description in this manual is accompanied by a diagram 
which shows that class and its superclass(es) in hierarchical order. This diagram is placed at the beginning 
of the class description. 


The diagram consists of a series of adjacent columns. The rightmost column represents the class being 
described and will be marked by a double line border while the column to its left represents its immediate 
superclass (if any) marked by a single line border and so on up the hierarchy. Each column is headed by 
the class name followed by two boxes; the first lists that class's property and the second lists its methods. 


Deferred methods are separated from the preceding methods by a blank line and are printed in italics. If a 
class re-defines an inherited method, the method name in the appropriate superclass is written with a line 
through it. 


For example, the following diagram would be included in a description of class cccc subclassed from BBEB 
which itself subclasses aaaa. 


Se den 
property _1 property 3 
property_2 


method a 


methods 


method_d 
method_e 


In this illustration, method_a is supplied by the superclass aaaa, while method_b is replaced in class BBBB 
and further replaced in class cccc. Another method, method_e, is introduced in class pps but replaced in 
cece, and so on. Note that method_u is a deferred method. 


The root class from which all classes are derived is assumed and will not be shown in the diagrams. 


Methods and property inherited from a superclass will be described in the appropriate class description. 


HWIM REFERENCE 


Structured Error Recovery 


As mentioned earlier, the enter and leave mechanism is commonly used to implement structured error 
recovery. 


Use of the p_leave mechanism 


In general, you should assume that all methods NOT marked with the © symbol (as discussed in the 
section on Notation) are capable of calling p_ieave, even if this is not explicitly mentioned in the method 
description. In some cases, such as where a method calls, directly or indirectly, a deferred method (which is 
supplied by a subclasser) it is not possible to specify whether the method may result in p_1leave being 
called. 


In the event of an error (such as out of system memory) occurring a method may: 
e call p_ leave, passing the (negative) error number, 
e return the error number, 
e either call p_leave or return an error number, depending on the nature of the error. 


Some methods call p_1eave (0), which has the effect of returning from the p_enter harness (with the 
retum value zero) without signalling an error. This is used, for example, to provide a normal exit from a 
deeply nested function call, without the need for a zero return value to be passed back through the chain of 
calls. Intermediate functions in the chain may then be declared as vorp. 


Some method functions that may call p_ieave are declared as vorp. One reason for this may be that the 
method forms part of a chain, as described in the preceding paragraph. If user code were to send such a 
message within a p_enter harness, the value returned from p_enter would be indeterminate if no error 
arose. The solution is to construct a shell function which sends the message and then returns zero, and call 
this shell within a p_enter harness. The call to p_enter will then return either zero (if the method calls 
p_leave (0) or it executes to completion) or a negative error number. 


Panic numbers 


See the Error Handling and Error Recovery chapter of the Object Oriented Programming Guide and the 
Error Handling chapter of the PLIB Reference manual for a discussion of panics and panic numbers. 


HWIM does not have its own unique panic numbers, but panics a client that attempts an illegal operation 
using PLIB, OLIB and Window Server panic numbers, defined in the respective SDK manuals. 


CHAPTER 2 


THE HWIMMAN APPLICATION MANAGER 


clean stop contig 
system nrid command 
reb err defext 
srcb sparel aliasinfo 
ipes spare2 yield 
task 


amcinit am_init 


am_start am_notify am_wait 

am_stop amrnetifyerr: am_rscname 

am_add_task am etean—up am_notifyerr 

amwait am_onlyone am_clean_up 

am_load_resource am—ftindimng am_findimg 

am_load_res_buf am_change_pri am_new_file name 
am_yield 
am_ensure_ipcs 


HWIMMAN is a subclass of the OLIB appman class and provides the functionality of the Series 3 HWIM 
application manager. The appman class is documented in the OLIB Reference manual. 


Every HWIM application must create and initialise an instance of (a subclass of) swimman, which must 
remain in existence until the application terminates. There is no need to send a DESTROY message to an 
instance of Hwimman since its resources will be released, along with all other application resources, on 
termination of the application. 


Subclassers may replace existing methods but, for future compatibility, should avoid adding new methods 
or property. 

As with the appman class, the ao_run method of an active object in the application manager's active object 
queue may terminate prematurely without triggering the error handling mechanism by calling, for example, 
p_leave (RUN_ACTIVE_USED). In addition, an ao_run method has the option of leaving with the call 
p_leave (RUN_ACTIVE_CLEANUP_NONOTIFY). In this case the cleanup mechanism is triggered but no error 
notification is presented to the user. This is useful in the case of an error where, for some reason or other, 
the user is notified of the error before p_leave is called. 


A built-in application, or any application which supports only one user language, may not need to subclass 
HWIMMAN. External multi-lingual applications will need at least to replace the am_rscname method to load 
the application resource file. 


Precursors 
Familiarity with the following topics will aid the understanding of this chapter: 
e the OLIB appman class 
e the active class (this is also documented in the OLIB Reference manual). 


e — the structure of the Series 3 process command line, as described in the Series 3 Programming 
Guide 


SSS 
2-1 


HWIM REFERENCE 


rr 


e the p enter and p_leave error handling services 


Class diagram 


Class definition 


“ hwimman > 


r 


Defined in sub-category file hwimman.cl (generated header file hwimman.g). 


CLASS hwimman appman 


Hwim application manager - schedules attached active objects 


REPLACE 
REPLACE 
REPLACE 
REPLACE 


am_init 
am_wait 
am_rscname 
am_clean_up 
REPLACE am_notifyerr 
REPLACE am_findimg 
ADD am_new_filename 
ADD am_yield 

ADD am_ensure_ipcs 


CONSTANTS 
{ 
H_COMMAND_DEFAULT_FILE 
H_COMMAND_OPEN_FILE 
H_COMMAND CREATE FILE 
H_COMMAND_EXIT 
H_COMMAND_TRANSLATE_FILE 
H_COMMAND RUN FILE 
H_COMMAND_LAUNCH_DYL 
H_COMMAND_BYPASS 


FLG_APPMAN_FULLSCREEN  0x1000 
FLG_APPMAN_ LINKING 0x2000 
FLG_APPMAN FROM_HWIF  0x4000 
FLG_APPMAN_OWNPRIO 0x8000 


FLG APPMAN S3FS 0x0100 


Oversee HWIM initialisation 

Check with window server everything is okay 
Name depends on language 

May need to clean wserv temporary resources 
Use wsAlertW not p_ notifyerr 

Insist on the SSD being replaced 

Record a new filename 

Wait for all active objects to stop processing 
Ensure that ipe is initialised 


'p! 
‘Oo! 
en 
x! 
Tv! 
'R! 
UD 
Al 
Matches PR_WSERV_FULLSCREEN 


Not used by HWIM applications 
Matches PR_WSERV_OWNPRIO 
Compatibility mode using full screen 


FLG_APPMAN_WSERV_MASK (PR_WSERV_FROM_HWIF|PR_WSERV_OWNPRIO|PR_WSERV_FULLSCREEN) 


RUN_ACTIVE_CLEANUP_NONOTIFY 


} 


TYPES 

{ 

typedef struct 
{ 
UWORD flags; 
HANDLE wserv_cat; 
UWORD wserv_class; 
} IN_HWIMMAN; 


} 


PROPERTY 
{ 
UBYTE contig; 
UBYTE command; 
TEXT *defext; 
TEXT *aliasinfo; 
PR_AIDLE *yield; 
} 

) 


-1 Same value as E_GEN_FAIL 


flags to supersend 
cat of wserv 
class of wserv 


TRUE if filename in same alloc block as command line 


The default extension for the application 


The Series 3 uwimman class does not support the am_ensure ipcs method. In addition, it does not define the 
command characters H_COMMAND_LAUNCH_DYL and H_CoMMAND_Bypass, or the FLG_APPMAN_FULLSCREEN flag. 


The Workabout introduces the flag FLG_APPMAN_s3FS. 


2 HWIMMAN APPLICATION MANAGER 


Property 

hwimman.contig TRUE if the application's current file name is in the same allocated heap cell as 
the process command line. This is, if appropriate, set to TRUE by the am_init 
method, but will be set rause by the first use of the am new filename 
method. 

hwimman .command the command byte, if any, read from the process command line by the 
am_init method (which converts an H_COMMAND_DEFAULT_FILE value to one 
Of H_COMMAND_CREATE_FILE Of H_COMMAND_OPEN_FILE, depending on whether 
the specified file already exists) 

hwimman .defext a pointer to the application's default file extension, if any, as supplied in the 
process command line. This item is initialised during the am_init method 

hwimman.aliasinfo a pointer to the application's alias information, if any, as supplied in the 
process command line. This item is initialised during the am_init method 

hwimman.yield either nuuL or the handle of an instance of the OLIB arpze class. The 


instance is created automatically on first use of the am_yie1a method 


ESS a ee a ee a a 
HWIMMAN methods 


AN_INIT 


INT am_init (IN_HWIMMAN *init,UBYTE *wserv) ; 


This method is documented for information only. It should not be replaced in any application-specific 
subclass of HwIMMAN. 


Initialise the application, creating an instance of (a subclass of) wseRv together with instances of other 
classes that may be specified by init->f1ags. These flags may be a combination of the FLc_APPMAN_Xxx 
flags listed above, together with the following rLc_appman_xxx flags defined for the OLIB appman class: 


FLG_APPMAN_CLEAN Create a cleanup list component 
FLG_APPMAN_SYSTEM Create a system configuration component 
FLG_APPMAN_RSCFILE Create a resource file component 


FLG_APPMAN_SRSCFILE Create a system resource file component 
FLG_APPMAN_IPCS Create an 1pcs component 
FLG_APPMAN_ONLYONE Fail if the process already exists 


The differences, compared with the allowed flag combinations for the am_init method of the OLIB appman 
class are as follows: 


e An HWIM application must have access to the system resource file and so init->f1lags should 
include FLG_APPMAN_SRSCFILE (and hence also FLG_APPMAN_CLEAN). 


e An HWIM application must be provided with an application resource file and so init->flags 
should include rLG_APPMAN_RSCFILE (and hence also FLG_APPMAN_CLEAN). 


e An HWIM application that wishes to create an instance of the system class, in order to access the 
link paste (Bring) system services (described in the System Services chapter of the OLIB Reference 
manual) must set init->£1lags to contain the flag rL¢_APPMAN_LINKING rather than the flag 
FLG_APPMAN_SYSTEM that is required by the appman superclass. If the application wishes to use an 
instance of the OLIB recs class to implement the link paste server, init->£1ags may contain the 
flag FLG_APPMAN_IPCs, as for APpman. Note that, on all machines except on the Series 3, an 
instance of rpcs will always be created (but at a later stage in the initialisation) so the presence or 
absence of the FLc_Appman_1pcs flag is less significant on this machine. 


e If set, the flag FLG_APPMAN_FULLSCREEN Causes applications on the Series 3a and the Workabout to 
run in native, rather than Series 3 compatibility, mode. 


HWIM REFERENCE 
ee SSSSeSFSeSeFeSeeSeeeeeSSSSSSSSSSSSMmMMHheheFeFeFSSFFSSSFSee 


e The additional flag rLc_appman_s3rs may be set. On the Workabout, this causes a Series 3 
application to run in compatibility mode, but using the full 240x100 screen. To take advantage of 
this, the Series 3 application must be able to adjust the size of its display to the available screen 
size. 


¢ The additional flag, rLc_apeman_ownprio may be included, to be written to wsERV property 
(where it is identified as pR_wsERV_owNPRIO). See the chapter The WSERV Class for further details 
of this flag. 


The following operations are performed: 
e Writes its own handle to the magic static w_am. 
e For the Series 3a, loads the general data that can be accessed via the magic static patcate. 


e Attempts to open a language-specific system resource file, expected to be in the ROM. If this 
succeeds, the FLG_APPMAN_SRSCFILE bit in init->flags is cleared to prevent any attempt to open 
the default system resource file by the superclass am_init method. 


e Supersends the am_inrT message to the appman superclass, passing the flag values in 
init->flags. If the previous step failed to load a language-specific system resource file, this will 
include an attempt to open the file (as described in the APPMAN Application Manager Class 
chapter of the OLIB Reference manual). 


e Ifinit->£1lags contains the flag rLc_APPMAN_LINKING, creates and initialises an instance of the 
OLIB system class for communication with the window server process, SYS$WSRV. 


e On the Series 3a anf Workabout, records the current value of the magic static w_ws for later use. 
This will only be non-zero in the case where the application is started, and hence owned, by 
another application (see the description of p_getowner in the Processes and Inter-process 
Messaging chapter of the PLIB Reference manual). A non-zero value is expected to be the address 
of a status word in the owning application's data segment. 


e Creates an instance of the class init->wserv_class from category init->wserv_cat and writes 
its handle to the magic static w_ws - it is assumed to be (a subclass of) the wserv active object 
class. 


e The FLG_APPMAN_ownpRio and (for the Series 3a and Workabout) the FLG_APPMAN_FULLSCREEN 
flag bits, if present, are extracted from init->flags and written to the w_ws->wserv. flags 
property field (where they are known as PR_WSERV_OWNPRIO and PR_WSERV_FULLSCREEN 
respectively). 


e On the Workabout, if the flag FLc_appman_s3Fs is present, sets the pR_xwsERV_s3Fs flag in 
DatGate->gate. flags. 


e The values of the magic statics patprocessNamePtr, DatUsedPathNamePtr and 
DatStatusNamePtr, together with the hwimman.contig, hwimman.defext, hwimman.command and 
hwimman.aliasinfo property fields, are set up as appropriate from the data in the process 
command line, pointed to by patcommandPtr. 


See the example below and The Series 3 command line in the Communicating with the System 
Screen chapter of the Series 3 Programming Guide for a description of the components of the 
command line. Note that this processing of the command line is specifically designed to handle a 
command line of the form that is passed to an application that is started from the System Screen. 
The command line data passed to an application started in any other way may not be of this form. 
In such a case (for example, a custom application running on the Workabout) the application may 
need to provide its own code to process the command line data. 


On the Series 3a and the Workabout there is an option to process a reduced command line, 
signalled by the presence of a command byte with value »_commanp_sypass. In this case, the 
command byte is assumed to be immediately followed by the alias information (rather than the 
ususal public name of the application) and, of the items previously listed, only hwimman. command 
and hwimman.aliasinfo are initialised. The application is expected to perform its own 
interpretation or processing of any additional command line data, starting at the byte pointed to by 
hwimman.aliasinfo. 


e If the application is file-based (DatusedPathNamePtr is not nuLL) and the command byte in 
hwimman->command iS H_COMMAND_DEFAULT_FILE, the flag PR_WSERV_CONNECT_AT_BACK is ored into 


2 HWIMMAN APPLICATION MANAGER 


w_ws->wserv. flags and the value of hwimman->command is converted to either 
H_COMMAND_OPEN_FILE OF H_COMMAND_CREATE_FILE, depending on whether the file specified by 
DatUsedPathNamePtr exists or does not exist. 


e On the Series 3a and the Workabout, if the application is not file-based and the command byte is 
H_comMaNnD_Bypass, the flag pR_WSERV_OWNPRIO is ored into w_ws->wserv. flags. 


e Sends w_ws an ao_INIT message, passing on the wserv parameter (which is a pointer to an 
IN_WSERV Struct). 


e On the Series 3a and the Workabout, sends itself an amM_ENSURE_IPCs message to create an 
instance of rpcs if one does not already exist. 


e Also, on the Series 3a and the Workabout, creates and initialises an instance of the arssv 
automatic test system server class. 


e Enables the future display of a temporary status window by calling wstnableTemp. 


e On the Series 3a and the Workabout, if the previously stored initial value of w_ws was not zero, it 
is assumed to be the address of a status word in the data segment of an owning process. A value of 
zero is written into that status word and the owning process is signalled by means of a call to 
p_iosignalbypid. This notifies the owner that the owned application has completed its 
initialisation and is now ready to receive inter-process messages. 


e Ifall the previous steps are completed without error, Hwrmman sends itself an aM_START message, to 
start the active object event scheduler. This will not return until the application terminates by 
sending Hwimman the corresponding am_stop message. On receipt of this message the application 
is terminated by means of a call to p_exit. If any of the previous steps result in an error, other 
than RUN_ACTIVE_CLEANUP_NONOTIFY, the error is reported by means of a call to p notifyerr 
before the application is terminated by a call to p_exit. 


The method formally returns zero, but the return is never executed since the method always terminates with 
a call to p_exit. Furthermore, an HWIM application will typically terminate with a direct p_exit (0) call, 
rather than sending HWwIMMAN an AM_sToP message (see, for example, the comman com_exit method in the 
Command Manager chapter). 


Although EPOC will not attempt to run the application unless there is sufficient memory for the 
application's start-up heap (as specified by the .app file header - see Greater control over the image file 
created in the Building an Application chapter of the General Programming Manual) the initialisation 
could still fail. Possible reasons for failure include the heap space of the window server process or the file 
server process becoming exhausted, the application being passed the name of a file of the wrong type, or 
running out of memory while loading a large file. 


Command line example 


If the heap cell (pointed to by patcommandPtr) containing the command line for a file-based application 
has, for example, the following content: 


ROM: : WORD .APP<0><0x29>0Program<0>.OPL OROPO<0>LOC: :M: \WRD\MYPROG.OPL<0> 
then, at the conclusion of the am_inrr method: 


hwimman.contig is TRUE 

hwimman.command is '0' (H_COMMAND_OPEN_FILE) 

DatProcessNamePtr points to the string "program" 

hwimman.defext points to the string ".opx" (the original following space is overwritten by zero) 
hwimman.aliasinfo points to the string "oropo" 

DatUsedPathnamePtr points to the string "Loc: :M: \WRD\MYPROG.OPL" 

DatStatusNamePtr points to the string "mypRoG.oPL" 


For an application that is not file-based, and therefore has nothing following the application file name in its 
command line, all the items in the above list will be set to nut. 


AM_RSCNAME 


VOID am_rscname (TEXT *pname) ; 


‘resource file name 


Write, to the buffer pointed to by pname, (which must be at least p_rwamEsize bytes long) the default full 
file specification (see the Files chapter of the PLIB Reference manual) of the application resource file. 


HWIM REFERENCE 
eee eee eeSSeSSSSSSSSSSSSSSSSSSSFesesesesee 


The name is generated from the application's start-up full file specification, pointed to by the magic static 
DatCommandPtr. The name also depends on the current language, as determined by the value returned by a 
call to p_ getlanguage. 


If the language is English (p_get1anguage returns a value of 1) the resource file is assumed to be built into 
the image file, so that the full file specification of the resource file is identical to that of the image file. 


For all other languages the resource file is assumed to be located in the same directory and have the same 
name as the application image file, but with a language-dependent file name extension. The extension is 
assumed to be .~nn, where the characters mn represent the language number, as two decimal digits. Thus, a 
German language resource file would have a .~03 extension. 


This method is designed for use by built-in applications, whose resource files are in the ROM:: device 
(which does not support subdirectories) and whose default language is English. A multi-lingual application 
that is run from an SSD should subclass this method. 


The following example, for a myHwman subclass of xwimman, implements the scheme described in the 
Resource Files chapter of the Additional System Information manual. In this scheme the resource file for 
the default language is built into the image file. Resource files for other languages are located in a 
subdirectory of the directory containing the application image file. The subdirectory has the same name as 
the application and the resource file name is derived from the application name, with the final two 
characters containing the language number. 


METHOD VOID myhwman_am_rscname(PR_MYHWMAN *self, TEXT *pname) 
{ 
TEXT *p; 
P_FPARSE crk; 
P_INFO f; 
TEXT buf [10]; 


p_fparse (DatCommandPtr, NULL, pname, &crk) ; 
p=pname+crk.system+crk.device+crk.path; 
*(p_bepy (&buf [0] ,p,crk.name) ) =0; 


‘pete \\'; 
p=p_sepy (p, &buf[0)); 
pete! \\'; 


if (crk.name>6) 

crk .name=6 ; 
p=p_bepy (p, &buf [0] ,crk.name) ; 
p_atos(p,"%02d.rsc",p getlanguage()); 
if (p_finfo(pname, &£) <0) 

P_scpy (pname, DatCommandPtr) ; 


The default resource file, built into the image file, is used if a particular language is not supported by a 
corresponding resource file. 


Of course, in a specific application - where the resource file name is known - less gereral code can be used 
for this method. 


Wait for an event 


VOID am_wait (VOID) ; 


Send w_ws an AO_QUEUE message, to ensure that window server events will be processed (a queued read 
may have been cancelled) and then call p_iowait. 


ip resources an ort an error 


VOID am_clean_up(INT err,UBYTE *htask) ; 


Call wcleanup to free any window server temporary resources, supersend the AM_CLEAN_UP message to 
provide the standard error recovery and reporting, then set appman. err to zero. 


2 HWIMMAN APPLICATION MANAGER 


AM_NEW FILENAME Record a new filename 
VOID am_new_filename (TEXT *newname) ; 


Record the new file name pointed to by newname. The buffer pointed to by newname must remain in 
existence until the name is changed again. 


If the current file name is specified to be in the process command line (hwimman. contig is TRUE) then the 
allocated heap cell containing the command line is truncated to remove the name, and hwimman. contig is 
set to FALSE. 


The magic statics patusedPathNamePtr and DatStatusNamePtr are set up to point to the appropriate 
positions in the text string. 


1 an error 


VOID am_notifyerr(INT err,INT resid) ; 


Notify an error for error number err, with text as specified by the resource id resid providing additional 
information about the context of the error. This text may be up to 80 bytes in length (50 bytes for the 
Series 3). If no additional text is required, resia may be zero. 


This method is guaranteed to succeed in displaying an error message. 


Cancels any busy indicator by calling wcance1BusyMsg and writes zero to the wsERv active object's 
wserv.£ilter property. On the Series 3a the value of wserv.£ilmethod is also set to zero but, provided the 
original value of wserv.£ilmethod was negative (ie it is a ‘permanent filter - see the WSERV Class 
chapter) both values are restored after notification of the error. On the Series 3, any application that needs 
to restore wserv. filter to its original state on conclusion of the error report may need to subclass the 
am_notify method. 


If err has the value RuN_ACTIVE_CLEANUP_NonoriFy the method returns, without displaying any error 
notification. On the Series 3 the value of wserv.£ilter will have been cleared, but on the Series 3a and the 
Workabout, both wserv. filter and wserv.filmethod are preserved. 


Unlike in the superclass am_notifyerr method, the p_notify service is not used. The method calls the 
hErrorDialog utility function, to attempt to display the error in an error dialog. If this fails due to lack of 
memory, the error is displayed as an alert, by sending w_ws a wS_ALERT message. This alert cannot fail, but 
may not display any context information specified by resid if the attempt to load this resource fails. 


Using one of these two forms of error display means that the error notification is application modal; only 
that application is suspended and the user may task switch to another application. The superclass method is 
system modal, preventing interaction with any application until the user has responded to the error report. 


VOID am_yield (VOID) ; 


Use an idle active object to suspend the current action until all active objects with priority greater than 
PRIORITY_ACTIVE_COMPUTE have had the opportunity to service their outstanding events. 


Automatically creates an instance of the OLIB arnt class, if it does not already exist, storing its handle in 
hwimman.yield. Sends this object an ao_quEUE message and then sends itself an am_sTART message, which 
will not return until the idle object has had an opportunity to run. 


ition image file 


INT am_findimg (VOID) ; 


Refuse to continue until the image file has been located. 


If the image file can not be found, it is assumed that this is because the SSD containing it has been 
removed. The application is suspended by sending a ws_ALERT message to wsERV, displaying an alert 
requesting that the SSD be replaced. 


It is worth noting that, in consequence, the am_load_res_buf method can never fail in an HWIM 
application. 


HWIM REFERENCE 


AN Guarantee existence of IPCS 


VOID am_ensure_ipcs (VOID) ; 


This method is not available on Series 3 computers. 


If it does not already exist, create the application's instance of the rpcs class. The handle of the instance is 
written to appman.ipcs. 


This method is called from the am_init method, following the sending of the ao_1nrv message to the 
applications instance of (a subclass of) the wsErv class. 


An application is free to call this method at an earlier stage - for example, from the wsERV ws_dyn_init 
method. 


CHAPTER 3 


THE WSERV CLASS 


q 
priority 
isactive 
peb 

stat 


destroy 


ws 
com 

dial 

bar 

cli 

info 
oldinfo 
filter 
£filmethod 
flags 


ao_init 

ao_cancel 
ao_queue 

ao_run 

ws_do_dial 
ws_add_ dial 
ws_remove_dial 
ws_sense_accel 
ws_change_cliwin 
ws_cancel 
ws_wrap_para 
ws_error_dialog 
ws_query dialog 
ws_do_help 
ws_do_submenu 
ws_set_menubar 
ws_reset_menubar 
ws_load_chlist_res 
ws_append_country 
ws_free dial 
ws_smart_dial 
ws_dial_env 
ws_lock 
ws_format_dialog 
ws_evaluate 
ws_eval_env 
ws_sense_pdev_text 


help_index_id 
help 

lock 

subdial 
sc[10] 
locmask 
filelist 

anim 

printer 


ws_edit_pdev_serup 
ws_edit_print_context 
ws_ens_print_context 
ws_add_filelist 
ws_remove_filelist 
ws_anim_tick 
ws_switch_ files 
ws_alert 

ws_unknown 
ws_foreground 
ws_background 
ws_dyn_init 
ws_process_ key 
ws_date_changed 
ws_launch_dyl 
ws_define_fnbar 
ws_hook_today_ changed 
ws_get_alloc_info 
ws_get_print_context 
ws_self_check 
ws_hide_app 
ws_attach_app 
ws_file_ info print 
ws_run_memo 
ws_do_remote_dial 
ws_user_abandoned 


An instance of the wsErv active object class is the application's event source for events (keypresses, 
redraws and so on) generated by the window server process. Every HWIM application must create a WSERV 
object at an early stage in its initialisation and this instance should remain in existence until the application 
terminates. 


The handle of the wserv object is stored in the w_ws magic static and can be accessed by the associated 
application. 


HWIM REFERENCE 
SSS 


In addition to its main role as the source of window server events, WSERV supplies a number of general 
services and utilities, including, for example, methods to: 

e — start up an application-specific dialog 

e una variety of system-supplied dialogs 

e evaluate a numeric expression 

e word wrap a paragraph of text 


An application is expected to subclass wserv, at least to supply a ws_dyn_init method which should 
perform all application-specific initialisation. 


Subclassers may, where appropriate, replace existing methods but, for future compatibility, should avoid 
adding new methods or property. 


Precursors 

Familiarity with the following topics will aid the understanding of this chapter: 
e the p_enter and p_leave error handling services 
e the OLIB active active object class. 


Class diagram 


eine tale 


/ shutter “> 


Class definition 


Defined in sub-category file hwimman.cl (generated header file hwimman.g). 


CLASS 


The window server active object 


{ 


wserv active 


REPLACE ao_init 


REPLACE ao_cancel=p_ dummy 


REPLACE ao_queue 
REPLACE ao_run 


ws_do_dial 
ws_add_ dial 
ws_remove_dial 
ws_sense_accel 
ws_change_cliwin 
ws_cancel 

wsS_wrap para 
ws_error_dialog 
ws_query dialog 
ws_do_help 

ws_do_ submenu 
ws_set_menubar 
ws_reset_menubar 
ws_load_chlist_res 
ws_append_country 
ws_free dial 
ws_smart_dial 
ws_dial_ env 
ws_lock 


Queue a message from the server 

Process a message from the server 

Start a dialog going 

Add a dialog to the list 

Remove a dialog from the list 

Lookup an accelerator for a pull down menu 
Log in a new client window 

Cancel pending window server read 

Wrapping service 

error dialog 

query dialog 

Help system 

Run a submenu 

Set an alternative menu bar 

Reset the menu bar 

Get text of a chlist item direct from resource file 
country selector dialog, for mark up purposes 
Invoke the free-form dialling dialog 

smart dial of a number with reference to home 
Set or get dial setup environment variable 
Increment or decrement the lock count 


3 THE WSERV CLASS 


ooo eee AOD 


ws_format_dialog 

ws_ evaluate 
ws_eval_env 
ws_sense_pdev_text 
ws_edit_pdev_setup 
ws_edit_print_context 
ws_ens_print_context 
ws_add_filelist 
ws_remove_filelist 
ws_anim_tick 
ws_switch_files 
ws_alert 
ws_unknown_wm=p_dummy 
ws_foreground=p_dummy 
ws_background=p_dummy 
ws_dyn_init=p_dummy 
wS_process_key 
ws_date_changed 
ws_launch_dyl 
ws_define_fnbar 
ws_hook_today_changed 
ws_get_alloc_info 
ws_get_print_context 
ws_self_check=p_false 
ws_hide_app 
ws_attach_app 
ws_file_info_print 
ws_run_memo 

ws_do remote_dial 
ws_user_abandoned 


TYPES 


{ 


typedef struct 
{ 
HANDLE com_cat; 
UWORD com_class; 
} IN_WSERV; 


typedef struct 


{ 
UBYTE menu; 
mnitem; 
menubar_id; 
first_com; 
count; 
UBYTE accel [1]; 

} WSERV_INFO; 


typedef struct 
{ 
UWORD id; 
VOID *rbuf; 
PR_DLGBOX **pdilg; 
} DL_DATA; 


typedef struct 


{ 
TEXT *dupnp; 
TEXT hidden [6] ; 


} WS_HIDE_APP_DATA; 


typedef struct 
{ 
UWORD margin; 
UWORD fmargin; 
WORD font; 
UWORD style; 
WORD nlines; 
UBYTE *ptable; 
} WRAP_DATA; 


Launch set format dialog for evaluator or calc 
Evaluate an expression 

Set or get evaluator environment variable 
Sense text describing current printer device 
Invoke printer device setup dialog 

Invoke print setup dialog 

Check context data has been initialised 

Add a filelist to the list 

Remove a filelist from the list 

Animator has ticked over 

Switch files instruction received 
Subclassable interface to wsAlert 

Unknown message received from server 

Process WM_FOREGROUND 

Process WM_BACKGROUND 

Applications usually supply this 

Process WM_KEY 

Process WM_DATE_CHANGED 

Launch DYL in response to wGetCommand('L') 
Utility layer over wsSetList 

Request or cancel today changed notification 
p_allent facility 

Fetch printer context from other process 

For access by IPC testing or otherwise 

Hide or show application 

Appear to attach to other application 
Present standard file infoprint 

Run memo editor 

Run dialog in attached process 

Exit application with alert 


command manager category 
command manager class 


Which menu was pulled down 

Which item was selected in the menu 
Resource ID of menu bar 

Method number of first command 
Number of accelerators 

Accelerator keys 


Comes from a resource file 


dialog resource ID 
NULL or address of dialog result buffer 
NULL or location to receive handle of dialog 


Stores DatUsedPathNamePtr 
Por "SYSSK" 


Width in pixels to fill with text 
Width of margin for first line 
Font used 

Style used 

Max no lines to add to table 
Table to write line lengths to 


HWIM REFERENCE 


> kee 


typedef struct 
{ 
UWORD ncells; 
UWORD nbytes; 
} WS_ALLOC_INFO; 


typedef struct 
{ 
VOID *next; 
VOID *object; 
UWORD message; 
} WS_TODAY_HOOK; 


typedef struct 
{ 
UWORD len; 
VOID *p; 
} MEMO_DATA PART; 


typedef struct 
{ 
MEMO_DATA_PART body; 
MEMO_DATA_PART styles; 
MEMO_DATA_PART title; 
} MEMO_DATA; 


typedef struct 
{ 
VOID *owner; 
UWORD method; 
} MEMO_CALLBACK; 


} 


CONSTANTS 
{ 
PR_WSERV_CONNECT_AT BACK 
PR_WSERV_FOREGROUND 
PR_WSERV_CLIWIN_KEY 
PR_WSERV_CANCELLING 
PR_WSERV_BASIC_HELP 
PR_WSERV_FREEFORM_DIALLING 
PR_WSERV_INSERT_MODE 
PR_WSERV_INSERT_PENDING 
PR_WSERV_OWN_DEFAULT_FONT 
PR_WSERV_RECEIVED_KEY 
PR_WSERV_HIDDEN 
PR_WSERV_ METRIC 
PR_WSERV_FULLSCREEN 
PR_WSERV_CANCELLING DIALOG 
PR_WSERV_FROM_HWIF 
PR_WSERV_OWNPRIO 
PR_WSERV_HELP_INDEX 
WSERV_DTOB_HEX 3 
DEGREES_MODE 0x80 
DTOB_MAX WIDTH 20 
WS_EVAL_ENV_SET 0 
WS_EVAL_ENV_GET 1 
WS_DIAL_ENV_SET ) 
WS_DIAL_ENV_GET 1 
PDEV_TEXT_MAX_LEN 14 


WS_LOCCHG_Low 0x0100 
WS_LOCCHG_HIGH 0x4000 
WS_EM_STYLES 
WS_EM_PRINT_CONTEXT 
WS_EM_REUSE_ BODY BUFFER 


WS_EM_REUSE STYLES BUFFER 
WS_EM_ CALLBACK 

MEMO_NO_CHANGE ) 
MEMO_NULL_LENGTH 1 
MEMO_STANDARD CHANGE 2 


} 


W_CONNECT_AT_ BACK 
0x02 

0x04 

0x08 

0x10 

0x20 

0x40 

0x80 

0x100 

0x200 

0x400 

0x800 

0x21000 

0x2000 

0x4000 

0x8000 

0x01 (Bit re-used) 
continue from P_DTOB type 


(ie 0x01) 


-X.xx...x (13 dec places) e-99 


0x01 
0x02 
0x04 
0x08 
0x40 


PROPERTY 


} 


{ 

WS_EVENT_X ws; 
PR_COMMAN *com; 
PR_DLGCHAIN *dial; 
PR_MENUBAR *bar; 
PR_WIN *cli; 
WSERV_INFO *info; 
WSERV_INFO *oldinfo; 
PR_WIN *filter; 

INT filmethod; 
UWORD flags; 

UWORD help_index_id; 
UWORD help; 

UBYTE lock; 

UBYTE subdial; 

TEXT sc[10); 

UWORD locmask; 
PR_ROOT *filelist; 
PR_ROOT *anim; 
PR_ROOT *printer; 


} 


3 THE WSERV CLASS 
—_—<—“— ee SER CLASS 


to take WSERV event 

command manager 

handle of current dialog, or NULL 

menu bar (if present) 

client window (if present) 

menu bar ID, command manager cat and class ete 
store info when in submenu mode 

send all keys here if non-NULL 
possible filter message (if not WN_KEY) 
foreground state, etc 

resource ID of application help index 
count of help screens 

count of how many times locked 

index of subdialog to launch, less one 
array of special characters 

mask for locchg 

topmost filelist 

animator 

print manager 


The following methods, structures and defined constants are not available on the Series 3. 


Methods: 


ws_process_ key 
ws_date_ changed 
ws_launch_dyl 
ws_define_fnbar 
ws_hook_today_changed 
ws_get_alloc_info 
ws_get_print_context 
ws_self_ check 
ws_hide_app 
ws_attach_app 

ws_ file info_print 
ws_run_memo 
ws_do_remote_dial 
ws_user_abandoned 


Structures: 


WS_HIDE_APP_DATA 
WS_ALLOC_INFO 
WS_TODAY_HOOK 
MEMO_DATA_PART 
MEMO_DATA 
MEMO_CALLBACK 


Constants: 


WS_EM_STYLES 
WS_EM_PRINT_CONTEXT 
WS_EM_REUSE_BODY_BUFFER 
WS_EM_REUSE_STYLES_BUFFER 
WS_EM_CALLBACK 
MEMO_NO_CHANGE 
MEMO_NULL_LENGTH 
MEMO_STANDARD_CHANGE 


The constants PR_WSERV_HIDDEN and PR_WSERV_FULLSCREEN have replaced the Series 3 constants 
PR_WSERV_SHUTTER and PR_WSERV_MACRO_DIALOG respectively. Neither of these two Series 3 constants were 
used in any Series 3 application code. 


HWIM REFERENCE 


eos eee 


Property 


WSERV property is accessible via the w_ws magic static. Although this means that the property may be 
accessed from any point in the application code, the property should, except where write access is 
specifically allowed, be considered as read-only. 


wserv. 


wserv. 


wserv. 


wserv. 


wserv. 


wserv 


wserv. 


wserv. 


ws 


com 


dial 


bar 


cli 


.info 


oldinfo 


filter 


This, together with the immediately preceding active. stat superclass 
property, effectively forms a ws_Ev struct, in which is stored the data 
relating to a window server event. The ws_EventT_x and wS_Ev structs are 
defined in wilib.h as: 


typedef struct 
{ 
UWORD handle; /* Destination handle */ 
UWORD time; 
WS_EVENT_UNION u; 
} WS_EVENT_X; 


typedef struct 
{ 
WORD type;/* E_FILE_PENDING, err or (+ve) event */ 
UWORD handle; 
UWORD time; 
WS_EVENT_UNION p; 
} WS_EV; 


Note that the ws_kv struct and the ws_rvenr struct (also defined in wiib. h) 
are alternative descriptions of the same physical structure. The 
WS_EVENT_UNION struct is a union of the structures used to store the details 
of each of the possible window server events (keypress, redraw, etc) and is 
also defined in wiib.h. 


The handle of the application's command manager, assumed to be an 
instance of (a subclass of) comman, set by system initialisation code, in the 
wserv_ao_init method. 


NULL if the application is not currently displaying a dialog, otherwise the 
handle of the application's current (foremost) dialog (but see the 
ws_add_diai method). 


NULL if the application is not displaying a menu bar, otherwise the handle 
of the application's menu bar, set by system code in the ws_process key 
and ws_do_submenu methods. 


The handle of the application's client window, set by application-specific 
initialisation code (in ws_dyn_init ) and modified either directly by 
application code or by the ws_change_cliwin method. 


A pointer to a WSERV_INFo struct, containing the the current menu bar and 
accelerator data. This data is initially loaded from the application resource 
file during wserv initialisation of an HWIM application. The elements 
wserv.info->menu and wserv. info->mnitem respectively indicate which 
menu was last pulled down and which item was selected in that menu (if 
both are zero this indicates the first item in the first menu). An application 
may read (and, if necessary, write to) either or both of these elements. 


A pointer to the main menu bar and accelerator data while an alternate 
menu or submenu is in use. 


If not nuut, indicates that keyboard input is filtered, by being diverted 
away from its normal destination. The value of wserv.filter may be either 
-1 to discard all incoming keypresses, or the handle of a window to which 
all keypresses are diverted. An application may write this property. 


3 THE WSERV CLASS 


—_—_--_—— Corwen READS 


wserv. 


wserv. 


wserv 


wserv 


wserv. 


wserv. 


wserv. 


wserv. 


wserv. 


wserv 


wserv. 


filmethod 


flags 


-help_index_id 


-help 


lock 


subdial 


sc 


locmask 


filelist 


-anim 


printer 


State flags 


If not zero, the method number of the message to be sent to the object 
specified by wserv.£ilter on receipt of a keypress. Otherwise a wn_KEY 
message is sent. On the Series 3a, if the method number is stored in 
wserv.filmethod as a negative value, the filter is said to be permanent. A 
permanent filter allows keyboard access to the application's Help and is 
preserved across error notification by the application manager's 
am_notifyerr method. Note that the concept of a permanent filter does not 
exist on the Series 3. An application may write this property. 


A collection of state flags, described below. 


Either zero or the resource ID of the application's Help index. An 
application may write this property. 


A count of the number of levels of help currently being displayed, 
incremented and decremented by system code, in the ws_do_help method 
and the destroy method of the HELppte class. 


Zero if the application is not locked. Otherwise a count of the current 
number of times the application is locked. The count is incremented and 
decremented by the ws_lock method. 


Set and cleared by system code and used to identify a subdialog to be 
launched by the current dialog. Application code should not modify this 
item. 


A buffer containing special characters, loaded from the system resource 
file during wserv initialisation of an HWIM application. 


A bitmask used to ensure that successive items in the wserv. filelist list 
have distinct bits set, in the range ws_LOcCHG_Low to WS_LOCCHG_HIGH 
inclusive, for use with calls to p_locchg. 


Either nut or the handle of the first item in a list of FrILELIST instances. 


Either wowt or the handle of an instance of the OLIB anrmator class, used 
when wserv. filelist is not NULL to send WSERV a WS_ANIM_ TICK message 
every three seconds. 


The handle of the application's print manager, assumed to be an instance 
of (a subclass of) the FORM printer class, set by the 
ws_ens_print_context method. 


The state flags, stored in wserv. flags, may be any combination of the pr_wseRv_xxx flags specified in the 
class definition (with the exception of PR_WSERV_CONNECT_AT_BACK). 


The flags may be divided into several groups. The first group consists of those wserv flags that may be 
written into wserv. flags by the HWIMMAN am_init method, before it calls the wsERV ao_init method. 


PR_WSERV_OWNPRIO 


PR_WSERV_FULLSCREEN 


TRUE if the application is to connect to the window server with the 
priority specified in the header of its .app file. Otherwise the process 
priority is determined by the window server's client process priority 
management mechanism. This flag may be set explicitly (as 
FLG_APPMAN_OWNPRIO) in the flags passed to the application's 
instance of Hwimman from the start-up code in main(). 


On the Series 3a, rauss if the application is running in compatibility 
mode. Only applications writtm expressly for the Series 3a set this 
flag to rruE. This flag may be set explicitly (as 
FLG_APPMAN_FULLSCREEN) in the flags passed to the application's 
instance of Hwimman from the start-up code in main(). 


HWIM REFERENCE 


cr 


PR_WSERV_CONNECT_AT_BACK 


TRUE if the application is to connect to the window server as a 
background process. This flag is exceptional in that it is used during 
initialisation, but is not stored permanently in wserv.flags - its 
value is reused for PR_WSERV_HELP_INDEX. The HWIMMAN am_init 
method includes this flag automatically if the command line 
includes the command byte H_comMAND_DEFAULT_FILE. It can not be 
set explicitly in the flags passed to the application's instance of 
HWIMMAN from the start-up code in main(). An application that 
expressly wishes to make a background connection to the window 
server should replace the wseRV ao_init method to or 
PR_WSERV_CONNECT_AT_BACK into wserv.flags and then supersend 
the ao_INIT message. 


The next group consists of those flags used to record semi-permanent state information. These are read and 
written by system code, but may also be read by application code: 


PR_WSERV_FOREGROUND 
PR_WSERV_METRIC 


PR_WSERV_RECEIVED KEY 


PR_WSERV_HIDDEN 


TRUE if the application is the foreground process. 
TRUE if metric units are selected. 


TRUE if the application has received a key since coming to 
foreground. 


On the Series 3a, this flag indicates whether the application is 
hidden, being set or cleared by the ws_hide_app method. On the 
Series 3 it is used internally, under the name PR_WSERV_SHUTTER, in 
code that controls the locking of an application against Shutdown or 
Switchfiles messages from the System Screen. 


The next group contains flags that are generally of no interest to application code. Most of them indicate 
states that are more transient than those of the previous group. 


PR_WSERV_HELP_INDEX 


PR_WSERV_BASIC_HELP 


PR_WSERV_FREEFORM_DIALLING 


PR_WSERV_CANCELLING 


PR_WSERV_CANCELLING DIALOG 


PR_WSERV_FROM_HWIF 


TRUE if a help index dialog is present. 


Used during the display of Help to indicate that a ‘Help on help’ 
dialog is present. 


TRUE if the free-form dialling dialog is present. 


Used internally by the mechanism that cancels a read request on the 
window server process. 


Used internally by the dialog cancel mechanism. 


Must always be rause for an HWIM application. 


The final group contains flags that are primarily intended for use by an application. Although system code 
may set or clear them as a service to an application, the application may also write these flags. 


PR_WSERV_OWN_DEFAULT_FONT 


PR_WSERV_CLIWIN_KEY 


an application, such as Word, that supplies its own specification of 
printer fonts, rather than using a single default printer font, should 
set this flag. It is read by the prnmopex dialog and, if set, disables the 
selection of a default font for printed output 


cleared by the ac_run method when a keypress is sent to a 
destination other the client window. Used by the Word application 
to abort the two-character sequence that enters a style or emphasis 
shortcode 


3 THE WSERV CLASS 
——_—_ OE WISER CLASS 


PR_WSERV_INSERT_PENDING cleared when a keypress event arrives with a keycode of 0x100 or 
greater, or (but only when using epw1n) when the keypress is either 
Psion-Delete or Shift-Psion-Delete. Used by the Word application, 
together with PR_WSERV_INSERT_MODE, to control the creation of, and 
insertion into, an emphasis region by entering a two-character 
shortcode sequence and then typing characters 


PR_WSERV_INSERT_MODE cleared when a keypress event arrives with a keycode of 0x100 or 
greater, or (but only when using epwzn) when the keypress is either 
Psion-Delete or Shift-Psion-Delete. See pR_WSERV_INSERT_PENDING 


i Se i 
WSERV methods 


VOID ws_dyn_init (VOID) ; 


The application's wserv receives a ws_DyN_InrIT message at the end of the processing of the ao_init 
method. The supplied method does nothing. 


An application is expected to subclass wserv to supply a replacement ws_dyn_init method that performs 
application-specific initialisation. 


The application should create and initialise all objects that are required to display the initial view. This will 
generally involve at least the creation and initialisation of a client window, whose handle should be written 
to wserv.cli. 


An application that has engine components should create and initialise these components either directly 
from the ws_dyn_init method, or during the initialisation of the client window, depending upon which 
alternative is more convenient. 


A file-based application should open or create a file, depending on the data stored in 
w_am->hwimman.command and the file name pointed to by patusedPathNamePtr. It may also have to take 
note of the alias information in w_am->hwimman.aliasinfo. 


VOID ao_init (IN_WSERV *init); 


This method is documented for information only. It should not, in general, be replaced in any application- 
specific subclass of wsERV. One exception to this rule is to make a background connection to the window 
server, as indicated in the earlier description of the PR_WSERV_CONNECT_AT_BACK flag. 


Initialise the wsERv active object. 
The following points indicate significant aspects of the initialisation code: 


© wsERV adds itself to the application manager's active object queue with priority 
PRIORITY _ACTIVE_WSERV. 


e Special characters (those with u_sc_xxx #defines in symbols.h) are loaded into the wserv.sc 
buffer from the system resource file. Every HWIM application must therefore have access to the 
system resource file. 


e The method loads resource number | from the application's resource file into wserv. info. This 
resource is expected to be a WsERV_INFo resource struct (defined in Awim.rh, and duplicating the C 
WSERV_INFo struct that is declared in the wserv class definition). Every HWIM application must 
therefore have a resource file. 


© wserv. flags initially contains data written by the HwIMMAN am_init method and thus may contain 
any combination of PR_WSERV_OWNPRIO, PR_WSERV_CONNECT_AT_Bacx. and (on the Series 3a) 
PR_WSERV_FULLSCREEN. The application allocates memory for a WsERV_sPEc struct and connects to 
the window server, by calling wconnect, passing the address of this struct and the appropriate 
combination of w_coNNECT_PRIORITY and w_coNNECT_aT Back flags. The call to wconnect writes 
the address of the wserv_spxc struct to the magic static wserv_channel (application code may 


———SeSeSeSSSSeSeeSeSeeSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS 
3-9 


HWIM REFERENCE 
eee 


subsequently read the contents of the comvect_inFo struct accessed by wserv_channel->conn - 
see the description of wconnect in the General Window Server Functions chapter of the Window 
Server Reference manual). The PR_WSERV_CONNECT_AT_BACK flag is removed from wserv. flags, 
for later reuse as the PR_WSERV_HELP_INDEX flag. 


¢ On the Series 3a, if wserv. flags contains PR_WSERV_FULLSCREEN, the application is switched out 
of compatibility mode by means of a call to wcompatibilityMode. On the Workabout, full screen 
compatibility mode is set if patcate->gate.flags contains PR_XWSERV_S3FS. 


e On the Series 3a the pseudo-constant data that is accessed via the patcate magic static is set up 
(including patGate->gate.x and, additionally for the Workabout, patcate->gate .dx - see the 
chapter: The GATE Class). 


¢ An instance of a command manager, whose class and category are specified by the In_WSERV 
struct pointed to by init, is created and sent a com_rnrT message. All HWIM applications must 
therefore have a command manager, which will normally be a subclass of comman. 


e Ifacall to p_getctd indicates that the machine is currently set to use metric units, 
PR_WSERV_METRIC is ored into wserv. flags. 


¢ The final action of the ao_init method is to send a ws_pyn_rnzT message. The application must 
subclass wsERv to supply this method. 


INT ao_queue (VOID) ; 


HWIM applications are not expected to replace or to make explicit use of this method. 


If there is already an outstanding read (note that the Hwrmman am_wait method always sends wsERv an 
AO_QUEUE message) flush the client-side buffer by calling wcheckPoint. If this were not done window 
server calls (for example, wInvalidateRect) could, in some circumstances, remain buffered for an 
indefinite period of time. Regularly flushing such calls ensures that any consequential wm_REDRAW event is 
received promptly and the screen's appearance is kept up to date. 


Otherwise, queue a read to the window server process by calling weetEvent and then setting 

active. isactive to TRUE. The call sets active.stat to E_FILE_PENDING. On completion of the read, the 
result will be written to active.stat and the immediately following wserv.ws (these two items of property 
effectively form a ws_Ev struct, described earlier in this chapter). 


For historical reasons the method returns zero. 


Cancel 


VOID ao_cancel (VOID) ; 


HWIM applications are not expected to replace this method. 
Does nothing. The wserv cancel functionality is performed by the ws_cance1 method, described below. 


The reason for this is that an active object's ao_cancel method is called from the object's destroy method, 
but the wserv cancel action is not appropriate when wseErv is being destroyed. 


To some extent this is no longer necessary since the current tendency is that an application never destroys 
its instance of wsERv, relying on operating system code to recover an application's resources when the 
application terminates. 


| any pendint IW Server read 
VOID ws_cancel (VOID) ; 

HWIM applications are not expected to replace this method 

Cancel any pending read queued on the window server process by calling wcancelGetEvent. 


Since the destruction of a window involves operations on both the client side and the server side of 
application/window server interaction, it is possible that the window server could send an event, such as a 
redraw event, destined for a window that is in the process of being destroyed. To prevent this possibility, 


3-10 


3 THE WSERV CLASS 


the ws_cance1 method is called at an early stage of any window destruction sequence called from within 
the run method of an active object (apart from wsznv itself). This is done automatically when required and 
it is not expected that an application will ever have to make explicit use of this method. 


Note that there is no need to explicitly requeue a request following a cancel since wsERv is sent an 
AO_QUEUE message by the HWIMMAN am_wait method. 


Process a message: e server 


INT ao_run (VOID) ; 


HWIM applications are not expected to replace this method. 


Handle an event that indicates the completion of a window server read - the application has received an 
inter-process message from the window server process. On entry to the method the event type is in 
active.stat and any further data relating to the event is in wserv.ws. In particular, if relevant, the handle 
of the destination window is in wserv.ws. handle. 


The ao_run method always returns RUN_ACTIVE_USED. 


If the event is not one of those listed below, wserv sends itself a ws_UNKNowN_wM message. Otherwise the 
various event types are handled as follows: 


WM_REDRAW 


Sends the destination window a wn_REDRAW message, passing the address of wserv.ws.u.rect, specifying 
the rectangle to be redrawn. 


WM_FOREGROUND 


If wserv. flags contains PR_WSERV_HIDDEN, indicating that the application has attached to another process 
(this mechanism is not available on the Series 3) that process - provided it has not terminated - is brought 
to the foreground by means of a call to wclient Position. Otherwise, processing is as follows. 


Clears PR_WSERV_RECEIVED_XEY and set PR_WSERV_FOREGROUND in wserv. flags. If wserv.anim is not NULL, 
it is sent an Ao_QUEUE message with a time interval of zero, to restart any animated message. wserv then 
sends itself a ws_FOREGROUND, TRUE Message. 


WM_BACKGROUND 


Clears PR_WSERV_FOREGROUND in wserv. flags. If wserv.anim is not NULL, it is sent an AO_CANCEL message 
to suspend any animated message. wserv then sends itself a ws_BACKGROUND, FALSE Message. 


WM_COMMAND 


Processes an Exit or a Switchfiles message from the System Screen. Does nothing if the magic static 
DatLocked is non-zero. 


If DatLocked is zero, calls the window server function weet commana. If the content of the first byte of the 
resulting command buffer is H_commanp_Ex1T, the HWIM utility function hwservcomsend is used to send 
the command manager a com_ExIT message. Otherwise the command string is assumed to contain a file 
name and wserv sends itself a ws_swrTCH_FILES message, passing the address of the (temporary) command 
buffer. 


WM_CANCELLED 
There is no action on receipt of this event. 
WM_KEY 


If DatGate->gate.getkeys is not NULL, it is the handle of an instance of atssv. This object is notified of 
the receipt of a keypress by being sent an sv_key message (see the Series 3a Automatic Test System chapter 
of the Object Oriented Programming Guide, and the description of arssv in the Automatic Test System 
Classes chapter of the XADD Reference manual). 


WSERV Sends itself a ws_PROCESS_KEY message, passing the values of wserv.ws.u.key. keycode and 
wserv.ws.u.key.modifiers. 


Note that, on the Series 3, the ws_process_key method does not exist. On the Series 3, processing 
equivalent to that described for the ws_process_key method is performed by code that is called directly 
from the ac_run method. 


HWIM REFERENCE 


WM_DATE_CHANGED 


WSERV sends itself a ws_DATE_CHANGED message. 


This event will not occur on the Series 3. 


Process WM_KEY 


VOID ws_process_key(INT keycode, INT modifiers) ; 
This method is not available on the Series 3. 


On the Series 3, equivalent processing is performed by code that is called directly from the ao_run method. 
There are minor differences between the code executed in the two cases and, where significant, the 
differences are noted in the following description. Note that the Series 3 W_KEY_MODE keycode is broadly 
treated in the same way as described for w_KEY_DIAMOND. 


Unless otherwise stated, the processing of all types of keypress terminates with the clearing of the 
PR_WSERV_CLIWIN_KEY flag in wserv. flags. 


The method first clears the w_caps_MoDIFIER flag in modifiers since the caps lock status is of no 
significance to HWIM key processing. It sets the PR_WSERV_RECEIVED_KEY in wserv. flags to record that a 
keypress has been received since the last time the application became the foreground process. 


There is some further manipulation of the keycode and modifiers values to aid the distinguishing and 
recognition of command accelerators. If keycode is w_KEY_DIAMOND and modifiers contains 
W_PSION_MODIFTIER, the value w_spEcraL_KEY is ored into keycode. If modifiers contains 
W_CTRL_MODIFIER, the w_spEcIaAL_xey flag is removed from keycode, regardless of the value it contains; 
no keypress will be recognised as an accelerator if the Control key is held down. 


If the keypress is not consumed by a keyboard filter, as described below, and if keycode is greater than 
ox££ (cursor movement keys and others - see the Events chapter of the Window Server Reference manual 
for a full list of the keys concerned) the PR_WSERV_INSERT_MODE and PR_WSERV_INSERT_PENDING bits are 
cleared in wserv. flags, as a service to the Word application (see the earlier description of these flags). 


The keypress may be dispatched to one of a number of destination objects, as illustrated in the following 
diagram, where the clockwise order of the destinations broadly indicates their priorities. The destination 
depends on both the type of the keypress and the presence or absence of the various destination objects, as 
described below. 


ws_do_help wn_key 


window server 
process 


The menu bar is 
created when the 
Menu key is pressed 


wn_key 
—~, 


com_statwin 
com_accl_check 
com_menu 
com_mode_change 


The command manager also 
has a set of methods that 
correspond to menu items 


3 THE WSERV CLASS 
—_ SSE WISER CLASS 


Keyboard filters 


Keyboard input may be filtered, that is, diverted from its normal destination, by setting a non-zero value 
for wserv. filter. The filter behaviour may be further modified by the value of wserv. filmethod. 


If wserv. filter is equal to -1, regardless of the value of wserv.filmethog, the keypress is discarded and 
processing of the keypress terminates. 


Any other non-zero value of wserv. filter is assumed to be an object handle and a message is generally 
sent to that object. The only exception is that a permanent filter (wserv. £ilmethod is negative) does not 
filter the Help key, nor does it filter any key if Help is being displayed. (Note that this exception does not 
apply to the Series 3, which does not support the concept of a permanent filter.) 


If the absolute value of wserv.£ilmethod is not zero it is assumed to be the method function number of the 
message to send to wserv. filter, otherwise a wi_kEy message is sent. In all cases the message contains 
the parameters keycode and modifiers. The message may return a value of WN_KEY_CHANGED to indicate 
that the keypress has been ‘consumed and that no further processing is required. For any other return value, 
the keypress is further processed as described below, as if wserv. filter were NULL. 


If wserv. filter is NULL, or if the message sent to wserv. filter returns any value except 
WN_KEY_CHANGED, the action depends on the current state of the application and on the values of keycode 
and modifiers, as described in the following sections. 


Help 


If keycode is w_xey_HELP, and Help is not currently being displayed, one of the following is done, 
depending on the value of modifiers: 


Help The resource ID of the help to be displayed is found by sending a 
WN_SENSE_HELP message. The message is sent to either the current dialog 
or the client window, depending on whether a dialog is present 
(wserv.dial is not woLL) or absent. The resulting ID is sent as a parameter 
to a Ws_DO_HELP message, to display the appropriate Help, and processing 
of the keypress then terminates. 


Control-Help Provided wserv. flags does not contain PR_WSERV_HELP_INDEx, sends a 
WS_DO_HELP message to display the system Help index and then terminates 
processing of the keypress. Otherwise the behaviour is as for the Help key. 


Control-PSION-Help Sends a Ws_FREE_DIAL message to run the free format dialling dialog and 
(Control-Dial) then terminates processing of the keypress. 
other Continues with further processing. 

Dialogs 


Ifa dialog is present (wserv.diai is not NULL) a wN_KEY message is sent to the dialog, passing keycode and 
modifiers. The wn_key message is not sent under two circumstances: 


¢ ifmodifiers contains the w_specraL_xey flag, processing of the keypress simply terminates. 


e if the dialog's win. £1ags contains DLGCHAIN_WITH_MENU, processing continues as described in the 
following section, to allow access to the dialog's command menu. Any keypress that is not 
consumed by the command and command menu processing will be offered back to the dialog via 
a WN_KEY message. Note that this option is not available on the Series 3. 


If the return value from the wi_key message is non-zero, the dialog is sent a DESTROY message. If the return 
value is wN_KEY_CANCELLED, the value that will be retumed by the ws_po_pzaz method that launched the 
dialog is set to zero. If, on return from the wn_KEY message, wserv.subdial is non-zero, the dialog is sent a 
DL_LAUNCH_SUB message, passing the index of the dialog item that is launching the subdialog (one less than 
the value of wserv.subdial) and wserv.subdial is cleared. Processing of the keypress then terminates. 


Commands and command menus 


The value of keycode is then tested for any value that initiates a command by one of the following three 
means: 


e A value of w_KEY_DIAMOND (w_KEY_mopE on the Series 3) is interpreted as a COM_MODE_CHANGE 
command. On machines other than the Series 3, the com_mopE_CHANGE message is sent direct to the 


3-13 


HWIM REFERENCE 
a 


command manager, passing the value of modifiers masked with w_sHtFT_mop1FTER. On the 
Series 3 the message is sent as described below, with a preceding com_accL_CHECK message 
(which is expected always to return TRuvE in this case). 


e If the w_specraL_xey bit is set in keycode (indicating the Psion key was held down) this bit is 
masked out and keycode is tested against the list of accelerators held in wserv.info->accel. A 
match determines the method function number of the command to be executed, otherwise 
processing of the keypress terminates. The match is forced to be independent of case on the 
Series 3 but is otherwise case-dependent. 


e Ifamenu bar is displayed, it is sent a ww_kEy message, passing keycode and modifiers. If this 
returns a zero value, processing of the keypress terminates. Otherwise, the return value specifies 
the method function number of the command to be executed. 


Before executing the command (with the exception of com_MoDE_CHANGE, as noted above) a 
COM_ACCL_CHECK message is sent to the command manager, passing the proposed method function number. 
Processing of the keypress terminates at this pont if the com_accl_check method returns FALSE. 


Otherwise, if a menu bar is displayed, it is sent a Destroy message and the underlying window is sent a 
WN_EMPHASISE, TRUE message. This window is normally the client window but, except on the Series 3, it 
could be a dialog that allows the use of a command menu. 


The command is executed by sending the command manager the appropriate message, by means of the 
HWIM hwservcomSend utility function (again, with the exception of com_MoDE_CHANGE). Processing of the 
keypress then terminates. 


If keycode has a value of w_key_menu, one of the following is done, depending on the value of modifiers: 


Menu Create an instance of mznusar, storing its handle in wserv.bar, load the 
menu bar resource with resource ID wserv.info->menubar_id and send 
the menu bar a wy_rnrT message, followed by a wN_VISIBLE, WV_INITVIS 
message. Finally, send the client window a wN_EMPHASISE, FALSE message 
and terminate processing of the keypress. 


Shift-Menu As for the Menu key. 

Control -Menu Send the command manager a com_sTATwIN message, by means of the 
HWIM hwservcomsend utility function, and terminate processing of the 
keypress. 

other Terminate processing of the keypress. 


Client window 


Any unconsumed combination of values of keycode and modifiers is sent to the client window ina 
wN_KEY message. On return from this message, processing of the keypress terminates, without clearing the 
PR_WSERV_CLIWIN bit in wserv. £1ags. Thus, this bit is only set if the keypress has been offered for 
processing to the client window. Any return value from the client window is ignored. 


Ifa dialog is in existence, any keypress not consumed by the command and command menu processing is 
offered to the dialog, as described earlier, rather than to the client window. 


INGE_CLIWIN 


PR_WIN *ws_change_cliwin(PR_WIN *wh) ; 


Provided that the window with handle wn is not already the current client window, record this window as 
the new client window. 


The previous client window, which must still exist, is de~-emphasised (it is sent a WN_EMPHASISE, FALSE 
message). The new client window is emphasised (sent a WN_EMPHASISE, TRUE message) and is made the 
foreground window. Its handle is stored in wserv.cli. 


Returns the handle of the previous client window as a courtesy to the caller. 


The method does nothing but return the client window handle if the new window handle is the same as the 
previous one. 


3-14 


3 THE WSERV CLASS 


© WS SENSE 


INT ws_sense_accel(UINT comid) ; 


accelerator 


HWIM applications are not expected to replace this method. 


Return the lower case accelerator character corresponding to the command manager method number comid. 
The return value is meaningless if the method number is outside the range for which accelerators are 
defined. 


This method is used by the display code for pull-down menus. 


_ Runa dialog 
INT ws_do_dial (HANDLE cat, INT class, DL_DATA *pdata) ; 


Load, initialise and run the dialog specified by category handle cat and class number class. All HWIM 
dialogs must be started, directly or indirectly, via this method. 


The method creates an instance of the class specified by cat and class, assumed to be (a subclass of) 
pLGBox. It then loads the resource specified by pdata->id and uses it to create and initialise the dialog's 
components. The pi_para struct is defined in the wszrv class definition section of hwimman.g as: 


typedef struct 


{ 

UWORD id; dialog resource ID 

VOID *rbuf; NULL or pointer to dialog result buffer 
PR_DLGBOX **pdlg; NULL or location to receive dialog handle 
} DL_DATA; 


On the Workabout, if the flags in the dialog's resource contain pLGBox_sMALL_Fowt, this flag is cleared in 
the loaded resource and the dialog's digbox. font property is set to DLGBOX_ROMANS_FONT. 


The dialog is then sent a pL_1n1T message, followed by pL_pyn_in1T and pL_SET_s1zE messages. The 
initialisation of the dialog is completed by a call to the HWIM utility function htnitvis and this 
completion is noted by oring PR_WIN_INITIALISED into the dialog's win. flags. If pdata->pdig is not 
NULL, the dialog's handle is written to pdata->pdlg. The dialog is then added to the wserv. dial list of 
dialogs by means of a ws_ADD_DIAL message. 


If the dialog's digbox. f1ags does not contain pLGBox_no_warr, the application manager is sent an 
AM_START message. This will not return until the dialog has terminated. 


Users of this method should note the following significant points: 


e The dialog receives, in order, pt_InIT, DL_pyN_INIT, and DL_SET_sIzE messages before being 
made visible. 


e The creation and initialisation is protected from out of memory failure, by the use of OLIB 
CLEANUP mechanisms, until the dialog has been made visible. The application does not need to 
provide any explicit protection against failure unless application initialisation code allocates 
additional resources. 


¢ The dialog handle is not lodged in *pa->pdig until the dialog has been made visible. 


The return value is zero if the dialog is cancelled by the cancel mechanism provided by system code (that 
is, without the intervention of application-specific code - see the Dialog Boxes chapter for further details). 
This value is only of significance for dialogs for which the pLcBox_no_wart flag is not set. 


The method calls p_leave (which will trigger the automatic cleanup mechanism) on failure. 


S_ADD_DIAL | 


VOID ws_add_dial(PR_DLGCHAIN *hand) ; 


Add the object with handle hana (normally a dialog but, more accurately, an instance of any subclass of 
DLGCHAIN) to the front of the list whose first element is pointed to by wserv.dial. 


If a menu bar is visible send it a pestroy message, otherwise send a wN_EMPHASISE, FALSE message to the 
currently emphasised window, which will be either the first item in the wserv.diat list or, if this list is 


3-15 


HWIM REFERENCE 


empty, the client window. Then add hana to the front of the list (wserv.dial now contains the handle 
hand) and send this object a wN_EMPHASISE, TRUE message. 


Note that system-supplied subclasses of pLccuatn include help screens, pL¢gox and all system dialog 
classes. 


Remove a dialog from the dialog list 


VOID ws_remove_dial(PR_DLGCHAIN *hand) ; 


Remove the dialog with handle hand (not necessarily the first in the list) from the list of dialogs whose first 
element is pointed to by wserv. dial. If, after its removal, there are no dialogs in the list, wserv.dial will 
now be nuuu. Then send a wN_EMPHASISE, TRUE message to either the first dialog in the list or, if there are 
no such dialogs, the client window. 


raph word wrap 
INT ws_wrap_para(TEXT *buf, INT len, WRAP_DATA *pd) ; 


Word wrap the first 1en characters in the buffer pointed to by buf, writing the number of characters in each 
line to successive bytes of the table pointed to by pd->ptabie (assumed to be pd->nlines bytes long). 


The wrap_pata struct is defined in the wssrv class definition as: 


typedef struct 


{ 
UWORD margin; width (pixels) to fill with text 
UWORD fmargin; width (pixels) of first line 


WORD font; font used 

UWORD style; style used 

WORD nlines; max no lines to add to table 

UBYTE *ptable; table of bytes to receive line lengths 
} WRAP_DATA; 


Returns either the number of lines into which the text has been wrapped, or zero if there is not enough 
space in the line length table. 


Ws 


VOID ws_do_help(INT start_id); 


Run help system 


Create, initialise and make visible a help dialog displaying the help information contained in the resource 
with ID start_ia. 


Help: Sustem screen 


Create an instance of the HELPpie class and intialise by sending it a ww_inrT message with an argument of 
start_id. Make the dialog visible and add to the dialog list by sending a ws_app pra message to self 
passing as argument the handle of the nELppte instance. Increment wserv.help and or 
PR_WIN_INITIALISED into the win. flags property of the HeELppte instance: this indicates that the HELPDLG 
destroy method should decrement wserv. help. 


WS_ LOAD CHLIS Get choice list resource text 


TEXT *ws_load_chlist_res(INT rid, INT nsel, TEXT *buf) ; 


Copy, into the buffer pointed to by bug, the zero terminated string that forms choice list item number nse1 
(0 selects the first item) in the choice list resource with ID rid. This method is somewhat analogous to the 
more general application manager am_load_res_buf method. 


It is the user's responsibility to ensure that ria refers to a choice list resource and that the buffer is 
sufficiently long to contain the specified string. 


The method returns a pointer to the trailing zero that follows the loaded resource. 


3-16 


3 THE WSERV CLASS 


_ Run the free-form dialling dialog 
VOID ws_free_dial (VOID) ; 


Create, initialise and make visible the free-form dialling dialog: 


es message 
VOID ws_switch_files(UBYTE *buf) ; 


Create an instance of the sHurTER active object class and send it an ao_rnrT message, passing but, which is 
assumed to point to a buffer containing a command byte followed by a string specifying the new file name. 


This method is called as a result of the receipt of a Switchfiles message from the System Screen. If 
necessary, the SHUTTER active object delays the processing of the message (this processing includes sending 
the command manager a com_swITCH_FILEs message) until the application is in a suitable state to proceed. 


See the description of the sHurrer class, later in this chapter, for a fuller explanation of Switchfiles 
processing. 


Alte 


: ‘ock count 
INT ws_lock (INT lock); 
Add or remove a level of locking, depending on whether 1ock is TRUE Or FALSE. 


The application is considered to be locked if the magic static DatLocked is non-zero. A locked application 
does not receive Exit or Switchfiles messages from the System Screen, that is, the wseRV ao_run method 
ignores events of type wM_COMMAND. 


Note that the method stores the locked state in both wserv.lock and DatLocked. 


It is the programmer's responsibility to ensure that adding and removing levels of locking are balanced 
within an application. 


WSERV_INFO *ws_set_menubar (INT rid); 


Use hboadResource to allocate a cell and load into it the resource with ID ria (assumed to be a 
WSERV_INFO resource that defines the accelerators and the menu bar resource ID) writing the address of the 
cell to wserv. info. 


Returns the previous value of wserv. info, pointing to the allocated memory holding the original menu bar 
resource data. It is the programmer's responsibility to store this value for future restoration of the original 
menu bar data (normally by use of ws_reset_menubaz). If, exceptionally, this resource is not to be restored, 
it may be released with a call to p_free. 


Note that this method does not make the new menu bar visible, but the new menu will appear when the 
user next presses the Menu key. There is no straightforward automatic means of forcing the new menu bar 
to be displayed. 


VOID ws_reset_menubar (WSERV_INFO *info) ; 


Reset the menu bar 


Free the heap cell pointed to by wserv. info and set wserv. info equal to info. 


This is typically used as follows: 


HWIM REFERENCE 


p_send3 (w_ws,WS_RESET_MENUBAR, w_ws->wserv.oldinfo) ; 


to restore the main menu data after, for example, using the ws_set_menubar method. 


Run a submenu 


VOID ws_do_submenu(INT rid); 


Run the submenu specified by the wszrv_1nFo resource with ID ria. 


Sends a WS_SET_MENUBAR Message, passing rid, storing the returned pointer (to the loaded main menu 
resource data) in wserv.oldinfo. Then creates, initialises and makes visible an instance of MENUBAR 
(writing its handle to wserv.bar) to display the specified submenu. Sends a wN_EMPHASISE, FALSE message 
to the client window. 


An example of a submenu is the Series 3 Spreadsheet application's Print submenu, displayed by selecting 
the Print command from the Special menu of the main menu bar: 


(File Edit View Search Range 


Note that, as illustrated above, commands in a submenu may have accelerators that duplicate those 
appearing in the main menu. Submenus therefore provide a means of exceeding an application's normal 
limit of 30 commands (see The Command Manager). 


This method would normally be called from within the command manager method associated with the 
main menu option that gives rise to the submenu. 


The original menu bar is automatically restored when the submenu menu bar ceases to be visible. 


INT ws_query_dialog(INT secondrid, INT rid, INT *pargs) ; 


Run the system query dialog, with up to two lines of text. 


i’ Delete all files on "[BI"? 
No Yes 


as has 


The first line of text is generated, using hatob, from the format string loaded from the resource with ID ria 
and the list of arguments pointed to by pargs. The generated text may not exceed 50 characters, including 
the terminating zero. The value of pargs may be nut if there are no arguments, and rid may be zero, in 
which case there will be no first line text. The second line of text is loaded from the resource with ID 
secondrid, which is assumed to be a simple string resource. The value of secondrid may be zero, in which 
case there will be no second line text. 


On the Series 3 this method can call p_leave if there is insufficient memory to create and initialise the 
dialog. On the Series 3a the method will not fail, since it will call wsalertw to present an equivalent alert if 
there is insufficient memory to display the dialog. 


The method returns True if the user confirms, otherwise it returns FALSE. 


See also the hconfirm and h2LineConfirm utility functions. 


3 THE WSERV CLASS 


Run an error dialog 
INT ws_error_dialog(INT err, INT rid, INT *pargs); 


Run the system error dialog, with up to two lines of text. 


The argument is 12 units 
Invalid arguments 
Continue 


Saal 


The first line of text is generated, using p_errs, from the error number err. The second line of text is 
generated, using hatob, from the format string loaded from the resource with ID ria and the list of 
arguments pointed to by pargs. The generated text may not exceed 50 characters, including the terminating 
zero. The value of pargs may be nut if there are no arguments, and ria may be zero, in which case there 
will be no second line text. 


Returns zero, to confirm that the method did not call p_1eave. This method is suitable for calling under the 
protection of p_ enter. 


See also the hErrorDialog utility function. 


INT ws_evaluate (TEXT *pResult, TEXT *pExpr, VOID *oplmod); 


Evaluate the expression contained in the zero terminated string pointed to by pexpr, writing the result to 
the buffer pointed to by presult. 


The result is evaluated according to the format preferences derived from the evaluator environment 
variable, MSV, accessed via the ws_eval_env method, described below. 


If the initial value of the byte *presult is zero, the evaluation is performed in so-called ‘calculator’ mode. 
After evaluation in this mode, the result buffer contains the numerical value, as a DOUBLE, in its first eight 
bytes. This is followed by the text representation of the value, as a zero terminated string, using the calc 
preferences from MSV. 


Any initial non-zero value in *pResuit causes the evaluation to be performed in 'evaluator' mode. After 
evaluation in this mode, the result buffer contains only the text representation of the value, as a zero 
terminated string, using the eval preferences from MSV. 


The expression to be evaluated may be any expression that is acceptable to the OPL programming 
language. The value of op1mod may be either nut or a pointer to the name of an OPL module containing 
additional functions (for example, a set of hyperbolic trigonometrical functions) to be used in evaluating 
the expression. 


Returns -1 if the evaluation is successful. Otherwise reports an error, using hinfoPrintErr, and then 
returns the byte offset, within the buffer at pexpr, to the point at which the error was detected. 


WS_EVAL ENV r get evaluator en 


VOID ws_eval_env(EXTENDED_MEM_VALUES *pev, INT getit); 


nt variable 


Write, from « ev, OF read, to *pev, the M$ V environment variable, which stores evaluator format 
Pp 
preferences. 


The EXTENDED_MEM_VALUEs struct is defined in h_eval.h as: 


typedef struct 
{ 
UBYTE evalFormat; /* Dtob format code for all except calc */ 
UBYTE evalDPlaces; /* Decimal places for all except cale */ 
UBYTE calcFormat; /* Dtob format code */ 
UBYTE calcDPlaces; /* Decimal places, if relevant */ 
DOUBLE values [MAX_MEMORIES] ; 
} MEM_VALUES; 


HWIM REFERENCE 
eee eeeeSeSeSSSSSsSSFFSSSSSSSSSSSSSsSSSSSSSSSSSSSSSSsSSSSSSSSeee 


typedef struct 
{ 
UBYTE evalDegrees; 
UBYTE calcDegrees; 
MEM_VALUES memVal; 
} EXTENDED _MEM_VALUES; 


Note that the Series 3 supports two global sets of evaluator preferences, one specifically for the Calculator 
application (set by the Calculator's Format command) and one for all other evaluations (set by the System 
Screen's "Evaluate" format command). 


If getit is TRUE, read the contents of the M$V environment variable into *pev. If the environment variable 
does not exist it is created with default values as follows: 


pev->evalDegrees=DEGREES_MODE; 
pev->calcDegrees=DEGREES_MODE; 
pev->memVal.evalFormat=P_DTOB_FIXED; 
pev->memVal.evalDPlaces=EVAL DEFAULT_PLACES; 

pev->memVal .calcFormat=P_DTOB_GENERAL; 
pev~>memVal.calcDPlaces=CALC_DEFAULT_PLACES; 

p_bfil (&pev->memVal.values [0] ,MAX_MEMORIES*sizeof (DOUBLE) , 0) ; 


If getit is FALSE, write *pev to the MSV environment variable. Note that this process modifies the contents 
of «pev. 


dial environment variable 


VOID ws_dial_env(DIAL_ENVAR *pev, INT getit); 


Write, from «pev, or read, to *pev, the D3X environment variable, which stores telephone dialling 
preferences. 


The prIaL_ENvaR struct is defined in the sptanpxc smart dialling dialog class definition as: 


typedef struct 


{ 


UWORD toneLengthTicks; 

UWORD delayLengthTicks; 

UWORD pauseLengthTicks; 

UBYTE dialOutCode [6] ; to access an external line 
} DIAL_ENVAR; 


If getit is TRUE, read the contents of the DSX environment variable into «pev. If the environment variable 
does not exist it is created with default values as follows: 

pev->toneLengthTickss8; 

pev->delayLengthTicks=8 ; 

pev->pauseLengthTicks=48; 

p_scpy (&pev->dialoutCode[0],"9,"); /* from the SYS_DIAL_OUT system resource */ 


If getit is FALSE, write «pev to the DZX environment variable. 


VOID ws_format_dialog(INT flags) ; 


Run the set format dialog 


Run the system dialog to set the evaluation format preferences. 


Set "Evaluate" format 


Fixed > 
Decimal places 2 


Trigonometry units Degrees 


If flags is TRUE, run the dialog to set the general evaluate preferences, as shown in the above diagram, 
otherwise run it to set the preferences for the calculator. 


On exiting the dialog, except by pressing Esc, the preferences are written to the MSV environment variable. 
See the description of the EvALDLGc system dialog class for further details. 


3-20 


3 THE WSERV CLASS 


VOID ws_alert (TEXT *t1, TEXT *t2); 

Ensure the magic static DatLocked is TRUE and then call: 
wsAlertW(WS_ALERT_CLIENT,t1,t2,0,0,0); 

On return from this call, patLocked is restored to its original value. 


This method is called from the HwrMman am_notifyerr method as the final fail-safe stage of the system's 
error reporting mechanism. 


WS _ APPEND COUNTR 


INT ws_append_country (TEXT *outStr) ; 


lintry Selector dialog 


Run the dialog used to add the country name to a telephone number (on pressing 
Control-Shift-PSION-Help) when editing a Data application entry: 


Append country 


Gees) + Snited Kingdoms 
Append 


Writes, as a zero terminated string, the selected name, enclosed in square brackets and preceded by a single 
space, to the buffer pointed to by outstx and returns Trus if the dialog is terminated by pressing Enter. 
Otherwise just returns FALSE. 


See the description of the cwrrype system dialog class for further details. 


Smart dial of a number 


VOID ws_smart_dial(SMART_DIAL_DATA *data) ; 


Run the smart dialling dialog: 


3657339990 
Cancel Freeinput Dial Dial out 


« Haris: 


to dial any of up to four (on the Series 3) or six (on the Series 3a and Workabout) telephone numbers 
passed in the sMART_DIAL_DATA Struct pointed to by data. The struct is defined in the spranptc class 
definition, effectively as: 


#define SMART DIAL MAX PROMPT 11 /* max prompt length */ 


typedef struct 


{ 

TEXT pmt [SMART_DIAL MAX _PROMPT+1] ; 
TEXT str [WR_MAX_IN_STRING+2] ; 

} SMART_DIAL ITEM; 


typedef struct 


{ 


WORD count; how many separate numbers 
SMART_DIAL ITEM it [4]; 
} SMART_DIAL DATA; 

where wR_MAX_IN_STRING is defined in wr_io.h. 


See the description of the spraLpie system dialog class for further details. 


HWIM REFERENCE 


w 


VOID ws_ens_print_context (VOID) ; 


KT Ensure print context data ¢ 


If it does not already exist, create and initialise an instance of the FORM printer class, writing its handle 
to wserv.printer. 


The method does nothing if wserv. printer is not NULL. 


VOID ws_edit_print_context (VOID) ; 


Send a Ws_ENS_PRINT_CONTEXT message and then run the print setup dialog as, for example, is used by the 
Print setup command in the Series 3 Word application's Special menu: 


"Margins... 1.25, 1.25, 1.25, 1.25 
*Header.. “F 

*Footer.. “P 

"Paging control. 15 Nos 15253 

"Printer model... Canon BJ-1@e 


This dialog is used to review and/or modify the print context data stored in the application's instance of the 
PRINTER Class, whose handle is in wserv.printer. See the Print Classes chapter for further details of the 
Print setup dialog. 


VOID ws_edit_pdev_setup (VOID) ; 


Run the dialog to set up the system-wide printer device configuration, as for the Printer setup command in 
the Series 3's System Screen's Special menu: 


¢Parallels 
Serial characteristics .. 
Serial handshaking .. 
File: Name 
Disk 
Inches 


INT ws_sense_pdev_text (TEXT *buf) ; 


On the Series 3, this is a voip function. 


Write as a zero terminated string, to the buffer pointed to by bué, the text that describes the current printer 
device. This text will be one of "Parallel", "Serial" or, if printing to file, the name and extension of the print 
file. 


Except on the Series 3, returns the ID of the current printer device. 


WS_ADD_FILELIST _ 


VOID ws_add_filelist(PR_FILELIST *f1); 


Add the instance of rrLeLrst with handle £1 to the front of the list whose first item is pointed to by 
wserv.filelist. 


The instance's property, £1->filelist .1locmask is set to a distinct single bit value in the range 
WS_LOCCHG_LOw tO WS_LOCCHG_ HIGH inclusive 


If wserv.anim is nuLL, the method creates and initialises an instance of the ANIMATOR class, writing its 
handle to wserv.anim. The Ao_1NIT message sets up the aNIMaTor instance to send WsERV a WS_ANIM_TICK 
message every 3 seconds, with an initial delay of 6 seconds. 


3-22 


3 THE WSERV CLASS 


© WS_REMOV 


VOID ws_remove_filelist(PR_FILELIST *f1l); 


Remove the instance of FrLeLIst with handle £1 from the list whose first item is pointed to by 
wserv.filelist. 


If, after the removal, the list is empty and wserv.anim is not NULL, a DESTROY message is sent to the object 
with this handle and wserv. anim is set to NULL. 


The method does nothing if £1 does not appear in the list. 


VOID ws_anim_tick (VOID) ; 


If it exists, send the object whose handle is stored in wserv.filelist an FL_LOCCHG message. 


VOID ws_unknown_wm (VOID) ; 


This message is received when an event of a type not known to the ao_run method is received from the 
window server process. At the time of writing, possible unrecognised event types are ww_on and 
WM_TASK_UPDATE (this latter event type will be received only by the System Screen). 


The supplied method does nothing. 


An application should subclass this method if it needs to process such messages. 


VOID ws_foreground(UINT flag) ; 


The application receives this message, with f1ag set to TRUE, when it becomes the foreground process. The 
supplied method does nothing. 


The flag parameter is passed so that a subclasser may map the ws_foreground and ws_background 
methods to a single method function, the two cases being distinguished by the value of flag. 


VOID ws_background(UINT flag) ; 


The application receives this message, with f1ag set to FALSE, when it becomes a background process. The 
supplied method does nothing. 


The £1ag parameter is passed so that a subclasser may map the ws_foreground and ws_background 
methods to a single method function, the two cases being distinguished by the value of flag. 


VOID ws_hook_today changed(VOID *handle, INT message) ; 


This method is not available on the Series 3. 


Register or de-register the interest of the object specified by handie in being notified of the arrival of a 
WM_DATE_CHANGED inter-process message. 


If message is non-zero, the interest is registered by storing handle and message at the front of a list of such 
data items. On receipt of a wM_DATE_CHANGED inter-process message, message number message will be sent 
to the object specified by handle. 


If message is zero, the entry for the object indicated by handle is removed from the list. 


It is normally a programming error to register the same object more than once. An attempt to remove an 
object that has not been registered is a programming error with unpredictable results. 


HWIM REFERENCE 


WS_DATE CHANGED ~—__—s Process WM_DATE CHANGED 
VOID ws_date_changed (VOID) ; 


This method is not available on the Series 3. 


Send a message to each object that has registered, via the ws_hook_today_changed method, interest in the 
occurrence of date changes. 


Each object that has such an interest is sent a message of the type specified at the time it registered its 
interest. 


The Ws_DATE_CHANGED message is sent from the ws_process_key method, in response to a 
WM_DATE_CHANGED inter-process message from the Window Server process. 


Launch a DYL 


VOID ws_launch_dyl (TEXT *pname) ; 
This method is not available on the Series 3. 


Load and link the DYL whose full file specification is pointed to by pname, create an instance of its first 
class and send this instance a message with message number 1 (by convention, this is an initialisation 
message). This method is indended for use by an application that is started with a command line that 
contains the command byte H_CoMMAND_LAUNCH_DYL ('L' - see the HWIMMAN Application Manager 
chapter). 


If the loading of the DYL fails because the DYL is has already been loaded by this application, the 
ws_launch_dy1 method simply returns, without reporting any error. Any other loading error causes 
p_leave to be called. 


If the DYL is successfully loaded and linked, an instance of its class number zero is created. This instance 
is sent, under the protection of p_enter, message number 1, passing the DYL's category handle as the 
method's sole parameter. The corresponding method is expected to return zero to indicate its successful 
conclusion. 


If the method terminates without error, the DYL is considered to be successfully launched and 
ws_launch_dy1 then returns. If the method returns a non-zero value, or calls p_1eave, the DYL's instance 
of class number zero is sent a Destroy message and the DYL is unloaded. Any such error is not reported. 


If successfully launched, it is the DYL's responsibility to ensure that it unloads itself at some later time, 
when its task is complete. A convenient means of ensuring that the DYL is unloaded correctly is to supply 
the DYL's class number zero with a component object that is an instance of the XADD untoap class (using 
PROPERTY n in the class definition so that the component will receive a DESTRoy message when the owning 
class is destroyed). This component should be created and initialised as the last step of the initialisation of 
its owning class. See the description of the unioap class in the Additional Active Object Classes chapter of 
the XADD Reference manual. 


INT ws_define_fnbar(INT resid, INT pos, UBYTE *pselect) ; 


mond' list 


This method is not available on the Series 3. 


Set up, from a resource file, the text for the list of modes to be displayed in the application's status window. 
This method provides a utility layer over the Window Server's wsSetList function 


The text is read from the menu resource with ID resid. The following example shows the resource used by 
the Series 3a Agenda: 


3 THE WSERV CLASS 
——— eee WISER RLASS 


RESOURCE MENU diamond_list 


{ 


items = 
{ 
MENU_ITEM { mn_item="Day"; }, 
MENU_ITEM { mn_item="Week"; }, 
MENU_ITEM { mn_items"Year"; }, 
MENU_ITEM { mn_item="To-do"; }, 
MENU_ITEM { mn_item="Anniv"; }, 
MENU_ITEM { mn_item="List"; } 
}i 

} 


Note that there is a fairly serious width restriction on the text of each item - if you use more than five 
characters, you should test the application carefully. 


As for wsSetList, the value of pos should be either w_staTus_wIN_No_DIamonp or the index, counting 
from zero, of the item against which the diamond symbol is to be displayed. 


If pselect is NULL, all the text items from the resource will be shown in the list. Otherwise, pselect should 
point to a uByTE array where each byte is either Tru or FALSE to include or exclude the corresponding text 
item. 


The following example code uses the resource listed earlier. It would set up the Agenda diamond list to 
show no diamond symbol and contain the two text items "Week" and "Anniv". 


LOCAL_C VOID SetDiamondItems (VOID) 


{ 


UBYTE select [6]; 


p_bfil(sselect [0] ,6, FALSE) ; 

select [1] =TRUE; 

select [4] =TRUE; 

p_sends (w_ws,0_WS_DEFINE_FNBAR, DIAMOND_LIST,W_STATUS_WIN_NO_ DIAMOND, &select [0]); 


} 


The method calls p_leave if any error occurs. It returns zero if successful and is,therefore, suitable for 
being called under the protection of p enter. 


VOID ws_ (VOID) ; 
This method is not available on the Series 3. 


Walk the application's heap to determine the number of allocated cells and the total number of bytes of 
allocated memory. 


The method presents an information message showing both these values. 


An application may send this message to itself or the message may be sent from an external process, as part 
of an automated test suite for the application. 


xt from a process 


INT ws_get_print_context (UWORD pid) ; 


This method is not available on the Series 3. 
Copy the print context from the process with ID pia. 


The method first sends a ws_ENS_PRINT_CONTEXT message to ensure that the application has default print 
context data. It then performs a series of inter-process copies to overwrite the application's print context 
data with the corresponding data from the specified process. 


It is assumed that the process with ID pia exists and has a valid print context. 


The method calls p_ieave if any error occurs during the copying of the data. If the method completes 
successfully it returns zero to indicate that p_1eave has not been called. The method is suitable for being 
called under the protection of p_ enter. 


HWIM REFERENCE 


INT ws_self_check (VOID) ; 


Perform internal data check 


This method is not available on the Series 3. 
Perform an internal self-consistency check on the application's data. 


The supplied method simply returns ransz which, by convention, implies success of the check. This 
method is intended to be replaced to provide application-specific consistency checks. 


An application may send this message to itself or the message may be sent from an external process, as part 
of an automated test suite for the application. The behaviour following the failure of a self-check will be 
application-specific. 


VOID ws_hide_app(UWORD pid, WS_HIDE_APP DATA *p); 


This method is not available on the Series 3. 
Hide the application from, or reveal it to, the System Screen. 


This method is intended to be used as part of the mechanism to attach one application to another (see the 
Series 3a Attached Applications chapter of the Object Oriented Programming Guide). It should be called 
by the controlling application, after it has successfully launched the attached process. 


The application is hidden if pia is non-zero. In this case, the value of pid is assumed to be the process ID 
of the attached process. The application's current patusedPathNamePtr is preserved in p->dupnp and 
DatUsedPathNamePtr is set to point to the string "SYS$X" (a name that will not be displayed in the System 
Screen’s file lists). Provided the attached process has not yet terminated, the application is made system 
modal and sent to the back of the task list by means of a call to wsystemModal. The value PR_WSERV_HIDDEN 
is ored into wserv. flags. 


If pid is zero, the application is restored to visibility. The application's original value of 
DatUsedPathNamePtr is recovered from p->dupnp and, by means of a call to wCancelSystemModal, the 
application's modal state is cancelled and it is brought to the front of the task list. Finally, the value 
PR_WSERV_HIDDEN is cleared from wserv. flags. 


Note that the ws_HIDE_APP_para struct must remain in existence until the application is restored to 
visibility. 


VOID ws_attach_app(UWORD pid); 


This method is not available on the Series 3. 


Set the application's appearance as being attached to the application with process ID pia (the process that 
controls the attachment (see the Series 3a Attached Applications chapter of the Object Oriented 
Programming Guide). It should be called by the attached application itself, during its initialisation. 


Sets DatLocked to the value of patLocked in the controlling process and then sets patProcessNamePtx to 
point to a copy of the text pointed to by patprocessNamePtr in the controlling process. 


Copies over the text pointed to by patusedPathNameptr in the controlling process and sends the 
application manager an AM_NEW_FILENAME message, passing a pointer to this text. 


Any error will result in p_leave being called. 


3 THE WSERV CLASS 


VOID ws_file_info_print (TEXT *fname, INT rid); 


ed message 


This method is not available on the Series 3. 
Present a file-related information message. 


The text of the message is constructed from the file specification pointed to by fname and the text string 
resource with resource ID rid. The string resource is expected to be a format string containing a single ss 
that will be replaced by the file name. 


The passed file specification is parsed to locate the file name and extension. If the extension matches the 
application's default extension, pointed to by w_am->hwimman.defext, the extension is removed from the 
file name. The file name is string capitalised and the message is displayed by means of a call to the 
hInfoPrint HWIM utility function, passing rid and a pointer to the file name (with or without a trailing 
extension). 


The method is used extensively by applications built into the Series 3a to report the completion of file- 
based operations, in conjunction with the resource strings: 


SRT_FILE_CREATED 
SRT_FILE_OPENED 
SRT_FILE_SAVED 
SRT_FILE_COMPRESSED 
SRT_FILE_MERGED 

Thus, for example: 
GLREF_D VOID *w_ws; 
TEXT *p; 


p="LOC: :M: \AGN\AGENDA.AGN"; 
p_send4 (w_ws,O_WS_FILE_INFO_PRINT,p,-SRT_FILE_SAVED) ; 


will, in the Agenda application, display the message: 


"Agenda" saved 


_ Run Agenda memo editor 
INT ws_run_memo (INT flags, MEMO_DATA *pd, MEMO CALLBACK *cb) ; 
This method is not available on the Series 3. 


This method is supplied with the specific intention of being used by the Agenda application to edit a Memo 
attached to an Agenda entry. It is not intended to be used by any other application. 


Run dialog 


VOID ws_do_remote_dial(PR_ACTIVE **pa, INT mainrid, INT butrid); 


er process 


This method is not available on the Series 3. 
Run a dialog (an instance of arsp1at) in either an attached process or the foreground process. 


Determines the process ID of an attached process or, if no such process exists, the current foreground 
process, and checks that this process is suitable for receiving the instruction to run the dialog. 


The method then loads the main dialog resource, specified by the resource ID mainrid. If butria is not 
zero, the ‘button’ resource that it specifies is also loaded from the resource file. This resource may be either 
an ACLIST_ARRAY, defining the buttons for the dialog's single instance of an action list dialog item, or a 
MENU resource, defining the contents of the dialog's single instance of a choice list dialog item. 


If the dialog is not being run in an attached process, the value of pa must be nutu. Otherwise it should be a 
pointer to memory into which a handle can be written. In this case the ws_do_remote_dial method runs the 
dialog under the protection of an idle object (an instance of the OLIB arptz class) whose handle is stored 
in *pa as a service to the caller. This idle object will receive an ao_RuN message on successful termination 
of the dialog. 


HWIM REFERENCE 


An inter-process message starts the remote dialog. 


Providing there has been no error, the method does not terminate until the remote dialog is complete, when 
it returns the key code that terminated the dialog. On error, the method calls p_leave. 


Note that, although arspzat allows an option to present an editable text control in the dialog, the 
ws_do_remote_dial method does not support this mechanism. 


VOID ws_user_abandoned (VOID) ; 
This method is not available on the Series 3. 
Provide a standard means of terminating an application, with user notification. 


The method first terminates any attached process. It then presents an alert displaying the two messages 
"User abandoned' and 'Press Esc to exit application’. 


This method is intended to be used in the event that the user abandons a crucial operation, leaving the 
application in a state where it is unable to continue. The following example is taken from the Agenda 
application. It is displayed, for example, when a user removes the SSD containing the current Agenda file, 
attempts to modify an Agenda entry and refuses to replace the SSD whm prompted to do so. 


Agenda 


User abandoned 
Press Esc to exit application 


Continue 


aaa 


SHUTTER 


q count 
priority buf 
isactive 

peb 

stat 


destroy ao_init 
: ao_run 


ao_abrun 


ao_cancel 
ae—abren 


ao_queue 
S0—Fun 


An instance of the syurTEr class is used by wseRv to implement a switch to a new file initiated bya 
Switchfiles message from the System Screen. It is not expected that an HWIM application will ever 
explicitly create an instance of suurTer, nor is it ever expected to send explicit messages of any kind to any 
instance. The sHuTTER class is documented as a way of explaining the mechanism of the processing of a 
Switchfiles message, and under what circumstances that processing may succeed or fail. 


Processing a Switchfiles message 


A Switchfiles message may be received by an application at any time that it has not set itself in the locked 
state (see the WSERV ws_lock method). Even if an application is not locked, it may not be in a state where it 
can immediately respond to the message. It may be displaying a menu bar, or it may be interacting with the 


3-28 


3 THE WSERV CLASS 


user via a dialog. (which is likely to manipulate data that will change when a new file is loaded). The action 
of the sHuTTER object is to attempt, by removing any displayed menu and trying to cancel any dialogs, to 
return the application to a state in which it can respond to the Switchfiles message. 


A Switchfiles message is received by wsErv as an event of type ww_commann to the ao_run method. This, in 
turn, results in wserv being sent a ws_SwrTCH_FILEs message, whose main task is to create and initialise an 
instance of SHUTTER. 


SHUTTER'S first action is to remove any visible menu bar. Then, in successive calls of its ao_run method, it 
attempts to close down all the items in the wsERv wserv.dial list. These items, most commonly dialogs, are 
subclasses of DLGCHAIN and are expected to conform with the guidelines for this class. In some cases an 
item may not fully conform (for example, where a dialog responds to the Escape key by presenting an "are 
you sure?" query dialog) and suurTer may fail to close such an item. On such a failure sHuTTerR destroys 
itself, the net result being that the Switchfiles message is not processed. 


Otherwise, when all the wserv. dial items have been closed down, suurter's final action, before 
destroying itself, is to process the Switchfiles message by sending the command manager a 
COM_SWITCH_FILES message. 


Class definition 
Defined in sub-category file hactive.cl (generated header file hactive.g). 


CLASS shutter active 
{ 
REPLACE ao_init 
REPLACE ao_run 
REPLACE ao_abrun 


CONSTANTS 
{ 
SHUTTER_BUFFER_LEN 128 
SHUTTER_COUNT_MAX 32 
} 

PROPERTY 
{ 
WORD count; 


UBYTE buf [128] ; 
} 
} 


Property 
shutter. count a count of the number of ‘hits' of the sHuTTER ao_run method, used to 
terminate sHuTTER if it has not been able to initiate the file switch in 32 
cycles 
shutter. buf holds the Switchfiles command byte followed by a zero terminated string 


containing the name of the new file 


SE SO ae ne 8 i Ee Le ETE eT 
SHUTTER methods 


AO 


VOID ao_init (UBYTE *buf); 


in itialise 


Copy SHUTTER_BUFFER_LEN bytes from the buffer pointed to by buf into shutter .buf. This data consists of 
a Switchfiles command byte followed by a zero terminated file name. If a menu bar is displayed 
(w_ws->wserv.bar is not NULL) destroy the menu bar and send the client window (with handle 
w_ws->wserv.cli) a WN_EMPHASISE, TRUE message. 


Then add itself to the application manager's active object queue with priority PRIORITY_ACTIVE_WSERV-1 
and send itself an ao_QUEUE message. 


HWIM REFERENCE 


AO_RUN  — ~~—~—=—:CS So, or prepare for, the file switch ( 
INT ao_run (VOID) ; 


If shutter.count is equal to sHurrER_CouNT_MAX, send itself a DEsTRoy message and return, otherwise 
increment shutter .count. 


If a ‘dialog’ is visible (w_ws->wserv.dial is not NuLL) send itself an ao_QUEUE message to ensure the later 
receipt of a further ao_run message. Then send w_ws->wserv.dial a WN_KEY message with a keycode of 
w_key_EscapE. If this message returns a non-zero value, indicating that the dialog has not destroyed itself, 
send the dialog a pestroy message. This process will be repeated in successive ao_run methods until all 
items in the w_ws->wserv.dial list have been cancelled and destroyed unless the number of attempts 
exceeds SHUTTER_COUNT_MAX. 


Otherwise, if w_ws->wserv.dial is NuLL, the command manager (w_ws->wserv.com) is sent, under the 
protection of p_enter, a COM_FILE_CHANGE message, passing the command byte and a pointer to the file 
name, both of which are stored in shutter. buf. On an error-free return from this message, indicating that 
the file switch has been successfully completed, the method sends itself a pEstRoy message and returns. 
Any error results in p_leave being called. 


Returns RUN_ACTIVE_USED. 


VOID ao_abrun (VOID) ; 


Supersend the ao_aBRuN message to perform standard error reporting and then send itself a pEsTROY 
message. 


CHAPTER 4 


THE COMMAND MANAGER 


The command manager is a component of the application's instance of (a subclass of) wserv. Every HWIM 
application must create and initialise a command manager, which must remain in existence for the lifetime 
of the application. The command manager may be accessed via its handle which is stored in 
w_ws->wserv.com. The category and class of the application's command manager are passed in an 
IN_WSERV Struct to the application manager's am_init method from the application's main, as described in 
the Introduction chapter. 


There is no need to send a DesTRoy message to a command manager since its resources will be released, 
along with all other application resources, on termination of the application. 


Any HWIM application that supports commands that are initiated by a selection from a menu bar and pull- 
down menu (or a corresponding accelerator) must subclass comman to app a method for each such 
command (with the exception of the Exit command command that is assumed to be handled by the 
(possibly replaced) com_exit method. These methods must be apped in a single uninterrupted group, 
following immediately after the superclass com_exit method, in the command manager's class definition. 


It is not, however, always necessary to supply a separate method function for each method. All invocations 
of command manager methods that may be selected from a menu bar (that is, com_exit and the following 
methods added by a subclass) are via the hwservcomSend utility function, which sends messages to the 
command manager, passing the command method number as an additional parameter. The command 
manager's class definition may, if it is convenient, assign two or more methods to share a common method 
function. This function can distinguish between the different cases by the method number in this parameter. 


Every command must have an associated accelerator. These accelerators must be listed in the first item of 
the application resource file, in the same order as the corresponding command manager methods in the 
class definition. However, this is not necessarily the order in which they appear in the application's 
command menus; note that the Exit command, corresponding to the com_exit method (which is necessarily 
the first method in the sequence) conventionally appears as the last item in the last menu of all Series 3 
applications. See also the Commands and Command Menus and HWIM Resource Files chapters of the 
Object Oriented Programming Guide. 


All Series 3 keyboards, irrespective of language differences, support 30 distinguishable accelerator 
keypresses (the 26 non-accented alphabetic keys are common to all machines, but the remaining four 
depend on the keyboard layout, which varies from language to language). As a result, a Series 3 HWIM 
application is nominally restricted to a maximum of 30 commands, including Exit. This limit may, 
however, be exceeded if the application supports alternative menus and/or sub-menus. 


Series 3a machines distinguish between upper and lower case accelerators and therefore may use up to 56 
separate commands in a single menu bar. 


Each alternative menu or submenu requires a further contiguous block of anped command manager 
methods and a further resource file item to provide an accelerator for each command. 


Precursors 
Familiarity with the following topics would be helpful: 
e the p enter and p leave error handling services 


e the wserv class, especially the ao_init, ao_run and ws_switch_files methods, all of which send 
messages to the command manager 


HWIM REFERENCE 
Ss SSSFSFSSSFSFSSFFSSSSSSSSSSSSSsSFSFsFsFeFeFeFsFFMSSSSssSSsees 


Class diagram 


(0 Oa mee a pt eet 


/ wser / comman 
7 


ES ae ee a en a rere 
COMMAN 


com_init 
com_statwin 
com_acel_check 
com_menu 


com_mode_change 
com_file_change 
com_exit 


The comman class provides the basic skeleton for a command manager, supplying minimal functionality for 
the methods that an HWIM command manager must support. 


Although it is possible to build an application that uses an instance of comman as its command manager (for 
example, an application that consists of nothing but a chained sequence of dialogs) any non-trivial 
application will subclass comman, replacing one or more of the supplied methods and adding further 
application-specific methods. All file-based applications must replace the com_file_change method and, if 
they can modify the contents of their current file, the com_exit method. 


Class definition 
Defined in sub-category file comman.cl (generated header file comman.g). 


CLASS comman root 
Superclass of all command managers 


{ 


ADD com_init=p_dummy Users own initialisation 
ADD com_statwin=p_ dummy Toggle permanent status window 
ADD com_accl_check=p_true Called whenever an accelerator is matched 
ADD com_menu=p_dummy Called whenever a menu is pulled down 
ADD com_mode_change=p_dummy W_KEY_MODE received 
ADD com_file_change=p_dummy The core code for open or new 
ADD com_exit Message sent here on exit accelerator 
CONSTANTS 
{ 
O_COM_SYS_LAST O_COM_EXIT 
BREAK_LINE_FOLLOWS 0x80 item is underlined 
PURE_COM_ID Ox7£ Mask to exclude underline flag 


} 
} 


The Series 3 version does not contain the defined constants BREAK_LINE_FOLLOwSs and PURE_COM_ID. 


Property 
There is no property associated with the comman class. 


4 COMMAND MANAGER 


COMMAN methods 
COM_INIT | a Initialise 


VOID com_init (VOID) ; 
Perform application-specific initialisation. The supplied method does nothing. 


A subclass may use this method to create and initialise one or more command manager component objects, 
such as a link paste server to implement the supply of data for the Bring command executed in another 
process. 


The method is called from the wszrv ao_init method, immediately before wserv receives a ws_DYN_INIT 
message. Any failure should result in p_leave being called: this will cause the start-up of the application to 
be aborted. In general, this method would not be expected to fail since the application's start-up heap 
should be calibrated to provide sufficient memory. 


COM_STATV 


VOID com_statwin (VOID) ; 


This method is called when the application receives a Control-Menu keypress in circumstances explained 
in the description of the wseRv ao_run method. The supplied method does nothing. 


A subclass may, if appropriate, keep a record of the status window visibility in its property and use this 
method to toggle the visibility of a permanent status window by appropriate calls to either wsEnable or 
wsDisable - and adjust the size of its display accordingly. 


An application that can not reasonably alter its display size may choose not to subclass this method. 


co 


INT com_accl_check (INT comid) ; 


When an application command is selected, by either by pressing an accelerator key combination or by 
selecting a pull-down menu item, the command manager is sent the appropriate message, with message 
number comid. Before this message is sent, the command manager receives a com_ACCL_CHECK message 
from the application's instance of WSERV (on the Series 3, this message is sent from the ao_run method 
and on the Series 3a, it is from the ws_process_key method, called from the ao_run method). If the 
com_accl_check method returns rausz, the message with message number comid is not sent. 


This method may therefore be used to check if the application is in a state to respond to the comid 
command. The Word application, for example, uses this method to ignore the PSION-+ accelerator if the 
Spell check software has not been installed. 


The supplied method simply returns true, allowing all command messages to be received at all times. 


Il-down m out to appear 


VOID com_menu(INT menu_num, PR_VAROOT *array) ; 


This method is called when pull-down menu number menu_num (the leftmost menu is menu number zero) is 
about to appear. The supplied method does nothing. 


At the time this method is called, the text of the menu has been loaded from a resource file, with the items 
held in successive elements of the variable array with handle array, but the menu window has not yet been 
made visible. 


The data of the array is held in allocated memory. Each array element consists of a length byte followed by 
a MENU_ITEM Struct, defined in pulldown.g as: 


typedef struct 


UBYTE com_id; /* command manager method number */ 
TEXT mn_txt[i]; /* zero terminated text string starts here */ 
} MENU_ITEM; 


HWIM REFERENCE 


and containing the command manager method function number, followed by the text, stored as a zero 
terminated string. As for the menus themselves, the first menu item is item zero, the second is item one, 
and so on. 


A subclass may use the com_menu method to modify the menu contents according to the current state of the 
application, either to replace the text of one or more items - for example, to replace the text of the second 
item in the third menu: 


TEXT *p; 


if (menu_num==2) 


{ 
p=(TEXT *)p_send3 (array,O_VA_PREC,1); /* locate second item */ 
hLoadResBuf (REPLACEMENT _TEXT_RID,p+2); /* skip byte count and method number */ 


} 
or to completely remove one or more items - for example, to remove the third item in the fourth menu: 


if (menu_numss3) 
p_send3 (array,O_VA_DELETE,2); /* delete third item */ 


These operations must be performed each time the menu bar is about to appear, since it is always reloaded 
from the resource file. 


When replacing text note that, since the data is held in an allocated heap cell, any replacement text must 
not be longer than the original text for that item. The leading byte count allows system code to determine 
the amount of memory occupied by a menu item, even if the text has been replaced by text of a different 


length. 
COM_MODE_CHA! 


VOID com_mode_change (INT shifted) ; 


When wserv receives an event of type wm_key with a keycode of w_key_mopk, in circumstances explained 
in the description of the wseRV ao_run method, it sends the command manager a coM_MODE_CHANGE 
message. 


On receipt of this message the application should either do nothing or make some appropriate alteration to 
its state. On the Series 3 the Word application, for example, toggles in or out of Outline mode, the Data 
application switches in and out of data entry mode, while the Agenda application cycles around its views. 


On the Series 3a the standard action is to cycle around the application's ‘diamond list’. 


If shifted is TRUE, in an application that cycles between three or more states, the direction of cycling 
should be reversed. Note that the shifted parameter should be ignored by code running on the Series 3. 


The supplied method does nothing. 


COMEFIKE CHANGE ~~ ney _— 


INT com_file_ change (INT command,TEXT *pname) ; 


ate a file 


On receipt of this message the command manager of a file-based application should close its current file, 
saving it if necessary and, depending on whether command is H_COMMAND_OPEN_FILE or 
H_COMMAND_CREATE_FILE, open or create the file whose file specification is pointed to by pname. Note that 
pname points to a transient cell and thus should not be passed as an argument to the am_new_filename 
method. 


This message is sent to the command manager by wssrv as a result of the application receiving a 
Switchfiles message from the System Screen. The application itself may also send the command manager 
this message, for example, during start-up initialisation (normally in its ws_dyn_init method) and/or to 
implement the appropriate parts of its New file or Open file commands. 


An application that is not file-based will not receive this message from wsERv. 
The method should return zero to indicate that p_1eave has not been called. 


The supplied method does nothing other than to return zero. 


4 COMMAND MANAGER 
—_ EM MAND MANAGER 


See the description of the sHurTEr class in the chapter The WSERV Class for an explanation of the full 
processing of a Switchfiles message. 


COM EXIT : : Exit the application 


VOID com_exit (VOID) ; 


This message may be received either as the result of the application receiving a Shutdown message from 
the System Screen or as the result of the user having selected the application's Exit command. 


A file-based application must, if its file has changed, save the changes before exiting. If this fails it must 
come to the foreground and inform the user of the error, offering the user another chance to save the file. 


The supplied method simply calls p_exit (0). This is the recommended way to terminate the application, 
leaving the operating system to recover its resources. 


CHAPTER 5 


WINDOWS 


A window is a rectangle in screen coordinates that provides a coordinate system for clipped drawing. 
Everything that is displayed by an HWIM application is drawn within one or more windows. 


All HWIM windows subclass the wxn class, which is thus the ultimate superclass of all windows. The 
window classes supplied by HWIM are abstract classes and will normally need to be subclassed in order to 
create useful window objects. 


The supplied classes, listed below, are described in the following sections of this chapter. 
WIN the ultimate window superclass. 
BWIN a subclass of wrn that draws a standard border around the window. 


LODGER a pseudo-window that subclasses win. Such a window is assumed to occupy a rectangular 
region within another window. The enclosing window (referred to as the /andlord) will 
normally delegate all processing for that rectangle to the lodger. 


Precursors 
Familiarity with the following topics will aid the understanding of this chapter: 


¢ — the window concepts described in the Introduction and Windows chapters of the Window Server 
Reference manual 


e the wserv class, especially the ao_run method, which may send messages to a window 


¢ — graphics contexts and drawing, described in the Graphics Output chapter of the Window Server 
Reference manual 


Class diagram 


In addition to the methods and property in the application's code and data segments, a window has an 
associated data structure in the window server's resources, created by a call to wcreateWindow when an 
instance of win is itself created. The window server provides a set of functions that operate on such data 
structures, each data structure being uniquely identified by a window ID returned by wcreatewindow. 


Since a uniquely identifiable data structure with a set of functions that operate on it is effectively an object, 
the window server resources associated with a window can be considered as a component object. The 
existence of the window server resources is thus indicated in the above class diagram by the ‘using’ 
relationship between win and a notional wswin (Window Server WINdow) class. 


HWIM REFERENCE 


The WIN class 


destroy 
wn_redraw 
wn_dodraw 
wn_connect 
wn_key 


wn_visible 
wn_emphasise 
wn_position 
wn_calc_position 
wn_sense_help 


wn_set 
wn_sense 
wn_draw 
wn_init 


The wrn abstract class subclasses roor to form the superclass for all windows in HWIM applications. 


As described earlier, a window effectively has a component window server object. However, as can be 
seen from the pRopERTy section of the following class definition, the wxn class does not store an object 
handle for this ‘component’. Instead, it is referenced by means of a unique ID that is initialised in a call to a 
window's wn_connect method. 


In effect, the wn_connect method performs the function of creating and initialising the window server 
‘component’, in the same way that a normal component object is created and initialised in an object's 
initialisation method. It is therefore clear that the sending of a w_connecT message is an essential part of 
the initialisation of any window (with the exception of ‘lodger' windows, which are described later in this 
chapter). 


Class definition 
Defined in sub-category file win.c/ (generated header file win.g). 


CLASS win root 
The window object superclass 


{ 


REPLACE destroy Close server window then supersend destroy 

ADD wn_redraw Called in reponse to WM_REDRAW 

ADD wn_dodraw Same effect as redraw but called by application 
ADD wn_connect Connect the window to window server data (wswin) 
ADD wn_position Calculate position and re-position 

ADD wn_calec_position Calculate position 

ADD wn_key=p_false For processing WM_KEY from server 

ADD wn_visible Alters visibility state of window 

ADD wn_emphasise Window is highlighted in some way 

ADD wn_sense_help Give start ID for help 

DEFER wn_set Set some window object property fields 

DEFER wn_sense Sense some window object property fields 

DEFER wn_draw Draw to existing graphics context - usually subclassed 
DEFER wn_init Specific initialisation for a type of window 


5 WINDOWS 


CONSTANTS 
{ 
CURSOR_WIDTH 2 
CURSOR_COLWID 2 
SYSTEM_FONT_COLWID 2 
W_KEY_SPACE 32 
PR_BWIN_CUSHION oxi matches W_BORD CUSHION 
PR_BWIN_CORNER_4 0x2 matches W_BORD_CORNER_4 
PR_BWIN_SHADOW 2 0x4 matches W_BORD SHADOW_S 
PR_BWIN_SHADOW 2 0x8 matches W_BORD SHADOW _D 
PR_WIN_EMPHASISED 0x10 matches W_BORD_ SHADOW ON 
PR_BWIN_OPEN 0x20 matches W_BORD OPEN 
PR_BWIN_CORNER_1 0x40 matches W_BORD CORNER_1 


! Gap of four bits, reserved for the arrow bits, for subclasses of BWIN only 
! A dialog control is always a LODGER subclass, so can use 1 of the 4 bits 
PR_WIN_IS_DLCTRL 0x80 set by LODGER subclass whose landlord is a DLG 
PR_WIN_INITIALISED 0x800 Window completely initialised 
PR_WIN_FORCE_RIGHT 0x1000 

PR_WIN_FORCE_LEFT 0x2000 

PR_WIN_FORCE BOTTOM 0x4000 


PR_WIN_FORCE_TOP 0x8000 
PR_WIN_FORCE_FLAGS Oxf000 

WIN_3dBORDER PR_WIN_FORCE_RIGHT Alternative use, for S3a border style 
WIN_FROM_ATS PR_WIN_FORCE_LEFT Alternative use, for auto test system 
IN_WIN_EMPHASISED (PR_WIN_EMPHASISED) 

WV_INVISIBLE ) 

WV_VISIBLE 2 

WvV_INITINVIS 2 

WV_INITVIS 3 


WN_KEY_NO_CHANGE 0 
WN_KEY_CHANGED 3 
WN_KEY _CHANGED_DEFER 7 
( 
( 


WN_KEY_ CANCELLED -1) 
WN_KEY_ABSORB_ON -2) 
ERROR_RID_OFFSET 512 
} 
PROPERTY 
{ 
UWORD id; window server window ID 
UWORD flags; PR_WIN EMPHASISED etc. 


} 
} 


The Series 3 and Series 3a versions of the class definition do not contain the defined constant 
PR_WIN_IS_DLCTRL. 


The Series 3 version of the class definition does not contain the defined constants wIn_34BoRDER and 
WIN_FROM_ATS. 


It does, however, contain the following additional defined constants: 


SCREEN_WIDTH 240 
SCREEN_HEIGHT 80 

CURSOR_HEIGHT 10 

SYSTEM_FONT_HEIGHT 8 

SYSTEM_FONT_ASCENT 7 
SYSTEM_FONT_NUM_WIDTH 6 

CONTROL_HEIGHT (SYSTEM_FONT_HEIGHT+2) 
SYSTEM_FONT_ID WS_FONT_BASE 
BOLD_FONT_ID WS_FONT_BASE+1 
DIGITS_FONT_ID WS_FONT_BASE+2 
SYSTEM_MONO_WIDTH 6 

BOLD_MONO_WIDTH 8 

DEFAULT_ICON_ID WS_BITMAP_BASE+2 


On the Series 3a the corresponding values are read or derived from the globally accessible data that is 
described in the Introduction chapter of this manual. 


HWIM REFERENCE 


Property 
win.id the window ID, returned from a call to wcreatewindow, and used to 
identify the window server data structures associated with the window 
win.flags a collection of flags recording the state of the window, as described below 
Window flags 


The content of win.£1ags may be any legal combination of the following flags: 


PR_WIN_EMPHASISED TRUE if the window is to be drawn in a highlighted state, the flag is 
set or cleared by the wn_emphasise method 


PR_WIN_INITIALISED TRUE if some significant aspect of the window initialisation is 
successfully completed, normally implying some change in action 
during subsequent destruction of the window. This is currently used 
by only the pu¢zox subclass 


PR_WIN_IS_DLCTRL set TRUE , by pLcBox methods, for a LopcErR subclass if its landlord 
window is an instance of (a subclass of) p.cBox. Introduced for the 
Workabout to enable dialog controls to determine if they need to 
draw themselves in a small font. 


Additional flag bits are used by the pwrn subclass. 


The following flag values are used by system code, for example by the mm_calc_position method, during 
the initialisation of a number of types of window, but they are never set in win. flags: 


PR_WIN_FORCE_RIGHT the window is to be positioned at the right hand edge of the screen. 
This flag is mutually exclusive with pR_WIN_FORCE_LEFT 


PR_WIN_FORCE_LEFT the window is to be positioned at the left hand edge of the screen. 
This flag is mutually exclusive with pR_wIN_FORCE_RIGHT 


PR_WIN_FORCE_BOTTOM the window is to be positioned at the bottom edge of the screen. This 
flag is mutually exclusive with pR_WIN_FORCE_TOP 


PR_WIN_FORCE_TOP the window is to be positioned at the top edge of the screen. This 
flag is mutually exclusive with PR_WIN_FORCE_BOTTOM 


SSS EE a ae ee a 
WIN methods 


Destroy 
VOID destroy (VOID) ; 
Destroy the window, including its window server data structure, provided this has previously been 


successfully created. An application will not normally send this message to its client window (or to any 
permanent component of the client window). 


The method ensures that no window server event can be directed to the window after its destruction 
sequence is initiated, and calls wcloseWindowTree, passing win. id, to free the window's window server 
data. 


Finally, the method supersends the pEsTRoy message, to destroy the window's client-side resources 
(including automated destruction of any component objects). 


5 WINDOWS 


S window server data 


VOID wn_connect (PR_WIN *par, UINT fields, W_WINDATA *windata) ; 


Create the window server data structure for the window by calling the window server function 
wCreateWindow, writing the returned ID to win. id, as indicated by the following code: 


METHOD VOID win_wn_connect (PR_WIN *self,PR_WIN *par,UINT fields,W_WINDATA *wdata) 


{ 


self->win.id=wCreateWindow( (par ?par->win.id:0) ,fields,wdata, (UWORD) self) ; 


} 


The parameters windata and fields are as described for wcreateWindow in the Windows chapter of the 
Window Server Reference manual. The value of par should be nuxu if the window is to be a top-level 
window, otherwise it should be the handle of the parent window in the window tree. The value of sez is 
passed to wCreateWindow for use by the window server as a handle to identify the window, for example, 
when the window must be sent a wN_REDRAW message. The window server uses self in much the same way 
that window method functions use win. id. 


In general, HWIM windows are created with the w_w1n_BacK_BITMAp bit in windata->flags cleared, so 
that they will be redrawn by the window server wm_REDRAW mechanism, which causes the window to be sent 
a WN_REDRAW message. 


Assuming that the window server function woisableLeaves has not been called, any failure will result in 
p_leave being called. 


This method must be executed during the initialisation of any window (other than ‘lodger' windows - see 
later). 


Application code will frequently replace this method to customise the window's features and/or to create 
child windows. 


VOID wn_redraw(P_RECT *prect) ; 


This method is intended to be called by system code to redraw the window, following receipt by wserv of a 
window server event of type ww_REDRAW. An application will not normally replace this method, nor will it 
explicitly send a ww_REDRAW message to any of its windows. 


The operation of the method is as illustrated in the following code: 


VOID win_wn_redraw(PR_WIN *self, P_RECT *prect) 


{ 

wBeginRedrawWinGCo (self->win.id) ; 
p_send2 (self,O_WN_DRAW) ; 
wEndRedraw () ; 


} 


Note that the whole window is redrawn, the rectangle coordinates pointed to by prect being ignored. A 
window that selectively redraws only the area specified by prect should replace this method. 


WN_DODRA 


VOID wn_dodraw(VOID) ; 


Application-initiated redraw 


This method is intended to be called by the application itself, for example, following a change in the data 
being displayed. An application will not normally subclass this method. 


The operation is illustrated in the following code: 


VOID win_wn_dodraw(PR_WIN *self) 
{ 
wValidateWin (self->win.id); 
gCreateTempGC0 (self->win.id) ; 
p_send2 (self,O_WN_DRAW) ; 
gFreeTempGC() ; 
wFlush(); 


} 


HWIM REFERENCE 


The use of this method is equivalent to making a call to the window server function winvalidatewin, 
except that the redrawing is performed immediately, without having to wait for a redraw event to arrive 
from the window server. 


INT wn_visible(UINT flag) ; 


Set the visibility of the window, and any descendant windows, according to the value of flag. An 
application will not normally subclass this method. 


During initialisation of a window, possible values of flag are: 
Wv_INITVIS which calls winitialiseWindowTree (win. id) 
Wv_INITINVIS which calls wMakeInvisible(win.id) and then wInitialiseWindowTree (win.id). 


For an existing initialised window, this method may be called with flag set to either w_visrBLE or 
WV_INVISIBLE which respectively call wMakeVisible(win.id) OF wMakeInvisible (win.id). 


This method will normally be called during the initialisation of a window. See also the HWIM utility 
function htnitvis. 


The method returns zero and is thus suitable for being called under the protection of p_enter. 


dow highlight 
VOID wn_emphasise(UINT flag) ; 


Set or clear the PR_WIN_EMPHASISED bit in win. flags, depending on whether flag is TRUE or FALSE. Then 
call winvalidateWin (win. id) so that the window will eventually receive a wn_REDRAW message. 


Windows generally draw themselves differently in some way, according to whether or not they are 
emphasised. 


This method is not suitable for use in quality applications. It is expected that a subclass will always replace 
this method to provide specific and more effective redraw logic (see, for example the swzn subclass). 


rtiD for help 


INT wn_sense_help (VOID) ; 


Sense the resource ID for the application's current Help index. 


Returns the value of w_ws->wserv.help_index_id or, if this value is zero, the (negative) system resource 
ID -syS_HELP_ON_HELP. 


This method can be subclassed to facilitate context-sensitive Help. 


— Calcula 


VOID wn_calc_position(INT flags, P_EXTENT *pext); 


iw position 


Calculate, and write to pext->t1.x and pext->t1.y, the required screen coordinates of the top left corner 
of the window of width pext->width and height pext->height to place it on the screen in the position 
specified by flags. The calculation assumes that the window includes a surrounding blank ‘cushion’, one 
pixel wide. 


The value of flags may contain any ored combination of: 


e either PR_WIN_FORCE_RIGHT Or PR_WIN_FORCE_LEFT, with obvious meanings. In either case the 
window is positioned so that the single pixel cushion at the side of the window that touches the 
edge of the screen is not visible. If neither flag is present the window is centred horizontally 


¢ — either PR_WIN_FORCE_TOP OF PR_WIN_FORCE_BOTTOM, again with obvious meanings. In either case 
the window is positioned so that the single pixel cushion at the side of the window that touches the 
edge of the screen is not visible. If neither flag is present the window is centred vertically 


5 WINDOWS 


An application will not normally need to either replace or make explicit calls to this method. 


WN_POSITION _ _ Set window position 
VOID wn_position(INT flags) ; 
Position the window according to the value of flags, which may contain any ored combination of: 


e either PR_WIN_FORCE_RIGHT OF PR_WIN_FORCE_LEFT, with obvious meanings. In either case the 
window is positioned so that the single pixel cushion at the side of the window that touches the 
edge of the screen is not visible. If neither flag is present the window is centred horizontally 


¢ — either PR_WIN_FORCE_TOP Or PR_WIN_FORCE_BOTTOM, again with obvious meanings. In either case 
the window is positioned so that the single pixel cushion at the side of the window that touches the 
edge of the screen is not visible. If neither flag is present the window is centred vertically 


The method sends a wn_caLC_PosITIon message to determine the required position before moving the 
window by means of a call to wset window. 


If used, this method will normally be called during the initialisation of a window, but must not be called 
before the window has processed a wN_CONNECT message. 


An application will not normally need to replace this method 


cess a keypress 
INT wn_key (INT keycode, INT modifiers) ; 


Process a keypress, where keycode is the code of the key pressed and modifiers contains a set of flags 
indicatinf which modifier keys (SHIFT, CTRL etc.) were held down when the key was pressed. The possible 
values of keycode and modifiers are described in the Events chapter of the Window Server Reference 
manual. 


Depending on the type of keypress and the current state of the application, the ww_key message may be sent 
to a window (normally the client window or a dialog) by system code - notably the ws process key 
method of the application's instance of (a subclass of) wsERv. 


The supplied method does nothing other than return zero (wN_KEY_NO_CHANGE). 


A subclass will, in general, replace this method. In many cases the wn_key method of a window may 
delegate the processing by sending wn_kEy messages to one or more other windows. 


Note that the return value generally only has significance for subclasses of win. A dialog, for instance, will 
return a non-zero value to indicate that the keypress should terminate the dialog and a menu bar may return 
the ID of a command menu option to be executed. See the description of the wsERV ws process key 
method for the way in which system code interprets wn_key return values from various types of window. 


The possible return values given by the various wn_KEY_xxx constants specified in the wrn class definition 
are of particular significance for the wn_key methods of the pieBox class and the dialog component classes. 
See the Dialog Boxes chapter and the following dialog box component chapters for further details. 


Deferred WIN methods 


A window will generally replace one or more of the methods described below. Note that there is no 
requirement for any particular subclass to replace all these methods. 


WNUINIF . Initialise 


VOID wn_init(...); 
Provide class-specific initialisation. For most windows this will include a call of the form: 
p_sends (self,O_WN_CONNECT, parent,ws flags,&ws data); 


The number and types of parameters to the wn_init method depend on the class. However, once specified 
for a particular class, further subclasses will normally follow the same parameter structure. 


HWIM REFERENCE 


Note that a simple window may not need to supply this method, since all essential initialisation may be 
performed by the wn_connect and wn_visible methods. 


VOID wn_set(...); 


Set property 


Set one or more property fields. 


The number and types of parameters to the wn_set method depend on the class. However, once specified 
for a particular class, further subclasses will normally follow the same parameter structure. 


VOID wn_sense(...); 


Sense one or more property fields. 


The number and types of parameters to the wn_sense method depend on the class. However, once specified 
for a particular class, further subclasses will normally follow the same parameter structure. 


VOID wn_draw(VOID) ; 


Supply class-specific drawing for the whole area of the window, called from the wn_redraw and wn_dodraw 
methods. Most application subclasses will need to supply this method. 


The method assumes that an appropriate graphics context exists, so the caller is responsible for supplying a 
graphics context. Note, however that this method is called from the wn_redraw and wn_dodraw methods, 
both of which create a basic graphics context around the sending of a wx_DRAW message. 


5 WINDOWS 


The BWIN bordered window class 


destroy wn_draw 
wn_calc_position wn_emphasise 


wn_connect 
wn_dodraw 
wn_emphasise 
wn_key 
wn_position 
wn_redraw 
wn_sense_help 
wn_visible 


wn_set 
wn_sense 
wh-draw 


wn_init 


The Bwrn abstract class is the superclass for all bordered windows. 
Class definition 
Defined in sub-category file bwin.cl (generated header file bwin.g). 


CLASS bwin win 
All windows that have a border use this 


{ 


REPLACE wn_draw Redraw border 
REPLACE wn_emphasise Update border 
CONSTANTS 
{ 
IN_BWIN_CORNER_4 PR_BWIN_CORNER_4 
IN_BWIN_SHADOW_1 PR_BWIN_SHADOW_12 
IN_BWIN_SHADOW_2 PR_BWIN_SHADOW 2 
IN_BWIN_CUSHION PR_BWIN_CUSHION 
IN_BWIN_OPEN PR_BWIN_OPEN 


BWIN_CUSHION_X 
BWIN_CUSHION_Y 
BWIN_SHADOW_1_ HEIGHT 
BWIN_SHADOW_1_ WIDTH 
BWIN_SHADOW_2_ HEIGHT 
BWIN_SHADOW 2 WIDTH 


NNPRRP PB 


Draw border 


VOID wn_draw(VOID) ; 


Draw the window's border by calling 


gBorder (self->win. flags) ; 


HWIM REFERENCE 
See 


The significant flag bits are PR_BWIN_CUSHION to PR_BWIN_CORNER_1 inclusive, together with the following 
four bits (0x80 to 0x400 inclusive) used to indicate the corner arrows. These bits are equivalent to the 
window server flags W_BoRD_CUSHION to W_BORD_CORNER_1 and W_BORD_TOP_oN to W_BORD_BOT_oFF, whose 
effects are explained in the description of gBorder and gBorderrect in the Graphics Output chapter of the 
Window Server Reference manual. 


An application-specific subclass will normally replace this method to provide drawing of the window's 
content, including the line: 


p_supersend2 (self,O_WN_DRAW) ; 


to draw the border. 


e border 
VOID wn_emphasise(UINT flag) ; 


If f1ag is FALSE, Clear the PR_WIN_EMPHASISED flag (equivalent to the window server W_BORD_SHADOW_ON 
flag) in win. flags, otherwise set it. 


Then redraw the border as indicated in the following code: 
gCreateTempGCo (self->win.id) ; 
gBorder (self->win.flags) ; 


gFreeTempGC; 


The shadow of a shadowed bordered window is only visible when the window is emphasised. 


The LODGER class 


LODGER 


landlord 
offset 
width 


destroy 

wn_calc_ position 
wn_connect 
wn_dodraw 


wnh_emphasise 


wn_key 


wn_position 
wn_redraw 
wn_sense_heip 
wn_visible 


wn_set 
wn_sense 
wn_draw 
wn_init 


destroy 
wn_init 
wn_visible 
1g_draw 
ig_self_check 
ig_set_id_pos 


ig_sense_width 
lg_update 


The Loner class defines a window that does not have its own independent window server data structure, 
and therefore does not have an independent window server ID. A lodger window is defined to be any 
window that subclasses LopGER. 


A lodger window occupies a rectangular region within another window, referred to as the lodger window's 
landlord, and shares the window ID of the landlord window. In other respects a lodger window has broadly 
similar behaviour to a normal window, supporting a similar set of drawing and key processing messages. A 
lodger window can be considered to take over the responsibility for drawing the content of a rectangular 
region of the landlord window. 


5 WINDOWS 


A significant difference between the two types of window is that drawing in a lodger window is not clipped 
by the boundaries of the lodger window itself. Drawing will only be clipped by the landlord window 
rectangle. In consequence, a lodger window has a duty never to draw outside its bounding rectangle. 


The most common single use for a lodger window is as a component control within a dialog box. 


Since a lodger window does not have an independent window server data structure, it is more efficient in 
terms of memory usage. This can be significant in the case of a complex compound window (a dialog box, 
for example, can easily need ten or more component sub-windows). An additional advantage is that such a 
compound window will scroll more smoothly - the scroll mechanism operates on only the single 'real' 
window and does not require messages to be sent to any of the component lodger windows (except for 
those that have freshly exposed regions to draw). 


Subclasses of Lopcer (and, indeed, any windows that do not subclass swrn) are free to reuse the flag bits 
PR_BWIN_CUSHION tO PR_BWIN_CORNER_1 inclusive, together with the four flag bits 0x80 to 0x400 inclusive 
that are used to indicate corner arrows. 


Class definition 
Defined in sub-category file /odger.cl (generated header file lodger.g). 


CLASS lodger win 
Lodger window 


{ 


REPLACE destroy=root_destroy 


REPLACE wn_init Set up landlord 
REPLACE wn_visible 
ADD lg_set_id_pos Set window ID after dynamic initialisation 
ADD lg_draw Temp GC and call wn_draw 
ADD 1lg_self_check=p_true Returns TRUE if contents are legal 
DEFER lg_sense_width For dialogs to set their sizes 
DEFER lg update For fnselwn and fnedit 
CONSTANTS 
{ 
LG_CHECK_OK Zz Lodger self checked o.k., no change 
LG_CHECK_FAILED 0 Lodger failed self check, no change 
LG_CHECK_FAILED_CHANGED (-1) Lodger failed self check, changed 
LG_CHECK_OK_CHANGED (-2) Lodger self checked ok., changed 
) 
PROPERTY 
{ 
P_POINT offset; offset into landlord window 
UWORD width; width available to control 
PR_WIN *landlord; owner window 
} 
} 
Property 
lodger .offset the pixel coordinates of the top left corner of the lodger window with 
respect to the top left corner of the landlord window 
lodger.width the width, in pixels, of the area available to the lodger window 
lodger. landlord the handle of the window's landlord window, assumed to be (a subclass of) 


win. The lodger window has access to the window server ID of the 'real' 
window (the landlord) via lodger .landlord->win.id 


A lodger window's property does not record the height of the lodger window. This is suitable when a 
lodger window is a component of a dialog box since, in this case, it always has a fixed height of 
CONTROL_HEIGHT pixels. 


HWIM REFERENCE 


LODGER methods 
WNINT me Initialise 


VOID wn_init(UINT *par, PR_WIN *landlord) ; 


Initialise the lodger window by copying the value of landlord, which should be the handle of the owning 
landlord window, into Lodger .landlord. 


The method ignores the value of par, which is specified for use by subclassers. 


_ Destroy 


VOID destroy (VOID) ; 


Destroy only the client-side resources of the lodger window, together with automatic destruction of any 
components. 


Calls the Roor destroy method directly, to avoid calling the destroy method at the wxn level, which might 
free the landlord's window server data structure. 


VOID wn_visible(UINT flag) ; 


Make the lodger window invisible if f1ag is rausz, otherwise make the lodger window visible. (Note that, 
in contrast to the wrn superclass, only two flag values are supported.) 


If the lodger window is being made visible, the method copies the landlord window's window server ID 
into win.id and sends an LG_DRAW message to draw the lodger window's contents. 


If the lodger window is being made invisible, win. id is set to zero and the method creates a temporary 
graphics context, calls gclrrect to clear the area in the landlord window that is occupied by the lodger 
window and then frees the temporary graphics context. 


A non-zero value of win.id thus indicates that the window is visible and this test is used, for example, by 
the 1g_draw method. Setting win. ia to be a copy of the value in lodger. landlord->win.id is an 
implementation decision that simplifies access to the window server ID of the 'real' window. 


Set | 


VOID 1g_set_id_pos(INT id, P_POINT *pos, UINT width) ; 
Set win.id to the value of id, copy «pos into lodger.offset and set lodger.width to width. 


A typical call to this method will be from a dialog box after all the items have been loaded and the dialog 
box has been set to the required width to display all its items. 


VOID 1g_draw(VOID) ; 
If win.id is non-zero, indicating that the window is in the visible state, draw the window content: 


gCreateTempGCO (self->win.id) ; 
p_send2 (self,O_WN_DRAW) ; 
gFreeTempGC () ; 


Otherwise do nothing. 


This method is intended to be called following a change in the data displayed in the lodger window (for 
example, at the conclusion of a lodger window's wn_set method). Since it creates its own temporary 
graphics context, it must never be called when a temporary graphics context exists, for example, as a result 
of the landlord window receiving a wn_REDRAW message. 


5 WINDOWS 


sELF_CHECK a Check content is valid 


INT lg_self _check(INT item, INT can_defer) ; 


Perform a check that any property contains valid data. A numeric editor may, for example, check that its 
current value is within its allowed upper and lower bounds. 


Possible return values are as follows: 


LG_CHECK_OK the data has not changed and the check succeeded 
LG_CHECK_FAILED the data has not changed and the check failed 
LG_CHECK_FAILED_CHANGED the data has changed and the check failed 
LG_CHECK_OK_CHANGED the data has changed and the check succeeded 


The supplied method just returns 1G_CHECK_oK. 


Deferred LODGER methods 


These methods are intended to be replaced by classes that are used as components of a dialog box. 


red width 


INT lg_sense_width (VOID) ; 


This method is expected to return the width, in pixels, required to draw the lodger window contents. 


An object will only receive this message when it is a component of a dialog box (see the pLGBox 
dl_set_size method, described in the Dialog Boxes chapter). 


Some system-supplied subclasses assume that this method is called only once in the lifetime of an instance. 


LG{UPDATE: Up 


VOID lg_update (TEXT *pack, INT derr); 


3 file name 


This method is defined for the ryseLwn and rneprt dialog box component classes. See the descriptions of 
these classes for an explanation of the method. 


jL 


CHAPTER 6 


List BOXES AND MENUS 


All HWIM applications are expected to use commands and will normally require a menu bar and its 
associated pull-down menu(s). A menu bar is implemented with the aid of the LtsTBox class, which forms 
a basic component of a number of other HWIM window objects. 


Precursors 
Familiarity with the following topics will aid the understanding of this chapter: 


e the descriptions of the win and Bwrn classes in the Windows chapter 


e the creation of a menu bar and the sending of wn_kEy messages to a menu bar from the wsERv 
ao_run method, as described in the chapter The WSERV class 


Class diagram 


f 
Py % 
; 
FA a 
¢ 
ne \ 
: 
. 
7 1 Fa ae 
forts Ne (rte. See ne a Ves 
i ta ares 
j win / win / listbox “¢ 


goehe \ oe 
yet ses \ verte Pa ee 
iC Sone vmatcher ‘ 
é 
t 


va 
’ 


(ee ie oe 


‘ 


TPN a ote F, Bee g 
/ menutab * / menubar > / pulldown > 
f : , f 2 
Bc ————— On o————— H 


= 1 ws 4 


/ Xpulldwn ~> 
¢ ra 


HWIM REFERENCE 


List boxes 


wn_calc_position 
wn_connect 
wn_dodraw 


wn_position 
wn_redraw 
wn_sense_help 
wn_visible 


wn_set 
wn_sense 


match 
va 

flags 
width 
matchlen 
curofft 
offset 
current 


top 

first 

last 
vastart 
matchstart 


destroy 

wn_init 

wn_key 

wn_draw 
wn_emphasise 
1b_draw_item 
1b_draw_emphasis 
1b_size_ window 
ib_item_width 
lb_take_focus 
lb_inquire_focus 
1b_inquire_item 
lb_inquire_last 


A list box is a bordered window that displays a list of items, one per line. One of the items is normally the 
current item and is highlighted with an inverse obloid (a rectangle without its four corner pixels). 


List boxes - that is, instances of (a subclass of) L1sTBox - are used, for example, to display the expanded 
contents of a choice list, for listing items in help screens and for pull-down menus. The following diagram 
shows an example of selecting, by means of an expanded choice list, the use of a template file - within the 
dialog used by the Word application's Create new file command. 


Create new file 


else tenplate 
Template: Name 
Disk 


List boxes are also used to display file /ists, as shown in the following diagram. This illustrates that a list 
box may have a title consisting of one or more lines, separated from the main list by a horizontal line. The 
main list may contain more items than can be shown on the screen. The presence of further items before or 
after those that are visible can be indicated by up and down arrows in a right hand scroll gutter. 


¢ Disk Internal, 62K free + 
NURDN* 


NURDN ey 
Opl.urd 689 63:24pm _ 11702793 
pred 1HAVS Llitsan Sa-o1-92 
Vord.urd 7O9? = 1:81pm 24716792 
VJorkwrd 89¢ 6:24pm 11/82/93 4 


The current item may be changed by means of the page up, page down and cursor keys. If there are more 
items than can be displayed in the list box window, the contents will be scrolled so that the current item 
remains visible. 


6 LIST BOXES AND MENUS 
OES TE BUAES AND MENUS 


The t1stBox class provides support for incremental matching, whereby successive keypresses select the 
first item in the list box that starts with the sequence of matching characters that has so far been typed in. 
(This behaviour is exhibited, for example, by the file selector, displayed by selecting the file name item in 
the dialog for any file-based command and pressing the Tab key.) 


The items displayed in a list box are assumed to be stored in a variable array (an instance of a subclass of 
the OLIB varoor class). The data in each individual element of this array is assumed to be stored 
contiguously rather than, say, crossing the boundary between two or more allocated memory cells. Each 


element is assumed to contain a zero terminated string (which may, however, be preceded by a constant 
number of bytes of other data). There is no requirement for adjacent records to be contiguous with each 


other. 


Class definition 


Defined in sub-category file /istbox.c! (generated header file listbox. g). 


CLASS listbox bwin 
List box 
{ 
REPLACE destroy 
REPLACE wn_init 
REPLACE wn_key 
REPLACE wn_draw 
REPLACE wn_emphasise 
ADD 1b_draw_item Draw an item by index number 
ADD lb draw_emphasis Draw/undraw emphasis on an item 
ADD lb_size_window Resize the window to the correct size 
ADD 1b_item_width Returns the required width of the item 
ADD lb _take_focus Move focus item specified by index 
ADD lb inquire focus Returns index of item with focus 
ADD 1lb_inquire_item Get pointer to item text 
ADD 1b_inquire_last Get index of last item 
CONSTANTS 
{ 
IN_LISTBOX_MATCHER 0x0001 
IN_LISTBOX_KEEP_ARRAY 0x0002 
IN_LISTBOX_TEXT_OFFSET 0x0004 
IN_LISTBOX_CUR_SET 0x0008 
IN_LISTBOX_FIRST_SET 0x0010 
IN_LISTBOX_LAST_SET 0x0020 
IN_LISTBOX_POS_ALIGN_X 0x0040 
IN_LISTBOX_POS_ALIGN_Y 0x0080 
IN_LISTBOX_MIN_WIDTH 0x0100 
IN_LISTBOX_AUTO_SIZE 0x0200 
IN_LISTBOX_FORCE_WIDE 0x0400 
IN_LISTBOX_WRAP_ROUND ox0800 
IN_LISTBOX_FIXED WIDTH 0x8000 


PR_LISTBOX_KEEP_ARRAY 
PR_LISTBOX_FORCE_WIDE 
PR_LISTBOX_WRAP_ROUND 


IN_LISTBOX_KEEP_ARRAY 
IN_LISTBOX_FORCE_WIDE 
IN_LISTBOX_WRAP_ROUND 


PR_LISTBOX_UNSTABLE 0x1000 
PR_LISTBOX_BOLD_CURSOR 0x2000 
PR_LISTBOX_PLAQUE 0x4000 


PR_LISTBOX_FIXED_WIDTH 
PR_LISTBOX_SMALL FONT 


LISTBOX_TOP_EDGE 
LISTBOX_BOTTOM_EDGE 
LISTBOX_LEFT_EDGE 
LISTBOX_RIGHT_EDGE 
XLISTBOX_TOP_EDGE 
XLISTBOX_BOTTOM_EDGE 
XLISTBOX_LEFT_EDGE 
XLISTBOX_RIGHT EDGE 
LISTBOX_OBLOID_INDENT 


LISTBOX_TITLELINE_HEIGHT 3 


LISTBOX_SCROLL_GUTTER 
LISTBOX_SCROLL_OFFSET 


} 


IN_LISTBOX_FIXED_WIDTH 
PR_WIN_FORCE_RIGHT set into win.flags property 


(BWIN_CUSHION_Y¥+2) 
(LISTBOX_TOP_EDGE+BWIN_SHADOW_1_ HEIGHT) 
(BWIN_CUSHION_X+2) 
(LISTBOX_LEFT_EDGE+BWIN_SHADOW_1_ WIDTH) 
(LISTBOX_TOP_EDGE+6) 

(LISTBOX_BOTTOM_EDGE+S) 

(LISTBOX_LEFT_EDGE+6) 

(LISTBOX_RIGHT_EDGE+5) 

2 extra width on each side for highlight obloid 
additional height for line below a title 
7 horizontal space for a scroll indicator 
1 


HWIM REFERENCE 


_— eee 


TYPES 
{ 


typedef struct 


{ 


UWORD flags; 


PR_VAROOT *array; 


UWORD offset; 
WORD current; 
UWORD top; 
UWORD first; 
UWORD last; 
P_POINT pos; 
UWORD minwid; 
} IN_LISTBOX; 


} 


PROPERTY 1 


} 


{ 


PR_VMATCHER *match; 


PR_VAROOT *va; 
UWORD flags; 
WORD width; 


UWORD matchlen; 


UWORD curoff; 
UWORD offset; 
WORD current; 
WORD top; 
WORD first; 
WORD last; 
WORD vastart; 


WORD matchstart; 


matcher object if any 

item list 

holds PR_LISTBOX flags 

Width of the list box in pixels 

for matcher 

offset of text for matcher cursor 
offset of text in VA item 

current selection 

top visible item in scrolling section 
first item in scrolling section 

last item in scrolling section 

index in listbox where va starts 
index in listbox where matching starts 


The Series 3 version does not contain the definitions of In_LISTBOx_FIXED_WIDTH, PR_LISTBOX_PLAQUE, 
PR_LISTBOX_FIXED_WIDTH, XLISTBOX_TOP_EDGE, XLISTBOX_BOTTOM_EDGE, XLISTBOX_LEFT_EDGE and 
XLISTBOX_RIGHT_EDGE. 


It does, however, contain an additional constant definition: 


LISTBOX_ITEM_HEIGHT 


(SYSTEM_FONT_HEIGHT+2) 


On the Series 3a, this value is derived from the data described in the Globally accessible data section of the 
Introduction chapter. 


The constant pR_LISTBOx_SMALL_FonT is introduced in the class definition for the Workabout. 


Property 


listbox. 


listbox. 


listbox. 


listbox. 


listbox. 


listbox. 


match 


va 


flags 


width 


matchlen 


curoff 


Either wont or the handle of an instance of vmarcuer. Incremental 
matching is enabled if this element is not nouu. 


The handle of an instance of a subclass of varoot containing the items 
that are displayed in the list box. By default each item is assumed to 
contain zero terminated text, whose first character is at a byte offset of 
listbox.offset within the item. 


A combination of the state flags listed below. 


The width, in pixels, of the region within the list box that is used to 
display items (not counting the window borders and any scroll gutter). 


Provided incremental matching is enabled, the number of characters that 
have currently been incrementally matched. The address of this item is 
passed to any VMATCHER component, which automatically updates its 
value. 


Provided incremental matching is enabled, the current horizontal offset to 
the incremental matching cursor. 


6 LIST BOXES AND MENUS 
—_— I BU AES AND MENUS 


listbox.offset The byte offset within each element of the 1istbox.va array to the first 
character of the text to be displayed. 

listbox.current The index number of the currently highlighted item. 

listbox. top The index of the first visible item in the main list; its value is always 


greater than or equal to listbox. first. 


listbox.first The index of the first item that forms part of the main list of items in the 
list box. If non-zero, items with indexes in the range 0 to listbox. first- 
1 are drawn as the list box title, separated from the main list by a 
horizontal line. 


listbox.last If not zero, the index of the last item from the 1istbox.va array to be 
displayed in the main list. Setting 1istbox.1ast allows trailing array 
items to be excluded from the list. 


listbox.vastart The index of the first item whose content is stored in the 1istbox.va 
array, allowing subclasses (see, for example, the rrLeLrst class) to derive 
items, such as their title, from other sources. Such subclasses must replace 
the lb_inquire_item method. 


listbox.matchstart The index of the item at which incremental matching is to start - intended 
for use by the rrLeLrst subclass. No incremental matching cursor is ever 
drawn in an item whose index number is less than 1istbox.matchstart. 


List box flags 
The content of 1istbox. flags may be any combination of the following flags: 
PR_LISTBOX_KEEP_ARRAY If set, the 1istbox.va array is not sent a DESTRoy message on destruction 
of the list box. 
PR_LISTBOX_FORCE_WIDE If set, the list box is drawn to include a scroll gutter, even if all the list 


items can be displayed within the list box window. 


PR_LISTBOX_WRAP_ROUND If set, pressing the up cursor key when positioned on the first item in the 
list, or the down cursor key when positioned on the last item in the list 
will wrap between the first and last items. 


PR_LISTBOX_UNSTABLE This flag should be set by a L1sTBox subclass to indicate that the contents 
of the listbox.va array are in an inconsistent state. It is used in this way by 
the FILELISst class. 


PR_LISTBOX_BOLD_cursoR Should be set if all selectable list box items are displayed in bold text. 


PR_LISTBOX_PLAQUE If set, the listbox is drawn with a 3-dimensional style grey and black 
border, otherwise a simple black border is used, as on the Series 3. This 
flag is not supported on Series 3 machines. 


PR_LISTBOX_FIXED_WIpTH This flag should only be set on initialisation by including 
IN_LISTBOX_FIXED_WIDTH in the flags field of the 1n_LisTBox 
inintialisation struct. If set, the width of the listbox is exactly as specified 
by the minwid element of the 1n_ursTsox struct. Otherwise, the width of 
the listbox is adjusted if necessary to accommodate the widest item. This 
flag is not supported on Series 3 machines. 


The contents of the remaining bit fields of listbox. flags are undefined. 
On the Workabdout, an additional flag may be set in win. flags: 


PR_LISTBOX_SMALL FONT On the Workabout, this flag may be set in the win. £1ags property of the 
list box, to indicate that the list box contents should be displayed in the 
small font. This flag is currently only set on initialisation of the 
Workabout rILeutst class 


HWIM REFERENCE 


LISTBOX methods 


Destroy 
VOID destroy (VOID) ; 
Destroy the list box and, optionally, its variable array component. 


If listbox. flags does not contain PR_LISTBOX_KEEP_ARRAY, listbox.va (if not nuLL) is sent a DESTROY 
message. The method then supersends the pEstroy message. 


_ {Initialise 


VOID wn_init (IN_LISTBOX *init) ; 
Initialise the list box. 


The horizontal cursor offset, 1istbox.curoff, is set to a suitable initial value of LISTBOX_LEFT_EDGE + 
LISTBOX_OBLOID_INDENT. 


The list box data array handle, 1istbox.va, is set from init->array. This handle is assumed to be of an 
instance of a subclass of varoor and must always be supplied. 


The value of init->£lags is copied to listbox. f1ags. The significant flags for general behaviour of the 
list box are: 


IN_LISTBOX_KEEP_ARRAY Referred to in listbox. flags aS PR_LISTBOX_KEEP_ARRAY. If set, 
prevents the destroy method from sending a pEsTRoy message to 
listbox.va. 


IN_LISTBOX_FORCE_WIDE Referred to in 1istbox. flags aS PR_LISTBOX_FORCE_WIDE. If set, forces 
the list box width to include space for the scroll symbols that would 
otherwise only be shown if the list box contained more enties than could 
be displayed on the screen. 


IN_LISTBOX_WRAP_ROUND Referred to in listbox. flags aS PR_LISTBOX_WRAP_ROUND. If set, 
pressing the up and down cursor keys will cause wrapping between the 
first and last entries in the list box. 


PR_LISTBOX_PLAQUE If set, the list box is displayed with a 3D border (not available on the 
Series 3). This is used, for example, for Help lists. 


Further initialisation processing depends on other flags specified in init->f1ags. If set, these have the 
following meanings, explained in the order in which they are processed: 


IN_LISTBOX_MATCHER Create an instance of the vmatcuer class, storing its handle in 
listbox.match, and initialise it, effectively as follows: 
p_sends (listbox.match,O IM_INIT, &listbox.matchlen,128, 
init->array) ; 


IN_LISTBOX_TEXT_OFFSET Set listbox.offset from init->offset, otherwise listbox. offset is 


zero 
IN_LISTBOX_FIRST_SET Set listbox. first from init->first, otherwise listbox. first is zero 
IN_LISTBOX_LAST_SET Set listbox.last from init->1last, otherwise listbox. last is zero 
IN_LISTBOX_CUR_SET Set listbox.current from init->current, otherwise listbox. current 


is set equal to listbox. first 


IN_LISTBOX_MIN_WIDTH Set the initial value of listbox. width from init->minwid, otherwise 

or listbox.width is zero. The width of the list box will not be less than any 

IN_LISTBOX_FIXED_WIDTH initial value of Listbox.width. If the flag 1n_LISTBOX_FIXED_WIDTH is 
set (not on the Series 3) the width will not be further adjusted. 


6 LIST BOXES AND MENUS 
————_———_—. Ss OEE BO KAES AND MENUS 


IN_LISTBOX_AUTO_SIZE Send an LB_SIZE_WINDOW Message, passing init->flags and the address 
of init->pos. This sets the height and (provided the width of the list box 
is not specified to be fixed) width of the list box to be sufficient to display 
the contents. 


Note that if the 1n_t1sT_Box_auro_sizz flag is not set, the creator of an instance of prsTBox must send an 
explicit LB_SIZE_wInDow message before attempting to make the list box visible. 


The remaining initialisation flags, 1n_L1sTBox_Pos_aLIGN_x and IN_LISTBOX_POS_ALIGN_Y, are of 
significance to the 1b_size_window method. 


é key input 
INT wn_key(INT keycode, INT modifiers) ; 


Sends an LB_INQUIRE_LAST message to find the index number of the last item in the list box. Further 
processing depends on the value of keycode as follows: 


W_KEY_RETURN Retums listbox. current+1. 

W_KEY_ESCAPE Retums wN_KEY_CANCELLED. 

W_KEY_ LEFT, If modifiers contains W_CTRL_MODIFIER, positions to the top item in the main list 
W_KEY_UP (with index number listbox. first). Otherwise, moves up one item in the list 


unless the current item is already the first. If already on the first item and 
listbox. flags contains PR_LISTBOX_WRAP_ROUND, positions to the last item in 
the list. Sets 1istbox.matchlen to zero, sets the new item by sending an 
LB_TAKE_FOCUS message and returns WN_KEY_NO_CHANGE. 


W_KEY_ RIGHT, If modifiers contains W_CTRL_MODIFIER, positions to the last item in the main 

W_KEY_DOWN list. Otherwise, moves down one item in the list unless the current item is already 
the last. If already on the last item and 1istbox. flags contains 
PR_LISTBOX_WRAP_ROUND, positions to the first item in the list. Sets 
listbox.matchlen to zero, sets the new item by sending an LB TAKE Focus 
message and retumms WN_KEY NO_CHANGE. 


W_KEY_PAGE_UP If modifiers contains W_CTRL_ MODIFIER, or if all the items are visible in the list 
box, positions to the first item in the main list. Sets 1istbox.matchlen to zero, 
sets the new item by sending an LB_TAKE Focus message and returns 
WN_KEY_NO_CHANGE. 


Otherwise, scrolls up by one less than the number of visible items in the main list 
(or to the top of the list, if less) writing a new value to 1istbox. current, moving 
the emphasis to this item and, if 1istbox.match is not NULL, sending it an 
IM_SET_VAL message and resetting the match cursor to the first character of the 
item. The method then terminates by returning wN_KEY_NO_CHANGE. 


W_KEY_PAGE_DOWN If modifiers contains w_CTRL_MODIFIER, Or if all the items are visible in the list 
box, positions to the last item in the main list. Sets 1istbox.matchlen to zero, 
sets the new item by sending an LB_TAKE_Focus message and returns 
WN_KEY_NO_CHANGE. 


Otherwise, scrolls down by one less than the number of visible items in the main 
list (or to the end of the list, if less) writing a new value to listbox. current, 
moving the emphasis to this item and, if 1istbox.match is not NULL, sending it an 
IM_SET_VAL message and resetting the match cursor to the first character of the 
item. The method then terminates by returning w_KEY_NO_CHANGE. 


HWIM REFERENCE 
Ss eSSSSSSSSSSSSSSSSSSFFee 


any other key If 1istbox.match is NULL, keycode represents a printable character and 
listbox .va is not NULL, a cyclic search is made, forward from the current item, 
for a case-insensitive match between keycode and the first letter of an item. Ifa 
match is found, the matching item is made the current item by means of an 
LB_TAKE_FOCUS message. 


If 1istbox.match is not wuLL, incremental matching is attempted by sending 
listbox.match an IM_KEY message (which will adjust listbox.matchlen as 
appropriate) passing keycode and modifiers. 


e if this returns IM_NEW_DISPLAy, the new current item is found by adding 
listbox.vastart to the return value from an 1M_SENSE_VAL message 
sent to Listbox.match. This item is made the current item by means of 
an LB_TAKE_FOCUS message 


e if itreturns Im_nwew_En the incremental matching cursor is redrawn in 
its new position, according to the value of listbox.matchlen 


In all of these cases the method returns wN_KEY_NO_CHANGE. 


Draw 
VOID wn_draw(VOID) ; 


If listbox. flags contains PR_LISTBOX_UNSTABLE the method simply clears this flag and calls 
winvalidateWin so that the list box will receive a ww_REDRAW message at a later time. 


Otherwise the method draws the list box border and sends an LB_INQUIRE_LAST message to find the index 
number of the last item to be drawn. It then draws its content as follows: 


e if listbox. first is not zero the items with index numbers from 0 to listbox. first-1 are drawn 
at the top of the list box, followed by a horizontal line across the full width of the list box. 


e if 1listbox.top is greater than listbox. first, indicating that more items are available above the 
first visible item in the main list, an up arrow is drawn at the top of the scroll gutter 


e starting with the item with index number 1istbox.top, successive items are drawn until the items 
are exhausted or the list box is full. If the item that has just been drawn is the selected item (with 
index number equal to listbox.current) and win. flags contains PR_WIN_EMPHASISED, the item 
is emphasised by sending an LB_DRAW_EMPHASIS message 


e if more items are available following the last item drawn, a down arrow is drawn at the bottom of 
the scroll gutter 


The text for each item is found by sending an LB_INQUIRE_ITEM message and is drawn by sending an 
LB_DRAW_ITEM message. 


VOID wn_emphasise(INT flag); 
Set the list box window's emphasis if f1ag is TRUE, otherwise clear the emphasis. 


The method first sets or clears the pR_wIN_EMPHASISED flag in win. flags, creates a temporary graphics 
context and draws the border in the appropriate emphasised state. 


Provided listbox. current is greater than or equal to listbox. first, the method calculates, in a P_RECT 
struct, the rectangular region within its window corresponding to the 1istbox. current item. It then sends 
an LB_DRAW_EMPHASIS message, passing listbox.current, a pointer to the p_REct struct and the value of 
flag. 


The temporary graphics context is then freed. If incremental matching is being used the incremental text 
cursor is drawn in its current position if £1ag is TRUE, otherwise it is erased. 


6 LIST BOXES AND MENUS 


Set the window size and position 
VOID lb_size_window(INT flags, P_POINT *pos) ; 


Set the size of the window to that required to display the contents. The position of the window's top left 
comer is set, guided by the flags passed in f1ags and the coordinates in the p_poznr struct pointed to by 
pos. 


Note that this method includes the code that creates the window and so must be called before attempting to 
make the list box visible. It will normally be called from the wn_init method, provided the parameters to 
this method include the In_LIsTBox_AUTO_szzkE flag. 


On entry, 1istbox.width contains a previously specified minimum allowable width for the list box. 
Provided 1istbox. flags does not include pr_LIsTBox_FIXED_wipTH, the required width to display all the 
list box items is calculated as the larger of: 


e the value of listbox.width less the left and right borders 
e the widest of all the items, found by sending an LB_ITEM_wIpTH message for each item 


This value overwrites the original value of 1istbox.width, but the original value is also held for later use. 
The total width of the window is calculated by adding 1istbox.width, LISTBOX_LEFT EDGE, 
LISTBOX_LEFT_EDGE and (if either listbox. flags contains PR_LISTBOX_FORCE_WIDE, or there are more 
than seven items to be displayed) Ltstaox_scroLL_curTerR. Except in the case of the Workabout, if the 
calculated width exceeds the screen width, the method calls p_1eave (E_GEN_TOOWIDE). 


The height of the list box is calculated to display a the number of items in the list, provided this does not 
exceed the number of items that can be shown on the screen. If listbox. first is not zero, the height is 
increased by the additional amount required for the line dividing the title from the main list. 


Once the dimensions of the list box have been determined, the position on the screen is calculated. Three 
options are allowed: 


¢ if £1ags contains In_LIsTBox_Pos_aLren_x the list box is centred horizontally on the region 
starting as pos->x and of width equal to the value that 1istbox.width had on first entry to the 
method. If this results in the window extending beyond either the left or right edge of the screen, 
the window is positioned at the corresponding edge. The y-coordinate of the top left corner of the 
list box window is set to be equal to pos- >y. This option is used, for example, to display a pull- 
down menu, centred as closely as possible on its menu bar item. 


¢ if £1ags contains IN_LISTBox_Pos_aLIcn_y the list box is positioned so that, as far as possible, 
the currently highlighted item (the item with index 1istbox. current) is aligned with the position 
indicated by pos->y. The x-coordinate of the top left corner of the list box window is set so that 
the text of the items starts at the position indicated by pos->x, unless this results in the window 
exrending beyond the right edge of the window, in which case it is positioned as far to the right as 
possible. This option is used, for example, to display the list used to display an expanded set of 
choices for a dialog box choice list control. 


e if £1ags contains neither In_LISTBOX_POS_ALIGN_X Nor IN_LISTBOX_Pos_ALTGN_x, the list box is 
centred on the screen by sending a wN_CALC_POSITION message. 


The list box's win. flags is set to PR_BWIN_CUSHION| PR_WIN_EMPHASISED ored with either 
IN_BWIN_SHADOW_1 OT, if listbox. flags contains PR_LISTBOX_PLAQUE, IN_BWIN_SHADOW_2. The window is 
created with the required position and size as a root window (that is, with a nuL value of the parameter 
par) by sending a wN_CONNECT message. 


If incremental matching is enabled, the incremental matching cursor is drawn at the first character of the 
currently selected item. 


5B DRAW_ITEM : Draw an item 


VOID 1lb_draw_item(TEXT *buf, INT index, P_RECT *prect); 


Draw, in the rectangle specified by prect, the content for the list box item with index number index, using 
the zero terminated text pointed to by bug. 


The text is drawn to the current graphics context by a call to the window server function gprintBoxText: 


It is the caller's responsibility to ensure that a suitable graphics context exists. 


HWIM REFERENCE 


This method does not use index, which is provided for subclasses that replace this method (punipown, 
HELPLIST and FILELIST). 


MPHASIS =+=— Toggle emphasis for an item 
VOID 1lb_draw_emphasis(INT index, P_RECT *prect, INT on); 


Toggle the presence of a highlighting obloid, in the rectangle specified by prect, for the item with index 
number index. The value of on is Truz if emphasis is being set, and ranse if emphasis is being cleared. 


The action is as indicated in the following code: 


METHOD VOID listbox_lb_draw_emphasis(PR_LISTBOX *self, INT index,P RECT *prect, INT on) 


{ 


P_EXTENT ob; 


ob.tl=prect.tl; 
ob.width=p_send3(self,O LB ITEM_WIDTH, index) ; 
ob. height=DatGate->gate.x.cht; 
giInvObloid(&ob) ; 


} 


The supplied method does not use on, which is provided for use by the HELPLIsT subclass. 


‘Sense required width for an item 
INT 1b_item_width(INT index) ; 


Return the pixel width required to display the text of the item with index number index, including a gap of 
width LIsTBOx_OBLOID_INDENT at either side of the text, to allow the item to be highlighted. 


s to an item 
VOID 1lb_take_focus(INT focus) ; 
Select the item with index number focus. 


If focus is the index number of the item that is currently selected the method does nothing other than 
ensure that, provided 1istbox.match is not nuLL and the window is emphasised (win. flags contains 
PR_WIN_EMPHASISED) the incremental matching cursor is drawn in its current position. 


Otherwise, listbox. current is set to focus. Provided the window is emphasised, the previously selected 
item has its highlighting removed and the highlight is set on the item with index number focus. If 
necessary, the list box contents are scrolled until this item is visible. 


If incremental matching is enabled, 1istbox.match is sent an IM_SET_VAL message, passing the value of 
focus-listbox.vastart and, provided the window is emphasised, the incremental matching cursor is 
drawn in its newly set position. 


QUIRE FOCUS | 


INT lb_inquire_focus (VOID) ; 


Return the index number of the currently selected item. 


This method simply returns the value of 1istbox. current. 


RE_ITEM Get po 


TEXT *lb inquire _item(INT index) ; 


Return a pointer to the first character of the text of the item with index number index. 
The pointer is calculated by adding 1istbox.offset to the pointer returned by sending the message: 
p_send3 (self->listbox.va,O VA_PBUF, index) ; 


There is an implicit assumption that the entire content of the item is stored contiguously. 


6-10 


6 LIST BOXES AND MENUS 


Get index of last item 
INT lb_inquire_last (VOID) ; 
Return the index number of the last item in the list box. 


If listbox.1last is not zero, return this value. Otherwise return one less than the number returned bya 
VA_COUNT message Sent to listbox.va. 


The Menu Bar 


destrey wnedraw 
wn_calc_ position wn_emphasise 
wn_connect 

wn_dodraw 


destroy 
wn_init 
wn_key 


wn_draw 
wn_visible 
mb_add_menu 


wn_position 
wn_redraw 


wn_sense_help 


An HWIM menu bar provides a means of browsing through an application's commands and their 
associated command accelerators. In addition, it may be used to select and execute a command, as an 
alternative to the direct use of an accelerator. 


A menu bar uses component instances of the menuras and puLLDown classes. Note that one or other of a 
menu bar's pull-down menus is always displayed while a menu bar is visible, and one item, the current 
item, is highlighted. The command corresponding to the current item may be executed by pressing Enter. 


A typical menu bar (from the Series 3 System Screen) is shown below, together with a menuras anda 
PULLDOWN Component. 


Menu tab 


Menu bar —~( File Disk Info Special ) 


Install application ¥° 
Install standard LJ 
Remove application YY ,e=—=Pull-down 
Quit speplication =n 
Kill application 2 
Assign button 2 


In an HWIM application the menu bar and its components do not exist unless the menu bar is visible. They 
are created each time the menu bar becomes visible (generally from the wszRv ao_run method in response 
to the user pressing the Menu key) and destroyed when it disappears (when the user either presses Esc or 
executes a command). 


HWIM REFERENCE 


When the menu bar is displayed, one menu is pulled down (the Apps menu in the above example) and an 
item in that menu (for example, Quit application) is selected. The initial visible menu and selected item are 
determined by the wserv property items accessed by w_ws->wserv.info->menu and 
w_ws->wserv.info->mnitem respectively. 


An HWIM application will normally rely on system code to manage the presentation of the menu bar. 
Applications are not expected to subclass Menusar or to send explicit messages to any instance. The 
following description is included for completeness, and for interest. 


Class definition 
Defined in sub-category file menubar.cl (generated header file menubar.g). 


CLASS menubar bwin 
The menu bar 


{ 


REPLACE destroy Free any memory used 

REPLACE wn_init Set up the menu bar text and menus to pull down 
REPLACE wn_emphasise For 3d border effects 

REPLACE wn_draw Draw the menu bar text 

REPLACE wn_key Toggle through the menus or pass on to menus 
REPLACE wn_visible When made visible show menu as well 

ADD mb_add_menu Add a menu to the menu bar 

TYPES 


{ 


typedef struct 


{ 


UWORD menu_id; resource ID of associated pull-down menu 
TEXT mb_txt{1]; menu header text (2TS) 
} MENUBAR_ITEM; 

typedef struct 


{ 


UBYTE count; number of items 

} MENUBAR; (followed by count MENUBAR_ITEMs) 
} 
CONSTANTS 


{ 


MENUBAR_LEFT_ SHOULD 4 horizontal space occupied by the menu bar left shoulder 
MENUBAR_RIGHT_SHOULD 4 horizontal space occupied by the menu bar right shoulder 


MENUBAR_MAX MENU 15 
MENUBAR_MIN_GAP 3 half the minimum separation between successive text items 
MENUBAR_MAX_GAP 10 half the maximum separation between successive text items 


MENUBAR_3b TAIL WIDTH 18 


} 


PROPERTY 2 
{ 
PR_MENUTAB *tab; Tab top for current pull down menu 
PR_PULLDOWN *menu; Current pull down menu 
MENUBAR *mb; Pointer to menu bar information 
UBYTE num; Number of currently pulled down menu 
UBYTE xoff; X offset of start of menu bar on screen 
UBYTE toff; Offset of start of text from tab position 
UBYTE asc; Ascent where text should be drawn 


UWORD pos [MENUBAR_MAX_MENU+1]; Leading tab positions, including terminal entry 
} 
On the Series 3, the menubar. asc property is not defined and menubar .pos is a UBYTE alTay. 
The Series 3 version of the class definition includes the following additional constr definitions: 


MENUBAR_MAX WIDTH (SCREEN_WIDTH-MENUBAR_LEFT_SHOULD-MENUBAR_RIGHT SHOULD) 
MENUBAR_HEIGHT (SYSTEM_FONT_HEIGHT+ (BWIN_CUSHION_Y+2)*2+BWIN SHADOW 1 HEIGHT) 


On the Series 3a the corresponding values are read or derived from the globally accessible data that is 
described in the /ntroduction chapter of this manual. 


6 LIST BOXES AND MENUS 


Property 

menubar .tab The handle of the menu tab (an instance of menuras)for the currently 
displayed pull-down menu. 

menubar .menu The handle of the currently displayed pull-down menu. 

menubar .mb A pointer to a MENugaR struct, containing an array of MENUBAR_ITEM 
structs, one for each of the menu bar's pull-down menus. 

menubar .num The index number of the currently visible pull-down menu. 

menubar .xoff The screen x-offset, in pixels, to the left hand edge of the menu bar. This 
is stored for convenience, rather than repeatedly reading it from the 
window server. 

menubar. toff The pixel offset from the left edge of any menu tab to the start of the 
corresponding text. 

menubar.asc The ascent, in pixels, to the position where the menubar text is drawn. 
This differs for different machine types. This property is not defined on 
Series 3 machines. 

menubar .pos An array of the positions of the menu tabs for the tops of all the pull- 


down menus. Each entry contains the pixel position, relative to the left 
edge of the menu bar, of the left edge of the menu tab of the 
corresponding pull-down menu.The array contains a terminating entry 
that indicates the rightmost extent of the last menu tab. On the Series 3, 
menubar .pos iS an alray of UBYTES. 


i SSS ee ee a ia 
MENUBAR methods 


Displaying a pull-down menu 


A pull-down menu is displayed by creating and initialising component instances of the menutaz and of 
PULLDOWN Or (if a 3D border is used on the Series 3a) xpuLtown classes. An initial pull-down menu is set up 
by the wn_visible method, and the wn_key method may subsequently switch to another menu. 


The pull-down menu to be displayed is identified by the value of menubar .num, which is used to locate the 
corresponding MENUBAR_ITEM struct in the buffer pointed to by menubar .mb. 


If there are existing MENuTAB and PULLDOwN components they are destroyed before new instances are 
created, with their handles stored in menubar .tab and menubar .menu. 


The PuLLpown instance is initialised from an 1n_LIsTBox list box initialisation struct. This struct is defined 
in the ttsrsox class definition as: 


typedef struct 
{ 
UWORD flags; 
PR_VAROOT *array; 
UWORD offset; 
WORD current; 
UWORD top; 
UWORD first; 
UWORD last; 
P_POINT pos; 
UWORD minwid; 
} IN_LISTBOX; 


where: 


® flags is set to 
IN_LISTBOX_TEXT_OFFSET | IN_LISTBOX_MIN_WIDTH | IN_LISTBOX_WRAP_ROUND | 
IN_LISTBOX_POS_ALIGN_X | IN_LISTBOX_AUTO_SIZE | IN_LISTBOX_CUR_SET 


¢ array contains the handle of an instance of varEs, containing the items loaded from the pull-down 
menu resource specified by the value of menu_id in the relevant MENUBAR_ITEM struct 


HWIM REFERENCE 
— ee SSS 


* offset is set to 1 to skip the first byte (containing the command id) of each element of the array 


* current is set to either the value of w_ws->wserv. info->mnitem (on creation of the menu bar) or 
zero (when switching to another menu) 


® top, first and last are not used 


¢ pos.x is set to the value of menubar. pos [menubar .num) less the value MENUBAR_LEFT_SHOULD and 
pos.y is set to be four pixels less than the height of the menubar 


© minwid is set to the width of the menu tab plus an allowance for the left and right shoulders of the 
pull-down menu 


The command manager is sent a com_meNnu message (to inform it of the imminent display of the pull-down 
menu) passing menubar .num and the array handle. The pull-down menu is then sent a WN_INIT message, 
passing the address of the 1n_L1stsox struct described above. The menu tab is also sent a WN_INIT 
message, passing the address of the p_exrent struct described earlier, the value of menubar.tofé anda 
pointer to the menu bar text for that item. 


Finally both the pull-down menu and the menu tab are sent a wN_VISIBLE, WV_INITVIS message. 


The code to implement the display of a pull-down menu is executed under the protection of p enter and 
returns either zero on successful completion or a negative error number on failure. 


VOID destroy (VOID) ; 


Record the current pull-down menu item selection by writing menubar .num to w_ws->wserv. info->menu 
and menubar .menu->listbox.current to w_ws->wserv. info->mniten. If w_ws->wserv.oldinfo is not 
NULL (normally meaning that the current menu is a submenu) w_ws is sent a WS_RESET_MENUBAR message, 
passing W_ws->wserv.oldinfo, and then w_ws->wserv.oldinfo is set to NULL. 


The menu bar is destroyed by freeing the allocated cell pointed to by menbar .mb and then supersending the 
DESTROY message. Finally, w_ws->wserv.bar is set to NULL. 


INT wn_init (MENUBAR *pmenbar) ; 


Initialise the menu bar to display the menu items in the menupar struct pointed to by pmenbar (this struct 
will normally have been loaded from a resource file). 


The method scans the text of the items in the mznupar struct, calculating the cumulative pixel position of 
each item and storing the results in successive elements of the menbar.pos array. The text of successive 
items is separated by 2*MENUBAR_MIN_Gap pixels. Except in the case of the Workabout, if the total width of 
the menu bar exceeds the width of the screen (less the sum of MENUBAR_LEFT_SHOULD, 
MENUBAR_RIGHT_SHOULD and TaB_EDGES) the method calls p_leave (E_GEN_TOOWIDE). 


The value of win. flags is set to PR_BWIN_SHADOW| PR_BWIN_CUSHTION| PR_WIN_EMPHASISED and the window is 
created as a top-level window by sending a wn_connecT message. The method does not set the position or 
dimensions of the window. This must be done by the later sending of a WN_VISIBLE message. 


The method returns zero to indicate that p_1eave has not been called, and is thus suitable for being called 
under the protection of p_enter. 


vite 
sility 
INT wn_visible(UINT state) ; 


Set the position and size of the menu bar and make it (and one of its pull-down menus) visible. The 
implementation of the method assumes that a menu bar will receive only one WN_VISIBLE message in its 
lifetime, and that the value of state will be wv_inrtvis. 


To recover any previous selection of a pull-down menu, menubar .num is set to w_ws->wserv.info->menu. 
This pull-down menu will be drawn with a highlight set to the item indicated by 
w_ws->wserv.info->mnitem. Both of these values are protected against overrun, should the number of 


6-14 


6 LIST BOXES AND MENUS 


pull-down menus or the number of items within a pull-down menu be decreased since the last time the 
menu bar was visible. 


The gaps between the menu bar items are expanded as much as possible, up to a maximum of 
2*MENUBAR_MAX_GAP. This determines the width of the menu bar, which is then centred horizontally and the 
pixel position of the left edge of the menu bar is stored in menubar .xof£. The menu bar is positioned at the 
top edge of the screen, with a fixed height equal to the height of the menu bar. The position and dimensions 
of the menu bar are set by a call to wset window. The value of menubar .tof¢ is set so that the text of each 
menu bar item will appear centrally within its menu tab. 


The method supersends the wv_vis1BLe message before displaying the pull-down menu with index number 
menubar .num, highlighting the item with index number w_ws->wserv.info->mnitem. 


The method returns either zero on successful completion or a negative error number. Errors will be related 
to a failure to create and display the pull-down menu. 


VOID wn_draw (VOID) ; 
Draw the menu bar border and the text of each item. 


Each item of text is drawn by means of a call to gprint Text. The horizontal position of each text item is 
determined by adding menubar .tof¢ to the value of corresponding entry in the menubar .pos array. 


INT wn_key(UINT keycode,UINT modifiers) ; 


Process the keypress with key code keycode and the modifiers indicated by modifiers. The following 
table describes the response to specific keys. 


W_KEY_ LEFT Cycle left by one item and display the new pull-down menu. The return value is 
either wN_KEY_NO_CHANGE (0) or a negative error caused by a failure to create and 
display the pull-down menu. 


W_KEY_RIGHT Cycle right by one item and display the new pull-down menu. The return value is 
either wN_KEY_NO_CHANGE (0) or a negative error caused by a failure to create and 
display the pull-down menu. 


W_KEY_MENU If modifiers contains w_sHIFT_MODIFIER perform the same action as for 
W_KEY_LEFT, otherwise perform the same action as for W_KEY RIGHT. 


W_KEY_HOME Display the first pull-down menu. The return value is either ww_xEY_No_CHANGE 
(0) or a negative error caused by a failure to create and display the pull-down 
menu. 


W_KEY_END Display the last pull-down menu. The return value is either wn_KEY_NO_CHANGE 
(0) or a negative error caused by a failure to create and display the pull-down 
menu. 


numeric, i to 9 Display the corresponding pull-down menu; numbers greater than the number of 
items in the menu bar all display the last pull-down menu. The return value is 
either wN_KEY_No_CHANGE (0) or a negative error caused by a failure to create and 
display the pull-down menu. 


All other key codes for which p_isprint retums FALSE are sent, via a WN_KEY message, to the currently 
displayed pull-down menu, whose handle is in menubar .menu. Significant key codes are W_KEY_ ESCAPE, 
W_KEY_RETURN, W_KEY_UP, W_KEY_DOWN, W_KEY_PAGE_UP and W_KEY_PAGE_Down. The return value is the 
value returned by the wv_xey message to the pull-down menu. 


All remaining key codes are tested for a case-independent match with the accelerator keys, stored in 
w_ws->wserv.info.accel. If there is a match, and the corresponding command is in the currently 
displayed pull-down menu, the pull-down menu is sent an LB_TAKE_Focus message to highlight the 
appropriate item. If the match is with a command in another pull-down menu, the new pull-down menu is 
displayed, with the appropriate item highlighted. The return value is either ww_KEY_NO_CHANGE (0) or a 
negative error caused by a failure to create and display a pull-down menu. 


HWIM REFERENCE 
eee 


MB_ADD_MENU 


INT mb_add_menu(TEXT *title, INT menu_id) ; 


_ Add amenu 


Append a pull-down menu to the end of the menu bar. The additional item will be displayed with the text 
in the zero terminated string pointed to by title and uses the pull-down menu indicated by the resource ID 
menu_id. If used, this method may only be called between the calls to the wn_init and wm_visible 
methods. 


Uses p_realloc to reallocate the buffer pointed to by menubar ..mb so that it is large enough to contain the 
additional item. The text string and menu_id are copied into menubar .mb to form its final MENUBAR_ITEM 
struct, an additional entry is added to the menubar. pos array (as with the wn_init method, the inter-item 
gap is set to 2*MENUBAR_MIN_GaP) and menubar.mb->count is incremented. 


The method returns zero if it completed successfully, or one of the errors: 


E_GEN_NOMEMORY if there was insufficient memory to reallocate the buffer 

E_GEN_TOOWIDE if the new width is too wide for the screen (this error is not returned on the 
Workabout) 

E_GEN_TOOMANY if the number of menus exceeds MENUBAR_MAX_MENU (this error is not returned on 
the Workabout) 


PULLDOWN pull-down menu 


match 
va 

flags 
width 
matchlen 
curofft 
offset 
current 
top 
first 
last 
vastart 
matchstart 


destroy 
wn_calc_position 3 wn_init 
wn_connect wa-key 


wn_dodraw wn_draw 


wn_key 
lb_draw_item 


1b_draw_emphasis 
1lb_item_width 
wn_emphasise 


wn_position 


wn_redraw 
wn_sense_help 
wn_visible 


wn_set 
wn_sense 


1b_size_window 
ib-tem—width 
lb_take_focus 
1lb_inquire_focus 
1b_inquire_item 
1lb_inquire_last 


The puLpown class subclasses L1sTBox to provide the display of pull-down menus. In an HWIM 
application a pull-down menu does not exist unless it is visible. 


6-16 


6 LIST BOXES AND MENUS 
—_—_—_— eee BU AES AND MENUS 


An HWIM application will normally rely on system code to manage the presentation of pull-down menus. 
Applications are not normally expected to subclass puLLpown or to send explicit messages to any instance. 
The following description is included for completeness, and for interest. 


Class definition 
Defined in sub-category file pu//down.cl (generated header file pulldown.g). 


CLASS pulldown listbox 
pull down menu from menu bar 


{ 


REPLACE wn_key Check for accelerator matching 
REPLACE lb draw_item Draw accelerator at right edge 

REPLACE 1b draw_emphasis Emphasise whole area 

REPLACE lb item_width Returns the required width of the item 
TYPES 


{ 


typedef struct 


{ 

UBYTE com_id; 
TEXT mn_txt [1]; 
} MENU_ITEM; 


} 
Property 
There is no property associated with the puLLDown class. 


SSS See eee ee EE, ee) 
PULLDOWN methods 


WNUKEY” <n oe ey) ae “ as Handie key input 
INT wn_key(INT keycode, INT modifiers) ; 


Returns the value returned by supersending the wn_key message, provided the value is zero 
(WN_KEY_NO_CHANGE) or negative (wN_KEY_CANCELLED). 


The behaviour is thus similar to that of the LtsTBox superclass wn_key method, except for its response to 
the w_key_ENTER value of keycode (for which the superclass method returns the index number of the 
current item, plus one). 


In this case the PULLDoWN wn_key method returns the value of the first byte of the array entry for the 
currently selected menu item, obtained by sending 1istbox.va a VA_PBUF message. This byte contains the 
command ID of the command manager method corresponding to the menu item (any Series 3a 
BREAK_LINE_FOLLOws flag is removed). 


an item 
VOID 1b_draw_item(TEXT *txt,INT index, P_RECT *area) ; 


Draw the item with index number index within the area specified by area and containing the text pointed 
to by txt. This text is assumed to be part of a menu_rtem struct, that is, the byte immediately preceding that 
pointed to by txt is assumed to contain the ID of the corresponding menu command. 


The menu item text is drawn by supersending the LB_praw_rTEem message. Following this the accelerator 
text is constructed from the ws_symBoL_Pston character and the (uppercased) result of a ws_SENSE_ACCEL 
message sent to the application's instance of wszrv. This text is then printed in the item by means of a call 
to gPrintText. 


For Series 3a machines, if the accelerator is an upper case character the shift key indicator (in English, the 
text "Shift") is displayed before the accelerator text. If the command ID contains the Series 3a flag 
BREAK_LINE_FOLLOWS, a grey line is drawn below it. 


HWIM REFERENCE 


LB _DRAW_EMPHASIS Set item emphasis 
VOID 1b_draw_emphasis (INT index,P_RECT *prect,INT on); 


Toggle the presence of a highlighting obloid, in the rectangle specified by prect, for the item with index 
number index. The value of on is True if emphasis is being set, and rause if emphasis is being cleared. 


The action is similar to that of the 1b_draw_emphasis method of the LrsTsox superclass, except that the 
width of the highlighting obloid is not found by sending an LB_ITEM_w1pTH message, but is set to the full 
width of the rectangle specified by prect. It thus includes the accelerator key text. 


As for the LtsTBox 1b_draw_emphasis method, the supplied method does not use on. 


h for an item 


INT lb_item_width(INT index) ; 
Returns the width required to display the item with index number index. 


The required width found by adding the space required to display the accelerator text to the value returned 
by supersending the LB_ITEM_WIDTH message. 


XPULLDWN pull-down menu 


flags match 
i va 
flags 
width 

matchlen 
curofft 
offset 
current 
top 
first 
last 
vastart 
matchstart 


wn_key 
ib_draw_item 


tb—draw—emphasis 


lb_item_width 


dessxeey 
wn_calc_position 
wReeennect 


wn_dodraw 


ib_draw_emphasis 


wn_position 
wn_redraw 

wn_sense_ help 
wn_visible 


lb_size_window 
tbh—-item—width 
lb_take_focus 
lb_inquire_focus 
lb_inguire_item 
1lb_inquire_last 


wn_set 


The xpunLpwn Class subclasses puLLDown to provide the Series 3a version of the display of pull-down 
menus. This class is not present on Series 3 machines. 


An HWIM application will normally rely on system code to manage the presentation of pull-down menus. 
Applications are not normally expected to subclass xPpuLLDwn or to send explicit messages to any instance. 
The following description is included for completeness, and for interest. 


6-18 


6 LIST BOXES AND MENUS 


Class definition 
Defined in sub-category file xpul/dwn.cl (generated header file xpulldwn.g). 


CLASS xpulldwn pulldown 


REPLACE wn_connect 
REPLACE wn_draw 
REPLACE lb _draw_emphasis 
CONSTANTS 
{ 
PULLDOWN_3b_LEFT 4 additional space required by S3a menus 
PULLDOWN_3b RIGHT 3 
PULLDOWN_3b_BOTTOM 3 
PULLDOWN_3b_TOP 4 
} 
} 


Property 
There is no property associated with the xpuLLpwn class. 


XPULLDWN methods 
ONNEC 


VOID wn_connect (PR_WIN *par, UINT flags, W_WINDATA *pwd) ; 


The window dimensions, in pwd->ext, are adjusted to the slightly larger dimensions of the Series 3a pull- 
down menus, and the result adjusted if necessary to ensure that the window does not exceed the boundaries 
of the screen. The flags w_wIN_BACK_CLR and w_WIN_BACK_GREY_CLR are ored into pwd->background, and 
W_WIN_BACKGROUND is ored into flags. The method then supersends the wn_connecT message. 


VOID wn_draw(VOID) ; 


Draw the pull-down menu border and the text of each item. 


Each item of text is drawn by means of a call to gprint Text. The currently selected item is highlighted by 
dending an LB_DRAW_EMPHASIS message. 


VOID 1b _draw_emphasis (INT index,P RECT *prect,INT on); 


Toggle the presence of a highlighting obloid, in the rectangle specified by prect, for the item with index 
number index. The value of on is TRuE if emphasis is being set, and raLsE if emphasis is being cleared. 


Increment the x-coordinates in the p_recr struct pointed to by prect and supersend the LB_DRAW_ EMPHASIS 
message. 


As for the superclass method, the value of on is ignored. 


HWIM REFERENCE 


MENUTAB 


destroy wn_sense_help | wa-draw 
wn_calc_ position wn_visible wn_emphasise 
wn_connect 

wn_dodraw wn_set 

wh-emphasise wn_sense 


wn_key 


wn_position 
wn_redraw 


The menutas class subclasses swrn to provide the display of the tab above a currenly visible pull-down 
menu. In an HWIM application the tab does not exist unless it, and its associated pull-down menu, is 
visible. 


An HWIM application will normally rely on system code to manage the presentation of a menu tab. 
Applications are not normally expected to subclass menuras or to send explicit messages to any instance. 
The following description is included for completeness, and for interest. 


Class definition 
Defined in sub-category file menubar.cl (generated header file menubar.g). 


CLASS menutab bwin 


{ 
REPLACE wn_init 
REPLACE wn_draw 


PROPERTY 
{ 
TEXT *txt; Pointer to the text to display 
UWORD xoff; Offset at which to display the text 
} 
} 
Property 
menutab. txt A pointer to the menu tab text, assumed to be a zero terminated string. 
menutab.xoff The pixel x-offset in the menu tab window to the position at which the 


text is to be drawn. 


Sa eee a a a en ee ray 
MENUTAB methods 


WNONID alge 
VOID wn_init (P_EXTENT *pext,UINT xoff,TEXT *txt) ; 


Sets win. flags to PR_WIN_EMPHASISED|PR_BWIN_CUSHION|PR_BWIN_SHADOW_1|PR_BWIN_OPEN, 
menutab.off to xoff and menutab.txt to txt. Then sends a wN_CoNNECT message to create the window 
with position and size as specified by pext. 


Draw 
VOID wn_draw(VOID) ; 
Draw the menu tab. 


Supersends the ww_praw message to draw the border and then draws the text of the menu tab with a call to 
gPrintText. 


6-20 


CHAPTER 7 


DIALOG BOXES 


This chapter describes the classes provided in HWIM for the creation and operation of dialogs. A dialog 
box shows the user the current values of one or more data items and, in general, allows the user to modify 
one or more of these values. 


In an HWIM application the most common use of a dialog is as a result of the user selecting a command 
from a command menu. In response to an Open file command, for example, a dialog would be presented to 
allow the user to specify the name (and possibly the type) of the file to be opened. 


All HWIM dialogs are modal, that is, while the dialog is visible the user can interact with the application 
only via that dialog; the application enters a 'mode' such that all attempts to interact with, say the menu bar 
are disallowed. This mode terminates when the user satisfactorily completes the dialog. 


A number of pre-defined system dialogs exist and are described in later chapters of this manual. The 
system dialogs may be run by specific wserv methods, such as ws_error_dialog, ws_query dialog and 
ws_format_dialog, that are described in the chapter The WSERV Class. 


See also the dialog utility functions described in the Dialog box utilities section of the HWIM Utility 
Functions chapter. 


Precursors 
Familiarity with the following topics will aid the understanding of this chapter: 


e the window concepts described in the Introduction and Windows chapters of the Window Server 
Reference manual 


e the wssrv class, especially the ws_do_dial method, which starts up a dialog box, and the ao_run 
method, which may send messages to a dialog box window 


¢ graphics contexts and drawing, described in the Graphics Output chapter of the Window Server 
Reference manual 


e — the basic principles of resource files as described in the Resource Files chapter of the Additional 
System Information manual. (Further information is available in the HWIM Resource Files chapter 
of the Object Oriented Programming Guide.) 


Class diagram 


rote ee orm ee 


Ps 
f 


ee 7 ae ‘ area 
/ digchain ~ / digbox > / atsdiat ~ 
4 a 

i : 


HWIM REFERENCE 


DLGCHAIN 


destroy wn_sense_help wn_draw 
wn_cale position wn_visible wn_emphasise 


wn_connect 
wn_dodraw wn_set 


we-enpheacies wn_sense 


wn_key whedraw 


wn_position wn_init 
wn_redraw 


The piccuarn abstract class subclasses swrn, but adds or modifies no methods. It adds property that makes 
all instances of its subclasses suitable for including in a chained list of objects. Such a list is maintained by 
the application's instance of wserv (with the foremost dialog's handle stored in wserv.diai) to implement 
stacked dialog boxes. 


Other subclasses of pLGcuarn may also be included in this list. For example, Help 'dialogs' (which do not 
subclass pLGBox) may appear in the list, intermixed with true dialogs. 


Class definition 
Defined in sub-category file digbox.cl (generated header file digbox.g). 


CLASS dligchain bwin 
Dialog box next and previous chaining 
{ 
CONSTANTS 
{ ! All four bits re-used from original meanings 
PR_WIN_NO_DDP PR_WIN_FORCE_TOP DatDialogPtr should never point to this dialog 
HELPDLG_BASIC_HELP PR_WIN_FORCE_RIGHT 
HELPDLG_HELP_INDEX PR_WIN_FORCE_LEFT 
DLGCHAIN_WITH_MENU PR_WIN_FORCE BOTTOM 


} 


PROPERTY 


{ 


PR_BWIN *next; Next dialog, if present 


} 
} 


On the Series 3 the constants section of the class definition does not contain the definitions: 


HELPDLG_BASIC_HELP 
HELPDLG_HELP_INDEX 
DLGCHAIN_WITH_MENU 


Property 
dlgchain.next The handle of the next item in a list of pLccHarn instances, mainly used for 
the list headed by the item whose handle is stored in the wsERv property 
wserv.dial. 
DLGCHAIN flags 


The following flags may be set in win. flags: 


PR_WIN_NO_DDP If a subclass of piGcHarn sets the PR_WIN_NO_Dpp flag in win. flags during 
its initialisation, it will never have the handle of an instance written to the 
magic static DatDialogPtr. 


HELP_DLG BASIC_HELP Not defined for Series 3 code. 


HELPDLG_HELP_ INDEX Not defined for Series 3 code. 


7 DIALOG BOXES 


oon nr 


DLGCHAIN WITH_MENU Not defined for Series 3 code. If set, indicates that the dialog has an 
associated menu bar whose commands are accessible by the Menu and 
cursor keys, or by hot-key combinations. If, as is the case for most dialogs, 
the flag is clear, then all such keypresses are directed to the dialog box 
itself. 


If a subclass does not set PR_WIN_NO_pDppP in win. flags, it is signalling that it is prepared to have 
DatDialogptr set to the handle of any instance that appears in the wserv.diai list. An advantage of doing 
so is that the handle does not need to be passed as a parameter to any utility functions - see, for example, 
the dialog box utility functions described later in this chapter. The subclass should write its handle to 
DatDialogPtr when it adds itself at the front of the wserv.diai list, during initialisation. Note that this 
handle may be overwritten by a different value when another subclass of puccHatn adds itself to the list. 


Any such subclass must cooperate with other items in the wserv.dial list. On destruction, provided 
DatDialogPtr contains its handle, it must scan all the remaining items in the list and write to 
DatDialogptr the handle of the first item for which win. flags does not contain PR_WIN_NO_DDP. 


Note that this means that any such instance is liable to have its handle written to DatDialogPtr, and thus 
must perform the operation described above, even if it does not write its own handle to patpialogptr. This 
situation will never arise for a subclass that sets PR_WIN_No_Dpp. 


DLGBOX 


flags next 
id 
destrey wheodraw 


wn_position 
wn_redraw 


wn_sense_heip 


wn_visible 


current 
font” 
absorb 
changed 


dl_item_replace 
dl_item_append 
qa@l_init 
di_dimmed_message 
dl_item_add 
dl_set_size 
dl_ing_minsize 
dl_item_lock dl_dyn_init 
dl_item_dim dl_key 
dl_set_item_flags 
dl_set_prompt dl_changed 
dl_take_focus dl_focus 
di_handle_to_index dl_launch_sub 
dl_index_to_handle dl_item_new 


The piesox class provides a flexible set of mechanisms for displaying and controlling a wide variety of 
dialog boxes. Although formally an abstract class (since some methods are pererred) an instance of pLcox 
may be created and used to display simple notification dialogs. The majority of normal dialogs may be 
created and used with a subclass that replaces at most two methods: very few dialogs require all the 
beFErred methods to be defined. This is discussed at greater length in the Using dialog boxes section of the 
Object Oriented Programming Guide. 


HWIM REFERENCE 


An HWIM dialog box consists of a bordered window containing between one or more lines, or items. The 
maximum bumber of items that may be displayed varies from machine to machine as follows: 


Series 3 seven items 
Series 3a nine items 
Workabout six items in the system font, or eight items in a small font 


Each item may be plain text, a control, or a combination of a plain text prompt and a control. Each control 
may be an instance of one of many different classes, including: 


e aplain text window 
© achoice list 
¢ an action list of buttons (may only be the last item in the dialog box) 
e atext edit box 
© anumeric editor 
e a floating point editor 
e atime editor 
e a date editor 
e a scrolling or non-scrolling text editor 
e asecret data input box 
e a filename selector 
e a filename editor 
® an application-specific control 
All these controls are subclasses of the Lopcgr class. 


Any item in the dialog box may be separated from the following items by a horizontal line, referred to as 
an underline. In the case of the Series 3a and Workabout, any number of items may be underlined, but for 
the Series 3, only one underline may appear in a dialog box. In the majority of dialogs an underline is used 
to separate the first item, designated to be the dialog title, from those that follow. The title is normally, but 
not necessarily, plain text. 


Many dialogs can be created and run using the piczox class directly, together with wsERv's ws_do_dial 
method. 


Class definition 
Defined in sub-category file digbox.cl (generated header file digbox.g). 


CLASS dlgbox dlgchain 
Dialog box class 

{ 

REPLACE destroy 

REPLACE wn_key 


REPLACE wn_emphasise Pass on to item with focus 
REPLACE wn_sense_help Give start ID for help 
REPLACE wn_set Set item by index 

REPLACE wn_sense Sense item by index 


REPLACE wn_draw 


7 DIALOG BOXES 


ee 


dl_item_lock 
dl_item_dim 
di_set_item_flags 
dl_set_prompt 
@l_take_focus 
di_handle_to_index 
dl_index_to_handle 
dl_item_replace 
dl_item_append 
dl_init 
dl_dimmed_message 
dl_item_add 
dl_set_size 
dl_ing_minsize=p_dummy 
dl_dyn_init=p_dummy 
dl_key 


DEFER dl_changed 
DEFER di_focus 
DEFER dl_launch_sub 
DEFER dl_item_new 


CONSTANTS 


{ 


DLGBOX_NOTIFY_ENTER 
DLGBOX_NOTIFY_ESCAPE 
DLGBOX_RBUF_FILLED 
DLGBOX_ACTION_LIST 
DLGBOX_FROM_HWIF 
DLGBOX_SMALL_ FONT 
DLGBOX_NO_WAIT 
DLGBOX_NOTIFY_ALL ACT 
DLGBOX_REPORT_ACT HORIZ 


DLGBOX_APPEND_UNITS TITLE 0x0100 
DLGBOX_SMALL_ACTION_LIST 


DLGBOX_NO_SHADOW 
DLGBOX_NO_DDP 


Lock an item by index 

Dim an item by index 

Set some dlgbox_item flags 

Change the prompt for an item 

Move focus item specified by index 

Return index for given handle 

Return handle for given index 

Replace an existing item with another 

Add an item (by rid) to end of list 
Initialise dialog from a resource file 
Present reason for item being dimmed 

Add an item to the end of the list 

Sets size of dialog after dynamic initialisation 
Allows default minimum sizes to be changed 
For subclass dynamic initialisation 
Primarily for C call processing 


For users that request item changed messages 
For users that request change focus messages 
launch sub dialog if required 

Create instance of non-system dialog item 


0x0001 Notify when dialog terminated with enter 
0x0002 Notify when dialog terminated with escape 
0x0004 Set if subclasser fills rbuf 

0x0008 Dialog contains an action list 

0x0010 Reserved for system use 


DLGBOX_FROM_HWIF Dialog box uses the small font 


0x0020 No am_start 

0x0040 Report ALL keys to dl_key 

0x0080 Report matching action key as horiz 
Append units(cm/in) used to title 

0x0200 Dialog contains a small action list 

0x0400 Create dialog with no shadow 

0x0800 Do not overwrite DatDialogPtr 


! Four bits 0x1000 to 0x8000 reserved for PR_WIN_FORCE_XXX 
DLGBOX_ITEM_NOTIFY_CHANGED 0x0001 Report item changes to item 


DLGBOX_ITEM_DIMMED 
DLGBOX_ITEM_UNDERLINED 
DLGBOX_ITEM_APPL_CAT 
DLGBOX_ITEM_CENTRE 
DLGBOX_ITEM_DEAD 


DLGBOX_ITEM_NOTIFY_FOCUS 


DLGBOX_ITEM_NEEDS PACK 
DLGBOX_ITEM_LOCKED 


DLGBOX_ITEM_CAN_DEFER_X 
DLGBOX_ITEM_X_PENDING 
DLGBOX_ITEM_ACLIST 
DLGBOX_LEFT GAP 
DLGBOX_BULLET_GAP 
DLGBOX_VERT_GAP 
UNDERLINE_DEPTH 
EXTRA_GUTTER_WIDTH 
DLGBOX_MAX_ITEM 
DLGBOX_ROMAN8_FONT 


} 


0x0002 Item dimmed 

0x0004 

0x0008 Application specific item 

0x0010 Item centred in dialog 

0x0020 Can't ever select item 

0x0080 Report item focus changes to dialog 
0x0100 Add a pack selector immediately after 
0x0200 Visible & can take focus: values locked 
0x0400 Can defer self-check 

0x0800 Item must be checked before exit 
0x1000 This is the aclist in the dialog 


(BWIN_CUSHION_X+7) 
3 

(BWIN_CUSHION Y+2) 
3 
4 
9 
5 Add (WS_FONT_BASE-1) to get small font ID 


HWIM REFERENCE 
eee eS 


TYPES 

{ 

typedef struct 
{ 
UWORD flags; 
TEXT title[1]; 2ZTS string, 
! followed by a byte count of the following items, 
! each of which has a leading length byte 
} HD_DLGBOX_RSC; 

typedef struct 


{ 


WORD flags; initialisable DB_ITEM flags 

UBYTE class; class of item 

TEXT prompt [1] ; ZTS string 

! followed by IN_<item> structure 

} AD_DLGBOX; header for each item in resource information 


typedef struct 


{ 


PR_LODGER *hand; handle of item object 
PR_TEXTWIN *prompt; handle of prompt for item 

WORD flags; property DB_ITEM flags 

} DLGBOX_ITEM; internal representation of items 


typedef union 
{ 
DLGBOX_ITEM item(7] ; Array of items in dialog 
DLGBOX_ITEM *pitm; ptr to an array of more than 7 items 
} DLGBOX_ITEM_UNION; 


} 


PROPERTY 
{ 
DLGBOX_ITEM_UNION u; either array of items or ptr to array of items 
VOID *rbuf; address of result buffer 
WORD dimrid; rid for dimmed item status message 
WORD helprid; rid to start help 
UWORD flags; holds DLGBOX_XXX flags 
UBYTE focus; TRUE when an item has focus 
UBYTE count; number of items (ine title) in dialog 
UBYTE current; number of current control (0-6) 
UBYTE font; LSB+1 of WS_FONT_BASE font ID 
UBYTE absorb; direct all keypresses to the current control 
UBYTE changed; TRUE if the current item needs self check 


} 
On the Series 3 the constants section of the class definition does not contain the definitions of: 
DLGBOX_ITEM_ACLIST 
EXTRA_GUTTER_WIDTH 
DLGBOX_MAX ITEM 
but does contain two alternative definitions: 


GUTTER_WIDTH 10 
ACLIST_EXTRA_HEIGHT 20 


In the property section of the Series 3 class definition, the element: 


DLGBOX_ITEM_UNION u; either array of items or ptr to array of items 
is replaced by the simpler: 
DLGBOX_ITEM item[7] ; array of items in dialog 


These differences are associated with internal code changes and, apart from the additional number of items 
that a Series 3a dialog box may contain, have no significant consequences for the application programmer. 


The Workabout class definition introduces the defined constants pLGBox_sMALL_FONT and 
DLGBOX_ROMAN8_FONT. 


In the PRopERTy section of the Workabout class definition, the line: 


UBYTE font; LSB+1 of WS_FONT_BASE font ID 


a SSSSSSSSSSSSSSSSSSeSSeeSSSSeSeeeeSSSSeESee 
7-6 


7 DIALOG BOXES 


has replaced the Series 3/3a line: 


UBYTE underline; 


Property 


dlgbox. 
dligbox. 


dlgbox. 


digbox. 


digbox. 
dlgbox. 


dlgbox. 


digbox. 


dlgbox. 


dlgbox. 


dlgbox. 


digbox. 


digbox. 


u.item 
u.pitm 


rbuf 


dimrid 


helprid 
flags 


focus 


count 


current 


font 


underline 


absorb 


changed 


y offset of S3 underline (not used in S3a code) 


used to provide access to an array of pLGBox_rTEM structs for the 
component items. If the dialog box contains seven or fewer items, the array 
is stored directly in digbox.u.item. For more than seven items, the array is 
held in allocated memory, pointed to by dlgbox.u.pitm. Jn consequence, 
subclassers should not access the data in the array other than through the 
supplied methods, such as d1_index_to_handle. 


the address of a user-supplied ‘result’ buffer, from which initialisation data 
may be read and to which result data may be written. The buffer's address 
may optionally be passed to the window server object's ws_do_dial method 
(or the equivalent nuaunchpial utility function). 


either zero or the resource ID of a text message that is to be displayed if a 
user attempts to modify a ‘dimmed' control 


either zero or the resource ID of a context-specific Help resource 
a collection of state flags, described below 


TRUE if keyboard focus is held by one of the dialog box controls. Only 
system code may write to this item. 


a count of the number of items in the dialog box, including any dialog title. 
Only system code may write to this item. 


the index of the dialog's component control that currently has focus. Only 
system code may write to this item. 


introduced in the Workabout, to replace dlgbox .underline. If not zero, its 
value determines the ID of the small font used in dialogs and, optionally, in 
list boxes. The font ID is given by digbox. font+wS_FONT_BASE-1. 
Although the value could, in principle, specify any font ID, it is restricted 
to be either zero or DLGBox_RomaNs_FoNrT. This is because the pseudo-static 
data held in patGate->gate. dx, used to determine the size and position of 
dialog controls using the small font, is calculated for this font. 


not used in Series 3a code, and replaced by digbox. font in the 
Workabout. On the Series 3 only, if not zero, it is the pixel offset from the 
top of the dialog box to a horizontal line drawn across the dialog box. On 
the Series 3, a dialog box may contain only one such line, normally used to 
separate the dialog title from the remainder of the dialog content. 


TRUE if all keypresses are to be directed to the control that currently has the 
focus. Otherwise the dialog box intercepts keypresses that can be 
interpreted by any dialog action list, and those with keycodes 
W_KEY_RETURN, W_KEY_ESCAPE, W_KEY_UP, W_KEY_DOWN, W_KEY PAGE up and 
W_KEY_PAGE_DOWN. 


set TRUE if the 1g self_check method of any of the dialog's component 
controls reports that its value has changed. Cleared when focus is 
transferred to another control. 


HWIM REFERENCE 


DLGBOX flags 


The content of dlgbox. flags may be any combination of the following flags: 


DLGBOX_NOTIFY_ENTER 


DLGBOX_NOTIFY_ESCAPE 


DLGBOX_RBUF_FILLED 


DLGBOX_ACTION_LIST 


DLGBOX_SMALL_ACTION_LIST 


DLGBOX_NOTIFY_ALL ACT 


DLGBOX_REPORT_ACT_HORIZ 


DLGBOX_SMALL_FONT 


DLGBOX_NO_WAIT 


DLGBOX_APPEND_UNITS_TITLE 


DLGBOX_NO_ SHADOW 


DLGBOX_NO_DDP 


PR_WIN_FORCE_RIGHT 


PR_WIN_FORCE_LEFT 


if this flag is set the dialog box will be sent a pL_KEY message when 
the dialog receives an Enter keypress 


if this flag is set the dialog box will be sent a pL_kEy message when 
the dialog receives an Esc keypress 


if this is not set and algbox.rbuf is not NULL, system code will write 
to *dlgbox.rbuf on exiting the dialog. A subclass that uses 
dlgbox.rbuf for its own purposes should set this flag 


this flag must only be set if the dialog contains an action list (class 
ACLIST) as its last item. It is set automatically during the 
initialisation of an AcLIsT component control. When set (provided 
dlgbox. absorb is FALSE) all received keys are first offered to the 
action list by sending it a wn_key message, which returns a value 
indicating whether or not the keypress matched one of the buttons 


this flag must only be set if the dialog contains a 'small' action list 
(class smacLIST) as its last item. It is set automatically during the 
initialisation of an sMAcLIST component control. When set (provided 
dlgbox.absorb IS FALSE) all received keys are first offered to the 
action list by sending it a ww_KEy message, which returns a value 
indicating whether or not the keypress matched one of the buttons 


if this flag is clear, report only those keys that match an action 
button by sending the dialog box a pL_KEy message, otherwise send 
a DL_key message for all keypresses that have been offered to the 
action list, irrespective of whether they matched an action button 


if a keypress to an action button causes the dialog to terminate, a 
value may be written to *dlgbox.xbuf (See DLGBOX_RBUF_FILLED). 
If DLGBOX_REPORT_ACT_HoRIz is set, the value written to 
*dlgbox.rbuf is the index number of the button that matched the 
keypress (or -! if it did not match). Otherwise the value is the 
uppercased key code of the keypress. 


this flag is not defined for the Series 3 or 3a. If it is set in a dialog's 
resource, the dialog is initialised to use the small (8 point Roman) 
font, rather than the system font. This flag is not stored permanently 
in a dialog's property (see the wsERV ws_do_dial method) 


if this flag is clear, the dialog is run between am_start and aM_sToP 
messages to the application manager 


set this flag to append the current preferred units (cm or in) to any 
dialog title 


if this flag is set the dialog box is created without a shadow border 


if this flag is clear, the dialog box's handle is written to 
DatDialogPtr during initialisation and, on destruction, either nu. 
or the handle of the foremost of any remaining items in the 
wserv.dial list for which this flag is clear is written back to 
DatDialogptr. Normally this flag is clear to improve the efficiency 
of dialog-related utility functions, which then do not need to pass the 
dialog box handle as a parameter 


if set, the dialog will be positioned at the extreme right of the screen 
(see the wrn class) 


if set, the dialog will be positioned at the extreme left of the screen 
(see the wrw class) 


7 DIALOG BOXES 
—_—.:s Se IALUG BOAES 


PR_WIN_FORCE_BOTTOM if set, the dialog will be positioned at the bottom of the screen (see 
the wzn class) 

PR_WIN_FORCE_TOP if set, the dialog will be positioned at the top of the screen (see the 
WIN Class) 


These flags are set, during creation of the dialog, from the initialisation data for the dialog box, which is 
normally loaded from a resource file. 


Small font dialogs for the Workabout 


Workabout dialogs may be set to use the small (8 point Roman) font by including the flag 
DLGBOX_SMALL_FonrT in the flags field of the pranoc resource that defines the dialog. 


On initialisation of the dialog, this causes the value of digbox. font to be set to DLGBOx_ROMAN8_FonT and 
the value pR_WIN_IS_DLCTRL to be set in the win. flags property of each subclass of LopcEr that is used as 
a component of the dialog. 


All the supplied Lopcer subclasses that may be used as dialog controls will draw themselves using the 
small font, but only if: 


e they are components of a dialog i.e. if win. flags contains PR_WIN_IS_DLCTRL 


e they are set to use the small font i-e. if ((PR_DLGBOXx *) lodger->1andlord) ->dlgbox. font is 
non-zero 


Outside a dialog box, or if the dialog is not set to use the small font, these subclasses of LopcER will draw 
themselves using the normal, system font. 


When positioning controls within a dialog box, and when calculating the dimensions of controls and the 
dialog itself, the pre-calculated pseudo-static data is read from either patcate->gate.x or 
DatGate->gate.dx, depending on whether the dialog is set to use the normal or the small font. 


DLGBOX_ITEM flags 


The picBox_rrem flags can be set individually for each dialog box item and are stored in the flags field of 
the corresponding pLGBox_1T= struct in the array that is either held in the digbox.u. item property, or 
pointed to by dlgbox.u.pitm. The content of the f1ags field may be any combination of the following 
flags: 


DLGBOX_ITEM_NOTIFY_CHANGED if this flag is set, changes to the item result in the dialog box 
receiving a DL_CHANGED message. This flag is normally only set in 
the item's initialisation data 


DLGBOX_ITEM_NOTIFY_Focus if this flag is set, each loss or gain of focus by the item results in the 
dialog box being sent a pL_rocus message. This flag is normally 
only be set in the item's initialisation data 


DLGBOX_ITEM_UNDERLINED if this flag is set, the corresponding item will be drawn with an 
underline extending across the full width of the dialog box. This flag 
is normally only set in the item's inintialisation data. For a Series 3 
application it must not be set for more than one item in the dialog 
box 


DLGBOX_ITEM_APPL_CAT this flag should be set for any dialog item whose class definition is 
not in the HWIM category file. This flag may only be set in the 
item's initialisation data 


DLGBOX_ITEM_CENTRE this flag indicates that the corresponding item is to be centred in the 
dialog box. This flag is normally only set in the item's initialisation 
data 

DLGBOX_ITEM_NEEDS PACK this flag indicates that, on initialisation of the dialog box, a pack 


selector control is to be added as the item immediately following 
this one. This flag may only be set in the item's initialisation data, 
and must be set for FNSELWIN or FNEDIT component controls 


DLGBOX_ITEM_LOCKED an item for which this flag is set is visible and can take focus, but its 
value may not be changed. This flag may be set or cleared by the 
dl_item_lock method 


HWIM REFERENCE 
a SSFSSFSSSSSSSSSFSSSSeeeSSeeSeeSSSSSFSMSSSSSSFFFFFeeeee 


DLGBOX_ITEM_DIMMED if this flag is set, the item is 'dimmed, that is, its control is made 
invisible. This flag may be set or cleared by the d1_item_dim 
method 

DLGBOX_ITEM_DEAD an item for which this flag is set may never take focus and may 


never be modified. This flag may only be set in the item's 
initialisation data 


DLGBOX_ITEM_CAN_DEFER_X an item for which this flag is set can, on losing focus, defer its self- 
check. A deferred check is automatically registered by the setting of 
the DLGBOx_ITEM_x_PENDING flag, described below. Applications 
will normally only set the pucBox_ITEM_CAN_DEFER_X flag in an 
item's initialisation data, but the flag is set automatically during 
initialisation of FNSELWN Or FNEDIT component controls 


DLGBOX_ITEM_X_PENDING an item for which this flag is set must be checked before exiting the 
dialog. This flag is set and cleared by the system and should not be 
modified by application code 


DLGBOX_ITEM_ACLIST this flag indicates that the corresponding item has a control that is an 
instance of either acLIst or smacListT. This flag is set by the system 
and should not be present in any dialog resource, nor should it be 
modified by application code 


DLGBOX methods 


In addition to optionally providing replacements for the pererred methods: 


di_changed 
dl_focus 
di_launch_sub 
dal_item_new 


applications are, in general, not expected to subclass methods other than: 


dal_dyn_init 
dl_key 

dil_ing minsize 
dl_set_size 


Occasionally a dialog box may additionally need to subclass one or more of: 


dl_item_add 
dl_dimmed_message 
wn_sense_help 


Consistency checks 


A dialog box control may need to perform a consistency check on its content, a typical case being a 
numeric control whose value must remain within prescribed limits. 


In simple cases a dialog may check the consistency of its data in its d1_key method. However, in many 
cases it is either not feasible or inappropriate to check the value at each keypress that modifies the value. 
For example, a numeric edit box whose value is constrained to lie between 10 and 50 may transiently 
contain the ‘illegal’ text "1" while the number "18" is being typed in. 


The piesox class provides a mechanism for checking the validity of the content of its controls, triggered 
either when focus is transferred to one of its controls, or when the dialog is being terminated by any means 
other than by pressing Esc. Since a control's validity may, for example, depend on the values of one or 
more of the other controls, the check on change of focus may be deferred until the dialog termination, 
when the final values of all controls are known. Such items are indicated by setting the 
DLGBOX_ITEM_CAN_DEFER_X flag in the flags field of the corresponding puGBox_ITEM struct. 


The check on an item is always deemed to succeed if the item is locked or dimmed, or if the check is 
deferred. Otherwise the control is sent an L¢_sELF_CHECK message (see the description of this method for 
the LopcEr class, described in the Windows chapter). This message returns a value that indicates whether or 
not the content has changed as well as whether the check failed or succeeded. 


7-10 


7 DIALOG BOXES 
——_— SS IAL OG BOXES 


Regardless of the success or failure reported by the 1g_self_check method, if the return value indicates 
that the value has changed, digbox . changed is set to TRUE and, provided the flags field of the relevant 
DLGBOX_ITEM struct contains DLGBOX_ITEM_NOTIFY_CHANGED, the dialog box is sent a DL_ CHANGED message. 


On any failure the checking stops and focus is set to the item that failed its check. This may prevent the 
user from moving to another item in the dialog or from exiting the dialog (except by pressing Esc to cancel 
the dialog) until the item is modified so that it passes the check. 


DLINT — eee Initialise 


INT dl_init (HD_DLGBOX_RSC *head, VOID *rbuf) ; 


Initialise a dialog box from an item in a resource file. This method is called from the wsERV ws_do_dial 
method to create and initialise the component controls (before calls to the dl_dyn_init, and dl_set_size 
methods). 


The method performs the following actions: 


¢ copies the value of rbuf, which points to a user-supplied 'result' buffer, into algbox.rbuf, and 
copies head->flags into digbox. flags 


¢ sets win. flags tO PR_BWIN_CUSHION oRred with PR_BWIN_CORNER_4 and, if dlgbox. flags does not 
contain DLGBOX_NO_SHADOW, ORS PR_BWIN_SHADOW_2 into win. flags 


e if head->£1lags contains DLGBOx_NO_DDP, ORS PR_WIN_NO_ppp into win. flags, otherwise sets the 
magic static DatDialogptr to the handle of the dialog box 


¢ — sends itself a wi_connecT message, with a parent pointer of nuuz to create a top-level window, and 
with a zero flags field parameter so that the window is initially of indeterminate size and position 


e  ifhead->title does not contain a null string, creates and initialises an instance of TEXTWIN 
containing this text, with centred alignment. This is made the first, unprompted, item in the dialog 
box: 

its handle is written to the hand element of the dialog's first pL¢Box_1TEM struct 

the £1ags element of this struct is set to DLGBOx_ITEM_DEAD|DLGBOX_ITEM_CENTRE 

the prompt element of this struct is left nu 

the title is set be underlined 

Algbox.count Is set to 1 
On the Workabout, the initialisation of this instance of textwin is preceded by setting the 
PR_WIN_IS_DLCTRL flag in the instance's win. flags. This allows the text window to determine 
whether it needs to draw itself using the smaller font. 


e the byte following the zero terminator of any string in head->title is read to determine the 
number of items in any following list of items to be included in the dialog (this byte is generated 
by the resource compiler). The specified items are added to the dialog box, in order, with a 
sequence of pL_ITEM_ADD messages 


Any failure to add an item results in p_ leave being called. 


The method returns zero to indicate that no failure has occurred. It is suitable for calling under the 
protection of p_enter. 


This method is not intended to be replaced. 


DESTROY __ _ | Destroy 
VOID destroy (VOID) ; 


Destroy the dialog box and its component items. 


The method first sends pEstroy messages to each of the prompts and controls whose handles are stored in 
the dialog box's array of pLGBox_ITEM structs. 


Further action depends on how the dialog box was started up: 


e if the start-up of the dialog by the wseRv ws_do_dial method completed without error (this is 
indicated by the dialogs win. f1ags containing PR_WIN_INITIALISED) the dialog box will have 


7-11 


HWIM REFERENCE 
ee 


been added to the wserv. dial list. In such a case w_ws is sent a WS_REMOVE_DIAL message, passing 
the dialog's handle 


e the DatDialogptr magic static may contain the dialog's handle. If this is so, the wserv. dial list is 
searched for the foremost item that does not have pR_wIN_No_ppp set in its win. flags and 
DatDialogPtr is set to contain this item's handle, or nuxz if no such item is found 


¢ if the dialog was successfully started by ws_do_dial and does not have pLGBox_No_WArT set in 
digbox . flags, aN AM_START message was sent to w_am, so the destroy method sends w_am an 
AM_STOP message 


In all cases, before the optional sending of the am_stop message, the method supersends the pEsTRoy 
message. 


This method is not intended to be replaced. 


Add an item 
INT di_item_add(AD_DLGBOX *par) ; 


Append, as the current last line of the dialog box, the control specified by the ap_pLGxox struct pointed to 
by par. This struct is defined in d/gbox.g as: 


typedef struct 


{ 


WORD flags; /* initialisable DB_ITEM flags */ 

UBYTE class; /* class of item */ 

TEXT prompt [1] ; /* ZTS string */ 

/* followed by an IN_XXX component-specific initialisation structure */ 
} AD_DLGBOX; /* header for each item in resource information */ 


It is a programming error, with unpredictable results, to add an item if the dialog box currently contains the 
maximum number of items. 


The method first creates an instance of the class par->class, writing its handle to the hana element of the 
corresponding DLGBox_ITEM struct. If par->f1ags does not contain pLGBox_ITEM_aPPL_car the class is 
assumed to be a standard control in the HWIM category. Otherwise the method sends a pL_ITEM_NEW 
message to create the instance. The par->f1ags value is copied into the flags element of the 
corresponding DLGBOx_ITEM struct. 


If the string at the start of the par->prompt buffer is not a null string, an instance of rextwrn is created, 
writing its handle to the prompt element of the corresponding pLGBox_zTeM struct. This instance is sent a 
WN_INIT message, passing the address of an 1n_TExtwrn struct and the dialog box handle. The 1n_TExTwIN 
struct contains the prompt string and.a state value of 0 if par->£1ags contains any of 
DLGBOX_ITEM_DIMMED, DLGBOX_ITEM_LOCKED OF DLGBOX_ITEM_DEap, otherwise state is set to 
IN_TEXTWIN_BULLET. 


The method then sends a wn_1n1T message to the item's control, passing a pointer to any data (assumed to 
be a suitable initialisation structure) that follows the terminating zero of the string in the par->prompt 
buffer. Further parameters are the dialog box handle and the handle of the control in the previous line! (see 
also the Special note below). 


On the Workabout, the sending of the wy_1n1T message to both the control and any prompt is preceded by 
setting the PR_wIN_IS_picTRu flag in the corresponding object's win. f1ags. This allows the control or 
prompt to determine whether it needs to draw itself using the smaller font. 


If par->f1ags contains DLGBOX_ITEM_UNDERLINED, the item will be drawn with an underline (only one 
underline is allowed on the Series 3). 


Finally, the value of digbox.count is incremented by one. 


The method returns zero to indicate that no failure has occurred. It is thus suitable for calling under the 
protection of p_enter. 


!This will contain an indeterminate value when adding the first item, but the wn_init methods of most 
controls ignore this value. Those that make use of this parameter are never used as the first item in the 
dialog box. 


7-12 


7 DIALOG BOXES 
_-———————-———————— SS TALLOG BOXES 


This method may be either used or replaced by application writers. It is called by system code, once for 
each component control, from the wsERv ws_do_dial method after the dialog resource has been loaded 
from the resource file. 


An application may call this method to add one or more items, depending on run-time circumstances, 
although the ai_item_append method - which also loads the item's resource - will usually be more 
appropriate. All such uses must be before the pL_seT_s1zE message is processed at the picsox level. 
Application code will typically send a pi_1T=m_app message from the a1_dyn_init method. 


Since the method is called by system code once for each item that appears in the dialog resource, it may be 
replaced to omit one or more items, or to add items at positions other than the end of the dialog, depending 
on run-time circumstances. 


The following example is a replacement of the a1_item_add method that optionally omits the third item 
(with index number 2) from a dialog. It assumes that the mvpze subclass of pucpox adds two items of 
property: mydlg.needed, which is True if the item is to be included, and mydig.omittea which is initially 
FALSE and is set to True if the item is not included in the dialog (an alternative would be to store this 
information in a result buffer, pointed to by digbox. rbuf). 


METHOD VOID mydlg_dl_item_add(PR_MYDLG *self, AD _DLGBOX *par) 


Lf ((sel£->dlgbox.count==2) &&(!self->mydlg.needed) &&(!self->mydlg.omitted) ) 
self->mydlg.omitted=TRUE; 

else 
p_supersend3 (self,O_DL_ITEM_ADD, par) ; 


Special note 


If par->flags contains DLGBOX_ITEM_NEEDS_PACK (normally only if adding a control of either the rneprtT 
or the rNsELwn class) then this method will result in the addition of two controls, thus occupying two lines 
in the dialog box. After the creation of the first control, but before its initialisation, the method sends a 
further, recursive, pL_ITEM_ADD message to create a PACKSEL control with an associated "Disk" prompt 
string (this prompt is read from the sys_pacx resource in the system resource file). In this case the final 
parameter passed in the wn_rnzT message to the first control is the handle of the following control (that is, 
the instance of pacxset). If par->flags contains DLGBOX_ITEM_UNDERLINED, the underline is transferred to 
be below the pacxsex control, so that an item and its corresponding pack selector will never be separated 
by an underline. 


em by resource ID 
VOID dl_item_append (INT rid) ; 
Append the item specified by the resource item with resource ID ria. 


The resource item is loaded into a temporarily allocated buffer, the loaded data being assumed to be an 
AD_DLGBOx struct. The control and any associated prompt are appended to the dialog box, as described for 
the dl_item_add method. The temporarily allocated buffer is freed before the method returns. 


The method must not be used to add an item following any action list item. 


An application may call this method to add one or more items at the bottom of a dialog, depending on run- 
time circumstances, for example, to generate two different, but similar, dialogs from a common dialog box 
resource. All such uses must be before the pn_seT_szzE message is processed at the pLGpox level. A call 
from application code to the a1_item_append method will typically be from the dl_dyn_init method. 


This method is not intended to be replaced. 


DL_ITEM_REPLACE 


VOID dl_item_replace (INT index, INT rid); 


place an existing item 


Replace existing item number index by the item specified by the resource item with resource ID ria. 


The existing control and any corresponding prompt are sent pesTRoy messages. The resource item is then 
loaded into a temporarily allocated buffer, the loaded data being assumed to be an AD_pLGBox struct. The 
replacement item and any corresponding prompt are created and initialised as described for the 


HWIM REFERENCE 
ee SSSSSSSSeSSSSSSSSeFeFeSSSSSSSSSSSSSSSSSSSSSSSSSSSSFSEeee 


dl_item_add method, their handles overwriting those that they replace. The method does not increment 
digbox.count. The temporarily allocated buffer is freed before the method returns. 


This method must not be used with a resource which has the pL¢Box_ITEM_NEEDS_Pack flag set in its flags 
data. 


An application may call this method to replace one or more items, depending on run-time circumstances, 
for example, to generate two different, but similar, dialogs from a common dialog box resource. All such 
uses must be before the pu_szT_s1zE message is processed at the picxox level. A call from application 
code to the dl_item_replace method will typically be from the a1_dyn_init method. 


This method is not intended to be replaced. 


"Set item by index 


VOID wn_set (INT index, VOID *par); 


Set one or more data elements in the property of the control associated with the dialog box item with index 
number index, by sending a wn_sET message to the control. 


The parameter par is assumed to be a pointer to a struct that specifies the data to be set. The type of struct 
that is expected depends on the class of the control that is being set; the various structs are described in the 
following Dialog Controls chapter. 


This method will normally be used (rather than replaced) by application writers. See also the various 
hD1gSet Xxx utility functions. 


VOID dl_set_prompt (INT index, SE_TEXTWIN *par) ; 


Send a wn_sET message to the prompt associated with item number index, passing the parameter par, 
assumed to be a pointer to an SE_TEXTWIN struct. 


This method replaces an existing prompt; it can not be used to add a prompt to an item that does not 
already possess a prompt. Thus the method may not be used on an item for which no prompt was defined 
in the item's resource. 


It is perfectly permissible for a replacement prompt to be longer than the prompt text that was supplied in 
the dialog's resource. However, such a replacement may alter the width needed to display the dialog. If this 
is the case, the replacement should not be made after the wsERV ws_do_dial method has sent the dialog a 
DL_SET_SIZE message. 


This method is not intended to be replaced. 


by index 
VOID wn_sense (INT index, VOID *par); 


Sense the property of the control associated with the dialog box item with index number index, by sending 
a WN_SENSE message to the control. 


The parameter par is assumed to be a pointer to a struct that matches the data to be sensed. The type of 
struct that is expected depends on the class of the control that is being sensed; the various structs are 
described in the following Dialog Controls chapter. 


This method will normally be used (rather than replaced) by application writers. See also the various 
hD1lgSensexxx utility functions. 


7 DIALOG BOXES 


Handle a keypress 
INT wn_key (INT keycode, INT modifiers) ; 


The description of this method is included for interest only. Applications should neither replace this method 
nor call it explicitly. 


Handle a keypress, directing it, if necessary, to a component control. This message is sent by the 
application's instance of wserv. Any non-zero return value from the wn_key method will terminate the 
dialog, causing the dialog box to receive a DESTROY message. 


If digbox.absorb is TRUE, all keys are directed to the current control, as described later. Otherwise keys are 
processed as follows. 


If the dialog contains an action list (which must always be the last item) the action list is sent a wn_KEY 
message, passing a key code of p_toupper (keycode). This message returns either a negative value if the 
keypress does not match any of the action buttons, or the index number of the button that matched the 
keypress (the leftmost button has index number zero). 


If there was no match and digbox. f1ags does not contain DLGBOX_NOTIFY_ALL ACT , processing continues 
with the testing for specific keys, as described later. 


Otherwise (that is, either the keypress matches an action button, or dlgbox. flags contains 
DLGBOX_NOTIFY_ALL_AcT) a forced consistency check is applied to all controls. If any control fails its check 
the method terminates, returning wN_KEy_No_CHANGE (0) so that the dialog box is not exited. If the 
consistency check succeeeds, the method sends a pL_KeY message, passing dlgbox. current, 

p_toupper (keycode) and the key-matching value returned by the wn_xey message that was sent to the 
action list. The method terminates, returning the value returned by the pL_Key message. Before returning, 
and provided that: 


e the return value is non-zero (that is, the dialog is terminating) 
@ dlgbox.rbuf is not NULL 
®  dalgbox. flags does not contain pLGBOX_RBUF_FILLED 


a worn of data is written to *dlgbox.rbuf. If digbox. flags contains DLGBOX_REPORT_ACT_HoRrz this data 
is the index number of the action button that was selected. Otherwise the value written to *dlgbox. rbuf is 
the uppercased key code. 


Provided the keypress has not been processed by an action list, the following specific keypress codes are 
tested: 


W_KEY_ RETURN this key is ignored if the dialog contains an action list (a1gbox. flags contains 
DLGBOX_ACTION_LIST OF DLGBOX_SMALL_ACTION_ LIST) in which case the method 
terminates immediately, returning wn_KEY_No_CHANGE. Otherwise a forced 
consistency check is applied to all controls. If any control fails its check the 
method terminates, returning wN_KEY_NO_CHANGE. 


If dlgbox. flags does not contain DLGBOx_NOTIFY_ENTER the method just 
retums WN_KEY_CHANGED, otherwise it returns the result from sending a pL_KEY 
message. In either case, provided: 


e — the return value is non-zero (that is, the dialog is terminating) 
e § dlgbox.rbuf is not NULL 
@ dlgbox. flags does not contain DLGBOX_RBUF_FILLED 
the value of dlgbox. current is written to the worp pointed to by digbox. rbuf. 


W_KEY_ESCAPE provided dlgbox. rbuf is not NULL and dlgbox. flags does not contain 
DLGBOX_RBUF_FILLED write, to the worD pointed to by digbox. rbuf, either 
W_KEY_EScAPE or, if dlgbox.flags contains DLGBOX_REPORT_ACT HORIZ, a value 
of -1 


HWIM REFERENCE 
Ss SSS 


W_KEY_UP move up 'one' item in the dialog. The current item becomes the first earlier item 
whose flags do not contain pLcBox_ITEM_DEAD. A DL_TAKE_FOcUS message is 
sent, passing the new current item's index number. Moving up from the first 
item in the dialog positions to the last item 


W_KEY_DOWN move down ‘one’ item in the dialog. The current item becomes the first 
following item whose flags do not contain pLGBox_ITEM_DEAD. A 
DL_TAKE_FOCUS message is sent, passing the new current item's index number. 
Moving down from the last item in the dialog positions to the first item 


W_KEY_PAGE_UP move to the 'first’ item in the dialog. The current item becomes the first item 
whose flags do not contain pLGBox_ITEM_DEAD. A DL_TAKE FOCUS message is 
sent, passing the new current item's index number. 


W_KEY_PAGE_DOWN move to the ‘last’ item in the dialog. The current item becomes the last item 
whose flags do not contain pL¢Box_ITEM_DEAD. A DL_TAKE_FOcUS message is 
sent, passing the new current item's index number. 


If dlgbox. focus is FALSE, any other keypress is ignored and the method returns wN_KEY_NO_CHANGE. 
Otherwise the keypress is directed to the dialog's current component control, as explained in the following 
paragraphs. All incoming keys are processed in this way if dlgbox. absorb is TRUE. 


If the flags field of the current item contains pLGBOx_ITEM_DIMMED Or DLGBOX_ITEM_LOCKED, a DL_DIMMED 
message is sent, to inform the user that the item can not be modified, and the method then returns 
WN_KEY_NO_CHANGE. 


Otherwise the current control is sent a wn_KEy message, and further processing depends on the return value: 


e if the return value is wN_KEY_ABSORB_ON, dlgbox. absorb is set TRUE, so that all subsequent keys 
will be directed to the current control 


e if the return value is anything other than wi_key_No_CHANGE and digbox. absorb is TRUE, 
digbox. absorb is set FALSE, so that subsequent keys may be processed by the dialog box as 
described above 


e if the return value is ww_kEyY_CHANGED and the current item's flags contain 
DLGBOX_ITEM_NOTIFY_CHANGED, the dialog box is sent a DL_ CHANGED message 


In all these cases the dialog wn_key method returns wn_KEY_NO_CHANGE. 


die key input 


INT dl_key(INT index, INT keycode, INT actbut); 
Process a keypress that may potentially exit the dialog. 


This method is supplied so that it may be replaced to perform application-specific processing of such 
keypresses. 


This message is sent by the dialog box wn_key method in the following circumstances: 


e when dlgbox. flags contains DLGBOx_NOTIFY_ENTER and the dialog is about to terminate after 
receiving a W_KEY_RETURN. The value of keycode is W_KEY RETURN and actbut is -] 


e when dlgbox. flags contains DLGBOxX_NOTIFY_ESCAPE and the dialog is about to terminate after 
receiving a w_KEY_ESCAPE. The value of keycode is W_KEY_ ESCAPE and actbut is -] 


e the dialog is about to terminate after receiving a key that matches a button in an action list. The 
value of keycode is the uppercased key code that was passed to the action list's wn_key method 
and actbut is the index (0 for the leftmost button) of the matching button 


e following any non-matching keypress received by an action list, provided algbox. flags contains 
DLGBOX_NOTIFY_ALL_act. The value of keycode is the uppercased key code that was passed to the 
action list's wn_key method and actbut is -1 


In all cases index contains the current value of dlgbox.current. 


The method should return w_xEy_No_CHANGE to prevent termination of the dialog, or wN_KEY_CHANGED to 
confirm termination (which causes the dialog box to be sent a DesTRoy message). Before returning 


7-16 


7 DIALOG BOXES 


WN_KEY_CHANGED the method is responsible for ensuring that any relevant dialog box state is either saved or 
returned to the initiator of the dialog box. Data may conveniently be returned to the initiator via a user- 
supplied buffer pointed to by digbox. rbuf. 


The supplied method simply returns wn_KEY_CHANGED. 


DL_TAKE FOCUS _ Move focus to specified item 
INT di_take_focus (INT index) ; 
Attempt to change the focus to item number index. 


A deferred consistency check is applied to the current item. If the check fails the focus change is not made. 
Otherwise, provided the specified item is not already the one with focus, the focus is switched to the 
specified item: 


¢ any prompt of the item that is losing focus is sent a wN_EMPHASISE, FALSE message 


© provided its flags do not contain pLGBOx_ITEM_DIMMED Or DLGBOX_ITEM_LOCKED, the control of the 
item that is losing focus is also sent a wN_EMPHASISE, FALSE Message 


e if the flags of the item that is losing focus contain pLGBox_ITEM_NoTIFY_Focus, the dialog box is 
sent a DL_Focus message to inform it that the item is losing focus 


© a TRUE value is written to dlgbox. focus and dlgbox.current is set to index, so that it now refers 
to the item that is gaining focus 


¢ any prompt of the item that is gaining focus is sent a WN_EMPHASISE, TRUE message 


© provided the item that is gaining does not have the either of the flags pLGBox_ITEM_DIMMED or 
DLGBOX_ITEM_LOCKED set, the control of this item is also sent a WN_EMPHASISE, TRUE Message 


e if the item that is gaining focus has the flag pLcBox_IT=M_NoT1FY_Focus set, the dialog box is sent 
a DL_Focus message to inform it that the new item is gaining focus 


The method returns rause if a failed consistency check prevents a change of focus being made. In all other 
circumstances (including the case where the specified item is already the one with focus) the method 
returms TRUE. 


This method is not intended to be replaced. It is not suitable for being called from the a1_ayn_init 
method. If an application wishes to set the focus on initialisation, it should do so from a replaced 
dl_set_size method. It may be called from any other method (such as 41_key) once the dialog has been 
made visible. 


dialog 
VOID wn_draw (VOID) ; 
Draw the dialog box and its contents. 


The method first draws the dialog box border. It then sends a wn_pRaw message to every prompt, and to 
every control that does not have pLGBox_1ITEM_DIMMED set in the flags field of the corresponding 
DLGBOx_ITEM struct. If the flags field of a control also has pLGBOXx_ITEM_UNDERLINED bit set, a horizontal 
line is drawn below the item, extending across the full width of the area inside the window's border. 


On the Series 3, only one underline can be present in a dialog box and its vertical position is specified by 
dilgbox underline. If this value is non-zero, a horizontal line is drawn at the specified position, extending 
across the full width of the area inside the window's border. 


On the Workabour, all text is drawn in the small (8 point Roman) font and line heights are calculated 
accordingly. 


HWIM REFERENCE 


Set size of dialog 


INT dl_set_size(VOID) ; 


Set the height and width of the dialog to the values required to display all the component items, and set the 
position all components within the dialog box. An Lc_sENsE_wIDTH message is sent to each component to 
determine the width needed to display it. 


A DL_SET_SIZE message is sent from the WSERV ws_do_diai method, after that method has sent the dialog 
box DL_INIT and DL_DyN_INIT messages. 


If digbox. flags contains DLGBOX_APPEND_UNITS_TITLE the SYS_CENTIMETRES OF SYS_INCHES resource 
(depending on whether w_ws->wserv. flags contains PR_WSERV_METRIC) is loaded from the system 
resource file and appended to the dialog title. This will call p_panic if the dialog has no title. 


Some dialog items (such as an instance of Textwrn used as a title) are composed of a single control 
component, whereas others are formed from two components - a prompt and a control. The width of each 
component is found by sending it an Lc_sENSE_wIDTH message. The dialog box width is set to contain the 
widest item from each of these two groups, subject to any explicit minimum widths set by sending each 
control a DL_INQ_MINSIZE message. 


The width for single-component items is the larger of the width written to *poverallwidth by 
dl_ing_minsize (zero by default) and the single-component item of greatest width. 


The width for two-component items is the width of the widest prompt plus the width of the widest control 
(respectively not less than any values written to ppromptwWidth and *pcontrolwidth by dl_ing minsize) 
plus a minimum gutter width separation between them. Provided at least one item is not marked with the 
DLGBOX_ITEM_DEAD flag, the prompt width allows space for the prompt to include a leading bullet to show 
that an item can be modified. 


The width of the dialog box is the greater of these two widths plus an allowance for the dialog box borders 
and a small gap at either side. If this is wider than the screen, an attempt is made to clip the right hand side 
of the control components. On all machines except the Workabout, if such clipping means that one or more 
controls will be entirely invisible the method calls p_leave (E_GEN_TOOWIDE). 


The height of the dialog box is just the sum of the heights of the controls, plus the top and bottom borders 
and a small additional amount for each item that is underlined. On all machines except the Workabout, if 
the total exceeds the screen height the method calls p_leave (E_GEN_ToomaNy) . In most cases there will 
always be room for the maximum number of items, but some items (for example, instances of ACLIST) take 
up additional height. 


The method then positions each prompt and control by sending it an Lc_seT_1D_Pos message. Unless 
marked as centred, prompts are positioned at the left side, aligned at their left edges, and controls occupy a 
right hand region, again aligned at their left edges. The prompt and control regions are aligned with the 
edges of the widest centred control, subject to their being separated by a small gap. 


Finally, provided that not all items are marked with the p.cBox_1TEM_pEap flag, the method sets the focus 
to the first such unmarked item - algbox. focus is set TRUE, dlgbox. current is set to the item and a 
WN_EMPHASISE, TRUE message is sent to the item's prompt, if it exists. The control itself is not sent a 
WN_EMPHASISE message as it will receive one later, when the dialog box itself receives a wN_EMPHASISE 
message. 


The method returns zero to indicate that p_1eave has not been called. It is suitable for calling under the 
protection of p_enter. 


This method may be replaced, but should not be called explicitly from application code. It offers the last 
opportunity to modify the dialog box content before it becomes visible. A common use is to modify the 
content after the size of the dialog box has been calculated. 


Any replacement method should only add further processing, before and/or after supersending the 
DL_SET_SIZE message. 


7 DIALOG BOXES 


_ Dim an item 


VOID dl_item_dim(INT index, UINT flag) ; 


Undim item number index if flag is FALSE, otherwise dim it. When an item is dimmed its control is not 
displayed and its prompt does not display a bullet point. It is harmless to send a dimmed item a 
DL_ITEM_DIM, TRUE Message, or an undimmed item a DL_ITEM_DIM, FALSE message. 


Dimming the item clears the pLGBox_ITEM_DIMmep flag in item number index and sends any prompt (an 
instance of TEXTWIN) a WN_SET message to Clear its PR_TEXTWIN_BULLET flag. The control is sent a 
WN_VISIBLE, FALSE message. 


Undimming the item reverses these flag changes and sends the control a wN_vIsIBLE, TRUE message. 


In either case the ww_v1sIBLE message is sent only if the dialog box win. flags contains 
PR_WIN_INITIALISED. This prevents any control from drawing itself during the initialisation of the dialog 
box, before the whole dialog box can be made visible. 


If item number index has the pLGBox_ITEM_NEEDS_PAcK flag set, the dimming/undimming operation is also 
performed on the following pacxseE item. 


This method is not intended to be replaced. 


Lock an ite 


VOID di_item_lock(INT index, UINT flag); 


Unlock item number index if £1ag is FaLse, otherwise lock it. When an item is locked its prompt does not 
display a bullet point but, unlike a dimmed item, its control remains visible. It is harmless to send a locked 
item a DL_ITEM_LOCK, TRUE message, or an unlocked item a DL_ITEM_LOCK, FALSE message. 


Locking the item clears the pL¢Box_ITEM_LocKEp flag in the item's flags field and sends any prompt (an 
instance of TEXTWIN) a WN_SET message to clear its PR_TEXTWIN_BULLET flag. 


Unlocking the item reverses these flag changes. 


If item number index has the pLeBox_ITEM_NEEDS_Pacx flag set, the locking/unlocking operation is also 
performed on the following packse item. 


This method is not intended to be replaced. 


ed’ message 


_ Display ‘d 


VOID dl_dimmed_message (VOID) ; 


Display a status message, using hInfoPrint, indicating that a locked or dimmed item can not be modified. 
This method will be called by system code when the uset attempts to modify an item that is either dimmed 
or locked. 


The resource ID passed to hinfoprint is digbox.dimrid or, if this is zero, either of the system resource 
ID's SYS_DIMMED_MSG OF SYS_LOCKED_mSG depending on whether or not the item's flags contain 
DLGBOX_ITEM_DIMMED (if this flag is not present the item is assumed to be locked, without testing for the 
presence of DLGBOX_ITEM_LOCKED). 


This method can be replaced, for example, to display a context-sensitive message. 


DL_HANDLE ~ 


INT dl_handle_to_index(PR_LODGER *handle) ; 


Sense item index 


Return the index number for the item whose control handle is handle. 
Returns -1 if handle does not match any dialog item. 


This method is not intended to be replaced. 


HWIM REFERENCE 


Sense item handle 


PR_LODGER *dl_index_to_handle (INT index) ; 
Return the handle of the control in item number index. 


It is a programming error to call this method with a value of index that does not correspond to an existing 
dialog box item. 


This method is not intended to be replaced. 


ee ee 


VOID dl_set_item_flags(PR_LODGER *lodger, UINT flags); 


or the passed f1ags into the flags field of the dialog box item corresponding to the control with handle 
lodger. 


This method is intended for use by a component control to set some aspect of the dialog's state. It is used, 
for example, by the rnsELwn and acuist dialog control classes. 


The DLGBOX_ITEM_LOCKED and DLGBOX_ITEM_DIMMED flags should be set (or cleared) by use of the 
appropriate specific method. Note that, apart from these two flags, no means is provided for clearing any of 
an item's flags. 


This method is not intended to be replaced. 


INT wn_sense_help(PR_DLGBOX *self) ; 
The action depends on the value of digbox.heipria as follows: 
¢ return digbox.helprid, if it is greater than zero. 


¢ if dlgbox.helprid is zero, return the result of supersending the w_SENSE_HELP message. This is 
handled by the win superclass and returns either w_ws->wserv.help_index_id or, if this is zero, 
the (negative) system resource ID -sys_HELP_ON_HELP. 


© if dlgbox.helprid is -1, call p_leave (RUN_ACTIVE_USED). This is used by the ERRORDLG class, to 
disable the display of help information when an error is being reported (so that, for example, 
multiple nested out of memory errors can not be generated by requesting Help while an out of 
memory error report is visible). 


ox emphasis 


VOID wn_emphasise(UINT flag) ; 


Emphasise the dialog box if flag is True, otherwise de-emphasise it. 


First supersends the wN_EMPHASISE message to set the border emphasis. If an item has the keyboard focus 
(dlgbox. focus is TRUE) and if the current item is not dimmed or locked, send a WN_EMPHASISE message to 
the control of this item. 


VOID di_ing minsize (INT *pOverallWidth, INT *pPromptWidth, INT *pControlwidth) ; 


Inform the caller of the minimum widths for whole line items (*poverallwidth) and for the prompt 
(*pPromptwidth) and control (*pcontrolwidth) segments of two-part items. The method is called from the 
dl_set_size method and, on entry, all three parameters point to locations containing zero. 


The supplied method does nothing. 
A subclass may replace this method to write application-specific minimum values to any or all of 


*pOverallWidth, *pPromptWidth Or *pControlwidth. On all machines except the Workabout, writing 


7-20 


7 DIALOG BOXES 


values that force a dialog to exceed the width of the screen will cause d1_set_size to call 
p_leave (E_GEN_TOOWIDE) . 


DL_DYN_INIT 


VoID dl_dyn_init (VOID) ; 


alisation 


A DL_DYN_INIT message is sent from the WsERV ws_do_dial method, after that method has sent the dialog 
box a pL_InitT message, but before the sending of apL_sET_s1z= message. 


The supplied method does nothing. It is supplied so that it may be replaced to perform application-specific 
initialisation of the dialog box after all its items have been added, but before its size is calculated and it is 
made visible. 


The most common use for this method is to set the initial value of one or more controls, depending on the 
current state of the application, but other actions may include dimming, locking, adding or replacing one or 
more dialog items. Initialisation data may conveniently be passed by means of a buffer pointed to by 
digbox. rbuf. 


Deferred DLGBOX methods 


There is no general requirement to subclass pLGBox to provide any of these pzrsrred methods. Each 
method need be supplied only if the conditions are satisfied for the corresponding message to be received. 


HANGED 


VOID dl_changed (INT index) ; 


éd message 


Notify the dialog box that the item with index number index has changed in some way. 


This message will only be received for values of index for which the flags field of the corresponding item 
contains DLGBOX_ITEM_NOTIFY_CHANGED. The method need not be supplied for any dialog in which no 
items are so marked. 


A typical use would be to modify an item - say the allowed range of a numeric edit box - as a result of 
changes made by the user to some other item. 


ged message 
VOID dl_focus (WORD index, WORD flag) ; 


Notify the dialog box that the item with index number index has gained or lost focus. The value of flag is 
TRUE if the item has gained focus, or rause if the item has lost focus. 


This message will only be received for values of index for which the flags field of the corresponding item 
contains DLGBOX_ITEM_NOTIFy_Focus. The method need not be supplied for any dialog in which no items 
are so marked. 


A common use is to detect when an edit box loses focus. This may be an appropriate time to sense the 
value and make any necessary modifications to other dialog box items. 


alog if required 
VOID dl_launch_sub(INT index) ; 
This message is sent by the window server object if, on return from a wn_key message sent to the dialog, 


the value of w_ws->wserv.subdial is non-zero. The value of index is the item number of the item that is 
launching the subdialog. 


The method need not be supplied for any dialog that does not write a non-zero value to 
w_ws->wserv.subdial. For further information, see the description of the use of subdialogs in the Dialogs 
chapter of the Object Oriented Programming Guide. 


HWIM REFERENCE 


Create non-system dialog item 


VOID *dl_item_new(AD DLGBOX *par) ; 
Create an instance of the application-specific dialog item with class number par->class. 


Assuming that the application category file is myapp.cat, the code of a d1_item_new method for a dialog 
box that has application-specific items defined only in this category would be: 


£_new(CAT_MYAPP_MYAPP, par->class) ; 


If, exceptionally, a dialog box contains two or more application-specific items, with classes defined in 
different categories, the method will need additional logic to create the item from the appropriate category. 


This message will only be received if the flags field associated with one or more of the items in a dialog 
box contains pLGBox_ITEM_APPL_car, indicating that the item does not have its class definition in the 
HWIM category. The method need not be supplied for any dialog whose items are not so marked. 


ATSDIAL 


flags next item count 
id rbuf current 
dimrid underline 
helprid absorb 
changed 
destrey wh—draw 


di_item_replace 
wn_key dl_item_append 
wn_emphasise dl_init 
wn_sense_help d1_dimmed_message 
wn_set di—itemadd 
wn_sense dl_set_size 
wn_draw di_ing_minsize 
di_item_lock di—dyn—inie 
dl_item_dim di—key 
dl_set_item_flags 

dl_set_prompt dl_changed 
di_take_focus di_focus 
dl_handle_to_index dl_launch_sub 
dl_index_to_handle dl_item_new 


wn_calc_position |wn—emphasise 


wn_position 
wn_redraw 


wn-senserheip 


wn_visible 


The atsp1au class is not present on the Series 3. 


The arspzax class implements ATS dialogs, that is, dialogs that are presented in response to an inter- 
process message from another, controlling, process. The ATS dialog mechanism is intended to be used 
only via the mechanisms supplied within the HWIM library (see, for example, the description of the 
ws_do_remote_dial method in the WSERV Class chapter. An application should not subclass arsDIAL. 


An ATS dialog may be dependent on two items of data that are copied from the controlling process. The 
first of these must be the resource for the dialog itself (considered to be an Hp_DLGBox_rsc struct). The 
second may be one of: 


e achoice list resource 
® an action list resource 


e editable text for an edit box. 


7 DIALOG BOXES 


The ATS dialog may therefore contain, in addition to controls of other types, not more than one control 
selected from these three types. None of the other controls may be of any type that requires additional data 
(for example, from another resource file item). 


See the Series 3a Automatic Test System chapter of the Object Oriented Programming Guide for a 
description of the use of ATS. 


Class definition 
Defined in sub-category file xd/gbox.cl (generated header file xdlgbox.g). 


CLASS atsdial dlgbox 
{ 
REPLACE destroy 
REPLACE dl_item_add 
REPLACE dl_dyn_init 
REPLACE dl_key 


PROPERTY 
{ 
VOID *owner; 
VOID *main; 
VOID *buts; 
PR_WIN *filter; 
WORD filmethod; 
WORD chlist; 
WORD pid; 
WORD ret; 
UWORD locked; 


} 


Property 

atsdial.owner If not nout, the handle of an instance of the arssv class (see the XADD 
Reference manual). 

atsdial.main A pointer to an allocated memory cell containing the main resource data 
for the dialog. 

atsdial buts If not NULL, a pointer to an allocated memory cell containing resource data 
for the dialog's one control that needs such data. The control may be a 
choice list, an action list or an edit box. 

atsdial.filter A preserved copy of the application's w_ws->wserv. filter property. 

atsdial.filmethod A preserved copy of the application's w_ws->wserv. £ilmethod property. 

atsdial.chlist Either zero or one plus the index of the control that makes use of the 
second item of data copied over from the controlling process. If positive, 
the control is a choice list, if negative the control is an edit box. 

atsdial.pid The process ID of the process that launched the ATS dialog. 

atsdial.ret A terminating value that can be sent in an sv_FREE message to 
atsdial.owner. 

atsdial.locked Normally revs, indicating that the ATS dialog code has incremented the 


application's patLocked magic static. 


HWIM REFERENCE 


[SEE Sa eae \ 
ATSDIAL methods 

DESTROY : _._ : Destroy 

VOID destroy (VOID) ; 

Destroy the ATS dialog and its resources. The action is as follows: 


e Frees the allocated memory cell pointed to by atsdial.main and, if it exists, the allocated 
memory pointed to by atsdial .buts. 


e Restores the values of w_ws->wserv. filter and w_ws->wserv. filmethod from the preserved 
values in atsdial.filter and atsdial.£ilmethod. 


e Ifatsdial.owner is not NULL, sends it an sv_FREE message, passing the value of atsdial. ret. 
e Ifatsdial.locked is non-zero, decrements patLocked. 


e Supersends the pEstroy message. 


VOID dl_item_add(AD_DLGBOX *p); 


Mark the dialog as being started by the ATS mechanism by oring the flag wIn_FROM_ATs into win. flags 
(for use by any AcLIST or cHLIST component) and then supersend the DL_TTEM_ADD message. 


INT dl_dyn_init(ATS_MESS *pm, VOID *owner) ; 


Copies the value of owner into atsdial.owner, and also copies w_ws->wserv. filter and 
w_ws->wserv.filmethod into atsdial.filter and atsdial.filmethod. 


If there is a keyboard filter that is non-permanent (atsdial . £ilmethod is not negative), the method then 
calls p_leave(E_GEN_IN_usE). An application with a temporary keyboard filter is deemed not to be ina 
suitable state to handle an ATS dialog. 


The process ID of the controlling process is copied from pm- >mess.pid into atsdial .pia, and the 
application's filter is cleared (w_ws->wserv. filter and w_ws->wserv.£ilmethod are cleared). The value of 
atsdial.ret is set to -1, the default value that will indicate termination of the dialog by pressing Esc. 


If pm->u.d.butslen is negative, this is taken to mean that pm->u.buts contains a pointer to initial text for 
an edit box. The value of pm->u.d.butslen is copied into atsdial.chlist, for later use, and 
pm->u.butsien is set to 2 (the length of a pointer). 


Memory is allocated to contain the resources specified by pm->u.d.main (the main dialog resource) and 
pm-u.d.buts (optional data for one of the dialog's controls) The data is copied from the controlling process 
and pointers to the two allocated cells are written to atsdial.main and atsdial.buts. 


The flags pLGBox_No_wart and DLGBox_No_ppp are ored into the dialog box flags in the main dialog 
resource and the dialog box sends itself a pL_1n1T message. 


If atsdial.chlist is negative, the dialog's edit box is seeded with up to ars_MAX_EDITOR_LEN bytes of text 
read over from the controlling process, at an offset that is specified by the two-byte cell pointed to by 
atsdial.buts. 


The dialog then sends itself a p._seT_s1z= message and calls hinitvis. The flag PR_WIN_INITIALISED is 
ored into win. flags, the dialog sends w_ws a wS_ADD DIAL message, DatLocked is incremented and 
atsdial.locked is set TRUE. 


The method returns zero to indicate that p_1eave has not been called. The method is thus suitable for being 
called under the protection of p_enter. 


7 DIALOG BOXES 
SSE ITALOG BOKES 


Handle key input 


INT dl_key (VOID) ; 
Handle the Enter key input that exits the dialog. 


If atsdial .chlist is positive (the dialog is presenting a choice list) write the index of the currently 
selected choice list item to atsdial.ret and retum WN_KEY_CHANGED. 


If atsdial.chlist is negative (the dialog is presenting an edit box) copy the text back to the controlling 
process, overwriting the string used to intialise the edit box, write zero to atsdial. ret and return 
WN_KEY_CHANGED. 


If atsdial.chlist is zero, just return WN_KEY_CHANGED. 


CHAPTER 8 


LABELS, BUTTONS AND CHOICE LISTS 


This chapter describes three of the basic components of a dialog box. 


The TExtwrn class, as its name suggests, is used to display static text, including any dialog box title and 
optional prompt messages for other controls. Dialog box buttons, used to exit the dialog box or to initiate 
other actions, are implemented by either the acList or smacuztsvt ‘action list' classes. The cuurst class 
provides the means of selecting one option from a number of alternatives. 


It is unlikely that an application will need to subclass any of the classes described in this chapter and it is 
expected that the vast majority of applications will simply use them as standard dialog components. In 
consequence applications will generally not send explicit messages to instances of these classes and it is 
therefore not necessary to understand the class methods in any great depth. 

Precursors 


Familiarity with the following topics will aid the understanding of this chapter: 
e the wr and Lopcer classes, described in the Windows chapter 


¢ — the description of the piczox class in the Dialog Boxes chapter, particularly the wn_key method 
which may sent wn_KEy messages to a dialog box component and respond to the return value 


e for the cuurst class, the description of its LtstBox component in the List Boxes and Menus 
chapter 


Class diagram 


[tra ee [oT eee ce 


a tata! ¢ 
“ epflat > 7 wid ; 
ra nf ¢ 
x‘. ‘ % 
NS E ‘AL 5 
x \ . : 
. er \ ee ‘ 
a ot 
me tes Pade ae Pe ee pom et 
‘ 4 ie: as ? * aK. ‘i rs -s. 
/ textwin ~ / lodger > / chlist 7s “~~ fAachlist “> 
é if ‘ Zz 4 i“ / ‘4 
NS c SSS <+—_———_ ¥ i re \ 
hs ' ee ‘ ‘ woes 7 
i) ort meee’ rte eee” Rae ee ‘ oo eee 
Nee” ea Dabs i No” 


a are he 
/ smaclist > 
Zc ‘ 


‘ pete 
, - a 
ae pore ede 


> vanumber > 


HWIM REFERENCE 


The TEXTWIN class 


flags landlord 
i offset 
width 


destroy 

ig_draw 

1lg_self_check 

ig_set_id_pos 
fe 


wn_visible 


lg_sense_width 
wn_draw 
wn_emphasise 
wn_init 

wn_key 


wn_cale_ position 
wn_connect 
wn_dodraw 


wn_sense 
wn_set 


wn_position 
wn_redraw 
wn_sense_help 


ig_update 


An instance of rextw1n is used within a dialog box to display static text. In addition to displaying simple 
informational messages, it may be used as a prompt (or label) to a control, or as the dialog box title. 


Text may be specified in a dialog resource in a number of ways. For example, the system error dialog, 
whose resource is listed below, simply declares two rexTwin components: 


RESOURCE DIALOG sys_error_dialog 
{ 
£lags=DLGBOX_RBUF_FILLED|DLGBOX_NO_DDP; 
controls= 
{ 
CONTROL 
{ 
class=C_TEXTWIN; 
£lags=DLGBOX_ITEM_CENTRE|DLGBOX_ITEM_DEAD|DLGBOX_ITEM UNDERLINED; 
info=TXTMESS 
{ 
flags=IN_TEXTWIN_AL CENTRE; 
}; 
} ’ 
CONTROL 
{ 
class=C_TEXTWIN; 
£lags=DLGBOX_ITEM_CENTRE|DLGBOX_ITEM_DEAD; 
info=TXTMESS 
{ 
flags=IN_TEXTWIN_AL CENTRE; 
}; 
}, 
CONTROL 
{ 
class=C_ACLIST; 
info=ACLIST 
{ 
rid=sys_ac_continue; 


); 


); 
} 


where the TxrmEss resource struct and its default values are defined in Awim.h as: 


STRUCT TXTMESS 


{ 


WORD flags=0; 
TEXT .str=""; 


} 


8 LABELS, BUTTONS AND CHOICE LISTS 


The first of the rexrwin components sets the flag DLGBOx_ITEM_UNDERLINED so that it appears as a dialog 
box title. The text of both components is determined by the type of the run-time error that causes the dialog 


to be displayed and is supplied dynamically. 


A Textwin dialog title may be specified more simply by providing text for the title element, as in the 
following example. This example also shows how to specify a TExTwrN prompt to a control, by providing 
text for the prompt item of a conrrot resource. In both of these cases the Textwrn flag values are set as 
appropriate by system code. 


RESOURCE DIALOG sys_printer_model 


{ 


title="Set printer"; 
flags=DLGBOX_NOTIFY_ENTER|DLGBOX_RBUF_FILLED; 
controls= 


} 


{ 


CONTROL 


{ 


prompt="Select printer"; 


flags=DLGBOX_ITEM_NOTIFY_CHANGED; 


class=C_CHLIST; 
info=CHLIST{}; 
} t 

CONTROL 


{ 


class=C_TEXTWIN; 


prompt="Default font"; 


info=TXTMESS 


{ 


flags=IN_TEXTWIN_POPOUT; 


by 
}; 


Class definition 


Defined in sub-category file textwin.cl (generated header file textwin.g). 


CLASS 


textwin lodger 


Text window 


{ 


REPLACE wn_draw 
REPLACE wn_init 
REPLACE wn_set 

REPLACE wn_sense 
REPLACE wn_key 
REPLACE 1g_sense_width 
REPLACE wn_emphasise 


CONSTANTS 


{ 

PR_TEXTWIN_AL LEFT 
PR_TEXTWIN_AL RIGHT 
PR_TEXTWIN_AL CENTRE 
PR_TEXTWIN_BOLD 
PR_TEXTWIN_BULLET 
PR_TEXTWIN_POPOUT 
PR_TEXTWIN_FLASHING 


IN_TEXTWIN_AL LEFT 
IN_TEXTWIN_AL_RIGHT 
IN_TEXTWIN_AL_CENTRE 
IN_TEXTWIN_BOLD 
IN_TEXTWIN_BULLET 
IN_TEXTWIN_POPOUT 


0x00 
0x01 
0x02 
0x04 
0x20 
0x40 
0x80 


PR_TEXTWIN_AL LEFT 
PR_TEXTWIN_AL RIGHT 
PR_TEXTWIN_AL_CENTRE 
PR_TEXTWIN_BOLD 
PR_TEXTWIN_BULLET 
PR_TEXTWIN_POPOUT 


HWIM REFERENCE 


a 


SE_TEXTWIN_ALIGN 
SE_TEXTWIN_BOLD 


(PR_TEXTWIN_AL_RIGHT|PR_TEXTWIN_AL CENTRE) 
PR_TEXTWIN_BOLD 


SE_TEXTWIN_TEXT 0x08 


SE_TEXTWIN_BULLET 


} 


TYPES 


{ 


typedef struct 


{ 


PR_TEXTWIN_BULLET 


UWORD state; 
TEXT label {1} ; 
} IN_TEXTWIN; 


typedef struct 


{ 


INT flags; 


UWORD state; Alignment, underline 


TEXT *buf; 
UWORD len; 


}SE_TEXTWIN; 


} 


PROPERTY 1 


{ 


PR_EPFLAT *label; 
UWORD state; 


} 
} 


label text object 
Alignment, underline 


The flag PR_TEXTWIN_FLASHING is not defined on the Series 3. 


Property 


textwin.label 


textwin.state 


TEXTWIN flags 


PR_TEXTWIN_AL LEFT 


PR_TEXTWIN_AL RIGHT 


PR_TEXTWIN_AL CENTRE 
PR_TEXTWIN_ BOLD 
PR_TEXTWIN BULLET 


PR_TEXTWIN_POPOUT 


PR_TEXTWIN_FLASHING 


either nuLL or the handle of the instance of epriat that contains the text 


any sensible combination of the flags listed below 


if set, the text is aligned left. No other pR_TEXTWIN_AL_ xxx flag should be 
set 


if set, the text is aligned right. No other pr_tExTWwINn_aL_xxx flag should be 
set 


if set, the text is centred. No other pR_TexTwIn_aL xxx flag should be set 
if set, the text is to be drawn in a bold font 
if set, the text is to be preceded by a rectangular bullet 


if set, the text window is to trigger a 'pop-out' subdialog on receiving a Tab 
keypress 


If set, use a flashing text cursor, otherwise any cursor is a highlighted 
obloid. This flag is not available on the Series 3, which is restricted to a 
non-flashing cursor. 


8 LABELS, BUTTONS AND CHOICE LISTS 


TEXTWIN methods 
WAUISU Sei 


VOID wn_init (IN_TEXTWIN *par, PR_WIN *landlord) ; 
Initialise the text window to contain any text specified by the 1n_TExtTwrn struct pointed to by par. 
Sets Lodger . landlord to the value of landlord and textwin.state tO par->state. 


If the par->labe1 buffer does not contain a null string, an instance of EprLar is created and initialised to 
contain the specified text, as indicated by the following code: 


p_send3 (epflat,O_EP_INIT,WS_MAX_PRINT_BOX_TEXT_LEN) ; 
p_send4 (epflat,O_EP_SET_ TEXT, &par->label [0] ,p_slen(&par->label [0] )); 


If this is successful, the handle of the instance of EPFLat is stored in textwin. label. On failure p leave is 
called. 


This message is sent from the DLGBox dl_item_add method. 


Draw text 


VOID wn_draw(PR_TEXTWIN *self); 


Draw the text of the text window, assuming the existence of an appropriate graphics context. 
If textwin.state contains PR_TEXTWIN_BOLD, the graphics context is set to use a bold font. 


On the Workabout, if the control is being used as a dialog component (win. flags contains 
PR_WIN_IS_DLCTRL) and the dialog is set to use the small font (the owning dialog box, whose handle is 
stored in lodger.1andlord, has a non-zero value of digbox . font) the graphics context is set to use the 
small font. 


The text is sensed by sending textwin. label aN EF_SENSE_BUF message and is then drawn, with a call to 
gPrintBoxText, at a position within the text window determined by the pR_TExtwin_aL xxx flag in 
textwin.state. The bullet rectangle is drawn or cleared, depending on the presence or absence of the 
PR_TEXTWIN_BULLET flag in textwin.state. If win. flags contains PR_WIN_EMPHAStIsED, the text (and any 
bullet) is highlighted. If textwin.state contains PR_TEXTWIN_FLASHING, the highlight takes the form of a 
flashing cursor. 


If the first character in the string is oxo1 then the second character is interpreted as an offset in pixels for 
the remaining characters. This technique is used to align the pack selector prompt as illustrated in the 
following picture: 


Open file 


| ¢ gelacuti+ 


ng Disk _ Internal 


The "Disk" text has been offset so as to align it with the "Name" text. 
If textwin.state contains PR_TEXTWIN_BOLD, the graphics context is reset to use a normal font. 


This message is sent from the DLGBox wn_draw method. 


WEST ) Set property 
VOID wn_set(SE_TEXTWIN *txtset); 


Set the text and/or the textwin. state flags according to the data in the sz_Texrwrn struct pointed to by 
txtset. The items that are to be modified are specified by txtset->flags, which should be a combination 
of se_TEXTwIN_xxx flags. The value of txtset->state should be a combination of pr_TExtwINn_xxx flags. 


HWIM REFERENCE 
ee SSSeSFSSeeFFeeeSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSOOee 


If txtset->flags contains sE_TEXTWIN_TEXT, the method sets the text (by sending textwin.1label an 
EP_SET_TEXT message) to the first txtset->1en bytes in the buffer pointed to by txtset->buf. If 
textwin. label is NULL, an instance of EPFLAT is created and initialised (as described in the wn_init 
method) before the Ep_seT_TExT message is sent. 


Each of the remaining flags in txtset->flags causes the corresponding PR_TEXTWIN_xxx bit in 
txtset->state to be written (either set or cleared) to textwin. state. 


An LG_DRAW message is sent, causing the text window to be redrawn, if txtset->£1ags contains any of the 
flags SE_TEXTWIN_TEXT, SE_TEXTWIN_ALIGN, SE_TEXTWIN_BOLD OF SE_TEXTWIN_BULLET. 


The following example sets the text to the string pointed to by str. It also clears any PR_TEXTWIN_BOLD flag 
and sets PR_TEXTWIN_AL_RIGHT (clearing PR_TEXTWIN_AL_LEFT and PR_TEXTWIN_AL_CENTRE in the process). 
No other flags in textwin.state are affected. 


LOCAL_C VOID SetTextWin(PR_TEXTWIN *textwin,TEXT *str) 


{ 


SE_TEXTWIN set; 


set .flags=SE_TEXTWIN_TEXT|SE_TEXTWIN_ALIGN|SE_TEXTWIN_BOLD; 
set.state=PR_TEXTWIN_AL_RIGHT; /* PR_TEXTWIN_BOLD not set, so will be cleared */ 
set .buf=str; 

set.len=p_slen(str) ; 

P_send3 (textwin,O_WN_SET, &set) ; 


} 


It is rare for application code to set more than the text of an instance of rextwrn used as a dialog box 
component. The flags in textwin. state are generally either set on initialisation (usually from 
IN_TEXTWIN_Xxx values set in a resource item) or are set or cleared by system code (see, for example, the 
DLGBOX dl1_item_lock and dl_item_dim methods). 


This message is sent from the pLczox wn_set method, normally invoked from application code by means 
of the hpigset and npigset Text utility functions. 


VOID wn_sense(SE_TEXTWIN *txtset) ; 
Write a pointer to the text in txtset->buf and the length of the text to txtset->1en, according to the code: 
txtset->len=p_send3 (self->textwin.label,O_EF_SENSE_BUF, &txtset->buf) ; 


On the Series 3, this method must not be called if the text window contains no text. On other machines the 
method simply writes zero to txtset->len if the text window contains no text. 


This message is sent from the pLGBox wn_sense method, normally invoked from application code by means 
of the hDigSense utility function. 


sirwia ae 
y input 

INT wn_key (INT keycode, INT modifiers) ; 

Simply returns wN_KEY_No_CHANGE (0) unless textwin. state contains PR_TEXTWIN_POPOUT. 


If textwin.state contains pR_TEXTWIN_POPOUT, the text window can trigger a subdialog (see the 
discussion of subdialogs in the Dialog Boxes chapter) on receipt of a wn_kEy message with keycode set to 
w_key_TAB. It does this by writing to wserv.subdial a value of one plus the text window's index within the 
dialog (the index is found by sending the dialog box a DL_HANDLE_TO_INDEX message). For any other value 
of keycode, the method uses the hinfoprint utility function to display the information message with 
system resource ID sys_popout_HELP (in English, this is the message "Press Tab to change this 
item"). 


In all cases the method returns wn_KEY_No_CHANGE (0). 


This message is sent from the pLGBox wn_key method. 


8 LABELS, BUTTONS AND CHOICE LISTS 


LG_SENSE WIDTH oS Return required contro! width 
INT lg_sense_width(VOID) ; 
If textwin. label is NULL, returns zero. 


Otherwise, senses the text window's text by sending textwin. label an EF_SENSE_BUF message and returns 
the width required to draw the string, plus an allowance for a preceding bullet (regardless of whether a 
bullet is actually present). 


This message is sent from the pu¢Box dl_set_size method. 


_. Emphasise 


VOID wn_emphasise(UINT flag) ; 


Emphasise the window if £1ag is TRUE, or remove the emphasis if f1ag is FALSE. Does nothing if 
attempting to set the emphasis to its current state, or if textwin. label is NULL. 


Sets the PR_WIN_EMPHASISED bit in win. flags if f1ag is TRUE, otherwise clears this bit and erases any text 
cursor. 


This message is sent from the DLGBox dl_take_focus method. 


The SMACLIST class 


landlord 
offset 
width 
totalwidth 


destroy 
1lg_sense_width 
1g_set_id_pos 
wn_draw 


destroy 
wn_calc_position lg_draw 
wn_connect 1lg_self_check 
wn_dodraw 


wn_init 
wn_key 
wn_sense 


wn_emphasise 

wnrkey 

wn_position 

wn_redraw 

wn_sense_ help ig_update 


SMACLIST is the 'small' form of an action list. It is used to implement a set of buttons in cases where there is 
a requirement for the dialog to occupy as small a region of the screen as possible. In consequence, a dialog 
containing an instance of smacuist usually does not contain any other controls. 


The following diagram shows an example of the use of smacutst in the Replace command of the Word 
application, to control how text replacements are made. In this case the dialog must be small since there is 
a requirement to display as much as possible of the text in which replacements are being made. 


(BEnd Replace (S)Skip <ADAL] 


HWIM REFERENCE 
See 


The dialog requires the two resources given below. 


RESOURCE ACLIST_ARRAY repl_ ac 


{ 


button = 


{ 


PUSH_BUT 


{ 
keycode=-'e'; 
str="End"; 
1 

PUSH_BUT 


{ 
keycode='r'; 
str="Replace"; 


}, 


PUSH_B 


{ 
keycode='s'; 
str="Skip"; 


}, 


PUSH_BUT 


{ 
keycode='a'; 
str="All"; 
} 
te 
} 


where the acLIST_ARRAY and PuSH_BUT resource structs are defined in Awim.rh as: 


STRUCT ACLIST_ARRAY 


{ 


LEN BYTE STRUCT button []; /* array of push_buttons */ 


} 


STRUCT PUSH_BUT 
BYTE { 
WORD keycode; 
TEXT str; /* text associated with button */ 


} 


An ACLIST_ARRAY resource defines, for each button, the key code that activates the button and the button's 
associated text. It must contain at least one pusH_BuT struct. 


The keycode value may be supplied in either upper or lower case, or may be a w_KEy_xxx value. If no 
keycode is set to W_KEY_ESCAPE, a negative keycode value, such as in the first item in the above example, 
indicates that the button may also be activated by pressing Esc. Only one such item may be included in the 
array. 


The following example illustrates the corresponding pratoc resource. If a dialog contains other controls, 
the smacList control must appear last. 


RESOURCE DIALOG repl_inst_dl 


{ 


flags=PR_WIN_FORCE_BOTTOM|PR_WIN_FORCE_LEFT; 
controls= 


{ 


CONTROL 


{ 


class=C_SMACLIST; 
info=ACLIST 


{ 


rid=repl_ac; 


}; 


}; 
} 


where the acizst resource struct is defined in Awim.rh as: 


§ LABELS, BUTTONS AND CHOICE LISTS 
$$ AED, BUTTONS AND CHOICE LISTS” 


STRUCT ACLIST /* Initialising struct for action list */ 


{ 


LINK rid; 


} 
Class definition 
Defined in sub-category file aclist.cl (generated header file aclist.g). 


CLASS smaclist lodger 
small action list lodges within dialog. No real button will be drawn 


{ 


REPLACE destroy 


REPLACE wn_init load action list, set dead & centre flags 

REPLACE wn_key process key press 

REPLACE wn_draw print text of current selection 

REPLACE wn_sense=p_dummy 

REPLACE lg_set_id_pos calculate position of button 

REPLACE lg_sense_width ret min width of control, real width may alter again 
later 

CONSTANTS 


{ 


SMACLIST_MAX_STRING 80 /* max of 80 characters */ 


} 


TYPES 


{ 


typedef struct 


{ 


UWORD width; width of ACLIST_button or letter within bracket for SMACLIST 


UWORD x; tl x-offset of ACLIST_but or ‘'(' in case of SMACLIST 
} BUT_POS; 

typedef struct 
{ 
WORD rid; resource ID of lbc text-array 
} IN_ACLIST; 

} 

PROPERTY 1 


{ 


PR_VARES *data; array holding keycode & text outside button 


BUT_POS *pos; array holding each button's width & x-offset 

UWORD totalwidth; cumulative total of button widths, excluding all gaps 
UWORD num; number of items in action list 

UWORD lwidth; width of left bracket 


} 
} 


The Series 3 version defines the sur_pPos struct as: 


typedef struct 


{ 


UWORD width; 
UWORD x; 
} BUT_POS; 


The Series 3 version also contains the following additional defined constants: 


SMACLIST_MIN_GAP 12 /* 2 numeric spaces between adjacent text items */ 
LEFT_BRACKET WIDTH 4 


On the Series 3a the corresponding values are read or derived from the globally accessible data that is 
described in the Introduction chapter of this manual. The left bracket width is stored in smaclist .lwidth - 
this property does not exist in the Series 3 smacuist class definition. 


Property 
smaclist.data the handle of an instance of a vares array, containing the key code and 
associated text for each button 


HWIM REFERENCE 
eee eS 


smaclist.pos a pointer to an allocated heap cell containing an array of the width and 
offset of each button. In the smacuist class, smaclist .pos->x is the x- 
offset of the button's leading left bracket character and 
smaclist .pos->width is the width of the single character that represents 
the button's key code 


smaclist.totalwidth the basic width of the control's buttons, including the smallest allowed 
button spacing. The actual width of the control, contained in 
lodger .width, may be greater than smaclist.totalwidth 


smaclist .num a count of the number of buttons in the action list 


smaclist.lwidth the width of a left bracket 


ae eS ES SS ers 
SMACLIST methods 


_ Destroy 
VOID destroy (VOID) ; 
Free the heap cell pointed to by smaclist .pos and supersend the pEsTRoy message. 
This message is sent from the pLGBox destroy method. 
Initialise 


VOID wn_init (IN_SMACLIST *init, PR_DLGBOX *landlord) ; 


Sets lodger. landlord to the passed value of landlord, which is assumed to be the handle of an instance 
of (a subclass of) pLcBox and ors DLGBOX_SMALL_ACTION_LIST into landlord->digbox. flags. 


Creates an instance of vares, then (provided init->rid is not zero) loads the resource specified by the 
resource ID init->ria and uses it to initialise the instance of vares (by means of a va_1nrT message). If 
this succeeds the handle of the instance of vargs is written to smaclist.data. The resource, when loaded, 
is regarded as a sequence of pusH_sur structs, this struct being defined in the acurst class definition as: 


typedef struct 


{ 


WORD keycode; /* keycode to match text of inside button */ 
TEXT str{1]}; /* text above the button */ 
} PUSH_BUT; /* correspond to push_but in hwim.rh */ 


It corresponds to the pusH_BuT resource struct used to construct an ACLIST_ARRAY resource (both of these 
resource structs are defined in Awim.rh). 


On the Series 3a, if 1andlord->win.flags contains wIN_FRoM_aTs (which implies that the landlord is an 
instance of arsprat or a subclass) the data in the varzs instance pointed to by smaclist .data is loaded 
with button data from the arspraz instance. 


The number of buttons is found by sending smaclist .data a VA_counT message and is written to 
smaclist .num. A heap cell is allocated to contain the width an offset of each button and its address is 
written to smaclist.pos. 


The dialog box flags for this item are set to contain DLGBOx_ITEM_CENTRE, DLGBOX_ITEM_DEAD and (but not 
on the Series 3) pLeBox_ITEM_ACLIsT by sending lodger.1landlord a DL_SET_ITEM_FLAGS message. 


The method calls p_leave on failure to create or initialise the smaclist .data component or to allocate the 
smaclist.pos heap cell. 


This message is sent from the pLGBox dl_item_add method. 


8 LABELS, BUTTONS AND CHOICE LISTS 


INT wn_key(INT keycode, INT modifiers) ; 


Scan the items in the smaclist .data array for a match between the stored key code and the passed 
keycode value. If the stored key code is negative it is considered to match with either the correponding 
(positive) value of keycode or the keycode value w_KEY_ ESCAPE. 


If there is a match, the corresponding button is animated to give a visual response to the keypress and the 
method then returns the index (the leftmost button has an index of zero) of the matching button. 


If there is no match the method returns -1. 


This method is not subclassed by acutrsr. It supplies the button animation for both the smaciist and 
ACLIST Classes, distinguishing the two cases by testing lodger . landlord->dlgbox. flags for the presence 
of pLGBOXx_ACTIoN_LIsT. In the smacutst case the button's key code character is animated by highlighting 
the button text for a period of two tenths of a second. For acurst the animation consists of a call to 
wDrawBut ton to draw the button in a depressed state, followed two tenths of a second later by another call 
to redraw the button in its undepressed state. In all cases a temporary graphics context is created for the 
animation and freed again afterwards. 


This message is sent from the pLGBox wn_key method. 


VOID wn_draw(VOID) ; 


Draw the row of buttons, assuming the existence of an appropriate graphics context. 


The method constructs a text string containing the buttons and displays it with a call to gprintBoxText. 
The data for each button is read from the smaclist .data array. The text of each button consists of the 
bracketed character corresponding to the button's key code, followed by the button text. Consecutive 
buttons are separated by two numeric spaces. 


This message is sent from the pLGBox wn_draw method. 


VOID wn_sense(SE_CHLIST *se) ; 


An instance of smacutst has no data that can usefully be sensed, so the supplied method does nothing. 


This method is supplied since it is called by system code. 


LG SET ID POS 


VOID lg_set_id pos(INT id, P_POINT *pos, UINT width) ; 


Supersend the Lc_seT_1p_Pos message and then, provided that smaclist .totalwidth (the width occupied 
by the buttons themselves) is less than lodger. width, adjust the button positions to centre them in the 
lodger window. 


This method is not subclassed by acutsv. It supplies the button positioning logic for both the smacuist and 
AcLIsT Classes, distinguishing the two cases by testing lodger . landlord->dlgbox. flags for the presence 
of DLGBox_AcTIon_utst. In the smacuist case the button separation is kept fixed but the buttons are 
centred by adjusting the value of lodger.offset.x. For acurst the button spacing is increased (by 
adjusting the x position of each button in the smaclist .pos array) as well as centering the buttons by 
changing lodger.offset .x. 


This message is sent from the pLGBOx dl_set_size method. 


HWIM REFERENCE 


LG SENSE 


INT lg_sense_width (VOID) ; 


Calculate the minimum width required to draw the contents. 


The content of the smaclist .pos element for each button is set so that smaclist .pos->x contains the 
x-offset to the leading left bracket of the button and smaclist .pos->width contains the pixel width of the 
uppercased character representing the button's key code. 


The display width of each button is calculated as the width of the uppercased key code character, including 
its enclosing brackets, plus the width of the following string. The button widths are accumulated into 
smaclist .totalwidth, together with a fixed separation between the buttons. The method assumes that 
smaclist .totalwidth initially contains zero, that is, it assumes that the method is called only once in the 
lifetime of an instance. 


The method returns the width of the control (which is also the final value stored in smaclist .totalwidth). 


This message is sent from the pLGBox d1_set_size method. 


The ACLIST class 


landlord 
offset 
width 


destrey 
wn_calc_ position lg_draw 
wn_connect 1g_self_check 
wn_dodraw 3 


wn_emphasise — 
wa-key wn_visible wn_key 
wn_position wn_sense 


wn_redraw tg—ense—width 


wn_sense_help lig_update 


The acutist class is used to add an action list of one or more buttons to a dialog, in cases where screen 
space is not at a premium. Each button has two associated items of text; one drawn inside the button, 
representing the key press that activates it, and one drawn above the button, intended to inform the user of 
the action that the button initiates. 


¢BT = Body text > 
Stop Delete Delete all 


8 LABELS, BUTTONS AND CHOICE LISTS 


ini paren 


As for sMacLIst, an AcLIsT control requires the buttons to be described in an ACLIST_ARRAY resource: 


RESOURCE ACLIST_ARRAY delete_ac 


{ 


button = 


{ 


PUSH_BUT 


{ 


keycode=W_KEY_ESCAPE; 
str="Stop"; 
} ’ 

PUSH_BUT 


{ 


keycode=W_KEY DELETE LEFT; 
str="Delete"; 
be 

PUSH_BUT 


ote Wee 

str="Delete all"; 

} 

}; 
} 

Again, the keycode of one element may be negative to allow it to be activated by pressing Esc as well as 
the specified key. The above example does not use this option since it explicitly uses a keycode of 
w_KEY_EscapE for one of its buttons. 


The dialog resource for the dialog illustrated above is as follows: 


RESOURCE DIALOG delete di 


{ 

title="Delete"; 
flags=DLGBOX_NOTIFY_ESCAPE|DLGBOX_RBUF_FILLED; 
controls= 


{ 


CONTROL 


{ 


class=C_CHLIST; 
prompt="Style"; 
info=CHLIST{}; /* choice list content supplied dynamically */ 
}, 

CONTROL 


{ 


class=C_ACLIST; 
info=ACLIST 


{ 


rid=delete_ac; 


}; 


}; 
} 


As with sMACLIST, an ACLIST control must be the last component of the dialog. 


HWIM REFERENCE 
eee 


Class definition ( 
Defined in sub-category file aclist.cl (generated header file aclist.g). 


CLASS aclist smaclist 
action list lodges within dialog.It is equivalent to a list of push_buttons 


{ 


REPLACE wn_init load action list given rid & set dead & centre 
REPLACE wn_draw 

REPLACE lg _sense_width returns min width of control 

TYPES 


{ 


typedef struct 


{ 


WORD keycode; keycode to match text of inside button 
TEXT str{1]); text above the button 
} PUSH_BUT; corresponds to push_but in hwim.rh 


} 


PROPERTY 1 
{ 
PR_VARES *text; array holding the keycode & text for above each button 
WORD width width of each button ( 
UWORD yl; offset to top of upper text boxes . 
UWORD y2; offset to top of buttons themselves 


} 
} 


The Series 3 version contains the following defined constants: 


ACLIST_BUTTON_MIN_GAP 5 min gap between 2 buttons 
ACLIST_BUTTON_WIDTH 38 For French 'Entrer' 
ACLIST_BUTTON_HEIGHT 12 

ACLIST_BUTTON_SHADOW 2 

ACLIST_TOP_GUTTER 4 from self->lodger.offset.y 


On the Series 3a the corresponding values are read or derived from the globally accessible data that is 
described in the Introduction chapter of this manual. 


The property items: 
WORD width width of each button 
UWORD yl; offset to top of upper text boxes 
UWORD y2; offset to top of buttons themselves 


do not exist in the Series 3 acu1st class definition. 


Property 

aclist.text The handle of an instance of a vanes array, containing the key code and 
associated text that is to be displayed above each button. 

aclist.width Used internally on the Series 3a to store the (fixed) width of all buttons. 
On the Series 3 this width is represented by the constant value 
ACLIST_BUTTON_WIDTH. 

aclist.yl Used internally on the Series 3a to store the (fixed) y-offset within the 
control's window to the top of the rectangle containing the text that is 
displayed above a button. On the Series 3 this is calculated from the sum 
of lodger offset .y and ACLIST_TOP_GUTTER. 

aclist.y2 Used internally on the Series 3a to store the (fixed) y-offset within the 


control's window to the top of the rectangle containing a button. On the 
Series 3 this is calculated from the sum of lodger.offset.y, 
ACLIST_TOP_GUTTER and ACLIST_BUTTON_HEIGHT. 


8-14 


8 LABELS, BUTTONS AND CHOICE LISTS 


The superclass property smaclist .data is set to the handle of an instance of vares that contains an array 
of key codes and text (to appear inside the button) for standard buttons. These are loaded from the 
SYS_BUTTON_TEXT system resource, which contains the following standard buttons: 


Keycode Button text (English version) 
W_KEY_RETURN Enter 
W_KEY_ESCAPE Esc 
W_KEY DELETE LEFT Del 
W_KEY_SPACE Space 
W_KEY_UP t 
W_KEY_DOWN + 
W_KEY_RIGHT > 
W_KEY_LEFT 
W_KEY_TAB Tab 
W_KEY_MENU Menu 


ACLIST methods 


_ Initialise 
VOID wn_init (IN_ACLIST *init, PR_DLGBOX *landlord) ; 


Sets DLGBOX_ACTION_LIST in landlord->dlgbox. flags, creates an instance of vars and loads into it the 
standard button data from the sys_BuTTon_TEXxT system resource. If this is successful, the vars handle is 
written to aclist.text. 


On the Workabout lodger.landlord is set to the passed value of 1andiord (as is done on all machines in 
the sMACLIST wn_init method) so that the control can determine if it should draw itself using the small 
font. 


Finally, the method supersends the wy_In1T message and, on the Series 3a, clears the flag 
DLGBOX_SMALL_ACTION_LIsT that is set in landlord->dlgbox. flags by the superclass wn_init method. 
Note that this means that a Series 3 acurst sets both the pLcBox_ACTION_LIsT and 
DLGBOX_SMALL_ACTION_LIST flags in 1andlord->dlgbox.flags (system code that must distinguish 
between the two classes always tests for the presence of pLGBOX_ACTION_LIST). 


This message is sent from the pLGBox d1_item_add method. 


Draw 
VOID wn_draw(VOID) ; 
Draw the row of buttons, assuming the existence of an appropriate graphics context. 


For each button, the method uses gprintBoxText to draw centred text above the button, the text (and the 
key code) being read - via a va_pBur message - from the corresponding element of the vares array whose 
handle is stored in smaclist .data. Each button is drawn with a call to worawButton, the text for the button 
being read from the element of the aclist .text array whose key code matches the one read earlier from 
the button's smaclist .data array element. If the button's key code does not match with any of the standard 
buttons, its text is taken to be the uppercased key code. 


This message is sent from the pLGBox wn_draw method. 


required width 


INT 1g_sense_width(VOID) ; 


Calculate the minimum width required to draw the contents. 


The method calculates the width of each button, sufficient to contain its text, subject to each button having 
a minimum width that is dependent on the machine type. These widths are stored in successive elements of 
the array pointed to by smaclist .pos. The button separations are calculated so that they are evenly spaced, 
with a minimum separation that is dependent on the machine type. The corresponding button positions are 


8-15 


HWIM REFERENCE 


also stored in the smaclist .pos array. Note that the button positioning logic pays no attention to the widths 
of the labels that appear above the buttons. It is the responsibility of the application programmer to select 
the text for these items so that they do not overlap. 


The method writes the sum of the widths of the buttons and the inter-button gaps to smaclist .totalwidth 
and returns this value. 


The width of the control may subsequently be increased, on receipt of an LG_sET_ID_Pos message, with the 
control's actual width then being stored in lodger.width. 


This message is sent from the pLGBox d1_sense_size method. 


The CHLIST class 


flags landlord 
i offset 
width 


data 
flags 
matcher 
matchlen 
nsel 

pop 


destroy 
1g_sense_width 
wn_draw 


wn_calc_ position 
wn_connect 
wn_dodraw 


eestzeay 

1lg_draw 

lg_self_check 

ig_set_id_pos 
ins 


wn_visible 


wn_emphasise 
wn_init 


wn_key 
wn_sense 
wn_set 


wn_position 
wn_redraw 


te-sensewidth 
lg_update 


wn_sense_help 


The cuurst class provides a choice list control that can be used to select one of a range of options. A 
choice list appears as shown by the ‘Page size' control in the following illustration, taken from the page size 
system dialog. 


¢A49 
Width 8.27 
Height 11.69 
‘Orientation Portrait 


A particular option may be selected by means of the Home and End keys, the left and right cursor keys, or 
by first letter match. A choice list may additionally be configured to perform incremental matching with a 
sequence of key presses. 


A choice list responds to the Tab key by displaying a pop-out expanded view, as shown below. 


“Orientation 


The simplest form of choice list has its items specified by menu resource structs. The dialog illustrated 
above contains two choice list controls, with their resources defined in the system resource file as follows: 


8-16 


§ LABELS, BUTTONS AND CHOICE LISTS 


rar ee 


RESOURCE MENU sys_page_size 

{ 

items= 
{ 
CHOICE_ITEM {str="A4";}, 
CHOICE_ITEM {str="Custom";}, 
CHOICE_ITEM {str="Executive";}, 
CHOICE_ITEM {str="Legal";}, 
CHOICE_ITEM {str="Letter";}, 
CHOICE_ITEM {str="Monarch";}, 
CHOICE_ITEM {str="DL"; } 
la 

} 


RESOURCE MENU sys_orient 
{ 
items= 


{ 


CHOICE_ITEM {str="Portrait";}, 
CHOICE _ITEM {str="Landscape"; } 
}; 

} 


where the cHorce_ITEM resource struct is defined in Awim.rh as: 


STRUCT CHOICE_ITEM /* choice list item */ 


BYTE { 
TEXT str=""; /* identification text */ 


} 


The corresponding system pra.oc resource is as follows where, for clarity, only the choice list control 
elements are shown: 


RESOURCE DIALOG sys_pagesize_dl 
{ 
title="Page size"; 
£lags=DLGBOX_NOTIFY_ENTER |DLGBOX_RBUF_FILLED|DLGBOX_APPEND_UNITS TITLE; 
controls= 


{ 


CONTROL 
{ 
class=C_CHLIST; 
flags=DLGBOX_ITEM_NOTIFY_CHANGED; 
prompt="Page size"; 
info=CHLIST{rid=sys_page_size;}; 
}, 

CONTROL 
{ 
class=C_CHLIST; 
prompt="Orientation"; 
info=CHLIST{rid=sys_orient;}; 
} 

he 

} 


where the cuurst resource struct and its default values are defined in hwim.h as: 


STRUCT CHLIST 


{ 

LINK rid=0; 
BYTE nsel=0; 
BYTE flags=0; 


} 


The content of a choice list may be set dynamically, using the wn_set method. This will typically be 
performed in the dialog's d1_dyn_init method. Changing the content of a choice list after the dialog box 
has become visible is not recommended, particularly if there is any risk that the new content may need a 


wider display. 


HWIM REFERENCE 
Ss SSS 


Class definition 


Defined in sub-category file chlist.cl (generated header file chlist.g). 


CLASS chlist lodger 


choice list 


self->win.offset.x is tl.x of text (excluding left arrow) 


{ 


REPLACE destroy 
REPLACE wn_key 
REPLACE wn_draw 
REPLACE wn_set 
REPLACE wn_sense 


process key press 

print text of current selection 
set data,nsel or retain property 
sense nsel value 


REPLACE wn_emphasise draws arrow if highlighted 
REPLACE wn_init create menu given rid 
REPLACE lg _sense_width returns (min text width + right arrow). 
CONSTANTS 
{ 
SE_CHLIST_NSEL 0x01 
SE_CHLIST_DATA 0x02 
SE_CHLIST_RETAIN 0x04 
IN_CHLIST_INCREMENTAL 0x01 
PR_CHLIST_RETAIN 0x04 
PR_CHLIST_SUSPENDED 0x08 To suspend display of cursor 


PR_CHLIST_FIXED WIDTH 0x10 


} 


TYPES 

{ 

typedef struct 
{ 
WORD rid; resource ID of lbc text-array 
UBYTE nsel; initial value of nsel 
UBYTE flags; IN_CHLIST INCREMENTAL 
} IN_CHLIST; 


typedef struct 


{ 


UWORD set_flags; which fields significant 

PR_VAROOT *data; possible new data value 

UWORD nsel; possible new nsel value 

} SE_CHLIST; 
} 

PROPERTY 2 

{ 
PR_LISTBOX *pop; handle of pop-out menu (NULL if un-squirted mode) 
PR_VMATCHER *matcher; set if incremental matching required 
PR_VARES *data; pointer to lbc text-array struct 
UWORD nsel; selected item in list (zero for first) 
UWORD flags; holds PR_CHLIST_ flags 
UWORD matchlen; length of match string 


} 
} 


The Series 3 version does not define pR_CHLIST_FIXED_WIDTH. 


Property 
chlist.pop 


chlist.matcher 
chlist.data 


chlist.nsel 


chlist.flags 


either wut or the handle of an instance of LrsTzox, used to display a pop- 
out expanded view 


either nuut or the handle of an instance of vmarcuer, used to perform 
incremental matching 


the handle of an instance of vargs, containing the text for the choice list 
items 


the index number of the currently selected item 


a combination of the pr_cuList_xxx flags described below 


8 LABELS, BUTTONS AND CHOICE LISTS 


chlist.matchlen if chlist.matcher is not NULL, the character offset to the incremental 
matching cursor, otherwise not used 
CHLIST flags 
PR_CHLIST_RETAIN if set, the instance of vanes whose handle is stored in chiist .data will 
not be destroyed when replaced by another instance of vanes or when the 
choice list is destroyed 
PR_CHLIST_SUSPENDED when set, disables the drawing of any incremental matching cursor 


CHLIST methods 


Destroy 


VOID destroy (VOID) ; 


If chlist . flags does not contain pR_CHLIST_RETAIN and chlist.data is not uLL, send chlist.dataa 
DESTROY message. Then supersend the pEstroy. 


This message is sent from the pLGBox destroy method. 


oo Initialise 


VOID wn_init (IN_CHLIST *init, PR_WIN *landlord) ; 


Set lodger. landlord to the passed value of landlord. Create an instance of vares and (provided 
init->rid is not zero) load into it the resource with ID init->ria. If the creation and initialisation is 
successful, write the handle of the instance to chiist .data. 


On the Series 3a, if landlord->win. flags contains win_FRom_ats (which implies that the landlord is an 
instance of aTspIat or a subclass) the data in the varzs instance pointed to by smaclist .data is loaded 
with data from the arsp1at instance, rather than from the resource. 


If init->flags contains IN_CHLIST_INCREMENTAL, create and initialise an instance of vmarcuer, according 
to the following code: 


p_send5 (self->chlist.matcher,O_IM_INIT, &chlist .matchlen, 80,chlist.data) ; 
and store its handle in chlist .matcher. 


If init->nsel is not zero, sets chlist .nsel tO init->nsel, provided this is within the range of choice list 
items, otherwise sets to the last item. If this changes chlist .nsel and chlist.matcher is not NULL, sends 
chlist.matcher an IM_SET_VAL message, passing chlist .nsel, and Sets chlist.matchlen to zero. 


This message is sent from the pLGBox a1_item_add method. 


WN KEY sc ccc cc _ Handie key Input 
INT wn_key (INT keycode, INT modifiers) ; 
If the choice list contains no items, the method simply returns ww_KEY_No_CHANGE (0). 


Ifa pop-out expanded view is currently displayed, chlist .pop is sent the wn_kEy message. Subsequent 
processing depends on the return value from this message as follows: 


WN_KEY_NO_CHANGE the method simply returns wN_KEY_NO_CHANGE 


any positive value this indicates the selection of a new item in the choice list, and 
chlist .nsel is set appropriately. The method then returns 
WN_KEY_CHANGED 


any other (-ve) value chlist .pop is sent a DESTROY message, chlist.pop is set to NULL, and the 
method returns the message return value 


Otherwise, processing is dependent on the value of keycode, as follows: 


HWIM REFERENCE 


W_KEY_LEFT 


W_KEY_RIGHT 


W_KEY_HOME 


W_KEY_END 


W_KEY TAB 


any other non- 
printable key, except 
W_KEY_ DELETE_LEFT 


any other key 


chlist .nsel is decremented by one or, if already zero, set to the last item 
in the choice list. The method sends an Lc_pRaw message and returns 
WN_KEY_CHANGED 


chlist .nse1 is incremented by one or, if already at the last item in the 
choice list, set to zero. The method sends an L¢_praw message and returns 
WN_KEY_ CHANGED 


chlist.nsel is set to zero. The method sends an Lc_praw message and 
returns WN_KEY CHANGED 


chlist.nsel is set to the last item in the choice list. The method sends an 
LG_DRAW Message and returns WN_KEY_ CHANGED 


an instance of ursTsox is created, initialised and made visible (using the 
utility function hinitvis. The initialisation uses an In_LIsTBox struct that 
is set up as indicated in the following code fragment: 


IN_LISTBOX lst; 


ist .flags=IN_LISTBOX_KEEP_ARRAY|IN_LISTBOX_CUR_SET| 
IN_LISTBOX_POS_ALIGN_Y|IN_LISTBOX_AUTO_SIZE; 
if (self->chlist.matcher) 
lst .flags|=IN_LISTBOX_MATCHER; 
if (self->chlist.flags&PR_CHLIST_FIXED WIDTH) 
{ /* fixed width code not present for Series 3 */ 
ist .minwid=p_send2(self,0_LG SENSE_WIDTH) ; 
lst. flags |=IN_LISTBOX_FIXED_WIDTH; 


winquireWindowOffset (0, self->win.id, &lst.pos) ; 
lst.pos.x+=self->lodger.offset.x; 

lst .pos.y+=self->lodger.offset.y; 
lst.current=self->chlist.nsel; 


If successfully created and initialised, the prsTsox handle is written to 
chlist.pop. The method returns wn_KEY_ABSORB_oN to instruct the dialog 
box to direct all future key presses to the wn_key method of this control. 


the method sends an L¢_praw message and returns WN_KEY_NO_CHANGE. 


if chlist .matcher is not nuL, this object is sent an 1m_KEY message, 
passing keycode and modifiers. If the return value is IM_NEW_DISPLAY, 
chlist .nse1 is set to the value returned by sending chlist .matcher an 
IM_SENSE_VAL message. The method then sends an Lc_pRaw message and 
returms WN_KEY_CHANGED. 


Otherwise the method attempts to make a first letter match between the 
choice list items and the value of keycode. This matching is performed by 
cycling forwards from the current item (so that repeated pressing of an 
alphabetic key will select, in turn, each item whose text starts with that 
letter). The method then sends an Lc_pRaw message and returns either 
WN_KEY_NO_CHANGE, OF WN_KEY_CHANGED if the first letter match changed 
the current item 


This message is sent from the pLGBOx wn_key method. 


VOID wn_draw(VOID) ; 


Draw 


Draw the choice list control, assuming the existence of an appropriate graphics context. 


If the choice list contains no items, the method simply clears the rectangular area occupied by the control. 


Otherwise, draw (using gprintBoxText) the text of the current item and, if win. flags contains 
PR_WIN_EMPHASISED, enclosing left and right arrow characters. If the choice list supports incremental 


8 LABELS, BUTTONS AND CHOICE LISTS 


matching the incremental matching cursor is drawn, provided the choice list is emphasised, chlist. flags 
does not include pr_cHLIST_sUsPENDED and a pop-out expanded view is not currently displayed. 


This message is sent from the pLGBox wn_draw method. 


WN_SET 


VOID wn_set (SE_CHLIST *set) ; 


titem and/or data 


Set the data array that contains the choice list items and/or the currently selected item from the SE_CHLIST 
struct pointed to by set. 


If set->set_flags contains se_cuListT_pata, the choice list is set to use the data array whose handle is 
stored in set->data. Provided chiist . flags does not contain PR_CHLIST_RETAIN, any existing 
chlist.data is sent a Destroy message before the handle in set->data is copied to chlist.data. If 
chlist .matcher is not nuLL, the value of set->data is also written to chlist -matcher->vmatcher. va. 


If set->set_flags contains SE_CHLIST_NSEL, the choice list is set to the item with index number 
set->nsel or, if this number is too large, the last item in the choice list. If chlist .matcher is not NULL, 
chlist.matcher is sent an IM_SET_VAL message, passing the value of chlist .nsel, and chlist.matchlen 
is set to zero. 


If set->set_flags contains sE_CHLIST_RETAIN, the flag PR_CHLIST_RETAIN is ored into Chlist. flags, SO 
that the instance of vares whose handle is in chlist .data will not subsequently be destroyed. Note that a 
means of clearing this flag, once set, is not supplied. 


On conclusion, the method sends an L¢_pRaw message. 


This message is sent from the pLGBox wn_set method, normally invoked from application code by means 
of the hDlgSet, hDlgSetChlist and hDlgsetch1istOn utility functions. 


Sense data and selected item 
VOID wn_sense(SE_CHLIST *set); 
Writes chlist .nsel and chlist.data to set->nsel and set->data respectively. 


This message is sent from the pLGBox wn_sense method, normally invoked from application code by means 
of the hplgSense and hDlgSenseChlist utility functions. 


INT 1lg_sense_width (VOID) ; 


Returns the width required to display the widest item in the choice list. If there are no items, the method 
returns the width required to display text of zero length. 


This message is sent from the DLGBox d1_set_size method. 


VOID wn_emphasise (INT flags) ; 
If chlist .pop is not NULL, simply send the wn_EMPHASISE message to chlist .pop. 


Otherwise, set or clear PR_WIN_EMPHASISED in win. flags, depending on whether the passed flags value is 
TRUE OF FALSE and, if FALSE, erase any incremental matching cursor. Then send an Lc_pRaw message. 


This message is sent from the DLGBox di_take_focus method. 


HWIM REFERENCE 


The NCHLIST numeric choice list class 


aestesy 
wn_calc_position 
wn_connect 


landlord 
offset 
width 


destrey 
ig_draw 
lg_self_check 


matcher 
matchlen 
nsel 

pop 


destroy 
1g_sense_width 
wn_draw 


wn_dodraw 1g_set_id_pos wn_emphasise 


wWR-ERLE 


wn_visible 


wn_position 
wn_redraw 
wn_sense_help 


The ncuutst class is not present on the Series 3. 


The neuiist class provides a choice list control that allows the selection of a positive integer value in the 
contiguous range from 1 to a specified maximum value. 


Class definition 
Defined in sub-category file nchlist.cl (generated header file nchlist.g). 


CLASS nchlist chlist 
Numeric choice list class 


{ 

REPLACE wn_init 
REPLACE wn_set 
REPLACE wn_sense 


} 
Property 
There is no property associated with ncxuisr. 


Ee aaa ae ee ae ey 
NCHLIST methods 


WNLINIT 


VOID wn_init (IN_CHLIST *init, PR_WIN *landlord) ; 


Initialise 


Initialise the numeric choice list. 


The method sets 1odger. landlord to the passed value of landlora. amd creates an instance of the 
VANUMBER Class, storing its handle in chlist.data. 


The list of numeric choices is not set up during initialisation, the init parameter being ignored. In 
consequence, there must be a following call to the wn_set method. 


8 LABELS, BUTTONS AND CHOICE LISTS 


WN_SET =————SsSSett current itei# 


VOID wn_set (SE_NCEDIT *pset) ; 


sr maximum value 


Set the currently selected item and/or the maximum selectable value from the se_ncEDrT struct pointed to 
by set. The sz_nceprT struct is defined in ncedit.g as: 


typedef struct 


{ 

UWORD value; 
UWORD low; 
UWORD high; 
UWORD flags; 
} SE_NCEDIT; 


For further explanation, see the description of the nceprr class, in the Numeric Editors chapter. 


If pset->£1ags contains s—E_NCEDIT_HIGH, the maximum selectable value is set by sending the component 
instance Of VANUMBER a VAN_SET_MAX message, passing the value of pset->high. It is essential that an 
instance of NCHLIST receives at least one wN_SET message to set the maximum value after processing a 
WN_INIT message. 


If pset->£1ags contains sE_NcEDIT_vaLuE, the current selection (as specified by chlist -nse1) is set to the 
item with index number pset->value - 1 and Ncuuist sends itself an Lc_pRaw message. 


It is the programmer's responsibility to ensure that a wn_seT message does not attempt to set a current 
selection that exceeds the current maximum value. 


VOID wn_sense(UWORD *psense) ; 


Writes the value of chlist.nsel + 110 «psense. 


The VARES resource array class 


destroy va_replace va_copy 
va_count va_reclen 
va_delete va_init 
va_sort va_deletem 
va_key va_insertm 
va_findisq ind va_prec 
va_insertisq va_pbuf 
va_append i va_compress 
va_insert 

va_search 

va_compare va_capacity 

va_reset va_compress 

va_test 


The vares class subclasses varoot to provide an array suitable for storing a sequence of leading byte 
counted text elements, the array being preceded by a byte count of the number of elements in the array. It is 
primarily intended for storing data such data that has been loaded from a resource file (for example, a Menu 
resource that contains the set of text items to be displayed in a choice list). It is used as a component by the 
CHLIST, ACLIST and smacttst classes. 


HWIM REFERENCE 
eee 


Class definition 
Defined in sub-category file vares.cl (generated header file vares.g). 


CLASS vares varoot 
{ 
REPLACE va_copy 
REPLACE va_reclen 
REPLACE va_init 
REPLACE va_deletem 
REPLACE va_insertm 
REPLACE va_prec 
REPLACE va_pbuf 
REPLACE va_compress 


PROPERTY 
UBYTE *data; 
} 
} 
Property 
vares.data Either nuuz or a pointer to an allocated cell that contains a byte count of 
the number of elements, followed by the elements, each consisting of 
leading byte counted text. 


a i a es 
VARES methods 


UWORD va_copy(UWORD num, UBYTE *prec) ; 


Copy the data of record number nun, not including its leading count byte, to the buffer pointed to by prec 
and return the length of the copied data. 


UWORD va_reclen(UWORD num) ; 
Return the length of record number nun. 


The record is located by sending a va_PREc message. 


VAUIN 


VOID va_init(UBYTE *data) ; 


Initialise the array to contain the elements pointed to by data. It is assumed that data points to a leading 
byte that contains a count of the following items, each of which is leading byte counted text. 


Copies the pointer data to vares .data and, if the pointer is not NULL, sets varoot .nrec to the value in the 
first byte pointed to by data. Finally, varoot .key.ofs is set to one - i.e. sizeof (UBYTE). 


Delete sequence of récords 


VOID va_deletem(UWORD num, UWORD nrec); 
Delete nrec records, starting with record number num. 


The method does nothing if vares.data is nuLL. Otherwise the specified items are removed and the alloc 
cell adjusted in size by means of a call to p_adjust. The value of varoot .nrec and the item count in the 
first byte of the data are adjusted accordingly. 


8 LABELS, BUTTONS AND CHOICE LISTS 


VOID va_insertm(UWORD num, UBYTE *prec, UWORD nrec); 


Insert nrec records from the buffer pointed to by prec, immediately before record number num. The data 
pointed to by prec is assumed to be one or more leading byte counted text items, with no leading item 
count. 


If vares .data is NuLL, the method creates an alloc cell to contain the data, otherwise a gap is opened in the 
existing cell by means of a call to p_adjust. 


If this succeeds, the data is copied into the alloc cell. The value of varoot .nrec and the item count in the 
first byte of the data are adjusted accordingly. 


The method does nothing to the data and calls p_1eave if there is insufficient memory to create or expand 
the alloc cell. 


UBYTE *va_prec({UWORD num) ; 


Return a pointer to record number num, including its leading count byte. 


UBYTE *va_pbuf (UWORD num) ; 


Return a pointer to the data of record number nun, that is, excluding its leading count byte. 


VOID va_compress (VOID) ; 


Free unused allocated memory. 


The method does nothing unless varoot .nrec is zero (inserting or deleting records always adjusts the size 
of the cell accordingly). 


If varoot .nrec is zero, the method frees the alloc cell pointed to by vares. data and sets vares.data to be 
NULL. 


HWIM REFERENCE 


The VANUMBER numeric array class 


va_count 
va_delete 
va_sort 
va_key 
va_findisq 
va_insertisq 
va_append 
va_insert 
va_search 
va_compare 
va_reset 


va_replace destroy 
va_pbuf 


va_copy van_set_max 


va_reclen 
va_swap 
va_init 
va_deletem 
va_insertm 
va_prec 
va—pbut 
va_capacity 
va_compress 


va_test 


The VANUMBER Class is not present on the Series 3. 


The vanumBer class subclasses varoor to provide a pseudo-array that behaves as though it contains records 
that consist of string representations of consecutive positive integers, starting with "1". It is used as a 
component by the ncuurst class. 


Class definition 
Defined in sub-category file nchlist.cl (generated header file nchlist.g). 


CLASS vanumber varoot 


{ 


REPLACE destroy=root_destroy 
REPLACE va_pbuf 

ADD van_set_max 

PROPERTY 


{ 


TEXT data [8]; 


} 
} 


Property 


vanumber.data A buffer containing the string representation of the array 'record' last 


referenced in a vA_PBUF message. 


LS a a 
VANUMBER methods 


Destroy 
VOID destroy (VOID) ; 


This method calls root_destroy since, exceptionally, a vanumBEr array has no allocated memory to 
contain its ‘records’. 


8 LABELS, BUTTONS AND CHOICE LISTS 


VA_PBUF =—sese Point to record data 
TEXT *va_pbuf (INT num) ; 
Return a pointer to 'record' number num. 


The method uses a call to p_itob to generate, in vanumber .data, a zero-terminated string representing the 
number num and returns a pointer to this string. 


VAN_SET.MAX == Set maximum value 
VOID van_set_max(INT max) ; 


Set the maximum displayable value. 


The method simply sets varoot .nrec to the value max. 


CHAPTER 9 


NUMERIC EDITORS 


This chapter describes the numeric editor dialog components provided by the HWIM library. There are 
currently seven variants as follows: 


e the multi-field numeric editor that provides the base class for the remaining six variants: it is not 
intended to be used as a stand-alone class 


e the long numeric editor that allows the user to edit a signed long value 

e the integer numeric editor that allows the user to edit an unsigned integer value 

e the word numeric editor that allows the user to edit a word value 

e the date/time numeric editor that allows the user to edit either a date, a time or a duration 
e — the latitude/longitude editor that allows the user to edit either a latitude or a longitude 


e — the range numeric editor that allows the user to edit two unsigned words specifying the upper and 
lower values of a range. 


Precursors 
Familiarity with the following topics will aid the understanding of this chapter: 


¢ — the win and Lopcer classes described in the Windows chapter of the HWIM Reference manual. 


e the description of the piggox class in the Dialog Boxes chapter, particularly the wn_key method 
which may send wn_key messages to a dialog box component. 


Class diagram 


af ie 

oe i 

Fai baesti H 

ci 

_/ ledger a 

a ( 

Tame ors ‘ oom 3 
rs wncedit ? i / tgedit > 
AL ' R ‘ 
~, ‘ As, ' 
: Lees < oo eee te eee * atte 

ae ~ Incedit i a mfne wae fase 


~~ ~ 
x \ ~ 4 
. 


HA ncedit > é lledit rorad 


HWIM REFERENCE 


landlord 
offset 
width 


selected 
cField 
nField 
totWidth 
cPos 
changed 
eStr 
dStr 
trail 

£ 


destrey destroy 


wn_key 


wn_calc_position wn_init 
wn_connect wn_visible 
wn_dodraw ig_draw 


wn_draw 

wn_set 
wn_emphasise 
ig_sense_width 
lg_self_check 
mf£_range_beep 


ig_set_id_pos 
wn_position 
wn_redraw tg—sense—width 


wn_sense_help ig_update 


The mrwe multi-field numeric editor class is intended to be subclassed to create a numeric editor control. In 
addition to the subclasses supplied in the HWIM library, two example subclasses are described later in this 
chapter. 


MFNE supports the display of a series of fields, each of which may be edited, as shown in the following 
picture: 


Set time and date 


(37:14 pm 
‘Date 67/12/1993 


In this illustration, the Time control allows the user to edit the hours, minutes and seconds fields, and to 
type a P or an A to toggle the am/pm indicator. The Date control allows the user to edit the day, the month 
and the year. 


Class definition 
Defined in sub-category file mfne.c/ (generated header file mfne.g). 


CLASS mine lodger 
Multi field numeric editor 


{ 


REPLACE wn_key process key press 

REPLACE wn_draw display current number 

REPLACE wn_set set data 

REPLACE wn_emphasise set initial highlight, validate number 
REPLACE lg_sense_ width return width of max number plus cursor 
REPLACE lg_self_check check the current number is valid 

ADD mf_range_beep beep and give range info message 


9 NUMERIC EDITORS 
KK SE SNUMERNG EDITORS 


CONSTANTS 


{ 


MFNE_MAX FIELDS 4 
MFNE_MAX WIDTH 10 

MFNE_MAX TRAILER 3 
MENE_LOWER 0 

MFNE_UPPER 1 
MFNE_CURSOR_WIDTH 3 
MFNE_SIGNED 0x01 

MFNE_LEFT ALIGN 0x02 
MFNE_SUPPRESS LEADING 0x04 
MFNE_SUPPRESS_ SEPARATOR 0x08 
MFNE_TRAILER 0x10 

MFNE_SETS NEXT 0x20 
MFNE_SETS PREV 0x40 
MFNE_AUTO_ SIZE 0x80 


} 


TYPES 


{ 


typedef struct 


} 


{ 


WORD flags; 
LONG value; 
UBYTE width; 
UBYTE hWidth; 
UBYTE hPos; 
UBYTE separator; 
LONG limits [2]; 
} MFNE_FIELD; 


PROPERTY 
{ 
WORD selected; Current state 
WORD cField; The current field 
WORD nField; The number of fields 
WORD totWidth; The total field width (chars) 
WORD cPos; The cursor position (chars) 
WORD changed; The field has changed 
TEXT eStr (MFNE_MAX_WIDTH+2] ; The current edit context 
TEXT dStr([MFNE_MAX_FIELDS* (MFNE_MAX_WIDTH+1)+MFNE_MAX TRAILER+2] ; 
TEXT trail[2] [MFNE_MAX TRAILER+1] ; The trailer text 
MFNE_FIELD f [MFNE_MAX_FIELDS] ; The fields 
} 
} 
Property 
mfne.selected TRUE if the current field is selected/highlighted 
mfne.cField the index of the current field: the first field has index zero 
mfne .nField the number of fields: less than or equal to MFNE_MAX_FIELDS 
méne.totWidth the width of the lodger window: a subclasser need not set this 
mfne.cPos the cursor position within the current field - units of characters: a subclasser need 
not set this 
mfne . changed TRUE if one or more fields have been changed. This property is set by the 
1g_self_check and wn_key methods. 
mfne.eStr the editable text of the current field: a subclasser need not set this 
mfne.dStr the formatted string representing the entire content of the editor: a subclasser need 
not set this 
mfne.trail the two zero terminated strings that define the trailer text 


HWIM REFERENCE 
ae 


mfne.f an array of MFNE_FIELD structs. 
The MFNE_FIELD struct is defined as follows: 


typedef struct 


{ 

WORD flags; 
LONG value; 
UBYTE width; 
UBYTE hWidth; 
UBYTE hPos; 
UBYTE separator; 
LONG limits [2]; 
} MFNE_FIELD; 


The significance of the members of the mrwe_FIELD struct is as follows: 
flags may contain an ored combination of the following flags: 


MFNE_TRAILER which specifies that one of the zero terminated strings 
specified in mfne.trail is to be drawn: the string to be drawn is 
specified by the current value. 


MFNE_SUPPRESS_SEPARATOR which specifies that the separator 
character is to be ignored. 


MFNE_SIGNED which specifies that the editable value can assume 
negative values. 


MFNE_SETS_NEXT which specifies that the value member provides a 
lower bound for the next field. 


MFNE_SETS_PREV which specifies that the value member provides an 
upper bound for the previous field. 


MEFNE_AUTO_SIZE which specifies that automatic sizing is allowed. 


MFNE_LEFT_ALIGN which specifies that the field is to be drawn as left 
aligned text. Note that mrwe_LEFT_aLIGn takes precedence over 
MFNE_SUPPRESS LEADING. 


MFNE_SUPPRESS_LEADING which specifies that the field is to be 


drawn without leading. 
value either the numeric editable value or the index of the trailer text 
width the character width of the field ignoring the separator 
hWidth the pixel width of the field in pixels ignoring the separator: a 


subclasser need not set this 


hPos the horizontal distance in pixels of the field from the left edge of the 
lodger window: a subclasser need not set this 


separator the optional separator character that appears to the right of the 
editable value/trailer text: the separator is ignored if 
MFNE_SUPPRESS_SEPARATOR is set in flags 


limits the upper and lower limits for the value member: the elements 
should be accessed using the mrnE_UPPER and MFNE_LOWER symbolic 
constants. For a trailer field these should be set to one and zero 
respectively. 


9 NUMERIC EDITORS 


77 eS a eee ery 
MFNE methods 


WN KEY Handle key press 


INT wn_key(INT code, INT modifiers) ; 


Handle a keypress. 


The return value will be ww_KEY_No_cHance whenever: 


the editable value is selected and the keypress is either a left arrow, a right arrow, a tab ora space. 
When there is more than one field the effect of any of these keys is move the current field, and 
hence the highlight, to the left, or to the right, by one field. 


the MFNE_stcNeD flag is not set for the first field, the editable value is not selected (mfne selected 
is FALSE), the cursor is not in the leftmost position, and the keypress is a plus or a minus key. The 
keypress has no effect. 


the MFNE_SIGNED flag is not set for the first field, the editable value is selected, the MFNE_SIGNED 
field £1ag is not set in the current field and the keypress is a plus or a minus key. The keypress has 
no effect. 


The return value will be w_KEY_CHANGED whenever: 


there is only one field, the editable value is not selected and the keypress is a right arrow, a left 
arrow, a tab or a space. The effect of any of these keypresses is to select the editable value thus 
highlighting the field. 


there is only one field and the keypress is a full stop or a comma. If the editable value is selected 
the effect of the full stop (comma) keypress is to increment (decrement) the current value of the 
current field. Otherwise the effect of either keypress is to select the editable value thus 
highlighting the current field. 


the current field is a trailer field and the keypress corresponds to the first character of one of the 
two alternative trailer text strings. The effect of the keypress is to toggle the trailer text. 


The return value will be ww_KEY_CHANGED_DEFER whenever: 


there is more than one field, the editable value is selected, and the keypress is a right arrow, a left 
arrow, a tab or a space. The effect of the key is to move the current field by one field to the right 
(or to the left in the case of the left arrow). 


there is more than one field and the keypress is a full stop or a comma. The effect of the key is to 
increment or decrement respectively the current value: if the result is out of range then it is reset 
to the nearest limit. 


the current field is not selected, the cursor is currently in the leftmost position (cpos is zero) and 
the keypress is the plus key or the minus key. Sets the sign of the value member of the current 
field according to the keypress. 


the current field is selected, does not have the MrnE_sIGNeED flag set in its flags member, the 
keypress is a plus or minus key, and the mrwe_siGNep flag is set in the flag member of the first 
field. The effect of the keypresses is to set the sign of the value member of the first field 
according to the keypress. 


the current field is not selected, the cursor is not in the leftmost position (cPos is not zero), the key 
press is a plus or a minus, and the Mrne_stenep flag is set in the flag member of the first field. The 
effect of the keypresses is to set the sign of the value member of the first field according to the 
keypress. 


the current field is not selected and the keypress is either delete left (w_kKEY_DELETE_LEFT) or 
delete right (w_KEY_DELETE_RIGHT). Unless the cursor position is zero, the character at the current 
position will be replaced with a numeric space, and the cursor positon decremented by one. Note 
that for a trailer field the cursor position is always zero. 


the current field is selected and the keypress is either delete left (w_KEY DELETE LEFT) or delete 
right (W_KEY_DELETE_R1GHT). The effect of either keypress is to reset the current field index to the 
preceding field (mfne.cFie1d is decremented), or, if the current field index is zero, reset the 


9-5 


HWIM REFERENCE 


current field index to the rightmost field. If the cursor position is not zero, the character at the 
current cursor position is replaced by a numeric space and the cursor positon is decremented. 


Note that the wN_KEY_CHANGED_DEFER flag includes the wn_KEY_CHANGED flag: thus 
WN_KEY_CHANGED_DEFER&WN_KEY_CHANGED would give wN_KEY_CHANGED. 


Note also that the while the control key is held down the full stop and comma keys increment/decrement by 
ten units rather than one. 


In all cases the mfne . changed property is set to TRUE if the keypress modified the content or the appearance 
of the editable value. 


VOID wn_draw (VOID) ; 


Draw the current editable value. 


If the PR_WIN_EMPHASISED flag is set in win. flags, and mfne. selected is TRUE, draws the current field as 
white text on a black background. 


If the pR_wIN_EMPHASISED flag is set in win. flags, and mfne. selected is not TRUE, draws a cursor in the 
current field. 


Otherwise draws the editable value with no cursor and no highlight. 


Note that the text string pointed to by mine .dstr is not updated before it is drawn. To update and draw the 
text string the 1g_self_check method should be called instead. 


VOID wn_set (VOID) ; 


Set mfe.selected to TRUE, make a direct call to the 1g_se1f_check method with an argument of rRuE and 
evaluate mnfe.totWidth. 


The method calls p_leave with an argument of &_cEN_arc if the lower limit of any field exceeds its upper 
limit. 


VOID wn_emphasise(UINT flag); 
If £1ag is TRUE emphasize the control, otherwise de-emphasise the control. 


If £1ag is TRUE, emphasises the control by oRing PR_WIN_EMPHASISED into win. flags and setting the 
current field index to zero. 


Otherwise, clears pR_WIN_EMPHASISED in win. flags, and erases the cursor. 


In both cases an LG_DRaw message is sent before the method returns. 


LG_SENSE_ WIDTH 


INT lg_sense_width(VOID) ; 


Return the width in pixels required to draw the lodger window. 
The code is effectively: 


return (mnfe.totWidth*SYSTEM_FONT_NUM_WIDTH) ; 


Validate the current number 


INT lg_self_ check (INT can_defer) ; 


Validate each field and then update and draw the text string representing the editable value. 


9-6 


9 NUMERIC EDITORS 
—_————————S SSS NU MENE EDITORS 


The following conditions must be satisfied: 


e the vaiue member of each field must lie within the specified limits. A value member that is out of 
range is reset to the nearest limit. 


e the value member of each field must be greater than or equal to the value member of the previous 
field whenever that field has the mrne_seTs next flag set in its £1ags member. A value member 
that fails this condition is reset to the value member of the previous field. 


e the value member of each field must be less than or equal to the value member of the next field 
whenever that field has the mrwe_seTs_prev flag set in its £1ags member. A value member that 
fails this condition is reset to the value member of the next field. 


If the above conditions are satisfied and méne. changed is FALSE, the method returns LG_CHECK_OK. 
If the above conditions are satisfied and mfne.. changed is TRUE, the method returns LG_CHECK_OK_CHANGED. 


If one or more of the above conditions is not satisfied, and can_defer is TRUE, the method returns 
LG_CHECK_OK_CHANGED. 


Otherwise if one or more of the above conditions is not satisfied, the method makes a direct call to the 
mf_xange_beep method and then returns LG_CHECK_FAILED_CHANGED. 


In all cases the method updates and draws the text string representing the editable value. 


MF_RANGE BEEP = Showrrange iri 


VOID mf_range_beep (VOID) ; 


Give a warning beep and present the following message - "Out of range - reset to limit". 


HWIM REFERENCE 


MFNE subclass examples 


A basic subclass 


The peo class is provided as a simple illustration of the subclassing of the mrwe class. It is typical of the 
numeric editor classes described later in this chapter. 


The pemo control presents an offset followed by three characters that indicate whether the offset is relative 
or absolute. An example of a pemo control used as a dialog component is shown in the following pictures: 


Write to file { Write to file 
- Name Dump.dmp 


¢ Internal+ : Disk Internal 
'Fromoffset 1688 ‘Fromoffset 1880 
‘To offset 1286 Abs 'To offset 206 Rel 


The peno class is defined in a category file as follows: 


CLASS demo mfne ? 
{ \ 
ADD wn_init 
REPLACE wn_set 
REPLACE wn_sense 


} 


The initial appearance of the control is specified in the resource file by the following control resource: 


RESOURCE CONTROL demo_control_res /* demo control resource */ 
{ 
flags=DLGBOX_ITEM_APPL_CAT; 
class=C_DUMO; 
prompt="To offset"; 
info=LNCEDIT 
{ 
low=0; 
high=65535; 
current=10; 


}; 
(The tnceprr struct is used for convenience.) 


The fields are initialised and property set in the wn_init method as follows (the wn_init method is called 
from within the pucBox class, before the dialog a1_dyn_init method ): 


METHOD VOID demo_wn_init(PR_DEMO *self,IN_LNCEDIT *pin_Incedit, PR_LWIN *landlord) 
{ 
/* general settings */ 
self->lodger.landlord=landlord; 
self->mfine.selected=FALSE; 
self->mfne.cField=1; 
self->mfne.nField=2; 


/* in a 'real' application, trailing text would be read from a resource file */ 
p_scepy (&self->mfne.trail [0] [0], "Abs"); 
Pp_scpy (&self~->mfne.trail [1] [0],"Rel"); 


/* settings for first field */ 

self->mfne.f[0] .flags=MFNE_LEFT ALIGN; 
self->mfne.f [0] .value=pin_ncedit->value; 
self->mfne.f [0] .limits [MFNE_LOWER] =pin_ncedit->low; 
self->mfne.f[0] .limits [MFNE_UPPER] =pin_ncedit->high; 
self->mfne.f [0] .width=5; 
self->mfne.f£[0].separator=' '; 


9 NUMERIC EDITORS 
NUMERIC EDITORS 


/* settings for second field */ 

self->mfne.f [1] . flags=MFNE_TRAILER|MFNE_SUPPRESS_SEPARATOR|MFNE_SUPPRESS LEADING; 
self->mfne.f[1] .value=0; 

self->mfne.£ [1] .limits [MFNE_LOWER] =0; 

self->mfne.f [1] .limits (MFNE_UPPER] =1; 

self->mfne.f [1] .width=3; 


p_supersend2 (self,O_ WN_SET); 


} 
The contents of the control are set and sensed as follows: 


METHOD VOID demo_wn_set (PR_DEMO *self,SE DEMO *pset) 


{ 


if (pset->flags&SE_DEMO_VALUE_LONG) 
mfne.f [0] .value=pset->value_long; 

if (pset->flags&SE_DEMO_VALUE_TRAILER) 
mfine.£ [1] .value=pset->value_trailer; 

p_supersend2 (self,0_WN_SET) ; 


METHOD VOID demo_wn_sense(PR_DEMO *self,SE DEMO *psense) 


{ 


psense->value_long=mfne.f [0] .value; 
psense->value_trailer=mfne.f [1] .value; 


} 
where the sE_pEno struct is defined as follows: 


typedef struct 


{ 


LONG value_long; 
LONG value_trailer; 


} 
Extended range date editor control 


The pate class is provided as an illustration of the subclassing of the mene class and is somewhat more 
complex than the pEmo class described above. 


The patE control presents an editable date consisting of the day, the month and the year and improves on 
the preprr control by providing a wider range of allowed dates. Whereas preprr is restricted to an earliest 
displayable date of 01/01/1980, the pars class can display dates in the range 01/01/1900 to 31/12/2154 
inclusive. An example of a pare control used as a dialog component is shown in the following picture: 


( Current date 


pay 6271988 


Note that an application which wishes to use the pars class must declare the class number by including the 
following line in its .re file: 


_C_DATE 


As the use of the pare class is non-trivial, the C SDK disks include an example application, installable into 
a \sibosdk\hwimdemo\ directory, which uses the pate class. 


The example dialog shown above may be defined using the following resource: 


RESOURCE DIALOG date_dl_res 
{ 
title="Current date"; 
flags=DLGBOX_NOTIFY_ENTER; 
controls= 
{ 
CONTROL 
{ 
class=C_DATE; 
flags=DLGBOX_ITEM_CENTRE|DLGBOX_ITEM_APPL_CAT; 
} 
}; 


HWIM REFERENCE 


The piGsox_1TEm_appi_cart flag indicates that the pare class is supplied by the application. 
The parte class is defined as follows: 


CLASS date mfne 


{ 

REPLACE wn_init 
REPLACE wn_set 
REPLACE wn_sense 
REPLACE lg_self_check 
PROPERTY 


{ 
WORD dType; 
UINT day; 
UINT month; 
UINT year; 
ULONG max; 
} 

} 


The significance of the above property is as follows: 

aType may contain one of the following values: 
E_DATE_EUROPE - specifies that the date is displayed as day, month and year. 
E_DATE_USA - specifies that the date is displayed as month, day and year. 
E_DATE_JAPAN  - specifies that the date is displayed as year, month and day. 
This property is set by the wn_init method. 

day specifies the index of the field which displays the current day. 

month specifies the index of the field which displays the current month. 

year specifies the index of the field which displays the current year. 


max specifies the maximum allowed date in days elapsed since 1/1/1900. This property is set by the 
wn_init method. 


The fields are initialised and property set in the wn_init method, as follows (the wn_init method is called 
from within the picBox class, before the dialog 41_dayn_init method ): 


LOCAL _C VOID InitField(PR_DATE *self,UINT i,LONG val,LONG min,LONG max, UBYTE width) 
{ 
self->mfne.f [i] .value=val; 
self->mfne.f [i] .limits [MFNE_LOWER] =min; 
self->mfne.f[i] .limits [MFNE_UPPER) =max; 
self->mfne.f [i] .width=width; 


} 


LOCAL_C VOID DayMonthYear(PR_DATE *self,INT i,INT j,INT k) 
{ 
self->date.day=i; 
self->date.monthsj; 
self->date.year=k; 


} 


9 NUMERIC EDITORS 
SO NUMERIC EDITORS 


#pragma METHOD_CALL 


METHOD VOID date_wn_init (PR_DATE *self,VOID *par,PR_WIN *landlord) 
{ 
P_DAYSEC ds; 
P_DATE dt; 
E_CONFIG cfg; 


p_getctd(&cfg) ; 

self->lodger.landlord=landlord; 

self->mfne.selected=FALSE; 

self->mfne.changed=FALSE; 

self->mfne.cField=0; 

self->mfne.nField=3; 

self->mfne.f£[0] .separator=cfg.dateSeparator; 

self->mfne.f [1] .separators=cfg.dateSeparator; 

self~>mfne.f [2] .flags=MFNE_SUPPRESS_ SEPARATOR; 

self->date.dType=cfg.dateType; 

if (self->date.dType==E_DATE EUROPE) 
DayMonthYear(self,0,1,2); 

else if (self->date.dType==E_DATE_USA) 
DayMonthYear (self,1,0,2); 

else if (self->date.dType==E_DATE_JAPAN) 
DayMonthYear (self,2,1,0); 

InitField (self, self->date.day,1,1,31,2); 

InitField(self,self->date.month,1,1,12,2); 

InitField (self, self->date.year,1,1900,2154,4); 

dt.year=254; 

dt .month=11; 

dt .day=30; 

dt. hour=dt .minute=dt.second=dt .yrday=0; 

p_dttods (&dt, &ds) ; 

self->date.max=ds.day; 


} 


The contents of the control are set and sensed as follows: 


METHOD VOID date_wn_set (PR_DATE *self,ULONG *par) 
{ 
P_DAYSEC ds; 
P_DATE dt; 


ds.day=*par; 
ds.sec=0; 
if (ds.day>self->date.max) 

ds .day=self->date.max; 
p_dstodt (&ds, &dt) ; 
self->mfne.f[self->date.day].value=dt-day+1; 
self->mfne.f[self->date.month] .value=dt.month+1; 
self->mfne.f[self->date.year] .value=dt.year+1900; 
p_supersend2 (self,O_WN_SET) ; 


METHOD VOID date_wn_sense(PR_DATE *self,ULONG *par) 
{ 
P_DATE at; 
P_DAYSEC ds; 


dt .second=0; 

dt.minute=0; 

dt .hour=0; 

dt .day=self->mfne.f ({self->date.day] .value-1; 

dt .month=self->mfne.£ [self->date.month] .value-1; 
dt .year=self->mfne.f [self->date.year] .value-1900; 
p_dttods (&dt, &ds) ; 

*parsds.day; 


} 


HWIM REFERENCE 


The validity of the current date is checked as follows: 


METHOD INT date_lg_self_check(PR_DATE *self,INT can_defer) 
{ 
INT ret; 
INT days; 


xet=p_supersend3 (self,O LG SELF CHECK, can_defer) ; 
if ((can_defer==FALSE) && (ret==LG_CHECK_OK_CHANGED) ) 
{ 
days=p_dayinm( (INT) self->mfne.f {self->date.year] .value-1900, 
(INT) self->mfne.f [self->date.month]) .value-1) ; 
if (self->mfne.f[self->date.day] .value> (LONG) days) 
{ 
hBeep () ; 
self->mfne.cField=self->date.day; 
self->mfne.f[self->date.day] . value= (LONG) days; 
p_supersend3 (self,O_ LG SELF_CHECK, TRUE) ; 
hinfoPrint (MONTH_DAY_RESET) ; 
ret=LG_CHECK_FAILED CHANGED; 
} 
} 


return (ret) ; 


} 


The MONTH_DAY_RESET resource used by the 1g_self_check method is defined as follows: 


RESOURCE STRING month_day_reset 
{ 


str="Day exceeds days in month: reset"; 


} 


The dialog resource shown above may be used with the following parepLc example dialog class: 


CLASS datedlg dlgbox 


{ 


REPLACE dl_item_new 
REPLACE dl_dyn_init 
REPLACE dl_key 


} 


An instance of the pate class is created by the d1_item_new method as follows: 


METHOD VOID *datedlg_dl_item_new(PR_DATEDLG *self,AD_DLGBOX *par) 


{ 


return (f_new(CAT_DAT_DAT,par->class)); 


} 


The dialog is dynamically initialised and its contents sensed before closing using the d1_ayn_init and 
dl_key methods as follows: 


METHOD VOID datedlg_dl_dyn_init(PR_DATEDLG *self) 


{ 


P_DAYSEC ds; 


p_send4(((PR_DATWIN *)w_ws->wserv.cli) - 
>datwin.time,O TO SENSE, SENSE_TIME_DAYSEC, &ds) ; 
p_send4 (self,O_WN_SET,1,&ds.day) ; 


} 


METHOD INT datedlg_dl_key(PR_DATEDLG *self,INT index,INT keycode) 
{ 
P_DAYSEC ds; 
PR_DATWIN *cli; 


p_send4 (self,O_WN_SENSE,1, &ds.day) ; 

ds.sec=0; 

cli=(PR_DATWIN *)w_ws->wserv.cli; 

£_leave (p_send4 (cli->datwin.time,O_TO_SET,SET_TIME_DAYSEC, &ds) ); 
return (WN_KEY CHANGED) ; 


9 NUMERIC EDITORS 


Se ee eee eee 


LNCEDIT 
a 


flags landlord 
i offset 
width 


selected 
cField 
nField 
totWidth 
cPos 
changed 
eStr 
dstr 
trail 

£ 


dese} 
wn_calc_ position 
wn_connect 

wn_dodraw 


destroy 
—ind 


wn_visible 
1g_draw 


wn_key 
wn_draw 
VECSGE 
wn_emphasise 
1lg_sense_width 
lg_self_check 


mf_range_beep 


lg_set_id_ pos 


wn_position 
wn_redraw 
wn_sense_help 


te-sense—width 
ig_update 


A long numeric editor control can be included in a dialog via the appropriate control resource. The 
following example would be suitable for the dialog illustrated in the above picture: 


RESOURCE DIALOG demonstration 
{ 
title="Demonstration"; 
flags=DLGBOX_NOTIFY_ENTER; 
controls= 
{ 
title="Demonstration"; 
flags=DLGBOX_NOTIFY_ENTER; 
CONTROL 
{ 
class=C_LNCEDIT; 
prompt="LONG" ; 
info=LNCEDIT 
{ 
low=1; 
high=700000; 
current=500000; 


); 


HWIM REFERENCE 


The tncenrt struct is defined in Awim.rh as: 


STRUCT LNCEDIT 


{ 


LONG current=0; 
LONG low=0; 
LONG high=10000000; 


} 
Thus the example long numeric editor contro] has replaced the values assigned to the current, low and 
high members. 
Class definition 
Defined in sub-category file ncedit.cl (generated header file ncedit.g). 


CLASS lncedit mfne 
Single field long numeric editor 


{ 


REPLACE wn_set set data 
REPLACE wn_sense sense value 
REPLACE wn_init initialise editor 
CONSTANTS 
{ 
SE_LNCEDIT_VALUE 0x02 
SE_LNCEDIT_LOW 0x02 
SE_LNCEDIT_HIGH 0x04 
} 
TYPES 


{ 


typedef struct 
{ 
LONG value; 
LONG low; 
LONG high; 
} IN_LNCEDIT; 
typedef struct 
{ 
LONG value; 
LONG low; 
LONG high; 
UWORD flags; 
} SE_LNCEDIT; 


} 


Property 
There is no property associated with the tyceprrt class. 


LNCEDIT methods 


VOID wn_init (IN_LNCEDIT *init,PR_WIN *landlord) ; 


Initialise the long numeric editor from the In_LNcEDIT struct pointed to by init, and write landlora, the 
handle of the owning landlord window, to ledger. landlord. 


The In_LNCEDIT struct is defined as follows: 


typedef struct 
{ 
LONG value; 
LONG high; 
LONG low; 
} IN_LNCEDIT; 


9 NUMERIC EDITORS 


The members of the 1In_tnceprt struct have the following significance: 


value the initial value for the editable Lonc. 
high the upper limit for the editable ton. 
low the lower limit for the editable Lonc. 


SET ee oe | . Set data 


= alle 


VOID wn_set (SE_LNCEDIT *set) ; 
Set the long numeric editor according to the content of the sz_LNcEDIT struct pointed to by set. 
The se_incep1T struct is defined as follows: 


typedef struct 
{ 
LONG value; 
LONG high; 
LONG low; 
UWORD flags; 
} SE_LNCEDIT; 


The setting is controlled by oring one or more of the following flags into the £1ags member of the 
SE_LNCEDIT struct 


SE_LNCEDIT_VALUE indicates that the editable value is to be set 
SE_LNCEDIT_HIGH indicates that the upper limit is to be set 
SE_LNCEDIT_LOW indicates that the lower limit is to be set 


VOID wn_sense (LONG *sense) ; 


Write the current value of the long numeric editor to the Lone pointed to by sense. 


HWIM REFERENCE 


NCEDIT 


flags landlord selected 
i offset cPield 

width nField 

totWidth 
cPos 
changed 
eStr 
dStr 
trail 
£ 


wn_calc_position 
wn_connect 
wn_dodraw 


destroy 
—tnd 


wn_visible 
lg_draw 


wn_key 
wn_draw 
wh—set 
wn_emphasise 
lg_sense_width 
1g_self_check 


mf£_range_beep 


lg_set_id_pos 


wn_position 
wn_redraw 
wn_sense_help 


igsesse dekh 


lg_update 


The unsigned word numeric editor presents an editable value of type uworp as illustrated in the following 
picture: 


Position to-do entry 


| 


An unsigned word numeric editor control can be included in a dialog via the appropriate control resource. 
The following example would be suitable for the dialog illustrated in the above picture: 


RESOURCE DIALOG demonstration 
{ 
title="Position to-do entry"; 
flags=DLGBOX_NOTIFY_ENTER; 
controls= 
{ 
CONTROL 
{ 
class=C_NCEDIT; 
prompt="Position within list"; 
info=NCEDIT 
{ 
low=1; 
high=100; 
current=1; 


}; 


9 NUMERIC EDITORS 
—_. EF NUMERIC EDITORS: 


The ncep1r struct is defined in Awim.rh as: 


STRUCT NCEDIT 


{ 


UWORD current=0; 
UWORD low=0; 
UWORD high=65535; 


} 


Thus the example unsigned word numeric editor control (see above) has replaced the values assigned to the 
current, low and high members. 


Class definition 
Defined in sub-category file ncedit.cl (generated header file ncedit.g). 


CLASS needit Incedit 
Single field unsigned word numeric editor 
{ 
REPLACE wn_set 
REPLACE wn_sense 
REPLACE wn_init 


CONSTANTS 
{ 
SE_NCEDIT_VALUE 0x01 
SE_NCEDIT_LOW 0x02 
SE_NCEDIT_HIGH 0x04 
} 

TYPES 


{ 


typedef struct 


{ 


UWORD value; 
UWORD low; 
UWORD high; 
} IN_NCEDIT; 
typedef struct 


{ 


UWORD value; 
UWORD low; 
UWORD high; 
UWORD flags; 
} SE_NCEDIT; 


} 


Property 
There is no property associated with the nceprr class. 


ht a er a ares 
NCEDIT methods 


Initialise 


VOID wn_init(IN_NCEDIT *init,PR_WIN *landlord) ; 


Initialise the unsigned word numeric editor from the 1n_nceprT struct pointed to by init, and write 
landlord, the handle of the owning landlord window, to 1odger. landlord. 


The IN_NcEDIT struct is defined as follows: 


typedef struct 
{ 
UWORD value; 
UWORD low; 
UWORD high; 
} IN_NCEDIT; 


HWIM REFERENCE 


The members of the 1n_NcEprT struct have the following significance: 


value the initial value for the editable uworp 
high the upper limit for the editable uworp 
low the lower limit for the editable uworp 


=F — : | Set new values 


VOID wn_set(SE_NCEDIT *set) ; 
Set the unsigned word numeric editor according to the content of the s=_nceprT struct pointed to by set. 
The se_NceEn1T struct is defined as follows: 


typedef struct 
{ 
UWORD value; 
UWORD high; 
UWORD low; 
UWORD flags; 
} SE_NCEDIT; 


The setting is controlled by oring one or more of the following flags into the £1ags member of the 
SE_NCEDIT struct: 


SE_NCEDIT_VALUE indicates that the editable unsigned word is to be set 
SE_NCEDIT_HIGH indicates that the upper limit of the editable unsigned word is to be set 
SE_NCEDIT_LOW indicates that the lower limit for the editable unsigned word is to be set 


VOID wn_sense(UWORD *sense) ; 


Write the current value of the editable unsigned word to the uworp pointed to by sense. 


9 NUMERIC EDITORS 


WNCEDIT 


landlord selected 

offset cField 

width nField 
totWidth 
cPos 
changed 
eStr 
dsStr 
trail 
£ 


destrey destroy wn_key 


wn_cale_ position wh-init wn_draw 


wn_connect wn_visible wn—set 


wn_dodraw lg_draw wn_emphasise 


tg—selfi—cheek lg_sense_width 
lg_set_id_pos lg_self_check 
wn_position mf_range_beep 
wn_redraw 
wn_sense_help lg_update 


A word numeric editor control can be included in a dialog via the appropriate control resource. The 
following example would be suitable for the dialog illustrated in the above picture: 


RESOURCE DIALOG demonstration 
{ 
title="Montreal"; 
flags=DLGBOX_NOTIFY_ENTER; 
controls= 
{ 
CONTROL 
{ 
class=C_WNCEDIT; 
prompt="Temperature"; 
info=WNCEDIT 
{ 


current=-100; 


3 


}; 
} 


The wnceptT struct is defined in hwim.rh as: 


STRUCT WNCEDIT 
{ 
WORD current=0; 
WORD low=-32768; 
WORD high=32767; 


} 


HWIM REFERENCE 
ee 


Thus the example word numeric editor control (see above) has replaced the value assigned to the current 
member. 


Class definition 
Defined in sub-category file ncedit.cl (generated header file ncedit.g). 


CLASS wnecedit Incedit 
Single field word numeric editor 
{ 
REPLACE wn_set 
REPLACE wn_sense 
REPLACE wn_init 


CONSTANTS 
{ 
SE_WNCEDIT_VALUE 0x01 
SE_WNCEDIT_LOW 0x02 
SE_WNCEDIT_ HIGH 0x04 
} 

TYPES 


{ 


typedef struct 
{ 
WORD value; 
WORD low; 
WORD high; 
} IN_WNCEDIT; 
typedef struct 
{ 
WORD value; 
WORD low; 
WORD high; 
WORD flags; 
} SE_WNCEDIT; 


} 


Property 
There is no property associated with the wnceprr class. 


Sa a ee ee ee ee a ee) 
WNCEDIT methods 


Initialise 


VOID wn_init(IN_WNCEDIT *init,PR_WIN *landlord) ; 


Initialise the signed word numeric editor from the 1n_wnceD1T struct pointed to by init, and write 
landlord, the handle of the owning landlord window, to 1odger . landlord. 


The In_wnczpzT struct is defined as follows: 


typedef struct 
{ 
WORD value; 
WORD low; 
WORD high; 
} IN_WNCEDIT; 


The members of the 1n_wncen1T struct have the following significance: 


value the initial value for the editable worp 
high the upper limit for the editable worp 
low the lower limit for the editable worp 


9 NUMERIC EDITORS 
—_——oe moe ENG EDITORS 


Set new values 


VOID wn_set(SE_WNCEDIT *set) ; 
Set the signed word numeric editor according to the content of the se_wnceprr struct pointed to by set. 
The sE_wNceptr struct is defined as follows: 


typedef struct 
{ 
WORD value; 
WORD high; 
WORD low; 
WORD flags; 
} SE_WNCEDIT; 


The setting is controlled by oring one or more of the following flags into the £1ags member of the 
SE_WNCEDIT struct: 


SE_WNCEDIT_VALUE indicates that the editable value is to be set 
SE_WNCEDIT_HIGH indicates that the upper limit is to be set 
SE_WNCEDIT_LOW indicates that the lower limit is to be set 


WNSENSE —— Sunes Kawwalie 


VOID wn_sense(WORD *sense) ; 


Write the current value of the editable signed word to the worn pointed to by sense. 


HWIM REFERENCE 


DTEDIT 


flags landlord selected cal 

i offset cField dType 

width nField changed 
totWidth inSelfCheck 
cPos in 

changed 
eStr 
dstr 
trail 
£ 


destrey 


destroy wn_key wn_set 


wn_calc_position wh-init wn_draw wn_sense 

wn_connect wn_visible wh-set wn_init 

wn_dodraw lg_draw wn_emphasise wn_emphasise 
ig—self—eheek lg_sense_width wn_key 


ig_set_id_pos 


lg_self_check 


wn_position 
wn_redraw 
wn_sense_help 


mf£_range_beep 


ig-sense—vidés 


ig_update 


(Set time and date 
[4:28:03 pm 
tDate 1171871993 


A date/time numeric editor control can be included in a dialog via the appropriate control resource. The 
following example would be suitable for the dialog illustrated in the above picture: 


9 NUMERIC EDITORS 
__ OO NUMERIC EDITORS 


RESOURCE DIALOG demonstration 


{ 


title="Set time and date"; 
flags =DLGBOX_NOTI FY_ENTER; 
controls= 


{ 


CONTROL 


{ 


class=C_DTEDIT; 
prompt="Time" ; 
info=DTEDIT 


{ 


flags=IN_DTEDIT_HHMMSS; 
}i 
} ‘ 


CONTROL 


{ 


class=C_DTEDIT; 
prompt="Date"; 
info=DTEDIT 


{ 
flags=IN_DTEDIT_DDMMYyyy; 


}i 


}; 
} 


The preprr resource struct is defined in hwim.rh as: 


STRUCT DTEDIT 


{ 

WORD flags; 
LONG current; 
LONG low; 
LONG high; 


} 


The example date/time numeric editor controls do not set initial values for the current, low and high 
members, but merely set appropriate values for f1ags. Note that any supplied values of current, low and 
high will only be used to initialise the control if the value rv_preprt_tntT is set in f1ags. If this value is 
not present, any values specified in the initialisation resource are ignored and the control is initialised with 
a set of standard values based on the current time and date. 


The format of the display is controlled on initialisation by setting one of the following flags into the flags 
member of the preprr struct: 


IN_DTEDIT_DDMMYYyy initialise as a date editor to display a date in day, month and year format: 
the current date is specified as days elapsed since 1/1/1900. 


IN_DTEDIT_HHMMSS initialise as a time editor to display a time as hours, minutes and seconds. 
The current time is specified in seconds elapsed since midnight. 


IN_DTEDIT_HHMM initialise as a time editor to display a time as hours and minutes. The 
current time is specified as seconds elapsed since midnight. 


IN_DTEDIT_HHMMSS_D initialise as a time editor to display a duration as hours, minutes and 
seconds. The current duration is specified in seconds. 


IN_DTEDIT_HHMM_D initialise as a time editor to display a duration as hours and minutes. The 
current duration is specified in seconds. 


IN_DTEDIT_HHMMSS_ND initialise as a time editor to display a negative duration as hours, minutes 
and seconds. The current duration is specified in seconds. 


IN_DTEDIT_HHMM_ND initialise as a time editor to display a negative duration as hours and 
minutes. The current duration is specified in seconds. 


Note: on the Series 3a version of the preprt class the user may select the required date by pressing the Tab 
key to obtain a calendar view. (The calendar view is implemented by the canwrn class.) This is especially 
convenient for selecting, for example, the first Monday in a given month. 


HWIM REFERENCE 
eee 


Class definition 
Defined in sub-category file dtedit.cl (generated header file dtedit.g). 


On the Series 3a the class definition is as follows: 


CLASS dtedit mfne 
Date, Time and Duration editor based on the MFNE. 
{ 
REPLACE wn_set 
REPLACE wn_sense 
REPLACE wn_init 
REPLACE wn_emphasise 
REPLACE 1g_self_check 
REPLACE wn_key 


CONSTANTS 

{ 

SE_DTEDIT_VALUE 0x01 
SE_DTEDIT_LOw 0x02 
SE_DTEDIT_HIGH 0x04 
PR_DTEDIT_DATE 0x0000 
PR_DTEDIT_TIME 0x0100 
PR_DTEDIT_DURATION 0x0200 
PR_DTEDIT_SECONDS ox1000 
PR_DTEDIT_ NEGATIVE 0x2000 
PR_DTEDIT_AMPM 0x4000 


PR_DTEDIT_NEG_DURATION (PR_DTEDIT_DURATION|PR_DTEDIT NEGATIVE) 


IN_DTEDIT_INIT (SE_DTEDIT_VALUE | SE_DTEDIT_LOW|SE_DTEDIT_HIGH) 
IN_DTEDIT_DDMMYYYY (PR_DTEDIT_DATE) 

IN_DTEDIT_HHMMSS (PR_DTEDIT_TIME|PR_DTEDIT_SECONDS) 

IN_DTEDIT_HHMM (PR_DTEDIT_TIME) 

IN_DTEDIT_HHMMSS_D (PR_DTEDIT_TIME|PR_DTEDIT_DURATION|PR_DTEDIT_ SECONDS) 
IN_DTEDIT_HHMM_D (PR_DTEDIT_TIME|PR_DTEDIT_DURATION) 


IN_DTEDIT_HHMMSS_ND 
(PR_DTEDIT_TIME|PR_DTEDIT_NEG_DURATION|PR_DTEDIT_SECONDS) 
IN_DTEDIT_HHMM_ND (PR_DTEDIT_TIME|PR_DTEDIT_NEG DURATION) 


} 


TYPES 


{ 


typedef struct 
{ 
UWORD flags; type of edit box 
LONG value; 
LONG low; 
LONG high; 
} IN_DTEDIT; 
typedef struct 
{ 
UWORD flags; 
LONG value; 
LONG low; 
LONG high; 
} SE_DTEDIT; 


} 


PROPERTY 1 
{ 
VOID *cal; 
WORD dType; 
UBYTE changed; 
UBYTE inSelfCheck; 
IN_DTEDIT in; 
} 
} 


On the Series 3 the class definition differs in that: 


e the wn_emphasise and wn_key methods are not replaced. 


9 NUMERIC EDITORS 


e the dtedit.cai property is absent. 


Property 

dtedit.cal this is either the handle of an instance of the canwrn class or NuLL. The caLwIn 
object provides a graphical calendar view. 
Note:on the Series 3 this item of property is absent. 

dtedit.dType specifies the system date format: may be one of either = pare _evRopE for 
day/month/year, &_paTe_usa for month/day/year or E_DATE_JAPAN for 
year/month/day. 

dtedit.changed see the description of the w_sense and 1g_self_check methods. 


dtedit.inSelfCheck not used. 


dtedit.in an IN_DTEDIT struct that contains the current editable value, the upper and 
lower limits and the initialisation flag 


he a ee SS — ee ey eee 
DTEDIT methods 


WN oe eee ees “Waiianee 


VOID wn_init(IN_DTEDIT *init,PR_WIN *landlord) ; 


Initialise the date/time numeric editor from the 1n_prep1T struct pointed to by init, and write landlord, 
the handle of the owning landlord window, to 1odger. landlord. Set dtedit .dType according to the 
current system setting. 


The In_DtTep1T struct is defined as follows: 


TYPEDEF STRUCT 
{ 
WORD flags; 
LONG current; 
LONG low; 
LONG high; 
} IN_DTEDIT; 


The members of the rn_preprr struct have the following significance: 


flags a combination of initialisation flags, as described below 
current the initial value for the editable date/time 

high the initial upper limit for the editable date/time 

low the initial lower limit for the editable date/time 


The appearance and behaviour of the date/time editor is specified by assigning one of the following flags 
into the flags member (note that the system will automatically display the time in am/pm or 24 hour format 
according to the current system settings): 


IN_DTEDIT_DDMMYYYY initialise as a date editor to display a date in day, month and year format: the 
current, low and high dates are specified as days elapsed since 01/01/1900. 
Note that the control can not display dates before 01/01/1980. 


IN_DTEDIT_HHMMSS initialise as a time editor to display a time as hours, minutes and seconds. The 
current, low and high times are specified in seconds elapsed since midnight. 
Whole days are ignored, so these values could also be supplied in system 
time format. 


IN_DTEDIT_HHMM initialise as a time editor to display a time as hours and minutes. The 
current, low and high times are specified in seconds elapsed since midnight. 
Whole days are ignored, so these values could also be supplied in system 
time format. 


HWIM REFERENCE 
See eSeeeeSeeeEeeeSeeSeSeSSSSSSSSSSSsFsFeFsFsSFSSsSSSSsSSees 


IN_DTEDIT_HHMMSS D initialise as a time editor to display a duration as hours, minutes and seconds. 
The current, low and high durations are specified in seconds. Whole days 
are ignored, so these values could also be supplied in system time format. 


IN_DTEDIT_HHMM_D initialise as a time editor to display a duration as hours and minutes. The 
current, low and high durations are specified in seconds. Whole days are 
ignored, so these values could also be supplied in system time format. 


IN_DTEDIT_HHMMSS_ND _initialise as a time editor to display a negative duration as hours, minutes and 
seconds. The current, low and high durations are specified in seconds. 
Whole days are ignored, so these values could also be supplied in system 
time format. 


IN_DTEDIT_HHMM_ND initialise as a time editor to display a negative duration as hours and minutes. 
The current, low and high durations are specified in seconds. Whole days 
are ignored, so these values could also be supplied in system time format. 


Any supplied values of current, low and high will only be used to initialise the control if the value 
IN_DTEDIT_INiT is ored into f1ags (in which case all three values must be supplied). If this value is not 
present, any values specified in the initialisation resource are ignored and the control is initialised with a set 
of standard values, dependent on the value of flags, as follows: 


IN_DTEDIT_DDMMYYYY The upper and lower limits are set to the dates 01/01/1980 and 31/12/2049 
respectively, and the current value is set to today's date. 


IN_DTEDIT_HHMMSS The upper and lower limits are set to the times 00h00m(00s) and 
IN_DTEDIT_HHMM 23h59m(59s) respectively, and the current value is set to the time of day. 
IN_DTEDIT_HHMMSS_D 

IN _DTEDIT_HHMM_D 


IN_DTEDIT_HHMMSsS_ND The upper and lower limits are set to the times -23h59m(59s) and 
IN_DTEDIT_HHMM_ND 23h59m(59s) respectively, and the current value is set to the time of day. 


VOID wn_set (SE_DTEDIT *set) ; 


_ Set new values 


Set the date/time editor according to the content of the sz_pTEprT struct pointed to by set. 
The se_preEpzT struct is defined as follows: 


typedef struct 
{ 
UWORD flags; 
LONG value; 
LONG low; 
LONG high; 
} SE_DTEDIT; 


The property to be set is indicated by oring one or more of the following flags into the £1ags field of the 
above struct. 


SE_DTEDIT_VALUE indicates that the current value is to be set. 
SE_DTEDIT_LOW indicates that the lower limit is to be set. 
SE_DTEDIT_HIGH indicates that the upper limit is to be set. 


The interpretation of the values of value, low and high in the sz_preprr struct depends on the type of data 
that the control has been initialised to display. See the explanation of the IN_DTEDIT_xxx flags in the 
description of the wm_init method. 


Sense value 


VOID wn_sense(SE_DTEDIT *sense) ; 


Write the current value of the editable date/time to the value member of the s—_preprr struct pointed to by 
sense. Note that the method does not write to sense->flags, sense->low OF sense->high. 


9-26 


9 NUMERIC EDITORS 


The interpretation of value depends on the type of data that the control has been initialised to display. See 
the explanation of the 1n_pTep1T_xxx flags in the description of the m_init method. 


If the editable value is a date, and the day is outside the allowed range, resets the day to the last of the 
month and sets dtedit . changed to FALSE, otherwise sets dtedit . changed to TRUE. 


VOID wn_key (INT keycode, INT modifiers) ; 


le a keypress 


Handle a keypress. 
If dtedit.cal is non-zero: 


e — sends the keypress to the calendar view by sending a wn_kEy message with arguments of keycode 
and modifiers. 


e if the keypress cancels the calendar view, i.e. the return value is ww_KEY_CANCELLED, removes the 
calendar view by sending a pestroy message to dtedit .cal and then writes zero to dtedit .cal. 


e — if the keypress selects the current date, i.e the return value is ww_KEY_CHANGED, senses the current 
date in the calendar view, sets this as the current date in the preprr control, removes the calendar 
view by sending a DESTRoy message to dtedit .cal and then writes zero to dtedit.cal. 


Otherwise if keycode is w_KEY_TAB and the control is not a time editor - i.e. dtedit . flags does not contain 
PR_DTEDIT_TIME - and w_ws->wserv. flags contains PR_WSERV_FULLSCREEN: 


e validates the current date in the prepzT control by sending self an LG_SELF_CHECK message and, 
if the return value is neither L¢_CHECK_OK nor LG_CHECK_OK_CHANGED, returns. 


® creates an instance of the canwin class and writes the handle to dtedit.cal. 


©  initialises the calendar view by sending a wn_1nrT message to dtedit .cal. The calendar view is 
centred. The current date is set to the current date in the prEp1T control. The number of months 
displayed is equal to twelve if modifiers contains w_CTRL_MODIFIER, three if modifiers contains 
W_SHIFT_MODIFIER, or one otherwise, 


Otherwise supersends a wN_KEY message with arguments of keycode and modifiers and returns the return 
value. 


Note: on the Series 3 this method is not replaced. 


ws 


VOID wn_emphasise (INT flag); 


Emphasise the control or calendar view if £1ag is rrug, otherwise de-emphasise the control or calendar 
view. 


If dtedit .cal is non-zero, sends a wN_EMPHASISE message to dtedit .cal with an argument of flag. 
Otherwise supersends a wN_EMPHASISE message with an argument of flag. 


Note: on the Series 3 this method is not replaced 


Validate values and fields 


INT 1lg_self_ check (VOID) ; 


Validate the current date/time and the fields. 


Supersends an LG_SELF_CHECK message and return either its return value, or alternatively -1 if either of the 
following are true: 


e the editable value is outside of the allowed limits in which case reset to its nearest limit and sends 
an MF_RANGE_BEEP message. 


© dtedit.changed is TRUE in which case sends an MF_RANGE_BEEP message. 


HWIM REFERENCE 


ae ee EE SS ee eee 
LLEDIT 


landlord selected 

offset cField 

width nField 
totWidth 
cPos 
changed 
eStr 
dstr 
trail 
£ 


destrey destroy wn_key 
wn_calc_position whoinit wn_draw 


wn_connect wn_visible wnaset 


wn_dodraw 1lg_draw wn_emphasise 
wh-emphasise te—seit—eheek ig_sense_width 
wa-key lg_set_id_pos 1g_self_check 
wn_position mf£_range_beep 
wn_redraw ig—sense—width 


wn_sense_help ig_update 


Denmark 
"Longitude 618°16E 
‘Latitude 656°H8 N 
4 ‘Area code 

‘GMT offset 1:80 
i :Zone European 


A latitude/longitude editor control can be included in a dialog via the appropriate control resource. The 
following example would be suitable for a dialog with a title and two latitude/longitude controls: 


oa 


9 NUMERIC EDITORS 


a, 


RESOURCE DIALOG demonstration 


{ 


title="Set latitude and longitude"; 
flags=DLGBOX_NOTIFY_ENTER; 
controls= 


} 


{ 
CONTROL 


{ 


class=C_LLEDIT; 
prompt="Latitude"; 
info=LLEDIT 


{ 


flags=IN_LLEDIT_LATITUDE; 
current=3368; 


}; 
}, 


CONTROL 


{ 


class=C_LLEDIT; 
prompt="Longitude" ; 
info=LLEDIT 


{ 


flags=IN_DTEDIT_LONGITUDE; 
current=33968; 


}; 
}i 


The nueprrT struct is defined in hwim.rh as: 


STRUCT LLEDIT 


{ 


WORD flags; 
WORD value=0; 


} 


The latitude/longitude value is specified in minutes of arc: a positive sign indicating a latitude/longitude in 
the northern /western hemisphere, and a negative sign indicating a latitude/longitude in the southern 
/eastern hemisphere. Thus -604 corresponds to a latitude of 10° 4 S or a longitude of 10° 4 E. 


The behaviour of a latitude/longitude editor is specified by assigning one of the following flags to the 
flags member. 


IN_LLEDIT_LATITUDE 


IN_LLEDIT_ LONGITUDE 


Class definition 


Defined in sub-category file //edit.cl (generated header file /edit.g). 


CLASS 
Latitude,Longitude editor based on the MFNE. 


lledit mfne 


REPLACE wn_set 
REPLACE wn_sense 
REPLACE wn_init 


CONSTANTS 


{ 


IN_LLEDIT_LATITUDE i) 
IN_LLEDIT LONGITUDE 1 


} 


display value as a latitude. 


display value as a longitude. 


9-29 


HWIM REFERENCE 
en eee 


TYPES 


{ 


typedef struct 


{ 

WORD flags; 

WORD value; 

} IN_LLEDIT; 
typedef struct 


{ 
WORD value; 
} SE_LLEDIT; 


} 


Property 
There is no property associated with the LuzprrT class. 


SS nS eee 
LLEDIT methods 


Initialise 


VOID wn_init(IN_LLEDIT *init,PR_WIN *landlord) ; 


Initialise the latitude/longitude editor from the 1n_LLEDIT struct pointed to by init, and write landlord, 
the handle of the owning landlord window, to 1odger. landlord. 


The 1n_LLEprT struct is defined as follows: 
typedef struct 
{ 
WORD flags; 
WORD value; 
} IN_LLEDIT; 


The behaviour of a latitude/longitude editor is specified by assigning one of the following flags to the 
flags member: 


IN_LLEDIT_LATITUDE value is to be displayed as a latitude 
IN_LLEDIT_LONGITUDE value is to be displayed as a longitude 
Note that the behaviour of a latitude/longitude editor can not be changed once it has been initialised, 


The value member of the 1n_LLEDrT struct specifies the angle in units of arc minutes. A positive sign 
indicates that the angle is either a northern latitude, or a western longitude depending on the editors 
initialisation flag. Otherwise the angle is either a southern latitude or an eastern longitude. 


_ Set new values 
VOID wn_set (SE_WNCEDIT *set) ; 


Set the current angle of the latitude/longitude editor to the value member of the SE_LLEDIT struct which is 
pointed to by set. 


The sz_LuEDIT struct is defined as follows: 
typedef struct 
{ 
WORD value; 
} SE_LLEDIT; 


See above for a description of the value member. 


9 NUMERIC EDITORS 
eee NUMERIC EDITORS 


Sense current value 


VOID wn_sense(SE_LLEDIT *sense) ; 


Write the current value of the latitude/longitude editor to the value member of the SE_LLEDIT struct 
pointed to by sense. 


The sE_LLEDIT struct is defined as follows: 
typedef struct 
{ 
WORD value; 
} SE_LLEDIT; 


See above for a description of the value member. 


RGEDIT 


landlord 
offset 
width 


selected 
cField 
nField 
totWidth 
cPos 
changed 
eStr 
dstr 
trail 

£ 


wn_calc_position 
wn_connect 
wn_dodraw 


wn_position 
wn_redraw 
wn_sense_help 


destroy 
—ins 


wn_visible 
lg_draw 


itg—seit—eheeck 
1g_set_id_pos 


lg_update 


wn_key 

wn_draw 

wh—set 
wn_emphasise 
ig_sense_width 
1g_self_check 


mf£_range_beep 


A range numeric editor control can be included in a dialog via the appropriate control resource. The 
following example would be suitable for the dialog shown in the above picture: 


HWIM REFERENCE 
eC oS 


RESOURCE DIALOG demonstration 
{ 
title="Define"; 
£lags=DLGBOX_NOTIFY_ENTER; 
controls= 
{ 
CONTROL 
{ 
class=C_RGEDIT; 
prompt="Age range"; 
info=RGEDIT 
{ 
value_1=30; 
value_2=60; 


}; 


}; 
} 


The rcpt struct is defined in hwim.rh as: 


STRUCT RGEDIT 


{ 


WORD low=1; 

WORD value_1l=1; 
WORD value_2=9999; 
WORD high=9999; 


} 


where value_1 must be not greater than value_2 and both values must be not less than low, and not greater 
than high. 


Class definition 
Defined in sub-category file rgedit.cl (generated header file rgedit.g). 


CLASS rgedit mfne 
Range editor based on the MFNE. 
{ 
REPLACE wn_set 
REPLACE wn_sense 
REPLACE wn_init 


CONSTANTS 
{ 
SE_RGEDIT_LOW 0x01 
SE_RGEDIT _VALUE_1 0x02 
SE_RGEDIT VALUE 2 0x04 
SE_RGEDIT_HIGH 0x08 
IX_RGEDIT_LOw ft) /* Indices into value */ 
IX_RGEDIT_VALUE_1 1 
IX_RGEDIT_VALUE_2 2 
IX_RGEDIT_HIGH 3 


} 


TYPES 
{ 
typedef struct 
{ 
UWORD value [4] ; 
} IN_RGEDIT; 
typedef struct 
{ 
UWORD value [4] ; 
UWORD flags; 
} SE_RGEDIT; 


} 


PROPERTY 


{ 


IN_RGEDIT in; 


9 NUMERIC EDITORS 


Property 
rgedit.in not used. 


mS ae Eee Se SS See 
RGEDIT methods 


Ogee 7 
Initialise 
VOID wn_init (IN_RGEDIT *init, PR_WIN *landlord) ; 


Initialise the range numeric editor from the 1n_RcEDIT struct pointed to by init, and write landlord, the 
handle of the owning landlord window, to 1odger landlord. 


The in_RGEp1T struct is defined as follows: 
typedef struct 
{ 
UWORD value [4]; 
} IN_RGEDIT; 


The value array is indexed as follows: 


IX_RGEDIT_LOW index of lower limit in value array. 
IX_RGEDIT_VALUE_1 index of lower current value in value array. 
IX_RGEDIT_VALUE_2 index of upper current value in value array. 
IX_RGEDIT_HIGH index of upper limit in value array. 


VOID wn_set (SE_RGEDIT *set) ; 
Set the current values in the range editor to those specified by the sz_RGEDIT struct pointed to by set. 
The sE_RGEpDIT struct is defined as follows: 

typedef struct 


{ 


UWORD value [4] ; 
UWORD flags; 
} SE_RGEDIT; 


The value array is indexed as explained above. 


The property to be set is indicated by oring one or more of the following flags into the flags field of the 
above struct. 


SE_RGEDIT_LOW indicates that the lower limit is to be set. 
SE_RGEDIT_VALUE_1 indicates that the current lower value is to be set. 
SE_RGEDIT_VALUE_2 indicates that the current upper value is to be set. 
SE_RGEDIT_HIGH indicates that the upper limit is to be set. 


Sense new value 
VOID wn_sense(SE_RGEDIT *sense) ; 
Write the current values and the limits of the range editor to the sE_RGEDIT struct pointed to by sense. 


The sE_RGeprT struct is defined above. 


CHAPTER 10 


TEXT EDITORS 


This chapter documents the text editor classes. These classes are: 


EDWIN The superclass for the majority of text editor windows. It is a lodger window that 
provides a wide range of facilities for the formatted display of editable text. 

FLTEDIT A dialog control that allows the user to edit a floating point number. 

PUNCTUED A dialog contro] that allows the user to select a punctuation character. 

XEDIT A dialog control allowing secret text entry - a password, for example. 

Precursors 


Familiarity with the following topics will aid the understanding of this chapter: 
e the wrn and Lopcer classes described in the Windows chapter, 
e the Eppoc and Eprpoc classes described in the FORM Reference manual, 
e the scriay and scric classes described in the FORM Reference manual, 
e use of the Series 3 Word application. 


Class diagram 


‘ 
win ; 
a f 
Lae 
as 
1 iaenancat 
ow 
i re 
7 Am 
or ~ f iB 
~~ a 
pA I is oA ‘ 
é ‘a 4 pone 
SN. t % ie 
~~ 1 od 
; ons 
ae eee j ON 
1 ? 
ie / gerlay ~} 
af i 
SAL 1 
> : 
Paeics ane poker 
ae Fy . a 
/ xedit > 2 edwin > poe len 
PS 1 os Ope ot 7 do Cc 
x ' ~ v2 ’ 
+ es s ‘ t 
Mee feet x > : 
= Mabe : 
Pao ee A gas” on 
’ i> . 
/ punctued * / fitedit > 
vA if if if 
4 A ‘ 


. l ~ . 


The document class doc may be (a subclass of) either of the FORM classes Eprpoc or EPDOC, or it may be 
an application-specific class that is compatible with these classes. See the Formatted Document Classes 
chapter of the FORM Reference manual for further details. 


10-1 


HWIM REFERENCE 


wn_calc_position 
wn_connect 
wn_dodraw 


wn_position 
wn_redraw 


landlord 
offset 
width 


destrey 
wn_visible 
1lg_draw 
1g_self_check 


lg_update 


scrimg 
scrlay 
doc 
cpos 
clen 
clip 


destroy 
wn_init 
wn_key 


wn_draw 
wn_sense_help 
wn_set 


wn_sense 
wn_emphasise 
lg_set_id_pos 
1g_sense_width 
ew_sense_size 
ew_set_size 
ew_set 
ew_sense 
ew_insert 


select 
change 
flags 
margins 
font 


ew_snuggle_insert 
ew_set_font 
ew_leave 
ew_find 
ew_replace 
ew_evaluate 
ew_replace_ clip 
ew_paste_clip 
ew_bring_ in 
ew_ep_insert 
ew_return_key 
ew_tab_key 
ew_init_style 
ew_readonly 


The Epwrn class provides the functionality of a window containing a formatted display of editable text. It is 
highly flexible since, in addition to being suitable for use as a simple one-line edit box ina dialog, it also 
supplies most of the basic functionality of a word processor. A subclass of epwrn is, for example, used by 


the Word application. 


Note that a tutorial introduction to the epwrn class may be found in the Edit Windows chapter of the Object 
Oriented Programming Guide. 


The edit window 


In general, the text in an edit window is arranged as a sequence of paragraphs. The text of each paragraph 
is automatically word wrapped within the window, as illustrated schematically in the following diagram: 


10-2 


This is an example paragraph in an edit window. The 
text is automatically wrapped and the first line is indented. 
Margins are present either side of the text region. 
This is the next paragraph containing one line only. 
This example edit window can display a maximum of 
six lines of text. Many more are not visible as they are out 


text region 


The margins can be altered by setting the edwin. margins property, and the size and position of the window 
can be altered by means of the ew_set_size method. 


Text lines 


The text lines in an edit window consist of text spaced out with top and bottom leading as illustrated in the 
following picture: 


10 TEXT EDITORS 


top leading 


bottom leading 


(Note: leading derives from the metal used by typesetters.) 


The font ascent, font descent and font height are characteristics of the font and the font style: see the 
Window Server manual for details of fonts. 


The font and style are by default global to the document: defining local styles and fonts is described in the 
Object Oriented Programming manual. 


The top leading is the space at the top of the line whilst the bottom leading is the space at the bottom of the 
line. The space between two lines is thus the sum of the topa and bottom leading - i.e. the total leading. The 
leading is global . 


The font, the style, and the leading can be altered using the ew_set_font method. 


Cursor position 


The position of the text cursor is simply the index of the preceding character - thus a cursor placed at the 
start of the document has a position of zero whilst a cursor placed immediately after the one hundredth 
character in the document has a cursor position of one hundred. 


Line cursor 


The scrimc document imaging class divides the drawing area into three columns consisting of a labels 
margin, a line cursor margin and a text region: by default the width of the first two columns is set to zero in 
the wn_init method. However a line cursor, which indicates the current line, may be specified on 
initialisation. The effect is illustrated by, for example, the Word application's main edit window. 


Link paste 


An edit window can act as a link-paste client using the bring in method. It must however be subclassed to 
allow it to act as a link-paste server. For details of the link-paste mechanism see the Link Paste chapter of 
the Object Oriented Programming manual. 


Class definition 
Defined in sub-category file edwin.cl (generated header file edwin.g). 


CLASS edwin lodger 

Editable text window 
{ 
REPLACE destroy 
REPLACE wn_init 
REPLACE wn_key 
REPLACE wn_draw 
REPLACE wn_sense_help 
REPLACE wn_set 
REPLACE wn_sense 
REPLACE wn_emphasise 
REPLACE lg_set_id pos 
REPLACE lg_sense_width 


10-3 


HWIM REFERENCE 


10-4 


ew_sense_size 
ew_set_size 

ew_set 

ew_sense 

ew_insert 
ew_snuggle_insert 
ew_set_font 

ew_leave 

ew_find 

ew_replace 
ew_evaluate 
ew_replace_clip 
ew_paste_clip 
ew_bring_in 

ew_ep_ insert 
ew_return_key=p false 
ew_tab_key=p_ false 
ew_init_style=p_dummy 
ew_readonly=p_true 


CONSTANTS 


{ 


PR_EDWIN_DIALLABLE 
PR_EDWIN_ACCEPT_TABS 
PR_EDWIN_ACCEPT_SOFT_HYPHENS 
PR_EDWIN_AUTO_CUR_END 
PR_EDWIN_AUTO_SELECT 
PR_EDWIN_DOC_SUPPLIED 
PR_EDWIN CLIPBOARD 
PR_EDWIN_NOTIFY_OVERFLOW 
PR_EDWIN_READONLY 


IN_EDWIN_DIALLABLE 
IN_EDWIN_ACCEPT_TABS 
IN_EDWIN_ACCEPT_SOFT_HYPHENS 
IN_EDWIN_AUTO_CUR_END 
IN_EDWIN_NO_AUTOSELECT 
IN_EDWIN_DOC_SUPPLIED 
IN_EDWIN_CLIPBOARD 
IN_EDWIN_VULEN 
IN_EDWIN_VULEN_NOSCALE 
IN_EDWIN_VULEN_CHARACTERS 
IN_EDWIN_VULEN_PIXELS 
IN_EDWIN LEFT CURSOR 
IN_EDWIN_TEXT_ SEGMENTED 
IN_EDWIN POSITION SUPPLIED 
IN_EDWIN_FONT_SUPPLIED 
IN_EDWIN LEADING SUPPLIED 
IN_EDWIN_VISLINES SUPPLIED 
IN_EDWIN_PAGINATABLE 


SET_EDWIN_TXT 
SET_EDWIN_EMPTY 

SET_EDWIN_CUR_END 
SET_EDWIN SEL ALL 
SET_EDWIN_CURSOR 
SET_EDWIN_ANCHOR 


EWF_BACKWARDS 0x0001 
EWF_CASESENS 0x0002 
EW_CHANGE_SINCE_SAVED 
EW_CHANGE_SINCE_PAGINATE 
EW_CHANGE 

EW_BRING SINGLE_SHOT 


} 


0x0001 
0x0002 
0x0004 
0x0008 
0x0010 
0x0020 
0x0040 
0x0080 
0x8000 


Same as IN_EDWIN_VULEN 


PR_EDWIN_DIALLABLE 
PR_EDWIN_ACCEPT_TABS 
PR_EDWIN_ACCEPT_SOFT_HYPHENS 
(PR_EDWIN_AUTO_CUR_END|PR_EDWIN_AUTO_SELECT) 
PR_EDWIN_AUTO_SELECT 
PR_EDWIN_DOC_SUPPLIED 
PR_EDWIN_CLIPBOARD 

0x0080 

0x0100 

IN_EDWIN_VULEN 
(IN_EDWIN_VULEN|IN_EDWIN_VULEN_NOSCALE) 
0x0200 

0x0400 

0x0800 

0x1000 

0x2000 

0x4000 

0x8000 


0x01 
0x02 
0x04 
0x08 
0x10 
0x20 


direction to scan (0=forwards, 1=back) 
TRUE iff case-sensitive search 


0x01 
0x02 
Oxffft 
oxfo000 


10 TEXT EDITORS 
AAT EDITORS 


TYPES 

{ 

typedef struct 
{ 
UWORD vulen; 
UWORD flags; 
UWORD maxlen; 
TEXT contents [1]; 
} IN_EDWIN; 

typedef struct 
{ 
WORD total; 
WORD top; 
} EDWIN_LEADING; 


viewing length or width 

autoselect etc 

maximum number of characters allowed 
rest of initial contents follows in line 


typedef struct 


{ 


UWORD vislines; number of lines visible in window 


P_POINT pos; top left offset relative to landlord 
WORD font; font ID 

UWORD style; font style 

EDWIN LEADING leading; total and top-only vertical leadings 
VOID *doc; document object to use 

VOID *clip; possible clipboard to use 


} IN_EDWIN_x; never used in edwins in dialogs 


typedef struct 
{ 
TEXT *buf; 
UWORD len; 
} SE_EDWIN; 
typedef struct 
{ 
UWORD flags; 
SE_EDWIN txt; 
UWORD cursor; 
UWORD anchor; 
} SET_EDWIN; 


cursor (moving point of select) 
anchor point (fixed end of select) 


typedef struct 
{ 
UWORD cursor; 
UWORD anchor; 
} SENSE_EDWIN; 


cursor (moving point of select) 
anchor point (may equal cursor) 


} 


PROPERTY 2 


{ 


VOID *serimg; 
VOID *scrlay; 
VOID *doc; 
UWORD cpos; 
UWORD clen; 
VOID *clip; 
UWORD select; 
UWORD change; 
UWORD flags; 


screen imager 

screen layout 

document content 

current position 

total content 

clipboard 

TRUE if there is a select region 
holds EW_CHANGE_ flags 

holds PR_EDWIN_ flags 


SCRLAY_MARGINS margins; 
SCRLAY_FONT font; 


} 
} 


Property 


edwin.scrimg 


edwin.scrlay 


edwin.doc 


the handle of an instance of scrime: responsible for the screen display. See the 
Document Layout Classes chapter of the FORM Reference manual for details. 


the handle of an instance of scriay: responsible for document layout. See the 
Document Layout Classes chapter of the FORM Reference manual for details. 


the handle of an instance of eppoc or EPFDoc: contains the document text. See the 
Editable Documents chapter of the FORM Reference manual for details. 


_ OC COO SSS 


10-5 


HWIM REFERENCE 


edwin.cpos the current cursor position 

edwin.clen total length of the document ignoring the terminating zero 

edwin.clip the handle of an instance of EprLaT or EPSEG: contains the clipboard text 

edwin.select TRUE if a region of text is selected, raLsE otherwise 

edwin. change set to indicate that the document has been edited: it is the responsibility of the 
application to reset this to FaLsE once the changes have been recorded. 

edwin. flags an ored combination of flags which determines the behaviour and content of the 
text window: the flags are described in the description of the methods 

edwin.margins the global settings for the margins 

edwin.font the global font information 


(Note that doc and clip are not on the auto-destroy list of epwrn - unlike scrimg and scrlay - as they can 
be created and looked after by the owner of the epwrn instance and may thus survive the destruction of the 
EDWIN instance.) 


AE a a a aS 
EDWIN methods 


DEST! 


VOID destroy (VOID) ; 


If PR_EDWIN_DOC_SUPPLIED is not set in edwin. flags, and edwin. doc is non-zero, sends a DESTROY 
message to edwin.doc. 


If PR_EDWIN_CLIPBOARD is set in edwin. flags, and edwin.clip is non-zero, sends a DEsTRoY message to 
edwin.doc. 


Supersends a DESTRoy message. 


Create components an 


VOID wn_init (IN_EDWIN *init, PR_WIN *landlord, IN EDWIN X *initx) ; 


Initialise the edit window: landlord should specify the window ID of the 1andlora window. 


The initial content and behaviour of the edit window are specified by means of an IN_EDWIN struct and an 
IN_EDWIN_X struct. 


The 1n_EpwIn struct is defined as follows: 


typedef struct 
{ 
UWORD vulen; 
UWORD flags; 
UWORD maxlen; 
TEXT contents [1]; 
} IN_EDWIN; 


The members of the In_Epwrn struct have the following significance: 


vulen the width of the view in characters or pixels. 
flags an ored combination of flags: see below. 
maxlen the maximum number of characters in the document: excludes the final zero terminator. 


contents the initial content of the document. 


10-6 


10 TEXT EDITORS 
EAT EDITORS 


The In_Epwin_x struct is defined as follows: 


typedef struct 
{ 
UWORD vislines; 
P_POINT pos; 
WORD font; 
UWORD style; 


EDWIN_LEADING leading; 


VOID *doc; 
VOID *clip; 
} IN_EDWIN_X; 


The members of the 1In_Epw1n_x struct have the following significance: 


vislines the maximum number of lines of text visible in the edit window. 


pos the top left offset of the edit window relative to the landlord window. 
font the global font ID 
style the global font style. 


leading the vertical line spacing. 


doc NULL or the handle of an instance of either Eppoc or EPpoc: contains the document text. 


clip NULL or the handle of an instance of =priar: contains the clipboard text. 


The initialisation is controlled by oring a suitable combination of the following flags into the f1ags 


member of the In_EDwrIN struct: 


IN_EDWIN_NO_AUTOSELECT 


IN_EDWIN_FONT_SUPPLIED 


IN_EDWIN_VULEN_CHARACTERS 


IN_EDWIN_VULEN_PIXELS 


IN_EDWIN_PAGINATABLE 


IN_EDWIN_TEXT_SEGMENTED 


IN_EDWIN_DOC_SUPPLIED 


IN_EDWIN_CLIPBOARD 


IN_EDWIN_POSITION_SUPPLIED 


Do not create a selected region: by default the entire document is 
selected. 


Use the font and style specified in initx->font and initx->style 
respectively: the default values are ws_ronT_sysTEem and 
G_STY_NORMAL respectively. 


Set the width of the edit window as specified in init->vulen: units 
of characters. 


Set the width of the edit window as specified by init->vulen: units 
of pixels. 


For advanced use only. 


If this flag is set, any document object created during initialisation 
will be an instance of eppoc, which uses segmented storage. In the 
absence of this flag (and assuming that the flag 
IN_EDWIN_DOC_SUPPLIED is also not set) an instance of EPFDoc.is 
created. 


Note that this flag must be set if the document object uses segmented 
storage (which is expected to be an instance of Eppoc or of a 
subclass of Eppoc) regardless of whether this instance is or is not 
created by the wn_init method. 


Use the document object specified in initx->doc. The default, in 
the absence of this flag, is to create the document object. 


Use the clipboard object specified in initx->clip , or, if initx- 
>clip Is Zero create a clipboard object with maximum length as 
specified in init->maxlen. The default is not to use a clipboard. 


Use the top left offset of the edit window specified by initx->pos. 
If this flag is not set the offset must be set by a subsequent call to 
ig_set_id_pos. 


10-7 


HWIM REFERENCE 
SS —  — SSSFSFSSSSSSSSSSSSSSSSSSSSSSMmMhFhFsFeFeFese 


IN_EDWIN_VISLINES_SUPPLIED Use the number of text lines visible specified in initx->vislines. 
The default is to show only one text line - i.e. a single text line 
editor. 

IN_EDWIN_ LEADING SUPPLIED Use the leading specified in initx->leading.top and initx- 


>leading.total. The default is to use top and total leading of one 
and two pixels respectively. 


IN_EDWIN_ACCEPT_TABS Accept Tab key presses. The default is to ignore Tab key presses. 
IN_EDWIN_ACCEPT_SOFT_HYPHENS Allow soft hyphens. The default is to ignore soft hyphens. 
IN_EDWIN_LEFT_CURSOR Draw a line cursor in the left margin. 


The above information is quite sufficient for simple use of the wn_init method. The following detailed 
explanation of the operation of the method is included for more advanced use. 


Sets the landlord window ID into property by writing Landlord to lodger . landlord. 
Writes init->flags to edwin. flags: 
e allows read and write access to the document by clearing pR_EDWIN_READONLY in edwin. flags. 


e if IN_EDWIN_NO_AUTOSELECT is set (clear) in init->flags clears (sets) PR_EDWIN_AUTOSELECT in 
edwin. flags. 


Sets the font and font style: 


e if init->flags contains IN_EDWIN_FONT_SUPPLIED, writes initx->font to edwin. font.fid and 
writes initx->style to edwin. font .style: defines user specified font and font style. 


e otherwise uses the system font, by writing w_ront_sysTem to edwin. font. fid. 


In the case of the Workabout, if the edit window is being used as a control in a small font dialog, 
edwin. font .£id is set to the font indicated by the value of digbox. font in the owning dialog box. 


Sets the width of the lodger window: 


¢ if init->£lags contains neither IN_EDWIN_VULEN_PIXELS nor IN_VULEN_CHARACTERS, writes 
init->maxlen multiplied by the maximum width of a character in the current font to 
lodger.width. 


e if init->flags contains IN_EDWIN_VULEN_PIXELS writes init->vulen tO lodger.width. 


¢ if init->flags contains IN_EDWIN_VULEN_CHARACTERS Writes init->vulen multiplied by the 
nominal maximum width of a character in the current font to lodger .width. 


If init->flags contains IN_EDWIN_DOC_SUPPLIED: 


© writes initx->doc to edwin.doc. This is assumed to be the handle of (a subclass of) either Eppoc 
or EPFDOC, depending on the presence or absence of the IN_EDWIN_TEXT_SEGMENTED flag. 


Otherwise creates and initialises a document object: 


e if init->£1ags contains IN_EDWIN_TEXT_SEGMENTED creates an instance of Eppoc and writes the 
handle to edwin. doc. 


e otherwise creates an instance of EPFDoc and writes the handle to edwin. doc. 


e sends an EP_INIT message to edwin. doc specifying a maximum length of init->maxlen 
characters plus a zero terminator. 


© copies the text specified by init->content into the document by sending an EP_SET_TEXT 
messsage to edwin. doc. 


Senses the document length by sending an Ep_sENSE_LEN message to edwin. doc and writes the result to 
edwin.clen. 


Builds a scray_poc struct containing document information and methods required by the scrLay 
component. If init->£1lags contains IN_EDWIN_TEXT_SEGMENTED (on the assumption that the document 
content object is, or is a subclass of, EpDoc): 


10-8 


10 TEXT EDITORS 
—_— SS SEAT EDITORS 


e writes 0_EPDOC_SENSE_cuHars to the sensechars member. 
© writes o_EPDOC_PARA_sTART to the toparst member. 


e if init->flags contains IN_EDWIN_PAGINATABLE, writes O_EPDOC_ENQ_PAGE to the enqpage 
member. 


Otherwise (on the assumption that the document content object is, or is a subclass of, EPFDOC) sets the 
above members as follows: 


© writes 0_EPFDOC_SENSE_cuaRs to the sensechars member. 
e writes o_EPFpoc_PaRA_ start to the toparst member. 
Sets the remaining members as follows: 
© writes zero to the sensepdata and senseplabel members: these are thus undefined. 
© writes edwin.doc to the content member: defines the document object. 


* sends an EP_SENSE_LEN message to edwin. doc and writes the return value plus one to the 1en 
member: defines the document length. 


Builds a scRLAY_STYLE struct containing style information required by the scriay component as follows: 
© writes SCRLAY_SHOW_TABS to the options member: defines tabs as visible. 
e writes raLsE to the printer member: defines the layout mode as screen. 
© writes a pointer to edwin.margins to the pd.margins member: defines the margins. 


¢ writes the address of edwin. font to the font and sfont members: defines the global printer and 
screen fonts. 


e writes the address of edwin. font .height to the pd. tabs member: defines zero tabs. 
© writes nuLL to the fwtab member. the global printer font width table is undefined. 
¢ writes zero to the scrpwidth member: the printer tab positions information is undefined. 


Allows subclassers to change the default style settings in the scrLAY_sTYLE struct by sending se1f an 
EW_INIT_STYLE message. (The default method does nothing.). 


Creates an instance of scriay and writes the handle to edwin. scriay. Initialises by sending an su_inrT 
message to edwin. scrlay with pointers to the above scrLay_poc and ScRLAY_STYLE structs. 


If init->£1ags contains IN_EDWIN_CLIPBOARD and initx->clip is zero, creates an instance of EPFLAT and 
writes the handle to edwin.clip. Initialises with maximum length init->maxlen characters excluding the 
zero terminator by sending an EP_INIT message to edwin. clip. 


If init->£1lags contains IN_EDWIN_CLIPBOARD, and initx->clip is non-zero, writes initx->clip to 
edwin.clip and clears In_EDWIN_CLIPBOARD from edwin. flags as the clipboard is now initialised. 


Builds an scrrmc_wrn struct containing window information. If init->£1ags contains 
IN_EDWIN_LEFT_CURSOR: 


¢ writes W_FONT_SYSTEM to win.1cfont: defines the line cursor font. 


e ifG_stTy_pouBLs is set in edwin. font .style, sets G_STY_DOUBLE in win.1cstyle: defines the line 
cursor style - zero for the default style. 


© writes WS_SYMBOL_MARGIN_CURSOR to win. 1ccode: defines the line cursor symbol. 
If init->flags contains IN_EDWIN_LEADING_SUPPLIED: 


¢ writes the sum of the font height in pixels and initx->1eading.total to win. lheight: defines 
the line height. 


¢ writes the sum of the font ascent in pixels and initx->leading.top to win. lascent: defines the 
line ascent. 


Otherwise sets the above members as follows: 


10-9 


HWIM REFERENCE 


e writes the font height in pixels plus two to win. Lheight: defines the line height. 

e writes the font ascent in pixels plus one to win. 1lascent: defines the line ascent. 
If init->flags contains IN_EDWIN_VISLINES: 

e writes initx->vislines to win.nlines: defines the maximum number of lines visible. 

e writes win.width divided by four to win. hscrim: defines the horizontal scroll behaviour. 
Otherwise: 

e writes one to win.nlines: defines the maximum number of lines visible. 

e writes zero to win. hscri1x and writes two to win. hscrim: defines the horizontal scroll behaviour. 
Sets the remaining members as follows: 

e writes landlord->win.id to win.wid: defines the landlord window ID. 

e® writes initx->pos to win.t1: defines the top left offset of the window. 

e writes lodger.width to win.width: defines the width of the edit window. 

© writes zero to win.margin: defines the default width of the label and line cursor margins. 

e writes two to win.cwidth: defines the width of the text cursor. 
Creates an instance of scrimc and write the handle to edwin. scrimg. 


Sets the window information by sending an s1_sET message to edwin. scrimg with as arguments a pointer 
to the above scriImG_WwIN stmict and edwin.scrlay. 


Subtracts the font maximum character width from the pixel width of the text area of the edit window (this 
is the return value from the last s1_seT message) and writes the result to edwin.margins. right. 


If win.nlines is one in which case only one line is visible: 

e disables the word wrap by writing 4096 to edwin. margins. right. 
If init->flags contains IN_EDWIN_POSITION_SUPPLIED: 

e sets the offset of the lodger window by writing win.t1 to lodger. offset. 

e sets the lodger window ID by writing win.wid to win.id. 

e sends an sI_INIT message to edwin. scrimg with as arguments zero and zero. 
(Otherwise does nothing and expects the caller to send an LG_sET_rp_ Pos message later.) 


If edwin. flags contains IN_EDWIN_POSITION_SUPPLIED and either IN_EDWIN_AUTO_CUR_END or 
IN_EDWIN_AUTO_SELECT: 


e moves the cursor to the end of the document and scrolls the view until the cursor is visible by 
sending an SI_MOVE_CURSOR message to edwin.scrimg. 


e writes the length of the document excluding the terminating zero to edwin. cpos. 


e if edwin.flags contains IN_EDWIN_AUTO_SELECcT selects the region defined by the old and new 
cursor positions. 


; "Handle key input 
INT wn_key(UINT keycode, UINT modifiers) ; 

Handle a keypress. 

If the keypress is w_KEY_ESCAPE: 


© cancels any selection, write FALSE to edwin.select and returns WN_KEY_NO_CHANGE. 


10-10 


10 TEXT EDITORS 
_—_—_—_—__ EET EDITORS 


If the keypress is w_kKEY_DELETE_RIGHT: 


© if edwin. flags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message 
- is TRUE, calls hBeep then p_leave with RUN_ACTIVE_USED as argument. 


e ifaselected region exists, moves the cursor to the start of the selection, delete the selection, and 
scrolls the view until the cursor is visible. Writes the cursor position to edwin. cpos. Writes FALSE 
to edwin.select. Writes the document length to eawin.clen. Rebuilds the layout and the view - 
the method sends an s1_FwD_CHANGED message to edwin. scrimg. Writes EW_CHANGE to 
edwin.change. Returns WN_KEY_CHANGED. 


¢ ifthe end of the document has been reached, returns wx_KEY_NO_CHANGE. 


¢ — otherwise deletes the character to the right of the cursor - the method reformats and redraws the 
edited document responsively by sending an st_PARA_CHANGED message to edwin.doc. Writes the 
document length to edwin.clen. Writes Ew_CHANGE to edwin. change. Return WN_KEY_ CHANGED. 


If the keypress is w_KEY_DELETE_LEFT: 


e if edwin. flags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message 
iS TRUE, Calls hBeep then p_leave with RUN_ACTIVE_USED as argument. 


¢  ifmodifiers contains w_PSTON_MODIFIER, Clear PR_WSERV_INSERT_MODE and 
PR_WSERV_INSERT_PENDING iN w_ws->wserv. flags. Selects the region to the left of the cursor and 
moves the cursor to the start of the line by sending se1f a wy_KEY message with arguments of 
W_KEY_HOME and W_SHIFT_MODIFIER. 


e if aregion is selected, moves the cursor to the start of the selection, deletes the selection, and 
scrolls the view until the cursor is visible. The selection is copied to the clipboard object if one 
exists. Writes the cursor position to edwin. cpos. Writes FALSE to edwin. select. Writes the 
document length to edwin.clen. Rebuilds the layout and the view - the method sends an 
SI_FWD_CHANGED message tO edwin.scrimg. Writes EW_CHANGE to edwin. changed and returns 
WN_KEY CHANGED. 


¢ if the cursor is at the start of the document returns wi_KEY_NO_CHANGE. 


e otherwise deletes the character to the left of the cursor, moves the cursor to the left by one 
character and scrolls the view until the cursor is visible: the method sends an SI_DELPREP message 
to edwin. scrimg, a EP_DELETE message to edwin.doc and an SI_PARA_CHANGED changed 
message to edwin. scrimg. Writes the length of the document to edwin.clen. Writes the cursor 
Position to edwin.cpos. Writes EW_CHANGE to edwin. changed and returns WN_KEY_CHANGED. 


If the keypress is W_KEY_LEFT: 


¢ — if'a selected region exists and modifiers does not contain w_SHIFT MODIFIER, moves the cursor to 
the start of the selected region, cancels the selection and scrolls the view until the cursor is visible. 
Writes FALSE to edwin. select. Returns WN_KEY_NO_CHANGE. 


¢ if the cursor is at the start of the document returns wN_KEY_NO_CHANGE. 


e ifmodifiers contains W_CTRL MODIFIER, moves the cursor backwards to the start of a word - the 
method sends an EP_SCAN_WORD message to edwin. doc - and scrolls the view until the cursor is 
visible. Writes the cursor position to edwin. cpos. If modifiers contains W_SHIFT_MODIFIER 
selects the text skipped and writes TRUE to edwin. select. Returms wN_KEY_NO_CHANGE. 


e otherwise moves the cursor backwards one character and scrolls the view until the line containing 
the cursor is visible. Writes the cursor position to edwin. cpos. If modifiers contains 
W_SHIFT_MODIFIER Selects the character skipped and writes TRUE to edwin. select. Returns 
WN_KEY_NO_CHANGE. 


If the keypress is W_KEY_ RIGHT: 


e if selected region exists and modifiers does not contain w_sHIFT_MODIFIER, moves the cursor to 
the end of the selected region, cancels the selection and scrolls the view until the cursor is visible. 
Writes FALSE to edwin.select. Returns wN_KEY_NO_CHANGE. 


¢ — if the cursor is at the end of the document, returns wx_KEY_NO_ CHANGE. 


¢ if modifiers contains w_cTRL_MODIFIER, moves the cursor forwards to the start of a word - the 
method sends an EP_SCAN_WORD message to edwin. doc and an SI_MOVE_CURSOR message to 


Sn 
10-11 


HWIM REFERENCE 
ee 


edwin .scrimg - and scrolls the view until the cursor is visible. Writes the cursor position to 
edwin. cpos. If modifiers contains W_SHIFT_MODIFIER selects the text skipped and writes truE to 
edwin. select. Otherwise writes FALSE to edwin. select. Returms wN_KEY_NO_CHANGE. 


otherwise moves the cursor forwards by one character and scrolls the view until the cursor is 
visible. Writes the cursor position to edwin.cpos. If modifiers contains W_SHIFT_MODIFIER 
selects the character skipped and writes TRUE to edwin. select. Otherwise writes FALSE to 
edwin.select. Returns wN_KEY_NO CHANGE. 


If the keypress is w_KEY_HOME: 


if modifiers contains both w_crRL_MODIFIER and W_SHIFT_MODIFIER, moves the cursor 
backwards until a word delimiter is located and then selects the word after the delimiter - i.e. 
selects the current word. The method sends an EP_sCcAN_woRD message to edwin. doc and an 
SI_MOVE_CURSOR message to edwin.scrimg. 


otherwise moves the cursor to the beginning of the current line. If modifiers contains 
W_SHIFT_MODIFIER Selects the text skipped and writes TRUE to edwin. select. Otherwise cancels 
any selected region and writes FALSE to edwin. select. 


If the keypress is W_KEY_END: 


if modifiers contains both w_crRL_MODIFIER and W_SHIFT_MODIFIER, moves the cursor forwards 
until a paragraph delimiter is located then selects the paragraph preceding the cursor - i.e. selects 
the current paragraph. The method sends an EP_scaN_PARA message to edwin. doc and an 
SI_MOVE_CURSOR message to edwin.scrimg. 


otherwise moves the cursor to the end of the current line. If modifiers contains 
W_SHIFT_MODIFIER Selects the text skipped and writes TRUE to edwin. select. Otherwise cancels 
any selection and writes FALSE to edwin. select. 


If the keypress is w_KEY_UP: 


if a region is selected and modifiers does not contain w_SHIFT_MODIFTIER, cancels the selection 
and writes FALSE to edwin.select. Moves the cursor to the start of the once selected region and 
scrolls the view until the cursor is visible. Returns wN_KEY_NO_CHANGE. 


if modifiers contains W_CTRL_MODIFIER, moves the cursor to the start of the current paragraph 
and scrolls the view until the cursor is visible. If modifiers also contains w_SHIFT_MODIFIER 
selects the characters skipped and writes TRUE to edwin.select. Otherwise cancels any selected 
region and writes FALSE to edwin. select. Returns wN_KEY_NO_CHANGE. 


otherwise moves the cursor up one line and scrolls the view until the cursor is visible. If 
modifiers Contains W_SHIFT_MODIFIER, anda region is not selected, selects the text skipped and 
writes TRUE to edwin. select. If modifiers contains W_SHIFT_MODIFIER, and a region is selected, 
moves the cursor point of the selected region to the new cursor position. Otherwise writes FALSE 
to edwin.select. Returns wN_KEY_NO_CHANGE. 


If the keypress is w_KEY_DOWN: 


if a region is selected and modifiers does not contain W_SHIFT MODIFIER, moves the cursor to the 
end of the selected region, cancels the selection, and scrolls the view until the cursor is visible. 
Writes FALSE to edwin.select. Returns WN_KEY_NO_CHANGE. 


if modifiers contains W_CTRL_MODIFIER, moves the cursor to the start of the first line of the next 
paragraph and scrolls the view until the cursor is visible. If modifiers also contains 
W_SHIFT_MODIFIER selects the characters skipped and writes TRUE to edwin. select. Returns 
WN_KEY_NO_CHANGE. 


otherwise moves the cursor down one line and scrolls the view until the cursor is visible. If 
modifiers Contains W_SHIFT_MODIFIER, anda region is not selected, selects the text skipped and 
writes TRUE to edwin. select. If modifiers contains W_SHIFT_MODIFTER, and a region is selected, 
moves the cursor point of the selected region to the new cursor position. Otherwise cancels any 
selection and writes FALSE to edwin. select. Retums WN_KEY NO CHANGE. 


If the keypress is W_KEY_PAGE_UP: 


if modifiers contains W_CTRL_MODIFIER, moves the cursor to the start of the document and writes 
the cursor position to edwin.cpos. If modifiers also contains w_SHIFT_MODIFIER selects the text 


ng et 


10-12 


10 TEXT EDITORS 
—_ HH EAT EDITORS 


skipped and writes TRUE to edwin. select. Otherwise cancels any selection and writes FALSE to 
edwin.select. Retumms wN_KEY_NO_CHANGE. 


e otherwise moves the cursor up by one ‘page’ (that is, by one fewer lines than the number of lines 
that can be displayed on the screen) and writes the cursor position to edwin.cpos. If modifiers 
also contains W_SHIFT_MODIFTIER selects the text skipped and writes TRUE to edwin. select. 
Otherwise cancels any selection and writes FALSE to edwin. select. Returns WN_KEY_NO_CHANGE. 


If the keypress is w_KEY_PAGE_DOWN: 


¢ ifmodifiers contains w_cTRL_MODIFIER, moves the cursor to the end of the document and scrolls 
the view until the cursor is visible. Writes the cursor position to edwin. cpos. If modifiers 
contains W_SHIFT_MODIFIER, Selects the text skipped and writes TRUE to edwin. select. Otherwise 
cancels any selection and writes FALSE to edwin. select. Returns WN_KEY_NO_CHANGE. 


e otherwise moves the cursor down by one 'page' (that is, by one fewer lines than the number of 
lines that can be displayed on the screen) and scrolls the view until the cursor is visible. Writes the 
cursor position to edwin. cpos. If modifiers contains w_SHIFT_MODIFTER, selects the text skipped 
and writes TRUE to edwin. select. Otherwise cancels any selection and write FALSE to 
edwin.select. 


If the keypress is w_KEY_ RETURN: 


e checks that the document accepts w_kEy_RETURN by sending self an EW_RETURN_KEY message. If 
the return value is non-zero the method terminates, returning this value. 


e ifedwin. flags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message 
is TRUE, Calls hBeep then p_leave with RUN_ACTIVE_USED as argument. 


¢ ifmodifiers contains w_SHIFT_MODIFIER, Sets keycode to a carriage return - ie. ‘\n’, 
e otherwise sets keycode to zero - i.e. ox00. 


¢ — inserts keycode into the document at the current cursor position and moves the cursor forwards 
one character. Writes the document length to edwin.clen. Cancels any selection and writes FALSE 
to edwin.select. Sends an sI_PARA_CHANGED message to edwin. scrimg. Writes EW_CHANGE to 
edwin.change. Returns WN_KEY_NO_CHANGE. 


If the keypress is w_KEY_ TAB: 


checks that the document accepts w_key_Tas by sending self an EW_TAB_KEY message. If the 
return value is non-zero returns the return value. 


° if edwin. £1ags does not contain pR_EDWIN_ACCEPT_TABS, returms WN_KEY_NO_CHANGE. 


° ifedwin. flags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message 
iS TRUE, Calls hBeep then p_leave with RUN_ACTIVE_USED as argument. 


* — inserts a tab character at the current cursor position, moves the cursor to the right by one character 
and scrolls the view until the cursor is visible. Writes the document length to edwin. clen. Cancels 
any selection and writes FALSE to edwin.select. Sends an st_PARA_CHANGED message to 
edwin.scrimg. Returns wN_KEY_NO_CHANGE. 


If the keypress is W_KEY_HELP: 


° ifmodifiers does not contain both w_pstoN_MODIFIER and W_SHIFT_MODIFIER, and edwin. flags 
does not contain PR_EDWIN_DIALLABLE, returns WN_KEY_NO_CHANGE. 


* ifedwin.£f1ags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message 
is TRUE, Calls hBeep then p_leave with RUN_ACTIVE_USED as argument. 


¢ if modifiers does not contain w_CTRL_MODIFIER, cancels then deletes any selected region - the 
selected region is copied to the clipboard. Inserts a ws_PHONE_SYMBOL character at the current 
cursor position, moves the cursor forwards one character and scrolls the view until the cursor is 
visible. Writes the document length to edwin.clen. Writes the cursor position to edwin. cpos. 
Writes FALSE to edwin.select. Writes EW_CHANGE to edwin. change and sends an SI_FWD_CHANGE 
message to edwin.scrimg. Returns wN_KEY_ CHANGED. 


10-13 


HWIM REFERENCE 
Se eEeeeSSSSSSSSSSSSSSSSSSMSESE 


otherwise runs a country selector dialog by sending a ws_APPEND_COUNTRY message to w_ws and 
inserts the selected country name into the document by sending se1f an EW_INSERT message. 
Returns ww_KEY_NO_CHANGE. 


If the keypress is ' ': 


if edwin. flags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message 
is TRUE, Calls hBeep then p_leave with RUN_ACTIVE_USED as argument. 


if a selected region exists, copies the selected region to the clipboard and then cancels and deletes 
the selected region. Writes the document length to edwin.clen. Writes FALSE to edwin. select. 


if modifiers contains W_CTRL_MODIFIER, replaces the value of keycode by 
WS_SYMBOL_HARD_ SPACE. 


inserts keycode. 


moves the cursor forwards one character and, if necessary, scrolls the view until the cursor is 
visible. Writes the document length to edwin. clen. Writes the cursor position to edwin. cpos. 


if a select region has been deleted, sends an st_poc_CHANGED message to edwin. scrimg, otherwise 
sends edwin.scrimg an SI_PARA_CHANGED message. Writes EW_CHANGE to edwin. change. Returns 
WN_KEY_CHANGED. 


If the keypress is '-': 


if edwin. flags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message 
is TRUE, calls hBeep then p_leave with RUN_ACTIVE_USED as argument. 


if a selected region exists copies the selected region to the clipboard and then cancels and deletes 
the selected region. Writes the document length to eawin.clen. Writes raLsE to edwin.select. 


if modifiers contains W_SHIFT_MODIFIER and w_CTRL_mopzFrer, the value of keycode is replaced 
by WS_SYMBOL_HARD HYPHEN. 


otherwise, if modifiers contains W_CTRL MODIFIER and edwin. flags contains 
PR_EDWIN_ACCEPT_SOFT_HYPHENS, the value of keycode is replaced by ws_SYMBOL_SOFT_HYPHEN. 


inserts keycode. 


moves the cursor forwards one character and, if necessary, scrolls the view until the cursor is 
visible. Writes the document length to edwin. clen and the cursor position to edwin. cpos. 


if a select region has been deleted, sends an st_poc_CHANGED message to edwin. scrimg, otherwise 
sends edwin.scrimg an SI_PARA_CHANGED message. Writes EW_CHANGE to edwin. change. Returns 
WN_KEY_CHANGED. 


For any other keypress: 


10-14 


if keycode does not specify a printable character or keycode is greater than or equal to oxi00, 
retums WN_KEY_NO_CHANGE. 


if edwin. flags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message 
is TRUE, calls hBeep then p_leave with RUN_ACTIVE_USED as argument. 


if a selected region exists, copies the selected region to the clipboard and moves to the start of the 
selected region scrolling the view until the cursor is visible. Cancels and deletes the selected 
region. Writes the document length to edwin.clen. Writes FALSE to edwin. select. 


inserts keycode at the current cursor position and moves the cursor forwards one character. Writes 
the document length to edwin.clen. Writes FALSE to edwin.select. 


if a selected region existed, rebuilds and redraws by sending an st_Doc_CHANGED message to 
edwin.scrimg. 


otherwise rebuilds and redraws responsively by sending an s1_PARA_CHANGED message to 
edwin. scrimg. 


writes EW_CHANGE to edwin. change. Returns WN_KEY_CHANGED. 


10 TEXT EDITORS 


Draw view 
VOID wn_draw (VOID) ; 
Draw the whole view. 


Sends an sI_REDRAW message to edwin. scrimg with an argument of NULL. 


Sense help ID 


INT wn_sense_help (VOID) ; 


Sense the ID for epwrn help resource. 


Returns -syS_HELP_EDIT. 


N_S Set text 


VOID wn_set(SE_EDWIN *pset) ; 
Set the content of the edit window according to the content of the sz_EpwrN struct pointed to by pset. 
The se_zpwrn struct is defined as follows: 
typedef struct 

te *buf; 

UWORD len; 

} SE_EDWIN; 
The members of the se_epw:n struct have the following significance: 
buf a pointer to the text to be set in the edit window 
len the total length of the text excluding the terminating zero 
Sets the text in the edit window by sending an Ep_sET_TExT message to edwin. doc. 


Writes the length of the document including the terminating zero to edwin.clen. 


Cancels any selected region, moves the cursor to the start of the document and scrolls the view until the 
cursor is visible by sending an st_poc_RESET message to edwin. scrimg. Writes the cursor position to 
edwin.cpos. 


If PR_EDWIN_AUTO_CUR_END is set in edwin. flags, moves the cursor to the end of the document and scrols 
the view until the cursor is visible by sending an s1_MovE_cuRSoR message to edwin. scrimg . Writes the 
cursor position to edwin. cpos. Writes FALSE to edwin. select. 


If PR_EDWIN_AUTO_SELECT is set in edwin. flags, moves the cursor position to the end of the document, 
scrolls the view until the cursor is visible and selects the whole document by sending an SI_MOVE_CURSOR 
message to edwin. scrimg. Writes the cursor position to edwin.cpos. Writes TRUE to edwin. select. 


WN_SENSE | _ Sense text 
VOID wn_sense(SE_EDWIN *psense) ; 
Sense the text in the edit window and write the results to the s=_EDwIN struct pointed to by psense. 


Senses the text by sending an Er_sENSE_BUF message to edwin.doc. Writes a pointer to the text to psense- 
>buf and writes the length of the text minus the zero terminator to psense->1en. 


This method is not supported if the text is not stored contiguously. 


10-15 


HWIM REFERENCE 


WN_EMPHASISE = = =e - Set emphasis 
VOID wn_emphasise (INT flag) ; 
Emphasise the edit window. 


Sends an sI_EMPHASIZE Message to edwin.scrimg with an argument of flag. 


Les 


VOID 1lg_set_id_ pos(INT id, P_POINT *ppos, UINT width) ; 


Set the offset of the lodger window as specified by ppos, the width of the lodger window as specified by 
width, and the ID of the lodger window as specified by ia. 


Sets the offset width, and ID of the lodger window by supersending an L¢_sET_ID_Pos message. 


Obtains a copy of the scrimc window information data structure by sending an s1_SENSE message to 
edwin.scrimg with as argument a pointer to a scRIMG_win struct. 


Writes the struct pointed to by ppos to the t1 member of the scrimc_wrn struct. Writes width to the width 
member of the scrrmc_WIN struct. 


Initialises the scriMe instance and sets the content of the above scrimc_wn struct into property by sending 
an SI_INIT messsage to €dwin.scrimg. 


If PR_EDWIN_AUTO_CUR_END is set in edwin.flags, moves the cursor to the end of the document by sending 
an SI_MOVE_CURSOR Message to edwin. scrimg. Writes the cursor position to edwin.cpos. Writes FALSE to 
edwin.select. 


If PR_EDWIN_AUTO_SELECT is set in edwin. flags, moves the cursor to the end of the document and selects 
the whole document by sending an s1_MovE_cuRSOR message to edwin. scrimg. Writes the cursor position 
to edwin. cpos. Writes TRUE to edwin.select. 


Le {WOT oo eee eee 


INT lg_sense_width(VOID) ; 


Sense the width of the lodger window. 


Returns lodger. width. 


VOID ew_sense_size(P_EXTENT *pext) ; 


Sense the top left offset of the lodger window, the width of the lodger window and the maximum number 
of text lines visible and write the results to the p_ExTENr struct specified by pext. 


Senses the window data for the scrime instance by sending an st_sENSE message to edwin. scrimg. 


Writes the pixel coordinates of the top left corner of the lodger window to pext->t1. Writes the pixel width 
of the lodger window to pext->width. Writes the number of text lines visible to pext->height. 


VOID ew_set_size(P_EXTENT *pext, VOID *hand, INT method); 


Set the top left offset of the edit window as specified by pext->t1, the width of the lodger window as 
specified by pext->width and the maximum number of text lines visible as specified by pext->height. 


Senses the current window data for the scrimc component by sending an s1_SENSE message to 
edwin.scrimg with as argument a pointer to an SCRIMG_WIN struct. 


Writes the new offset of the lodger window pext->t1 to lodger . offset. 


Writes the new coordinates of the top left point of the edit window pext->t1 to the t1 member of the 
SCRIMG_WIN Struct. 


eee 
10 - 16 


10 TEXT EDITORS 


Writes pext->height, which contains the new number of text lines visible, to the nines member of the 
SCRIMG_WIN struct. 


Sets the modified window data into the scrimc component by sending an s1_seT message to 
edwin.scrimg. 


If hand is non-zero, sends a method message to hand with as argument the pixel width of the text area: this 
allows for further processing before the document layout is rebuilt. 


Rebuilds the document layout and the view by sending an s1_sTYLE_CHANGED message to edwin. scrimg. 


VOID ew_set(SET_EDWIN *pset) ; 


Set the content and appearance of the edit window according to the content of the seT_=pwin struct 
specified by pset. 


The seT_EDWIN struct is defined as follows: 


typedef struct 


{ 

UWORD flags; 

SE_EDWIN txt; 

UWORD cursor; cursor (moving point of select) 
UWORD anchor; anchor point (fixed end of select) 
} SET_EDWIN; 


The members of the ser_zpwrn struct have the following significance: 
flags see below. 


txt an SE_EDWIN struct specifying the text to set in the edit window: see the description of the 
wn_set method for details. 


cursor the candidate cursor position. 
anchor the candidate anchor position. 


The setting is controlled by oring into £1ags a suitable combination of the following flags: 


SET_EDWIN_EMPTY empty the content of the edit window 
SET_EDWIN_TXT set the content of the edit window 
SET_EDWIN_SEL_ALL select the entire content of the edit window 
SET_EDWIN_CUR_END move the cursor to the end of the document 
SET_EDWIN_ANCHOR set the position of the anchor for the selected region 
SET_EDWIN_CURSOR set the position of the cursor 


If pset->flags contains SET_EDWIN_EMPTY: 
© sets SET_EDWIN_TXT iN pset->flags and Set pset->txt.1len to zero 
If pset->flags contains SET_EDWIN_TXT: 


e _ sets the text in the edit window by sending an EP_sET_TEXxT message to edwin. doc and writes the 
length of the text as specified by pset->txt .len to edwin.clen 


e cancels any selection, moves the cursor to the start of the document and scrolls the view until the 
cursor is visible by sending an st_poc_REsET message to edwin. scrimg. Writes the cursor 
position to edwin.cpos. 


If pset->flags contains SET_EDWIN_SEL_ALL: 


e — sets both sET_EDWIN_CUR_END and SET_EDWIN_ANCHOR iN pset->flags and writes zero to 
pset->anchor 


10-17 


HWIM REFERENCE 
Se Ss SSS 


If pset->flags contains SET_EDWIN_CUR_END: 
e sets SET_EDWIN_CURSOR in pset->flags and writes edwin.clen-1 to pset->cursor 
If pset->flags contains SET_EDWIN_ANCHOR: 


e writes pset->anchor to edwin. cpos, cancels any selected region, moves the cursor to edwin.cpos 
and scrolls the view until the cursor is visible by sending an s1_MovE_cuRSoR message to 
edwin. scrimg. 


If pset ->£1ags contains sET_EDWIN_CURSOR and SET_EDWIN_ANCHOR: 


e — selects the region between edwin. cpos and pset->cursor, moves the cursor to pset->cursor and 
scrolls the view until the cursor is visible by sending an s1_MovE_cuRSOR message to 
edwin.scrimg. Writes TRUE to edwin.select. Writes the cursor position to edwin.cpos. 


If pset->flags contains sET_EDWIN_cuRsoR but not SET_EDWIN_ANCHOR: 


e cancels any selection, moves the cursor to pset->cursor and scrolls the view until the cursor is 
visible by sending an s1_MovE_cURSOR message to edwin. scrimg. Writes FALSE to edwin. select. 
Writes the cursor position to edwin.cpos. 


Note that the order of the above tests is significant: for example a region may be selected by oring both 
SET_EDWIN_ANCHOR and SET_EDWIN_CuRSOR into pset->flags. 


_ Sense cursor and select data 
INT ew_sense (SENSE_EDWIN *psense) ; 


Sense the anchor and cursor position of the selected region and write the results to the sENsE_EDWIN struct 
specified by psense. 


The sENSE_Epwrn struct is defined as follows: 


typedef struct 


{ 
UWORD cursor; cursor (moving point of select) 
UWORD anchor; anchor point (may equal cursor) 
} SENSE_EDWIN; 
The members of the sensE_EDwIN struct have the following significance: 


cursor the cursor position of the selected region: equal to anchor plus the length of the selected 
region 


anchor __ the anchor position of the selected region 


The anchor and cursor positions are illustrated in the following picture: 


cursor position 


ban example JaGatecBye-stne] in a document 


anchor position 


(Note that it is quite possible for the cursor position to come before the anchor position.) 


Obtains the position of the first character and the length for the selected region by sending an 
SI_GET_SELECT message to edwin.scrimg and writes the anchor and cursor positions to psense. 


Returns the number of characters in the selected region: zero indicates that no selected region exists. 


10-18 


10 TEXT EDITORS 


EWINSERT == = _Insert at cursor 
VOID ew_insert (TEXT *buf£, UINT blen); 
Insert at the current cursor position bien characters from the buffer specified by but. 


Inserts the text into the document at the current cursor position by sending an EP_INSERT message to 
edwin.doc: the message is sent using p_entersend and on error an EW_LEAVE message is sent to self with 
the error code as argument. 


Writes the length of the document to edwin.clen. 


Moves the cursor to the end of the inserted text by sending an s1_MovE_CURSOR message to edwin. scrimg: 
the view is scrolled until the cursor is visible. Writes the cursor position to edwin. cpos. 


Writes Ew_CHANGE to edwin. change. 


Rebuilds the layout and view by sending an s1_Fwp_CHANGE message to edwin. scrimg: the top left corner 
of the view is kept fixed. 


face select and add surrounds 
VOID ew_snuggle_ insert (TEXT *before, TEXT *after, TEXT *replace) ; 


Replace the selected region with the before, replace and after strings (in that order) and select the 
inserted replace text: before, replace and after may each specify a nuuu address. 


Checks that the sum of the current document length and the length of each insert string does not exceed the 
maximum allowed document length. If the maximum document length is exceeded, sends se1¢ an 
EW_LEAVE message with argument of E_GEN_OVER. 


Obtains the length and position of the selected region by sending an s1_GET_sELECT message to 
edwin.scrimg. 


If no selection exists, inserts at the current cursor position the before, replace and after strings by 
sending EP_INSERT messages to edwin. doc. 


If a selection exists, inserts immediately after the selected region the before, replace and after strings by 
sending EP_INSERT messages to edwin. doc. Cancels the selection by sending an st_MovE_cURSOR message 
to edwin. scrimg, then deletes the once selected region by sending an Ep_DELETE message to edwin. doc. 


Writes EW_CHANGE to edwin. change and sends an sI_DOC_CHANGED message to edwin. scrimg. 


Selects the inserted replace string, moves the cursor to the end of the selected region, and scrolls the view 
until the cursor is visible by sending st_move_cuRSOR messages to edwin. scrimg. 


VOID ew_set_font (INT font, UINT style,EDWIN_LEADING *leading) ; 


Set the font as specified by font, the font style as specified by style, and the line spacing as specified by 
leading. 


Writes font to edwin. font. fid and writes style to edwin. font.style. 


Senses the window information for the scrime instance by sending an s1_sENSE message to edwin.scrimg 
with as argument a pointer to an scRIMG_wIN struct. 


Writes the line height in pixels to the 1height member of the scrimc_wrn struct: the line height is equal to 
the sum of leading->tota1 and the font height. 


Writes the line ascent in pixels to the ascent member of the scrimG_wrn struct: the line ascent is equal to 
the sum of leading->top and the font ascent. 


Sets the modified window information by sending an st_sET message to edwin. scrimg. 


This method is expected to be followed by a call to the ew_resize method. 


10-19 


HWIM REFERENCE 


EW 


VOID ew_leave (INT err); 


Leave handling 


Leave handling for the error code specified by err. 


If err is E_GEN_OVER, calls hBeep and if edwin. flags contains PR_EDWIN_NOTIFY_OVERFLOW, Calls 
hInfoPrint with an argument of -sys_ep1T_Ncuars. Calls ¢_1eave with an argument of 
RUN_ACTIVE_CLEANUP_NONOTIFY. 


Otherwise calls £_leave with an argument of err. 


INT ew_find(TEXT *pstr, UINT flags) ; 


Search the document for the zero terminated string specified by pstr ignoring strings that cross paragraph 
boundaries. The search starts at the selected region. 


The search mode is specified by the ored combination of flags in f1ags: 
EWP_CASESENS case sensitive matching: by default the matching is case insensitive. 


EWF_BACKWARDS search from the current cursor position moving towards the start of the document: by 
default the search moves towards the end of the document. 


Senses the length and start position of the select region by sending an s1_GET_SELECT message to 
edwin.scrimg. 


Senses the length of the document excluding the terminating zero by sending an EP_SENSE_LEN message to 
edwin.doc. 


If no selected region exists, starts the search from the current cursor position. 
If a selected region exists, starts the search from the position shown in the following picture: 


start of backward search 


an example sentence with akeeimculast included 


| 


start of forward search 


Since the search selects the first matching string the above ensures that repeated searches do not locate the 
same matching string, i.e. the method effectively supports find next. 


Starts the search for the first occurence of the required string. 


On success selects the matching text moving the cursor to the beginning or end of the selected region 
depending on the search direction by sending s1_Move_cURSOR messages to edwin.scrimg. Returns TRUE. 


On failure returns ranss. The cursor position remains unchanged. 


_ Replace select 
INT ew_replace (TEXT *replace, INT backwards) ; 


Replace the text in the selected region with that specified by repiace: the cursor is moved to the start (end) 
of the selected region if backwards is TRUE (FALSE). 


If edwin. flags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message is TRUE, 
calls hBeep then p_leave with RUN_ACTIVE_USED as argument. 


Inserts the replace string before the selected region by sending an EP_INSERT message to edwin. doc: the 
message is sent using p_entersend and on error the method sends an Ew_LEAVE message sent to self with 
the return value as argument. 


Deletes the selected region by sending an EP_DELETE message to edwin. doc. 


eS 
10 - 20 


10 TEXT EDITORS 


Cancels any selected region and moves the cursor to the end (start) of the inserted text if backwards is 
FALSE (TRUE) by sending an st_MovE_CuRSOR message to edwin. scrimg. 


Writes the cursor position to edwin.cpos. Writes EW_CHANGE to edwin. change. 
Rebuilds the layout and redraws the view by sending an st_poc_CHANGED message to edwin.scrimg. 


Confirms success by returning zero. 


é an expression 


VOID ew_evaluate (VOID) ; 


Evaluate an expression: the expression is assumed to be selected or, if no region is selected, the cursor is 
assumed to indicate the position of an expression. 


If edwin. flags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message is TRUE, 
calls hBeep then call p_leave with RUN_ACTIVE_USED as argument. 


Otherwise obtains the length and the position of the start of the selected region by sending an 
SI_GET_SELECT message to edwin. scrimg. If no region is selected attempts to select an expression as 
follows: 


¢ moves the cursor towards the start of the document until it is positioned immediately before a 
word - i.e. a continuous sequence of characters containing no spaces or paragraph delimiters: the 
method sends an EP_SCAN_WORD message to edwin.doc and an SI_MOVE_cURSoR to edwin. scrimg. 


e — selects the word - i.e. the candidate expression - moves the cursor to the end of the word and 
scrolls the view until the cursor is visible: the method sends an st_Move_cuRsoR message to 
edwin.scrimg and an EP_SCAN_WORD message to edwin. doc. 


¢ — obtains the length and start of the word by sending an st_GET_SELECT message to edwin. scrimg 


If no region is selected displays the text message specified by the sys_NOTHING_To EVAL system resource 
using the hInfoPrint utility routine. On English language machines this is "Nothing to evaluate". Returns. 


If the selected region contains more than 254 characters, displays the text specified by the 
SYS_TOOLONG_TO_EVAL System resource using the hInfopPrint utility routine. On English language 
machines this is "Too long to evaluate". Return. 


Copies the content of the selected region to a text buffer by sending an EP_ExTRACT message to edwin.doc 
and replaces all occurences of oxoo with a space - i.e.''. 


Evaluates the expression in the text buffer by sending a ws_EVALUATE message to w_ws. 
If the return value is less than zero indicating successful evaluation: 


© — inserts at the current cursor position an equals sign followed by the result of the evaluation by 
sending an EP_INSERT message to edwin.doc. The message is sent using p_entersend: on error 
sends self an EW_LEAVE message with the return value as the argument. 


¢ writes EW_CHANGE to edwin. change and rebuilds the layout and the view by sending an 
SI_FWD_CHANGE message to edwin. scrimg. 


e — selects the expression and the equals character and moves the cursor to the end of the selected 
region by sending s1_MoVE_CURSOR messages to edwin.scrimg. Writes the cursor position to 
edwin.cpos. The view is scrolled until the cursor is visible. 


Otherwise: 


¢ moves the cursor to the position in the expression where the error was detected by the 
WS_EVALUATE message and cancels any selected region by sending an st_MovE_CURSOR message to 
edwin.scrimg. The view is scrolled until the cursor is visible. 


10-21 


HWIM REFERENCE 


WHREPLACE CLIP Copy select to clipboard 
INT ew_replace_clip (VOID) ; 

Replace the text in the clipboard with the text in the selected region. 

Obtains the length and start of the selected region by sending an st_cET_SELECT message to edwin. scrimg. 
If no region is selected returns zero. 


Deletes the content of the clipboard excluding the terminating zero by sending an EP_cLEAR message to 
edwin.clip. 


Inserts the content of the selected region in the front of the clipboard by sending an EP_copy_To FRONT 
message to edwin. doc. 


Returns the number of characters copied. 


INT ew_paste_clip(VOID) ; 


Paste the content of the clipboard into the document at the current cursor position: the pasted text is 
selected and the cursor moved to the end of the selected region. 


If edwin. flags Contains PR_EDWIN_READONLY and the return value from an EW_READONLY message is TRUE, 
calls hBeep and then call p_leave with RUN_ACTIVE_USED as argument. 


If the clipboard is empty returns Fass - the length of the clipboard text excluding the terminating zero is 
sensed by sending an Ep_SENSE_LEN message to edwin.clip. 


Inserts the clipboard text into the document at the current cursor position and sets the cursor to the end of 
the inserted text by sending an Ep_pasTE message to edwin.doc. Note that the message is sent using 
p_entersend: on error send self an EW_LEAVE message with the return value as the argument. 


Writes the cursor position to edwin.cpos and writes EW_CHANGE to edwin.change. Rebuilds the layout and 
view as required by sending an s1_Fwp_CHANGE message to edwin. scrimg. 


Selects the inserted text maintaining the cursor at the end of the inserted text by sending s1_MovE_CURSOR 
messages to edwin. scrimg. 


Returms the number of characters inserted. 


INT ew_bring_in(INT pid, INT format) ; 


Insert into the document at the current cursor position one or more blocks of data of type format supplied 
by the process whose ID is pia. 


The blocks of data may each contain up to and not exceeding 256 bytes of data. 
The transaction can be terminated by sending a nuut block of data. 


If edwin. flags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message is TRUE, 
calls hBeep then p_leave with RUN_ACTIVE_USED as argument. 


The following f1ag may be set in format: 


EW_BRING_SINGLE_SHOT specifies that the method should accept only one block of data containing up 
to 256 characters 


The individual bits of format indicate the type of data: the bit index and the type of data are as follows: 
DF_LINK_PARAS insert each block of data without modification. 


otherwise add a paragraph delimiter - 0x00 -to the end of each inserted block of 
data except the last. 


10-22 


10 TEXT EDITORS 
_— eS EAT EDITORS 


DF_LINK_TABTEXT each block of data is ASCII text possibly containing tab characters. 
DF_LINK TEXT each block of data is plain ASCII text. 
(The pF_LINK_TABTEXT and pF_LINK_TExT data types are handled identically.) 


Creates an instance of the u1nxct class and initialises by sending the L1nxcu instance an LC_START 
message. 


If format contains EW_BRING_SINGLE_SHOT, requests and receives one block of data and then sends an 
LC_SToP message to the link object. 


Otherwise repeatedly requests and receives blocks of data until a nuuu block of data is received. 
The method handles each block of data as follows: 
e — gets the block of data by sending an Lc_ceT_paTa message to the link object. 


©  prepends an oxoo paragraph delimiter as required - see above - and insert the data into the 
document by sending self an EW_EP_INSERT message. 


N.B. If at any time the Ew_EP_INSERT message returns a non-zero value - indicating an error - the method 
deletes all blocks of inserted data by sending an Ep_DELETE message to edwin.doc and then sending self 
an EW_LEAVE message with as argument the non-zero return value. 


Writes the length of the document to edwin. clen and writes EW_CHANGE to edwin. change. 
Rebuilds the layout and view by sending an s1_Frwp_CHANGE message to edwin. scrimg. 


Selects the inserted text, moves the cursor to the end of the selected region and scrolls the view until the 
cursor is visible by sending s1_mMove_CURSOR messages to edwin. scrimg. Writes the cursor position to 
edwin.cpos. 


The PR_WSERV_RECEIVED_KEY flag is cleared in w_ws->wserv. flags. 
Returns FALSE. 


(Note that a more complete description of the link-paste mechanism can be found in the Link Paste chapter 
of the Object Oriented Programming Guide.) 


_ insert text 
INT ew_ep_insert (UINT pos, TEXT *buf, UINT blen) ; 

Insert blen characters from the buffer specified by buf into the document at offset pos. 

Inserts the text by sending an EP_INSERT message to edwin. doc. 


If the application needs to take special note of the insertion of paragraph terminators, this method may be 
subclassed to deal with any zeros in the buffer (a simple strategy could be to send an EP_ADD_PARA message 
to edwin.doc for each zero-terminated segment of the buffer). 


ess handling 
INT ew_return_key(INT shift); 
Non-standard Return key handling. 


The method is called from within the wn_key method - the default method retums rause indicating that 
Return keypresses are allowed. 


Subclassers may replace this method to provide the desired functionality. 


A subclass could for example constrain the document to contain a fixed number of lines and thus would 
return TRUE once the maximum number of lines had been reached. 


10 - 23 


HWIM REFERENCE 


INT ew_tab_key(INT shift) ; 
Non-standard Tab key handling. 


The method is called from within the wn_key method - the default method returns rause indicating that Tab 
keypresses are allowed. 


Subclassers may replace this method to provide the desired functionality. 


Style 


VOID ew_init_style(SCRLAY_STYLE *pstyle) ; 
The default method does nothing. 


The method is called from within the ew_init method immediately before the style specified by pstyle is 
set into property: it can be replaced by subclassers in order to modify the default initialisation style. 


INT ew_readonly (VOID) ; 

Return the read-only state of the current document. 

The default method returns TRUE. 

Subclassers may replace the method to provide the desired functionality. 


A subclasser could for example allow read-only access while in outline mode and read-write access in 
normal mode. 


PUNCTUED 


flags landlord scrimg select 
id offset scrlay change 
width doc flags 

cpos margins 
font 


PUNCTUED 


destees;: 
wn_calc_position 
wn_connect 
wn_dodraw 


destroy 
wn_visible 
lg_draw 
lg_self_check 


i ee 


ew_snuggle_insert 
wn_init ew_set_font 
wr—key ew_leave 

wn_draw ew_find 

wn_sense_ help ew_replace 
wn_set ew_evaluate 
wn_sense ew_replace clip 
wn_emphasise ew_paste clip 
1lg_set_id_pos ew_bring_in 
lg_sense_width ew_ep insert 
ew_sense_size ew_return_key 
ew_set_ size ew_tab_key 
ew_set ew_init_style 
ew_sense ew_readonly 
ew_insert 


wn_key 


wn_position 
wn_redraw 


The punctuep class provides an edit window displaying a single punctuation character. An example 
puctuation editor is shown in the following picture: 


10-24 


10 TEXT EDITORS 


Set date and time formats 
‘Date format ¢Day month year > 


‘Date separator  / 
‘Time format am-pm 
‘Time separator 


The punctuation editor is the fourth control in the above dialog and allows the user to alter the time 
separator character. The dialog is taken from the Time application. 


Class definition 
Defined in sub-category file edwin.cl (generated header file edwin.g). 


CLASS punctued edwin 
punctuation editor, one line editbox & it's a lodger 


REPLACE wn_key 


} 
Property 
None. 


Pe a Fir eS Sg | 
PUNCTUED methods 


e key input 
VOID wn_key(INT keycode, INT modifiers) ; 

Handle a keypress. 

If keycode is not a punctuation character, calls hBeep and return. 


Otherwise sets the punctuation character into the edit window by sending se1f a wn_SET message. 


10 - 25 


HWIM REFERENCE 


FLTEDIT 


destrey 

wn_cale position 
wn_connect 
wn_dodraw 


destrey 
wn_visible 
1lg_draw 


wn_position 
wn_redraw 


tge—sense—width 
lg_update 


wn_emphasise 
1g_set_id_pos 
1lg_sense_width 
ew_sense_size 
ew_set_size 
ew_set 
ew_sense 
ew_insert 


margins 
font 


ew_snuggle_insert 
ew_set_font 
ew_leave 
ew_find 
ew_replace 
ew_evaluate 
ew_replace clip 
ew_paste_ clip 
ew_bring_in 
ew_ep_ insert 
ew_return_key 
ew_tab_key 
ew_init_style 
ew_readonly 


Page size (cm) ae 


i-Pagesize Custom 
Pidth 
| ‘Height 29.70 


Orientation Portrait 


The second and third controls in the above dialog are both floating point editors with the display format set 
to fixed - i.e. a fixed number of decimal places. 


Class definition 
Defined in sub-category file /ltedit.cl (generated header file fltedit.g). 


CLASS fltedit edwin 
floating point editor; works in either general or fixed format 


REPLACE wn_init 
REPLACE wn_set 
REPLACE wn_sense 
REPLACE lg_self_check 


CONSTANTS 


{ 


FLTEDIT_MAX_CHAR 20 /* -x.xx...x (13 dec places) E-99 */ 


SE_FLTEDIT_CURRENT 0x01 
SE_FLTEDIT HIGH 0x02 
SE_FLTEDIT_LOW 0x04 


} 


10 - 26 


10 TEXT EDITORS 


ae 


TYPES 

{ 

typedef struct 
{ 
DOUBLE current; 
DOUBLE low; 
DOUBLE high; 
UBYTE vulen; 
UBYTE format; 
} IN_FLTEDIT; 

typedef struct 
{ 
DOUBLE current; 
DOUBLE low; 
DOUBLE high; 
WORD set_flags; 
} SE_FLTEDIT; 


} 


PROPERTY 
{ 
DOUBLE current; 
DOUBLE low; 
DOUBLE high; 
UBYTE point; 


/* 
/* 
/* 
/* 
/* 


current value */ 

lower bound */ 

upper bound */ 

view len, ie no. of char on display */ 
fixed no of dec places, or 0 for general */ 


current value 

lower bound 

upper bound 

which fields to set 


UBYTE format; stores #decPlaces, which determine format (fixed or general) 


} 
} 


Property 
fltedit.current the editable value. 
fltedit.low the lower limit on the editable value. 
fltedit high the upper limit on the editable value. 
fltedit.point the oe specific decimal separator character: a full stop on English language 
machines. 


fltedit. format the number of digits after the decimal point or zero indicating general format. 


SSeS a a a a a a 


FLTEDIT methods 


Initialise 


VOID wn_init (IN_FLTEDIT *init,PR_WIN *landlord) ; 


Initialise the floating point editor according to the content of the 1n_FLTeprT struct pointed to by init and 
the ID of the landlord window specified by landlord. 


Writes the country specific decimal separator character to fltedit .point. 


The 1n_FLTEDET struct is defined as follows: 


typedef struct 


{ 


DOUBLE current; /* current value */ 


DOUBLE low; /* lower bound +*/ 

DOUBLE high; /* upper bound */ 

UBYTE vulen; /* view len, ie no. of char on display */ 
UBYTE format; /* fixed no of dec places, or 0 for general +*/ 


} IN_FLTEDIT; 


10-27 


HWIM REFERENCE 
ae 


The significance of the members of the 1n_FLTzEpIT struct is as follows: 


current the initial value for the editable value. 

low the lower limit on the editable value. 

high the upper limit on the editable value. 

vulen the maximum number of characters to represent the editable value in the edit window. 

format ae number of digits after the decimal separator character or zero to indicate general 
ormat. 


Sets the current value in the edit window by supersending a wN_InIT message. 


VOID wn_set(SE_FLTEDIT *pset) ; 


Set the content of the floating point editor according to the se_FLT=DrT struct specified by pset. 
The sE_FLTEDIT struct is defined as follows: 


typedef struct 
{ 
DOUBLE current; 
DOUBLE low; 
DOUBLE high; 
WORD set_flags; 
} SE_FLTEDIT; 


The significance of the members of the sE_FLTEDIT struct is as follows: 


current the candidate editable value. 
low the candidate minimum allowed value. 
high the candidate maximum allowed value. 


set_flags see below. 


The setting is controlled by oring into the flags member of the se_FLTEp1IT struct a suitable combination 
of the following flags: 


SE_FLTEDIT_CURRENT indicates that the editable value should be set. 
SE_FLTEDIT_HIGH indicates that the upper limit should be set. 


SE_FLTEDIT_LOW indicates that the lower limit should be set. 


Converts £1tedit.current into a string representation and sets into the edit window by supersending a 
WN_SET message. 


‘Sense current value 


VOID wn_sense (DOUBLE *pdbl) ; 
Sense the current value and write the result to the pousLe specified by pab1. 


Senses the content of the edit window by supersending a wn_SENSE message. Converts the string 
representation of the editable value into a double and writes the result to *pab1. 


10 - 28 


10 TEXT EDITORS 


LG SELF CHECK Validate fields 
INT lg_self_check{VOID) ; 

Check the editable value. 

On success returm TRUE. 


If the editable value is less than 1. o£-99 displays an appropriate error message using the hInfoPrintErr 
routine and returns E_GEN_UNDER. 


If the editable value is greater than 1.o£99 displays an appropriate error message using the hinfoprintErr 
routine and returns E_GEN_OVER. 


If the editable value is not a number - 123abc for example - displays the sys_INVALID_NUM system resource 
using the hinfoprintérr utility routine and returns FALSE. 


If the editable value is less than f1tedit .1ow, writes £1tedit .low to fltedit current, displays an 
appropriate error message using the hInfoPrint utility routine - the error message is constructed from the 
SYS_OUT_OF_RANGE and sys_MIN system resources and fltedit.1low - and returns -]. 


If the editable value is greater than fltedit .high, writes £1tedit .low to fltedit .current, displays an 
appropriate error message using the hinfoprint utility routine - the error message is constructed from the 
SYS_OUT_OF_RANGE and sys_MAX system resources and f1tedit.high - and returns 1. 


Otherwise if no error detected returns TRuE. 


XEDIT 


flags landlord 
offset 
width 


current 
data 


destroy 


destroy 


wn_cale_position wn_visible 1g_sense_width 
wn_connect 1lg_draw wn_key 
wn_dodraw 1g_self_check wn_draw 
whremphasise : wn_set 

wa-key wn_sense 


wn_position 
wn_redraw 


wn_emphasise 


tge—sense—width 
ig_update 


The xeprr class provides a single line text editer suitable for entering passwords of eight characters or less. 
An example password editor is shown in the following picture: 


Set password 


‘Enter passwordyt-y-)-) Sa 


‘Confirm password 
‘Password set 


The characters typed in are indicated by the padlock symbols with the cursor position indicated by the solid 
black rectange. 


10 - 29 


HWIM REFERENCE 
ee SSeSSSSSSeeeEeSSSSSSSSSSSSSSSSSSSSSSSSSSSSSMhhhheeee 


Class definition 
Defined in sub-category file xedit.c/ (generated header file xedit.g). 


CLASS xedit lodger 

Secret editor with only 1 line of 8 chars to deal with keying in password. 
{ 
REPLACE lg_sense_width 
REPLACE wn_key process key press 


REPLACE wn_draw 
REPLACE wn_sense 


REPLACE wn_set clears/blanks the data in property 
REPLACE wn_emphasise always return false in this case 
CONSTANTS 

{ 

XEDIT_MAX_LEN 8 

} 
TYPES 


{ 


typedef struct 
{ 
TEXT *pstr; 
} SE_XEDIT; 


} 


PROPERTY 
{ 
UBYTE current; 
UBYTE width; 
TEXT data [(XEDIT_MAX LEN+2] ; 
} 
} 


Property 
xedit.current the length of the password. 
Warning: on the Series 3 this property is defined as a worn. 
xedit.width the width of a single character. 
Warning: on the Series 3 this property is not defined. 
xedit.data the password buffer containing the password - stored as a zero terminated string. 


See ee en ee ee en a i TT 
XEDIT methods 


Get required width 


INT lg_sense_width (VOID) ; 
Sense the width of the password editor. 


The method returns the width of the underscore character used in the password editor, multiplied by 
(EDIT_MAX_LEN+1). 


On the Series 3, on other machines running in compatibility mode and in a small font dialog on the 
Workabout, the character is the normal underscore (ASCII ox s¢£). In all other cases, the character is that 
specified by ws_syMBoL_PASS_UNDERLINE, defined in symbols.h. 


_Handie key input 
INT wn_key (INT keycode, INT modifiers) ; 
Handle a keypress. 


If keycode is W_KEY_DELETE LEFT, removes the last character from the password by writing zero to 
xedit .data[xedit.current] and decrementing xedit .current. Returns wN_KEY_CHANGED. 


10-30 


10 TEXT EDITORS 


Otherwise if keycode is less than oxoorr and the cursor position is less than xEDIT MAX LEN, adds the 
keypress to the password by writing keycode to xedit .data(xedit.current] and incrementing 
xedit.current. Returns wN_KEY_CHANGED. 


Otherwise calls hBeep and returns wN_KEY_NO_CHANGE. 


WN_DRAW = oy 


VOID wn_draw(VOID) ; 
Draw the password editor. 


Draws a ws_SYMBOL_PapLock character for each character of the password and an underscore character - as 
specified in the 1g_sense_width method - for the remaining characters in the display. 


If win. £1ags contains PR_WIN_EMPHASISED, draws a solid black rectangle to indicate the position of the 
cursor. 


os Sense data 
VOID wn_sense(SE_XEDIT *psense) ; 
Sense the content of the password editor and write the result to psense. 
Writes the address of the first character in xedit.data to sense->pstr. 
_ Clear password data 


VOID wn_set (VOID) ; 


Reset the password. 
Clears the password by writing zero to each element of xedit .data and writing zero to xedit.current. 


Draws the control by sending self an Lc_DRAw message. 


VOID wn_emphasise (INT flags) ; 

Emphasise the control if flags is non-zero, otherwise de-emphasise the control. 
If flags is non-zero, sets PR_WIN_EMPHASISED in win. flags. 

Otherwise clears PR_WIN_EMPHASISED in win. flags. 


Sends self an LG_DRAw message. 


10-31 


CHAPTER 11 


GAUGE CLASSES 


This chapter describes the cauce and ponzwn classes which support graphical gauge controls for use as 
components in a dialog. 


Precursors 
Familiarity with the following topics will aid the understanding of this chapter: 


e the wn and Loncer classes described in the Windows chapter of the HWIM Reference manual. 
e the picBox class described in the Dialog Boxes chapter of the HWIM Reference manual. 


Class diagram 


GAUGE 


landlord size 
offset 


width 


colour 


destroy 
wn_cale position whoinit 
wn_connect wn_visible 
wn_dodraw lg_draw 


wn_emphasise lg_self_ check 


wn_draw 


wn_init 
wn_set 
1g_sense_width 


wn_key lg_set_id_pos 
wn_position 
wn_redraw tg—sense—width 


wn_sense_help lg_update 


The Gauce class provides a graphical representation of a gauge with four segments each of which may be 
either, black, grey or white. An example of an instance of the cauce class used as a component in a dialog 
is shown in the following picture: 


11-1 


HWIM REFERENCE 


Memory 512K 
8 Internal disk 293K OFree 189K 


Previous 


a 


The above example uses three segments to indicate the usage of memory: the width of the fourth segment 
is set to zero. This dialog may be obtained by selecting the Memory info menu item in the system screen. 


See also the ponewn class described in a later section of this chapter. 
Class definition 
Defined in sub-category file gauge.cl (generated header file gauge. g). 


CLASS gauge lodger 
Gauge Display with 3 colour graphical representation 


REPLACE wn_init Set item Dead and centre & setup landlord 
REPLACE wn_set Sets up the colour and size of each section of gauge 
REPLACE lg_sense_width Return min possible width for gauge 
REPLACE wn_draw Draws the gauge 
CONSTANTS 

{ 

GAUGE_WHITE 1 

GAUGE_GREY 2 

GAUGE_BLACK 3 

} 
TYPES 


{ 


typedef struct 


{ 

UWORD size[4]; 
UBYTE colour [4] ; 
} SE_GAUGE; 


} 


PROPERTY 


{ 
UWORD size[4]; 
UBYTE colour [4] ; 
} 

} 


Property 
gauge.size an array of four elements each of which defines the width of a gauge segment. 


gauge.colour an array of four elements each of which defines the colour of a gauge segment. 
Available colours are GAUGE_WHITE, GAUGE_GREY and GAUGE_BLACK. 


SSS = ee ee er ry 
GAUGE methods 


lnitialise 
VOID wn_init (SE_GAUGE *par,PR_WIN *landlord) ; 
Initialise the gauge to appear as a dead and centred component in the window with id landlord. 


Writes landlord to lodger. landlord and sets DLGBOX_ITEM_ CENTRE and DLGBOX_ITEM_DEAD in the 
landlord flags property by sending a pL_sET_ITEM_FLAGS message to lodger. landlord. 


The par argument is included for use by subclassers: a replacement method might, for example, supersend 
a WN_INIT message and then send a w_SET message with initial values for the segment widths and colours 
as specified in the se_GaucE struct. 


11-2 


11 GAUGE CLASSES 


_ Set characteristics of gauge sections 
VOID wn_set(SE_ GAUGE *pset) ; 
Set the appearance of the gauge according to the content of the sz_Gauce struct with address pset. 


Scales the segment sizes specified in the s_Gavuce struct such that the gauge has width lodger. width. 
Writes the scaled sizes and the colours from the se_caucE struct to the gauge. size and gauge .colour 
property respectively. Draws the lodger window by sending an uc_praw message to self. 


INT lg_sense_width(VOID) ; 


Return the minimum width for the gauge. 


VOID wn_draw(VOID) ; 
Draw the gauge component in the lodger window. 


The gauge has height eight pixels on the Series 3 and thirteen pixels on the Series 3a and width 
lodger .width on both machines. The relative widths and the colours of the gauge segments are as 
specified by the last wn_sET message. 


DONEWN 


landlord size 
offset colour 
width 


destroy wn_draw 
wn_calc_ position wrh-init wn_init 
wn_connect wn_visible wh-set 
wn_dodraw 1lg_draw lg_sense_width 
wn_emphasise 1ig_self_check 
wn_key lg_set_id_pos 
wn_position 
wn_redraw ig—sense—nidth 
wn_sense_help lg_update 
wa-visible 


The povewn class supports a graphical gauge that can be used as a component in a dialog or ina 
compatible subclass of the Lopcsr class. An example of a ponewn gauge is shown in the following picture: 


Further examples can be obtained by selecting the Format disk and Copy disk commands from the Series 3 
system menu. 


11-3 


HWIM REFERENCE 
SSS 


The dialog shown in the picture above can be created using the following resources: 


RESOURCE ACLIST_ARRAY replace_ac 


{ 


button= 
{ 
PUSH_BUT 
{ 
keycode=W_KEY_ESCAPE; 
str="Cancel"; 
} 
}; 
} 


RESOURCE DIALOG replace_di_res 


{ 


title="DONEWN gauge demonstration"; 
flags=DLGBOX_NOTIFY_ESCAPE|DLGBOX_RBUF_FILLED; 
controls= 
{ 
CONTROL 
{ 
class=C_DONEWN; 
} 7 
CONTRO 


{ 
class=C_ACLIST; 
info=ACLIST 


{ 


rid=replace_ac; 


es 


~ 
— 


} 
Class definition 
Defined in sub-category file donewn.cl (generated header file donewn.g). 


CLASS donewn gauge 
{ 
REPLACE wn_set 
CONSTANTS 
{ : 
SE_DONEWN_RANGE Ox01 
SE_DONEWN_VALUE 0x02 
SE_DONEWN_INCREMENT 0x04 /* val will be increased by 1 */ 
SE_DONEWN_INC_VAL 0x08 /* val will be increased by whatever val is set */ 


} 


TYPES 

{ 

typedef struct 
{ 
UWORD flags; 
ULONG val; 
ULONG range; 
} SE_DONEWN; 


} 


PROPERTY 


{ 


ULONG val; 
ULONG range; 


} 


11-4 


11 GAUGE CLASSES 


Property 
donewn. val specifies the relative width of the first segment. This segment has colour grey. 


donewn.range _ specifies the relative width of the gauge display. The second segment has colour white 
and relative width range-val. 


DONEWN methods 


Set gauge 
VOID wn_set (SE_DONEWN *pset) ; 
Set the gauge according to the content of the sz_ponewn struct with address pset. 
The sE_Donewn struct is defined as follows: 
typedef struct 

ULONG flags 

ULONG val 

ULONG range 


} SE_DONEWN; 


The property to be set is specified by oring one or more of the following flags into the flags member of 
the above struct. 


SE_DONEWN_RANGE indicates that donewn. range should be set from member range 
SE_DONEWN_VALUE indicates that donewn.vai should be set from member val 
SE_DONEWN_INCREMENT indicates that donewn. vai should be incremented by one unit 
SE_DONEWN_INC_VALUE indicates that donewn.val should be incremented by member val 


Note that donewn.val is assumed to be less than or equal to donewn. range. Whenever this is not the case, it 
will be set equal to donewn. range. 


For the third and fourth segments, writes zero to the size and caucz_sxacx to the colour property. These 
segments will thus not be visible. 


Sets the values into the superclass property by supersending a wN_sET message. 


Using Gauges 


The following section includes examples of dialogs containing caucE and ponEwn controls. See also the 
gauge example code that can be installed from the SDK Optional disk into a \sibosdk\hwimdemo\ directory. 


A GAUGE class example 


The first example illustrates the use of the caucE class as a dialog component. The example dialog simply 
contains a title and a cauce control. 


The initial appearance of the cauce control is set by passing an appropriately initialised sz_Gaucs struct to 
the dialog on creation. 


The structure and content of the dialog is specified using the following dialog resource: 


11-5 


HWIM REFERENCE 
SESS 


RESOURCE DIALOG gauge_dl_res ( 


{ 


title="GAUGE demonstration"; 
£lags=DLGBOX_NOTIFY_ESCAPE|DLGBOX_RBUF_FILLED; 
controls= 


{ 


CONTROL 


{ 


class=C_GAUGE; 
} 
}; 
} 


The caucepte dialog class subclasses picBox and replaces the d1_dyn_init method to allow dynamic 
initialisation of the dialog. The caucepte class is defined as follows: 


CLASS gaugedlg dlgbox 


REPLACE dl_dyn_init; 


} 
The code for the a1_dyn_init method is as follows: 


METHOD VOID gaugedlg_dl_dyn_init (PR_GAUGEDLG *self) f 


{ 


p_sendé4 (self, WN_SET,1,self->dlgbox.rbuf) ; 


The dl_dyn_init method does no more than set the caucE control using the sE_caucE struct pointed to by 
self->dlgbox.rbuf. 


The following code may be used to launch the dialog: 


LOCAL_C INT LaunchDial(VOID *buf,INT id, INT class) 


{ 


DL_DATA dl_data; 


dl_data.id=id; 

dl_data.rbuf=buf; 

dl_data.pdlg=NULL; 

return (p_sends (w_ws,O_WS_DO_DIAL,p_getlibh(CAT_DEMO_DEMO) , class, &dl_data)); 


} 


SE_GAUGE se_gauge; 
/* set the members of se_gauge as appropriate */ 


LaunchDial (&se_gauge,GAUGE_DL_RES,C_GAUGEDLG) ; 


A DONEWN class example 


The second example illustrates using the ponswn class as a dialog control to inform the user of memory 
usage. 


The initial appearance of the ponewn control is specified by means of an sE_ponewn struct passed to the 
dialog on creation. 


The structure and content of the dialog is specified by the following dialog resource: 


RESOURCE DIALOG gauge_dl_res 
{ 
title="DONEWN demonstration"; 
flags=DLGBOX_NOTIFY_ESCAPE|DLGBOX_RBUF_FILLED; 
controls= 


{ 


CONTROL 
{ 
class=C_DONEWN; 
} 
hi 


11-6 


11 GAUGE CLASSES 
_—_—_ SS Ow CAGE CLASSES 


The ponent dialog class subclasses pigBox and replaces the d1_dyn_init method to provide application 
specific initialiation. The caucepue class and the d1_dyn_init method are defined as follows: 


CLASS donedlg dlgbox 


{ 


REPLACE dl_dyn_init; 


} 


RESOURCE STRING 


{ 


str="Memory used is %d Kbytes"; 


} 


METHOD VOID donedlg_dl_dyn_init(PR_DONEDLG *self) 


{ 


TEXT buf [DONEDLG MAX TITLE] ; 


hAtob (&buf [0] , DONEDLG_TITLE_RES, self->dlgbox.rbuf->val) ; 
hDlgSetText (0, &buf [0]); 
p_send4 (self, WN_SET,1, self->dlgbox.rbuf) ; 


The dl_dyn_init method initialises the text in the title and the segment in the gauge according to the 
content of the sE_DonEwn struct pointed to by digbox. rbuf. 


The dialog may be launched as follows: 
SE_DONEWN se_donewn; 
/* set the members of se_donewn as appropriate */ 


LaunchDial (&se_donewn, GAUGE_DL_RES,C_GAUGEDLG) 


where the LaunchDia1 utility routine is defined in the previous section. 
A dynamic gauge 


A common use of the ponewn class is to inform the user of the progress of a lengthy operation: the length of 
the shaded region of the gauge - which is initially set to zero - is simply incremented after the completion 
of each step of the operation. 


This may be done by simply queueing a suitable active object before launching the dialog by sending a 
wWS_DO_DIAL message to the wsERv object. The active object will run as soon as the dialog is visible: the 
WS_DO_DIAL Message Causes an AM_START message to be sent to the application manager thus giving an 
opportunity to all queued active objects to run. This opportunity to run is cancelled by the dialog when on 
terminating it sends an am_sTop message to the application manager. 


In the example, a lengthy operation is simulated by an active object that does no more than queue a timer 
and then update the gauge control in the dialog. 


An example dynamic gauge is shown in the following picture: 


Loading data 


Cancel 


Sa 


The active object and the dialog are launched as follows: 


ULONG duration; 
duration=100; /* tenths of a second */ 
£_newsend (CAT_DUMP_DUMP,C_ATIMER,O_AO INIT, &duration) ; 
LaunchDial (&duration,GAUGE_DL_RES,C_GAUGEDLG) ; 
where duration specifies the length of the operation in tenths of a second. 


The initial content and appearance of the dialog are specified by means of the following resources: 


ee 
11-7 


HWIM REFERENCE 
SS 


RESOURCE ACLIST_ARRAY escape_ac 


{ 
button= 
{ 
PUSH_BUT 
{ 
keycode=W_KEY_ESCAPE; 
str="Cancel"; 
} 
}; 
} 


RESOURCE DIALOG gauge_dl_res 


{ 


£lags=DLGBOX_NOTIFY_ENTER |DLGBOX_RBUF_FILLED; 
controls= 


{ 


CONTROL 


{ 


class=C_TEXTWIN; 
£lags=DLGBOX_ITEM_CENTRE | DLGBOX_ITEM_DEAD; 
info=TXTMESS 


{ 
flags=IN_TEXTWIN_AL CENTRE; 
str="Loading data"; 
}; 
} 7 


CONTRO: 


{ 


class=C_DONEWN; 


}, 


CONTROL 


{ 


class=C_ACLIST; 
info=ACLIST 


{ 


ridsescape_ac; 


}y 


}; 
} 


The GaucEpuc class subclasses pi¢cgox and replace the d1_dyn_init method to allow dynamic initialisation 
of the dialog. The caucepusc class is defined as follows: 


CLASS gaugedlg dlgbox 


REPLACE dl_dyn_init 


} 


The code for the dl_dyn_init method is as follows: 


METHOD VOID gaugedlg dl_dyn_init (PR_GAUGEDLG *self) 


{ 


SE_DONEWN se_donewn; 


se_donewn.val=0L; 

se_donewn.range=* (ULONG *)self->dlgbox.rbuf; 
se_donewn . flags=SE_DONEWN_RANGE|SE_DONEWN_VALUE; 
p_send4 (self,O_WN_SET,1,&se_donewn) ; 


} 


The di_dyn_init method does no more than set the initial value and the range of the pongwn control. 


The arimer class provides the active object which updates the gauge every one tenth of a second. After the 
elapse of a predetermined interval the active object destroys both itself and the dialog. The arrmer class is 
defined as follows: 


11-8 


11 GAUGE CLASSES 


eo eee ON OD ES 


CLASS atimer timer 


{ 


REPLACE ao_init 
REPLACE ao_run 
REPLACE ao_queue 
PROPERTY 


{ 


ULONG count; 
ULONG total; 


} 
} 


The code for the ac_queue method is as follows: 


METHOD VOID atimer_ao_queue(PR_ATIMER *self,UINT lsw,UINT msw) 


{ 


self->active.stat=E_FILE_ PENDING; 
self->active.isactive=TRUE; 
p_supersend4 (self,O AO QUEUE, 1sw,msw) ; 


} 


The ao_queue method queues a timer the duration of which is specified as a long integer broken down into 
the least significant word - 1sw - and the most significant word - msw. 


The code for the ac_init method is as follows: 


METHOD VOID atimer_ao_init (PR_ATIMER *self,ULONG *ptotal) 


{ 

p_send3 (w_am,O_AM_ADD_TASK,self) ; 
self->active .priority=PRIORITY_ACTIVE_WSERV-1; 
self->atimer.count=0L; 
self->atimer.total=*ptotal; 

p_supersend2 (self,0_ AO INIT); 

p_send4 (self,O_AO_QUEUE,1,0); 


The ao_init method carries out the following actions: 


e adds se1¢ to the task queue, and sets the task priority to PRIORITY_ACTIVE_WSERV less one, to 
ensure that the timer does not interfere with keypresses. 


e — sets the initial count and stores the total duration. 


© opens a timer channel by supersending an ao_1nzT message and then queues a timer. 


The code for the ao_run method is as follows: 


METHOD INT atimer_ao_run(PR_ATIMER *self) 


{ 


SE_DONEWN se_donewn; 


if (w_ws->wserv.dial) 
{ 
self->atimer.count++; 
se_donewn. flags=SE_DONEWN_INCREMENT ; 
p_send4 (w_ws->wserv.dial,O_WN_SET,1,&se_donewn) ; 
if (self->atimer.count<self->atimer.total) 
{ 
p_send4 (self,O_AO QUEUE,1,0) ; 
return (RUN_ACTIVE_USED) ; 


} 


else 
p_send2 (w_ws->wserv.dial,O_ DESTROY) ; 
} 


p_send2 (self,O_ DESTROY) ; 
return (RUN_ACTIVE_USED) ; 


} 
The ao_run method carries out the following actions: 


e — if the dialog does not exist - i.e the user has pressed the Escape key - it sends self a DESTROY 
message and returns RUN_ACTIVE_USED. 


a SSSFSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSeeeeEeEeee 
11-9 


HWIM REFERENCE 
aS ee 


© if the maximum allowed number of timers has been reached, it sends pesTRoy messages to self 
and to the dialog and then returns RUN_ACTIVE_USED. 


e — otherwise it increments the cauce control display and queues the next timer. 


Annotating a gauge 


The following section illustrates a convenient means of labelling a gauge control The following example 
dialog indicates the current memory usage: 


Memory usage 


8 Total used 188K O Free 412K 


The second item is a TexTwrn control with appropriate text set for the prompt and the body text. 
On the S3a the following resource may be used to create the above dialog: 


RESOURCE STRING used_kbytes res 


{ 


str="%tc Total used %1luK"; 


} 


RESOURCE STRING free_kbytes_res 


{ 


str="%c Free %luk"; 


} 


RESOURCE DIALOG demo_dl_res 


{ 


£lags=DLGBOX_NOTIFY_ENTER |DLGBOX_RBUF_FILLED; 
title="Memory usage"; 
controls= 


{ 


CONTROL 


{ 


class=C_TEXTWIN; 
£lags=DLGBOX_ITEM_DEAD; 
prompts" "3 
info=TXTMESS 
{ 
flags=IN_TEXTWIN_AL RIGHT; 
}; 
} 7 


CONTROL 


{ 


class=C_DONEWN; 
} 
}i 
} 
Note that the prompt for the r=xTwrn control is defined as a space in order that the prompt may be 
redefined dynamically. 


The pemopxe class subclasses the piGsox class and replaces the di_dyn_init method to allow dynamic 
initialisation of the dialog. The pemonte class is defined as follows: 


CLASS demodlg digbox 


{ 


REPLACE dl_dyn_init 


} 


The code for the dl_dyn_init method is as follows: 


11-10 


11 GAUGE CLASSES 


OO hr rrr — OE ES 


METHOD VOID demodlg_dl_dyn_init (PR_DEMODLG *self) 


{ 

TEXT buf [40] , resbuf [40] ; 
ULONG free; 

ULONG used; 


p_send4 (self,O_WN_SET,2, (SE_DONEWN *)self->dlgbox.rbuf) ; 
used=((SE_DONEWN *) self->dlgbox. rbuf) ->val; 

p_send4 (w_am,O_AM_LOAD_RES_BUF,USED_KBYTES_RES, &resbuf [0] ); 
p_atos (&buf [0] ,&resbuf [0] ,WS_SYMBOL_GREY_BOX, used) ; 
hDlgSetPrompt (1, &buf [0] ) ; 

free=((SE_DONEWN *) self->dlgbox. rbuf) ->range-used; 

p_send4 (w_am,O_AM_LOAD_RES_BUF,FREE_KBYTES RES, &resbuf [0]) ; 
p_atos (&buf [0] ,&resbuf [0] ,WS_SYMBOL WHITE_BOX, free) ; 
hDlgSetText (1, &buf [0] ); 


} 


The method carries out the following actions: 


sets the ponEwn control using the sz_ponewn struct pointed to by digbox. rbuf. 
sets an appropriate prompt for the TexTwrn control indicating the memory usage. 


sets an appropriate body text for the TExtTwin control indicating the free memory. 


The following code may be used to run the dialog: 


METHOD VOID democom_com_run(PR_DEMOCOM *self) 


{ 


SE_DONEWN se_donewn; 


se_donewn.val=100L; 

se_donewn.range=512L; 

se_donewn. flags=SE_DONEWN_VALUE|SE_DONEWN_RANGE; 
LaunchDial (&se_donewn, DEMO_DL_RES,C_DEMODLG) ; 


} 


where the hLaunchDial utility routine is defined in an earlier section. 


On the Series 3 boxes may be constructed as follows: 


a grey box may be constructed by concatenating the ws_symBoL_GREY_Boxi and 
WS_SYMBOL_GREY_BOx2 characters. 


a white box may be constructed by concatenating the ws_syMBOL_WHITE_Box1 and 
WS_SYMBOL_WHITE_BOx2 characters. 


a black box may be constructed by concatenating the ws_symMBoL_BLACK_Box1 and 
WS_SYMBOL_BLACK_Box2 Characters. 


11-11 


? 8 


CHAPTER 12 


FILE SELECTORS 


This chapter documents some of the classes associated with the filing system. These classes are: 
e the vanev class which creates and stores a list of the available devices. 
e the pacxseE class which provides a dialog contro! that allows the user to select a pack. 
e the rneprt class which provides a dialog control that allows the user to edit a path and a filename. 


e and the rnsELwn class which provides a dialog control that allows the user to select an existing 
file. 


For a description of the FrLELrsrt class - which supports the graphical file list - see the FILELIST chapter 
of the HWIM Reference manual. 


Precursors 
Familiarity with the following topics will aid the understanding of this chapter: 


e the varoor and related classes described in the Variable Array Classes chapter of the OLIB 
Reference manual. 


VADEV 


size 
gran 
base 
len 
recno 
precno 


destroy va_copy 
va_count va_reclen 
va_delete Varnie 


va_init 
va_search 


va_pbuf 


va_sort 
va_key va_swap 
va_findisq va_init 


va_insertisq 
va_append 
va_insert 
va—seareh 


va_compare 
va_reset 
va_test 


va_compress 
va_capacity 
va_deletem 
va_insertm 
va_prec 


va-pbut 


The vapev class may be used to create a list of available devices stored as variable length text records. The 
class provides methods to search for a device and to retrieve the public device name. 


12-1 


HWIM REFERENCE 
ee SSS 


The list may be updated by simply creating a new instance of the class. 

An application that wishes to use the vapev class should ensure that: 
e the application manager creates an instance of the cLEanup class during initialisation. 
e the application manager property is stored in the w_am magic static. 

Both of the above conditions are satisfied by the Hwrmman application manager class. 


Class diagram 


Class definition 
Defined in sub-category file files.cl (generated header file files.g). 


CLASS vadev vastr 


{ 

REPLACE va_init 
REPLACE va_search 
REPLACE va_pbuf 
PROPERTY 


TEXT buf [20]; 
} 


Property 


vadev. buf contains the public device specification written by the last va_psur message. If a vA_PBUF 
message has not been sent since instantiation the buffer contains the nuxt string. 


CEE I era ee ee ee a ee er 
VADEV methods 


VOID va_init (VOID) ; 


Scan the available devices and for each create a record containing a device specification with format 
node::device:. 


The first record specifies the local internal device: Loc: :m:. 


VA_SEARCH 


INT va_search(TEXT *target) ; 


Return the index of the record that matches the device specification pointed to by target. 


The device specification pointed to by target may omit the trailing colon thus obeying the format 
node: :device. This is not recommended as it increases the time required to locate the record. 


On failure return 1. 


VA_PBUF | Return public device specification 
TEXT *va_pbuf (UWORD num) ; 
Return a pointer to the public name of the device specified in record num. 


For the local internal device the public name is read from the sys_pEvrce_mEMoRY system resource. On 
English language machines it is "Internal". 


12-2 


2 FILE SELECTORS 


For all other local devices the public name for a device with specification Loc: : device: is device. (Thus the 
public form of oc: :a: is a.) 


For all other devices the public name is identical to the device specification. 


PACKSEL 


desteey 


landlord 
offset 
width 


wn_cale_positio 


n 
wn_connect 


wn_visible 
lg_ draw 


matcher 
matchlen 
nsel 

pop 


destroy 
1lg_sense_width 
wn_draw 
wn_emphasise 


PACKSEL 


filsel 
err 


wn_init 
wn_set 
wn_key 
lg_self_check 


wn_dodraw 


tg—seif—eheek 
lg_set_id_pos 


ig—sense—width waaset 


wn_position = 
lg_update 


wn_redraw 
wn_sense_help 


The pacxsex class implements the pack selector control which allows the user to select the required device 
from the available list. The selection may be changed using the left and right arrow keys, first letter 
matching, or by pressing the Tab key to obtain a pop-out menu. An example pack selector control is shown 
in the following picture: 


Open .pic file 
‘Name Dtedit 


¢Internal+ 


Both the file name editor and file name selector controls may include a pack selector simply by oring the 
DLGBOX_ITEM_NEEDS_Pack flag into the £1ags member of the contro resource as follows: 


RESOURCE DIALOG demonstration 
{ 
title="Open .pic file"; 
£lags=DLGBOX_NOTIFY_ENTERDLGBOX_RBUF_ FILLED; 
controls= 
{ 
CONTROL 
{ 
class=C_FNSELWN; 
flags=DLGBOX_ITEM_NEEDS_PACK; 
prompt=""; 
info=FNSELWN 
{ 


fname="Dtedit.pic"; 


}; 


12-3 


HWIM REFERENCE 


Class diagram f 


~~. ta ia ~~ t beat 
- $ ed i Cae: é mt ie: 
: > (7 Ghiist >  _|/ packsel™> fnedit ~> 
‘ / d i aes ; 
‘Ss. mt a hy . f _ O a { 
me 1 me n ~~ 1 ~~ iN “~~ 1 
. } : : . ‘ } 
‘ a weer” y ye eee! 4 wa ee! oa meee y [yatta tee 
wee tee Se Cannel eae 
“a oi mae, % Serer ae poss cel ewe 
 Nates > vmatcher>  vadev > 
8 : ¢ ‘ f ‘a 
Se 1 Nee ee, y ee ! 
, aie ae i \ eet? its See 
otal tee. ao ase Nn eee A asee 
/ listbox > 


Class definition 
Defined in sub-category file files.cl (generated header file files.g). 


CLASS packsel chlist 


{ 


REPLACE wn_init build data to pass on to chlist 
REPLACE wn_set convert text to nsel item f 
REPLACE wn_key notify filsel of any changes \ 
REPLACE lg _self_check checks whether drive is empty 
CONSTANTS 
{ 
PR_CHLIST_PACKSEL_DODINFO 0x8000 
} 
PROPERTY 
{ 
PR_LODGER *filsel; fnedit or fnselwn 
WORD err; result of last dinfo on self 
} 
} 
Property 
packsel.filsel — this must contain the handle of an instance of either the rweprt class or the rnsELWN 
class. 
packsel.err this is a code giving the error status of the current device. It is obtained by calling the 


p_dinfo PLIB routine. 


Sy ee ee a ye 
PACKSEL methods 


VOID wn_init (TEXT *init,PR_WIN *landlord,PR_LODGER *filsel) ; 


Initialise the pack selector according to the landlord window ID specified by 1andlora and the handle of an 
instance of either the rwepzrt class, or the rNsELwn class, specified by filsel. 


Writes landlord to lodger. landlord. 
Writes £i1sel to packsel. filsel. 


The class uses a vapEV component to store the names of the available devices: creates an instance of the 
VaDEV Class, writes the handle to chiist .data and then initialises the vapzv component by sending a 
VA_INIT message to chlist.data. 


Note that the init argument is not used. 


12-4 


12 FILE SELECTORS 


Str oo er re ~ Set pack from file name 


INT wn_set (TEXT *pset,P_FPARSE *pcrk) ; 


Set the current pack. 


The pset and perk arguments are assumed to point to a full file specification and an associated p_FPARSE 
struct respectively: sets the current device according to the device specified by the arguments. 


If chiist .flags contains PR_CHLIST_PACKSEL_DODINFO: 


e obtains an error code for the current device by calling the p_dinfo pLzB routine and writing the 
return value to packsel.err. 


Returns packsel.err. 


INT wn_key (INT keycode,INT modifierss) ; 


Handle a keypress. 
Allows the superclass to handle the keypress by supersending a wn_KEy message. 


If the return value from the wn_key message is wN_KEY_CHANGED - in which case the current device has 
changed - displays the information message in the sys_SCANNING system resource: on English language 
machines this is "Scanning". 


If chlist . flags contains the PR_CHLIST_PACKSEL_popinFo flag: 


e obtains an error code for the current device by calling the p_dinfo pure routine and writing the 
return value to packsel.err. 


Ensures that keypresses are not absorbed by the control by writing FALSE to dlgbox.absorb. 


Sets the current device for the associated FNEDIT or FNSELWN control by sending an LG_UPDATE message to 
packsel.filsel passing as arguments a pointer to the current device specification, and an error status: if 
chlist.flags contains PR_CHLIST_PACKSEL_DODINFo, the error status is packsel.err, and zero otherwise. 


Ensures that any information message is cancelled. 


Returns the return value from the wn_xey message. 


IS TEPC CR ATS AO 


INT lg self check (VOID) ; 
Validate the current device. 


If packsel.err is non-zero, or PR_CHLIST_PACKSEL popInFro is set in chlist. flags, obtains an error code 
for the current device by calling the p_dinfo puzs library routine and then writes the error code to 
packsel.err. 


If packsel.err is still non-zero, displays an appropriate information message, and then returns FALSE. 
If packsel.err was previously non-zero: 


e displays the information message in the sys_scanwinc system resource: on English language 
machines this is "Scanning". 


e — sets the current device for the associated FNEDIT or FNSELWN control by sending an L¢_UPDATE 
message to packsel . filsel. 


© ensures that the information message is cancelled and then returns True. 


12-5 


HWIM REFERENCE 


FNEDIT 


select 
change 
flags 
margins 
font 


destrey ew_snuggle_insert 
wn_calc_position ins int ew_set_font 
wn_connect sd ew_leave 


wn_dodraw hd ew_find 
ew_replace 
1lg_set_id_pos ew_evaluate 
wn_position ew_replace_ clip 
wn_redraw tg—sense—width : ew_paste_clip 
wn_sense_help ig_ update 1g_set_id_pos ew_bring_in 
lg_sense_width ew_ep insert 
ew_sense_size ew_return_key 
ew_set_size ew_tab_key 
ew_set ew_init_style 
ew_sense ew_readonly 
ew_insert 


wn_emphasise 
lg_self_check 
lg_update 


The repr class implements the file name editor control which allows the user to edit a file name. An 
example file name editor is shown in the following picture: 


Open .pic file 


‘Name  Dtedit 
¢ Internal> 


A file name editor may have an associated pack selector control by oring the DLGBOX_ITEM_NEEDS_ PACK 
flag into the £1ags member of the Fneprt resource as follows: 


RESOURCE DIALOG demonstration 
{ 
title="Open .pic file"; 
flags=DLGBOX_NOTIFY_ENTER | DLGBOX_RBUF_FILLED; 
controls= 
{ 
CONTROL 
{ 
class=C_FNSELWN; 
flags =DLGBOX_ITEM_NEEDS PACK H 
prompt=""; 
info=FNSELWN 
{ 
fname="Dtedit .pic"; 


); 


12-6 


12 FILE SELECTORS 


Class diagram 


ats Es artsy, ats. ® Parr i aa rs 


Om ae se ria eee Nag (Oot eee Mee, if Sa 1 te ee! oe 
’ * . S ri . a , H as : at, 
/ win > /“ lodger ©; /“ edwin > / fnedit ~> “ packsel > 
¢ ——— 7 ¢ 2 ya ng 4 u v2 it 
an ‘ : Be : SS : on \ 
1 on 4 Pe 4 Oca ‘ O-- 1 free 3%, 
(0 tt ee Sho POT tt ee fens ~~ * 
3 ac ’ ~e pardee ~ se 
vo & 7 ye? scrlay 0 ve li b 5 
eet ‘ Bison 1 a : 
SN : . i x ‘ 
H oo eee ‘ ed *, 
Not? Peele gee eee oS Le esees 
/— seri 5 


Note that an instance of the packsel class is optional. 
Class definition 
Defined in sub-category file files.cl (generated header file files.g). 


CLASS fnedit edwin 
{ 
REPLACE wn_init 
REPLACE wn_set 
REPLACE wn_sense 
REPLACE wn_key 
REPLACE wn_emphasise 
REPLACE lg self_check 
REPLACE lg update 


CONSTANTS 
{ 
IN_FNEDIT_STANDARD H_FILE_STANDARD_INIT 
IN_FNEDIT_ALLOW_DIRS | § H_FILE ALLOW DIRS 
IN_FNEDIT_JUST_DIRS H_FILE_JUST_DIRS 


IN_FNEDIT_FORCE_NXIST H_FILE FORCE NXIST 
IN_FNEDIT_NO_AUTOQUERY H_FILE_NO_AUTOQUERY 
IN_FNEDIT_ACCEPT_NULL H_FILE ACCEPT NULL 
IN_FNEDIT_SET_DEFEXT  H_FILE SET DEFEXT 
IN_FNEDIT_CAN WILDCARD H_FILE_CAN WILDCARD 


} 


TYPES 


{ 


typedef struct 
{ 
UBYTE flags; 
TEXT fname [1]; 
} IN_FNEDIT; 


} 


PROPERTY 1 
{ 
PR_LISTBOX *pop; handle of pop-out menu (NULL if un-squirted mode) 
PR_PACKSEL *pack; 
UWORD flags; 
TEXT *defext; 
TEXT extbuf [6] ; 
TEXT buf [P_FNAMESIZE] ; 
} 
} 


Property 

fnedit.pop this is either the handle of an instance of the FrLELrst class - in which case the user 
has pressed the Tab key - or wuut otherwise. 

fnedit.pack this is either the handle of an instance of the packset class or nuut if there is no 


associated pack selector control. 


fnedit.flags an ored combination of flags that specify the behaviour (see below) 


12-7 


HWIM REFERENCE 
a SSS 


fnedit.defext this is a pointer to the default file extension and points to either fnedit .but or w_am- 
>hwimman.defext. 


fnedit.extbuf this is a buffer for the default file extension. 


fnedit.buf this is the path for the current file, e.g. REM: : E: \SIBOSDK\OOPDEMO\. 


SS ee ee eS eee eer 
FNEDIT methods 


‘Initialise 
VOID wn_init(IN_FNEDIT *par,PR_WIN *landlord, PR_PACKSEL *pack) ; 

Initialise the file name editor according to the content of par- >flags. 

Writes pack to fnedit .pack. 


If par->£lags contains IN_FNEDIT_JusT_prirRs, ensures that the remaining flags are valid: sets 
IN_FNEDIT_ALLOW_DIRs, and clears IN_FNEDIT_SET_DEFEXT, IN_FNEDIT_CAN WILDCARD and 
H_FILE_CAN_TAG. 


Writes par. flags to fnedit. flags. 
Writes w_am->hwimman.defext to fnedit.defext. 


If fnedit .£1ags contains both In_FNEDIT_SET_DEFEXxT and IN_FNEDIT_STANDARD, and 
DatUsedPathNamePtr points to a file specification, copies the extension from patUsedPathNamePtr to the 
extension buffer fnedit .extbuf, and writes the address of the extension buffer to Enedit .defext. Clears 
IN_FNEDIT_SET_DEFEXT from fnedit. flags as the default extension is now set. 


Otherwise if fnedit . flags contains just IN_FNEDIT_SET_DEFEXT, and par->fname specifies a filename 
followed by an extension, copies the file extension from par->£name to the extension buffer 

fnedit .extbuf, and writes the address of the extension buffer to fneait.defext. Clears the 
IN_FNEDIT_SET_DEFEXT flag from fnedit .f1ags as the default extension is now set. 


If fnedit . flags contains IN_FNEDIT_STANDARD, builds a full file specification from DatUsedPathNamePtr, 
using the p_fparse PLIB library function, and a wuzs related file specification. Truncates the full file 
specification at the filename and write to fnedit .bué. 


Otherwise, if fnedit .f£1ags does not contain IN_FNEDIT_STANDARD, builds a full file specification from 
par->fname using the p_fparse PLIB library function, and a wutu related file specification. Truncates the 
full file specification at the filename and writes the result to fnedit .bué. 


Sets the pack by sending a wn_sET message to fnedit. pack passing as arguments fnedit . buf and the 
address of the p_Fparse struct written by the previous call to p_fparse. 


Sets the text in the edit box by supersending a wn_inrT message passing as arguments a pointer to an init 
struct and landlord, the id of the landlord window. The init struct is defined as follows: 


struct 


{ 


IN_EDWIN ed; 
TEXT buf [P_FNAMESIZE] ; 
} anit; 


If fnedit . flags Contains IN_FNEDIT_STANDARD, ed.contents [0] is set to zero. 


If fnedit .£1ags contains the 1n_FNEDIT_JUsT_pIrRs flag, par->fname is built into a full path specification, 
using the p_fparse PLIB library function, and a uu related file specification. The full file specification is 
then truncated before the trailing directory and copied to ea. contents. (Thus "Loc: :m:", 

"REM: :C:\SIBOSDK\" and "REM: :C\SIBOSDK\DEMO\" would become "Loc: :M: ", "REM::C:" and 

"REM: :C: \SIBOSDK\" respectively.) Note that the In_FNEDIT_gusT_prrs flags is ignored if par->£name 
specifies a filename. 


If neither the In_FNEDIT_STANDaRD nor the IN_FNEDIT_JuUsT_prrs flags are set, the text specified by par- 
>flags is built into a full file specification using the p_fparse PLIB library function and a wut related file 
specification, and then copied to ed. contents. 


— SSS 
12-8 


12 FILE SELECTORS 


Sets DLGBOX_ITEM_CAN_DEFER_X and DLGBOX_ITEM_X_PENDING in the dlgbox.item[] .flags dialog 
property associated with this control, and returns. 


VOID wn_set (TEXT *fname) ; 


Set file name 


Set the filename and, optionally, the default extension, according to the file specification pointed to by 
fname. 


If the first character in fname . buf is 'l', removes the first character and builds a full file specification from 
fname using the p_fparse PLIB library function, and a nutu related file specification. Writes the file 
extension to fnedit .extbuf, and truncates fname at the filename. 


Builds a full file specification from fname using the p_fparse PLIB library function, and a uuu related file 
specification, and copies the result to fnedit .buf. 


Sets the pack by sending a wn_seT message to fnedit .pack passing as arguments fnedit .buf, and the 
address of the p_Fparsz struct written by the previous call to p_fparse. 


If fnedit . flags contains IN_FNEDIT_JuST_DIRs and fnedit .buf does not specify a filename, truncates 
fnedit. buf before the trailing directory. (Thus Loc: :M:, REM: :C:\TMP\ and REM: :C\TMP\DEMO\ would 
become Loc: :M:, REM::C: and REM: :C: \TMP\ respectively.) 


Truncates fnedit .bué at the filename if present. 


Sets the full file specification into superclass property by supersending a wn_sET message. 


: name 


INT wn_sense (TEXT *fname) ; 


Write to fname the full file specification of the current directory, or non-directory, file. Thus fname should 
be a pointer to a buffer of length at least p_FNamesize. 


Senses the file name by supersending a wy_sensE message and copies the result to the buffer specified by 
fname. Builds a full file specification using the p_fparse PLIB library function, and a related specification 
of fnedit .buf. Writes the full file specification to fname. Retums the return value from the p_fparse 
function if it is non-zero. 


If the full file specification contains one or more wildcards, and the In_FNEDIT_CAN_WwILDcaRDs flag is set 
in fnedit .flags, returns -1 indicating legal use of wildcards. 


If the full file specification contains one or more wildcards, and the In_FNEDIT_CAN_WILDcaRDs flag is not 
set in fnedit. flags, returms E_FILE_NAME indicating illegal use of wildcards. 


If the full file specification contains a name, or an extension, and the 1In_FNEDIT_gusT_piRs flag is set in 
fnedit.flags, appends a delimiter character to the file specification if not already present. (Thus 

LOC: :M:\TMP and REM: :C:\TMP.Dos would become Loc: :m:\TMP and REM: :C:\TMP.Dos\ respectively.) 
Builds a full file specification using the p_fparse PLIB library function, with a nuzt related file 
specification, and returns the return value. 


If the full file specification contains a filename, and the In_FNEDIT_JUST_DIRs flag is not set in 
fnedit. flags, uses the p_fparse PLIB library function to appends the default extension in fnedit .defext 
to fnedit.buf and returns the return value. 


If the full file specification does not contain a name, and neither of the 1In_FNEDIT_ACCEPT_NULL and 
IN_FNEDIT_ALLOW_piRs flags are set in fnedit . flags, returns ERROR_RID_OFFSET-SYS_CHOOSE_FILENAME. 


INT wn_key (INT keycode, INT modifiers) ; 
Handle the keypress specified by keycode and modifiers. 


If a file selector is present and thus fnedit .pop is non-zero: 


12-9 


HWIM REFERENCE 


e allows the file selector to handle the keypress by sending a wN_KEY message to £nedit . pop with 
arguments Of keycode and modifiers. If the user selects a valid file, sets this as the current file by 
sending self a wN_SET message. If the user selects a file that for some reason is not valid, and 
fnedit .flags does not contain IN_FNEDIT_JusT_p1Rs, displays an appropriate information 
message and then returns WN_KEY_CHANGED. 


¢ otherwise if the return value from the wi_xey message is not wN_KEY_NO_CHANGE, destroys the pop- 
up file list by sending a pEstRoy message to fnedit . pop and writing FALSE to fnedit.pop. 
Emphasises the file name editor by sending a wn_EMPHASISE message to self. Returns the return 
value from the wn_KEy message. 


If keycode is a Tab, and modifiers contains the Psion modifier, displays the contents of fnedit .buf as an 
information message, and then returns wN_KEY_NO_CHANGE. 


If keycode is a Tab and modifiers does not contain the Psion modifier, senses the full file specification for 
the current file by sending a wn_SENSE message to self: 


¢ if modifiers contains the Control modifier, allows the user to edit the file name pattern and the 
full path for the current file by launching a File list dialog: if the user cancels the dialog, returns 
WN_KEY_NO_CHANGE. 


¢ presents a list of the files in the parent directory of the current file by creating an instance of the 
FILELIST Class, writing its handle to fnedit .pop, and sending a wN_INIT message to fnedit .pop. 


¢  de-emphasises the file name editor by supersending a wy_EMPHASISE message. 
¢ — ensures that the control absorbs subsequent keypresses by returning wN_KEY_ABSORB_ON. 


Otherwise lets the superclass handle the keypress by supersending a wn_KEY message, passing arguments of 
keycode and modifiers and then returns the return value. 


mphasise 


“en 


VOID wn_emphasise (INT flags) ; 
Emphasise the control. 


If fnedit .pop is non-zero, sends fnedit .pop 4 WN_EMPHASISE message passing as the argument flags. 
Otherwise supersends a wN_EMPHASISE message passing as the argument flags. 


LG _SE 


INT lg_self check (VOID) ; 


_ Validate file name 


Validate the file name. On success, return TRuE. Otherwise, display an appropriate error message, using the 
hInfoPrintErr utility function, and return raLseE. 


Sends a wN_SENSE message to se1f. If the return value is either E_FILE_NXIST, E_FILE DIR or -1, returns 
TRuE. If the return value is non-zero, displays an appropriate error message and returns FALSE. 


Otherwise performs further checks, which may lead to the hinfoPrintErr utility function displaying an 
error messsage corresponding to one of the following error codes: 


E_FILE_NAME invalid file name 

E_FILE_DEVICE invalid device name or the device does not exist 
E_FILE_DIR invalid directory name or the directory does not exist 
E_GEN_FSYS invalid file system name, or the file system does not exist 
E_FILE_NOTREADY the device does not contain a medium 

E_FILE_NXIST the file does not exist 

E_FILE_RDONLY the file is read-only 

E_FILE EXIST the file is not a directory file and tnedit . flags contains 


IN_FNEDIT_FORCE_NXIST 


12-10 


12 FILE SELECTORS 
—_— ILE SELECTORS 


ERROR_RID_OFFSET- the file is a directory file and fnedit . £1ags contains 
SYS_CHOOSE_NEW_DIRECTORY IN_FNEDIT_FORCE_NXIST 


ERROR_RID_OFFSET-SYS_CHOOSE_FILENAME the file is a directory file and fnedit . flags does not 
contain 1N_FNEDIT_ALLOW_DIRS 


ERROR_RID_OFFSET-SYS_CHOOSE_DIREcToRY _ the file is not a directory file and tnedit. flags contains 
IN_FNEDIT_JUST_DIRS 


(The error codes are produced by the p_finfo and p_testpth PLIB library routines.) 


If the file already exists, and fnedit .f1ags does not contain IN_FNEDIT_NO_AUTOQUERY, presents a query 
dialog with the sys_exIstTs_over resource. This informs the user that the file exists and asks if it should be 
overwritten. If the user confirms, returns TRUE. Otherwise returns FALSE. 


(path 
VOID lg_update (TEXT *path) ; 


Update the current path. 


Builds a full file specification from path using the p_fparse PLIB library function, and a related file 
specification of fnedit .buf, and copies the result to fnedit .buf. Sets the DLGBOX_ITEM_X_PENDING flag in 
the dlgbox.item[i] .£lags property associated with the control. 


FNSELWN 


flags landlord data 


offset flags 
width matcher 
matchlen defext 


extbuf 
ork 
buf 


nsel 
pop 


destrey 
wn_calc_position 
wn_connect 

wn_dodraw 


destroy 
wn_draw 
wn_emphasise 


destroy 

wn_init 

wn_set 

wn_sense 

wn_key 
1g_self_check 
lg_sense_width 
1lg_update 
fns_insert_tags 
fns_extract_tags 
fns_subset 
fns_validate_flist 


wn_position 
wn_redraw 
wn_sense_ help 


The rwseLwn class implements the file name choice list control which allows the user to select an already 
existing file. An example file name choice list is shown in the following picture: 


Open file 


| ¢ gelacuti> 


ie Disk Internal 


12-11 


HWIM REFERENCE 


rr 


A file name choice list may have an associated pack selector control simply by oring the 
DLGBOX_ITEM_NEEDS_PACK flag into the flags member of the rnsELww resource. For details see the 


introduction to the rneprT control. 


Class diagram 


Class definition 


Defined in sub-category file files.cl (generated header file files.g). 


CLASS £fnselwn 
{ 
REPLACE destroy 
REPLACE wn_init 
REPLACE wn_set 
REPLACE wn_sense 
REPLACE wn_key 
REPLACE lg_self_check 
REPLACE lg_sense_width 
REPLACE lg_update 
ADD fns_insert_tags 
ADD fns_extract_tags 
ADD f£ns_subset=p_dummy 
ADD fns_ validate_flist=p_true 


chlist 


CONSTANTS 
{ 
IN_FNSELWN_STANDARD 
IN_FNSELWN_SHOW_DIRS 
IN_FNSELWN_HIDE_FILES 
IN_FNSELWN_RESTRICT_LIST 
IN_FNSELWN_CAN_TAG 
IN_FNSELWN_ACCEPT_NULL 
IN_FNSELWN_SET_DEFEXT 
IN_FNSELWN_CAN WILDCARD 
PR_FNSELWN_TAGSHERE 
PR_FNSELWN_AT ROOT 
PR_FNSELWN_WILDCARDED 
PR_FNSELWN_PRESERVE_TAGS 
PR_FNSELWN_ON_DIR 
PR_FNSELWN_CHANGED_DIR 


} 


TYPES 


{ 


typedef struct 


{ 

UBYTE flags; 
TEXT fname [1] ; 
} IN_FNSELWN; 


12-12 


H_FILE_STANDARD_INIT 
H_FILE_ALLOW_DIRS 
H_FILE_JUST_DIRS 
H_FILE_RESTRICT_LIST 
H_FILE_CAN_TAG 
H_FILE_ACCEPT_NULL 
H_FILE_SET_DEFEXT 
H_FILE_CAN_ WILDCARD 
0x100 Tags in this directory 
0x200 

0x400 

0x800 

0x1000 

0x8000 


chiist es wi “inselwn ee “packsel-» 
G ‘matcher / “y J vadev >> 


12 FILE SELECTORS 
————_———— eee SELECTORS 


PROPERTY 
{ 
PR_VASTR *tags; which files are tagged 
PR_PACKSEL *pack; 
UWORD flags; 
TEXT *defext; 
TEXT extbuf [6] ; 
P_FPARSE crk; cracked information on current file 
TEXT buf [P_FNAMESIZE] ; 
} 
} 


Property 

fnselwn.tags this is either uxt or the handle of an instance of the vastr class that is used to store 
references to tagged files. 
If the instance of vastr exists, its first record contains the full path of the directory 
containing the tagged files. Each subsequent record contains the name of a tagged 
file. Note that this means that all tagged files must be in the same directory. 

fnselwn.pack this is either the handle of an instance of the pacxsst class - used to select the pack - 


Or NULL. 
fnselwn. flags an ored combination of flags that determine the behaviour of the rnsetwn instance. 
fnselwn.defext this points to the default extension. 


fnselwn.extbuf this is the default extension. 


fnselwn.crk a P_FPARSE Struct corresponding to the full file specification in fnselwn. buf. 
fnselwn.buf the full file specification of the current file. 
Tagged files 


On pressing the Tab key when an instance of rnseLwn has focus, a file list is presented (using an instance 
of FILELIsT). One or more of the file names in this list may be shown as being tagged, and tags may be set 
or cleared by using two language-dependent keypresses - on English machines, these are '+' and '-' (see the 
FILELIST wn_key method in the FILELIST Window Class chapter). 


The current list of tagged files, if any exist, is maintained in an instance of the OLIB vastr class whose 
handle is stored in fnselwn. tags. The first entry of this instance contains the full path name of the 
directory containing the tagged files and subsequent entries contain the names of the tagged files. 


The vastr instance may optionally be created by ryseLWzn on initialisation or it may be supplied 
externally, via the fns_insert_tags method. This method provides an option for the instance to remain 
under the ownership of the supplier. If this option is selected, the instance of vastr will not be destroyed 
when FNSELWN receives a DEsTRoy message. If this option is not selected, or if the instance of vastr has 
been created by rnseLwn, destruction of rnsELwn will also destroy the tagged files list. 


FE RI so FT a a ea tl 
FNSELWN methods 


Destroy 


VOID destroy (VOID) ; 
Destroy the rnsELwn instance. 


If fnselwn. flags does not contain PR_FNSELWN_PRESERVE_TAGS, and fnselwn.tags is non-zero, sends a 
DESTROY message tO fnselwn.tags. 


Supersends a DESTROY message. 


12-13 


HWIM REFERENCE 


Initialise 


VOID wn_init (IN_FNSELWN *par,PR_WIN *landlord, PR_PACKSEL *pack) ; 
Initialise the file name choice list. 


Writes landlord, the ID of the landlord window, to 1odger.landiora, and sets DLGBOX_ITEM_CAN_DEFER_X 
and DLGBOX_ITEM_x_PENDING in the dlgbox.item(i] . flags property associated with the control. Then 
writes pack to fnselwn.pack and sets PR_CHLIST_PACKSEL_DODINFO in chlist. flags. 


If fnselwn. flags contains IN_FNSELWN_HIDE_FILES, sets IN_FNSELWN_SHOW_DIRs and clears 
IN_FNSELWN_CAN_WILDCARD, IN_FNSELWN_CAN_TAG and IN_FNSELWN_SET_DEFEXT. 


Creates an instance of the vastr class and writes its handle to chlist . data. Initialises the vastR 
component by sending an va_InIT message to chlist .data specifying a granularity of 16. Requests the 
VASTR component to sort the records alphabetically ignoring case by sending a va_KEY messsage to 
chlist.data. 


Creates an instance of the vmarcuer class and writes its handle to chlist .matcher. Initialises the vMaTCHER 
component by sending an Im_InrT message to chlist .matcher. The length of the match string is stored in 
chlist .matchlen, the maximum length of the match string is 128 and the data is stored in chlist. data. 


If par->flags contains IN_FNSELWN_CAN_TAG, creates an instance of the vastr class, writing its handle to 
fnselwn.tags, and sends a vA_INIT message with a granularity of 32. 


If par->flags contains IN_FNSELWN_STANDARD, the filename is taken from patUsedPathNamePtr, otherwise 
the filename is taken from zpar->fname [0]. 


If par->flags contains IN_FNSELWN_SET_DEFEXT, a NULL file name is specified, and w_ws->wserv. flags 
does not contain pR_WSERV_FROM_HwzF, returns. In this case it is intended that the filename will be set by a 
subsequent wN_SET message. 


Otherwise, sets the extension by writing w_am->hwimman.defext tO fnselwn.defext. 
Sets the filename by sending a wn_set message to self. 


Clears the IN_FNSELWN_STANDARD flag from énselwn. flags. 


@ directo 
VOID wn_set (TEXT *fname) ; 
Set the file or non-file directory specified by fname into property. 


If the first character in fname is 'l', sets the default extension by copying the extension in fname to 
fnselwn.extbuf and returns. 


Sets PR_FNSELWN_CHANGED_DIR, and clears PR_FNSELWN_AT_ROOT in fnselwn. flags. 


Builds a full file specification from fname by calling the p_fparse PLIB library routine with a nut related 
file specification. If the device specified in fname is invalid, substitutes the default device. Writes the full 
file specification to fnselwn.buf, and the associated p_FPaRsE struct to fnselwn.crk. 


If IN_FNSELWN_SHOwW_pirs is set, and neither the filename nor the extension is specified in fname, clears 
IN_FNSELWN_SET_DEFEXT in fnselwn. flags. If the file is in the root directory, sets PR_FNSELWN_AT_ROOT in 
fnselwn. flags. Otherwise removes the trailing delimiter. 


If fnselwn. flags contains IN_FNSELWN_SET_DEFExT, and the extension in fnselwn. but is less than five 
characters long, sets the default extension by copying the extension in fnseiwn. buf to the extension buffer 
fnselwn.extbuf, and writing the address of the extension buffer to nselwn.defext. Indicates that the 
extension has been set by clearing IN_FNSELWN_SET_DEFEXT in fnselwn. flags. 


Sets the current pack according to the content of fnselwn.buf and fnselwn.crk by sending a wN_SET 
message to £fnselwn.pack. 


The remaining step is to build a list of the files in the parent directory using the BuildFileList function. 
The second argument in the call is the return value from the earlier w_seT message. The handle for the 
variable array is stored in chlist.data. 


12-14 


12 FILE SELECTORS 
—_—— EEE SELECTORS 


Building a file list 
The BuildrileList function is declared as follows: 
LOCAL _C BuildFileList (PR_FNSELWN *self, INT derr); 
It is called by the wn_set, 1g update and fns_insert_tags methods. 


Displays a scanning busy message using the sys_SCANNING system resource and the hBusyPrint utility 
function. 


Resets the list of files by sending a va_RESET message to chlist .data, and sets the selection to item zero 
by supersending a wn_seT message. Clears PR_CHLIST_SUSPENDED in chlist. flags, and clears both 
PR_FNSELWN_TAGSHERE and PR_FNSELWN_WILDCARDED in fnselwn. flags. 


If fnselwn. flags contains the IN_FNSELWN_RESTRICT_List flag, and fnselwn.buf contains both a 
filename and an extension, replaces the filename in fnselwn.buf with an asterisk character. Thus 
LOC: :M: \DIR\FILENAME.ExT would become Loc: :M:\DIR\*.EXT. 


If £nselwn. flags Contains IN_FNSELWN_CAN_TAG, and either fnselwn. flags does not contain 
IN_FNSELWN_CAN_WILDCARD, OF fnselwn.crk. flags is Zero, and fnselwn.tags contains multiple files 
sharing the path specified in fnselwn.buf, sets PR_FNSELWN_TAGSHERE in fnselwn. flags, and 
PR_CHLIST_SUSPENDED in chlist . flags, adds a record containing the sys_ FILES TAGGED system resource 
by sending a vA_APPEND message to chlist . data, sets the selection to item zero by supersending a WN_SET 
message, and returns. 


If derr is non-zero but not B_GEN_NomEMory, adds a record containing an appropriate error message by 
sending a vA_APPEND message to chlist . data, sets the selection to item zero by supersending a wn_sET 
message, and returns. 


If derr is B_GEN_NOMEMoRY, Calls p_leave, with an argument of E_GEN_NOMEMORY. 


Otherwise attempts to open a channel to the directory in fnselwn.buf using the p_open PLIB library 
function and the p_rprr mode. 


If the return value is =_GEN_NoMEMoRY, Calls p_leave, with an argument of E_GEN_NOMEMORY. 


Otherwise, if the return value is non-zero, adds a record containing an appropriate error message by 
sending a VA_APPEND message to chlist .data, sets the current selection to item zero by supersending a 
WN_SET message, and returns. 


If fnselwn. flags contains PR_FNSELWN_AT_RooT, sends a VA_APPEND message to chlist data to adda 
record containing the delimiter character which for the Series 3 filing system would be "\". 


If fnselwn.buf contains wildcards (thus fnselwn.crk. flags is non-zero) and IN_FNSELWN_CAN_WILDCARD 
is set in fnselwn.f1ags, adds a record containing the filename and extension in fnselwn. buf by sending a 
VA_APPEND message to chlist .data. Sets the selection to item zero by supersending a wn_SET message. 
Sets PR_FNSELWN_WILDCARDED in fnselwn. flags and returns. 


Otherwise reads the files in the current directory, ignoring volume name directories, and any file whose 
name starts with a full stop character. 


Directory files are considered only if 1s_FNSELWN_ALLOW_pIRs is set in fnselwn. flags. For each directory 
file, appends a delimiter character (taken from fnselwn.buf), and creates a new record containing the 
filename. 


Non-directory files are considered only if 1n_FNsELWN_susT_pIRs is clear in fnselwn. flags. For each non- 
directory file, removes the extension from the file name if and only if it matches that in tnselwn.defext, 
and creates a new record containing the filename. 


The new records are added by sending a va_aPPEND message to chlist .data, followed by a VA_INSERT 
message if a duplicate filename already exists. (Duplicate filenames may occur when scanning remote 
filing systems). 


To allow subclassers to add their own functionality the method sends a rns_suBSET message to self once 
the file list has been built. The default method does nothing. Subclassers would thus replace the 
fns_subset method with their own variant. They may wish, for example, to further restrict the file list 
according to additional application specific flags. 


12-15 


HWIM REFERENCE 
a ee 


If the number of files in the file list is zero, adds a record containing the sys_No_FILES system resource and 
returns. 


Locates the file list index of the current file by sending a va_SEARCH message to chlist.data and then sets 
the current selection by supersending a wn_sET message. 


If fnselwn. flags Contains IN_FNSELWN_STANDARD, sets the selection to item zero, unless the current file 
matches the first record and the number of records is greater than one, in which case sets the selection to 
item one. 


Otherwise sets the current selection to either the record that matches the current file, or to the first record if 
no such record exists. 


Get file name 


VOID wn_sense (TEXT *fname) ; 
Write the filename to fname. 
Senses the filename by calling the rnselwnsense function with an argument of Fase. 
The FnselwnSense function 
The rnselwnSense function is declared as follows: 
LOCAL_C FnselwnSense (PR_FNSELWN *self, INT internal) ; 
It is called by the wn_sense and wm_key methods. 


If chlist .f£lags contains PR_CHLIST_SUSPENDED, and fnselwn. flags contains any of 
PR_FNSELWN_WILDCARDED, PR_FNSELWN_TAGSHERE, OF PR_FNSELWN_AT_ROOT, copies the contents of 
fnselwn.buf to fname and returns. 


If chlist . flags contains PR_CHLIST_SUSPENDED, and internal is TRUE, copies the contents of fnselwn.buf 
to fname and returns. 


Otherwise if chlist .£1ags contains pR_CHLIST_SUSPENDED, but none of the other conditions specified 
above are satisfied, sets the first element of fname to zero and returns. 


Senses the current selection by sending a va_psuF message to chlist.data with an argument of 
chlist.nsel. 


Builds a full file specification from the current selection using the p_fparse PLIB library routine and a 
related file specification of fnselwn.buf truncated at the filename. Writes the full file specification to 
fname. 


If the current selection is not a directory file, checks the content of fname using the p_finfo PLIB library 
routine. If the return value is non-zero or the status member of the p_rwro struct is P_FADIR, writes the 
default extension in fnselwn.defext to fname. 


w 


INT wn_key(INT keycode, INT modifiers) ; 


Handle the keypress. 
Ifa file list is present and thus chiist.pop is non-zero, sends a WN_KEY message to chlist.pop. 


e if the return value from the wi_xEy message is greater than zero - thus the user has selected a file - 
clears PR_FNSELWN_AT_ROOT in fnselwn. flags.If the selected file is in the root directory, sets 
PR_FNSELWN_AT_ROOT in fnselwn. flags. Validates the file by sending a rns_VALIDATE_FLIST 
message to self and if the file fails the validation, calls p_1eave with an argument of 
RUN_ACTIVE_USED. Otherwise, clears IN_FNSELWN_RESTRICT_LisT from fnselwn. flags, and sets 
the file into property by sending se1f a wN_sET message. Returns wN_KEY_CHANGED. 


¢ ifthe return value from the wy_xey message is WN_KEY_NO_CHANGE, returns WN_KEY_NO_CHANGE. 


e ifthe return value from the wy_xey message is neither greater than zero, nor WN_KEY_NO_CHANGE, 
destroys the file list by sending a pesTRoy message to chlist .pop, and then writing zero to 
chlist.pop. Retums the return value from the wi_key message. 


12 - 16 


12 FILE SELECTORS 
—_—_—_—_— —__  —__—_ eee EE SELECTORS 


If keycode is a tab character, and modifiers contains the Psion modifier, displays the contents of 
fnedit .buf using the hInfoprint utility function, and returns wy_KEY_NO_CHANGE. 


If keycode is a tab character and modifiers does not contain the Psion modifier, sets IN_FNSELWN_CAN_TAG, 
IN_FNSELWN_HIDE_FILES, IN_FNSELWN_SHOW_DIRS and IN_FNSELWN_CAN_WILDCARD iN fnselwn. flags. 
Senses the current filename by calling the rnselwnsense function with an argument of TRUE (see the 
description of the wn_sense method for details), and, if it is not in the root directory, strips the terminating 
delimiter character, then: 


e if modifiers contains the Control modifier, allows the user to edit the file name pattern and the 
full path for the current file by launching a File list dialog: if the user edits neither the filename 
pattern nor full path, returns wn_KEY_NO_CHANGE. 


¢ — ifthe last keypress included the Control modifier, validates the file specification by sending se1f 
an FNS_VALIDATE_FLIST message. If it fails the validation, calls p_leave with an argument of 
RUN_ACTIVE_USED. Otherwise, clears In_FNSELWN_RESTRICT_LisT from fnselwn. flags and sets 
the edited filename into property by sending self a wN_SET message. Returns wN_KEY_CHANGED. 


¢ presents a list of files that match the current full file specification by creating an instance of the 
FILELIST file selector class, writing its handle to chlist .pop and sending it a wx_INrT message. 
Returns wN_KEY_ABSORB_ON. 


Otherwise clears PR_FNSELWN_CHANGED_DIR from fnselwn. flags and supersends a WN_KEY message with 
arguments of keycode and modifiers. Returns the return value. 


Validate file name 


INT 1lg_self_check(INT can_defer) ; 


If either fnselwn. flags contains any of PR_FNSELWN_WILDCARDED, PR_FNSELWN_TAGSHERE, 
IN_FNSELWN_ACCEPT_NULL OF PR_FNSELWN_AT_ROOT, Of chlist. flags does not contain 
PR_CHLIST_SUSPENDED, return TRUE. Otherwise beep using the hBeep utility routine and return FALSE. 


Sense width 


INT lg_sense_width(VOID) ; 


Return the pixel width of the control. 


The width is calculated as that of fifteen maximum-width characters in the appropriate font, plus a cushion 
of two pixels. 


VOID lg_update (TEXT *pack,INT derr) ; 
Update fnselwn. buf and fnselwn.crk according to the device specification in pack. 


Builds a full file specification from pack, using the p_fparse PLIB library routine and a related file 
specification of fnselwn. buf. Writes the full file specification and the associated p_FparsE struct to 
fnselwn.buf and fnselwn.crk respectively. 


Builds a list of the files in the parent directory of the current file using the BuildFilenist function with an 
argument of derr (see the description of the wn_set method), and writes the handle of the file list to 
chlist.data. 


Sets DLGBOx_ITEM_x_PENDING in the dlgbox.item[] . flags dialog property associated with this control, 
and sets PR_FNSELWN_CHANGED DIR in fnselwn. flags. 


12-17 


VOID fns_insert_tags(PR_VASTR *tags,INT preserve,TEXT *buf) ; 


Insert the list of tagged files in the vasTr array whose handle is tags and, optionally, set the path and/or 
default extension as specified by bu. 


Stores the new tags by sending a destroy message to fnselwn.tags, writing tags to fnselwn.tags and 
setting IN_FNSELWN_CAN_TAG in fnselwn. flags. 


If preserve is non-zero, adds PR_FNSELWN_PRESERVE_TAGS tO fnselwn. flags, recording the fact that the 
list is considered to remain under the ownership of the supplier. 


If but is non-zero, sets the path specified by but as the current path by sending a wy_sET message to self. 


Otherwise builds a list of the files in the current directory using the BuilaFilezist function with an 
argument of zero (see the description of the wn_set method), and writes the handle of the file list to 
chlist.data. 


PR_VASTR *fns_extract_tags (VOID) ; 


Return a pointer to the vastr instance used to store the list of tagged files or ratss if no valid list exists, 


Determines the number of tagged files by sending a va_counr message to fnselwn. tags. If no files are 
tagged, the method returns FALSE. 


Otherwise determines the path for the tagged files - this is stored in the first record - and if this does not 
match the path component in £nselwn. buf, returns FALSE. Otherwise sets the return value to fnselwn. tags 
and sets fnselwn.tags to zero (if FNsELWN owned the list, zeroing fnselwn.tags effectively removes this 
ownership). 


VOID fns_subset (VOID) ; 


The supplied method does nothing. 


It is intended that subclassers replace this method to provide additional application specific functionality 
when building a file list. Subclassers may, for example, wish to further restrict the filelist according to 
application specific flags in fnselwn. flags. For details see the description of the wn_set method. 


INT fns_validate_flist (TEXT *pbuf) ; 


The supplied method returns True. 


It is intended that subclassers replace this method to provide the desired application-specific functionality. 


12 - 18 


CHAPTER 13 


FILE List GENERATOR CLASSES 


This chapter documents the nonopz and upset classes which together support the creation and storage of a 


list of the files which match a specified path and filename pattern. The list of files may include file related 
details as required. 


Precursors 
Familiarity with the following topics will aid the understanding of this chapter: 
e the file classes described in the OLIB Reference manual. 


e the actrve class described in the OLIB Reference manual. 


Class diagram 


/ fnode ™ —/ pnode ~> / nonode > 
/ active >> ” factive ~ 
Yr ae ee ie 
/ fscan > a 4PSell * / hpsel > 
{ <— << 


NONODE 


priority 
isactive 
pcb 

stat 


destroy aetna ao_queue ao_abrun fn_list 
ini ao_cancel ao_run fn_end_list 


fa_close £n_nodename 
fn_list 


The nonops class is provided for use by the upset class and generates a list containg the default device and 
a list of files matching the current path and filename pattern. 


13-] 


HWIM REFERENCE 


Class definition ( 


Defined in sub-category file filelist.cl (generated header file filelist.g). 
CLASS nonode pnode 
{ 
REPLACE fn_list 
} 
Property 


None. 


NONODE methods 
FALL 


VOID fn_list(); 


Initialise 


Create a node list containing the default device - e.g. toc: :m: - and start the creation of a list of files 
matching the current path and filename pattern. ( 


Resets the node list by sending a va_RESET message to factive .owner->psel .pdir and then clears both 
PSEL_RESET_DIR_ARRAY and PSEL_QUEUED_CMD in factive.owner->psel. flags. 


Adds the default device to the node list by sending a va_APPEND message to factive.owner->psel .pdir. 


Closes the node list in factive.owner->psel.pdir and creates in factive.owner- >psel .pfile a list of 
files matching the current path and filename pattern by sending an ao_run message as follows: 


fnode. flags |=FNODE_NODE_ARRAY; 
active.stat=E_FILE_EOF; 
active .isactive=TRUE; 
p_iosignal(); 
It is assumed that: 
e the handle of the owning object is stored in factive.owner. 


e the handle of an instance of the pse.var class is stored in factive.owner->psel .pfile - this 
component is used to store the file list. 


e the handle of an instance of the vastr class is stored in factive.owner->psel .pdir - this 
component is used to store the node list. 


e — the current path and filename pattern are stored as a zero terminated string in factive .owner- 
>psel.fspec. 


Returns zero. 


13-2 


13 FILE LIST GENERATOR CLASSES 


dirnum 
setpath 


isactive builderr 
peb i fck 
stat i fspec 


ae—inite ps_set_path 
ao_abrun ps_sense filename 
ao_cancel ps_select_direntry 

fs_matchname fs filename ps_drives 

fs_fscan fs_dirname ps_settag 
fs_fscan_end Ps_gettag 
ps_get_file ps_order 


fs_end_dirlist 


The HpsEL class supports the creation of a list of files that match the current path and filename pattern. 
Note that the owning class must support the £1_1ist_complete method. 


Class definition 
Defined in sub-category file filelist.cl (generated header file filelist.g). 


CLASS hpsel psel 


{ 


REPLACE ao_init 
REPLACE ao_queue 
REPLACE fs_fscan 
REPLACE ps_new_list 
PROPERTY 


{ 


PR_ROOT *owner; 


} 
} 


Property 


hpsel.owner _— The handle of the owning object, assumed to be an instance of (a subclass of) 
FILELIST. 


2a ee ee ee eas 
HPSEL methods 


Initialise 


VOID ao_init (TEXT *fname,PR_ROOT *owner) ; 


Initialise the npsEx instance and create a list of files matching the possibly wildcarded path and filename 
pattern in fname. 


Records the handle of the owning object by writing owner to hpsel .owner. 
Supersends an ao_inrT message, to: 


© write the path and filename pattern specified by fname to psel. spec 


eee 
13-3 


HWIM REFERENCE 
See eS 


e create an instance of the vasrr class having a granularity of 32 and write the handle to psel.pdir 


© create an instance of the pszLvar class having a granularity of 32 and write the handle to 
psel.pfile 


¢ create an instance of the pwope class and write the handle to pse1 .pnode., then initialise the pNoDE 
instance by sending an ao_INIT message to psel .pnode. 


Changes the class of which psel.pnode is an instance from PNoDE to NONODE. 


If an asynchronous request is outstanding, cancels the outstanding request and then adds a record holding 
the default device specification to pse1.pdir and adds to psel .pfile a record for each file matching the 
path and filename pattern in pse1. fspec. (The method sends ao_cance and FN_LIST messages to 

psel .pnode.) 


_ Queue 


VOID ao_queue (VOID) ; 

Queue a read request. 

If the request is to build the node list - i.e. scan. flags contains FS_DIRECTORIES - 
e clears both pszL_RESET_DIR_ARRAY and PSEL_QUEUED_cwp in psel.. flags. 
® removes all records from the node list by sending a va_RESET message to psel. pdir. 
e adds the default device to the node list by sending a va_APPEND message to psel .pdir. 


¢ — closes the device list and starts the creation of the file list using the following code: 


active.stat=E_FILE_EOF; 
active .isactive=TRUE; 
p_iosignal (); 


where the last line forces se1¢ to be sent an Ao_RUN message. 


Otherwise queues a request to add the next file to the file list by supersending an AO_QUEUE message. 


VOID fs_fscan (TEXT *path) ; 


Start the scan of the files and directories in the directory specified by path including hidden and system 
files - note that the file specification pointed to by path is overwritten 


Sets Fs_HIDDEN and Fs_sysTEM in fscan.flags and then starts the scan by supersending an FS_FSCAN 
message with an argument of path. 


VOID ps_new_list (VOID) ; 
Complete the processing of the file list. 


Allows the owning class to perform further processing of the completed file list by sending an 
FL_LIST_COMPLETE message tO hpsel .owner. 


13-4 


CHAPTER 14 


THE FILELIST WiNDow CLASS 


This chapter documents the rrLELisT class which may be used to create a list box containing a list of files 
and directories in the specified path. 


Precursors 
Familiarity with the following topics will aid the understanding of this chapter: 


e the use of the file selector - obtained in the system screen by pressing the Tab key. The file 
selector is an instance of the FILELIsT class. 


e the vastr class described in the Variable Array Classes chapter of the OLIB Reference manual. 


e the vapgv class described in the File Selectors chapter of the HWIM Reference manual. 


FILELIST 


flags match current 

id va top 
flags first 
width last 
matchlen vastart 
curoff matchstart 

destrey wh-draw 


destrey ib_size_window 
waoinit ib_item_width 
warkey lb_take_focus 
wn_draw lb_inquire_focus 
wn_emphasise db—inguive—item 


1lb_inquire last 


thisdir 


crk 


derr 
x 


dfree 
wild 
subd 
ser 


targ 


1b_draw_emphasis 


wh_cale position |wh-emphasise 


wn_connect 


lb_enquire_item 


f£1_list_complete 


wn_dodraw £1_locchg 


1lb_draw_item 


wn_position 


wn_redraw 


wn_sense_help 


wn_visible 


14-1 


HWIM REFERENCE 
eee SSS 


The rrLeList class implements the file list which presents the user with a list of the files in a given 
directory. The user may change the path using the cursor keys. The user may also select the node by 
pressing the appropriate letter e.g. ‘B'. An example file list is shown in the following picture: 


¢ Disk(Bl,Flash,36K free + 
\NAPP\2 


ll\APP\CHESSS 

28938 16:69am 25/81/94 
2247 1:88am 69/62/94 
9856 4:87pm 14/82/94 
5776 =. 18:89am 12/61/94+ 


The file list displays: 


¢ the name and type of the current device and the amount of free memory: these constitte the first 
title line. 


e the current path and filename pattern which in the above example is \4PP\*. 


e the path of the parent directory: by selecting this line and pressing the Enter key the path ascends 
to the parent directory. In the above example this is |. 


e the current path which in the above example is \4PP\. 


* alist of the directories in the current path e.g. \apP\cuEss\ - by selecting a directory and pressing 
the Enter key the current path descends onto the selected directory. 


¢ alist of the files in the current path and the associated file information. This consists of the a tag 
marker, the size of the file in bytes, the time at which the file was last modified and the date at 
which the file was last modified. 


Class diagram 


14 THE FILELIST WINDOW CLASS 
———____ S$ eee EL TE WINDOW CLASS 


Class definition 
Defined in the sub-category file filelist.cl (generated header file filelist.g). 


CLASS filelist listbox 


{ 


REPLACE destroy remove from list kept by wserv 

REPLACE wn_init initialise listbox and do wn_set 

REPLACE wn_key convert \ to special and filter ENTER and arrows 

REPLACE wn_sense return current selection 

REPLACE 1b draw_item draw all the file infomation 

REPLACE 1b_draw_emphasis=pulldown_lb_draw_emphasis 

REPLACE lb inquire_item get pointer to text 

ADD f1_list_complete called by fsel when file list is complete 

ADD f1_locchg check for change in LOC:: 

CONSTANTS 
{ 
PR_FILELIST_ISFILE Ox100 Set or cleared as each line is drawn 
PR_FILELIST_TAGS_CHANGED 0x0200 Need to start a new tag list 
PR_FILELIST_NOSCAN 0x0400 No file scan for this directory 
PR_FILELIST_SCANNING 0x0800 Scan in progress 
PR_FILELIST_LOCAL 0x1000 Logged to LOC:: 
PR_FILELIST_WILDCARDED 0x2000 Effects next wn_sense 
PR_FILELIST_SET_UNMARKED 0x4000 Called p_unmarka 
IN_FILELIST_ALLOW_DIRS H_FILE_ALLOW_DIRS 
IN_FILELIST_JUST_DIRS H_FILE_JUST_DIRS 
IN_FILELIST_CAN_TAG H_FILE_CAN_TAG 
IN_FILELIST_CAN WILDCARD H_FILE_CAN WILDCARD 
IN_FILELIST_NO_FORCE WILD 0x8000 
FILENAME_WIDTH 12 
FILESIZE_WIDTH 7 
FILETIME WIDTH 7 
FILEDATE_WIDTH 9 
} 

TYPES 


{ 


typedef struct 


{ 


WORD dtype; disc type 

VOID *vadev; device list 

WORD ascoff; offset to where display should start 
UWORD tagoff; x-offset to filetag 

UWORD sizeoff; x-offset to filesize 

UWORD timeoff; x-offset to filetime 

UWORD dateoff; x-offset to filedate 

UWORD dateendoff; x-offset to end of filedate 


TEXT asc[P_FNAMESIZE]; ascend text 
} PR_FILELIST_X; 


14-3 


HWIM REFERENCE 
ek  SSSSSSSSSSSSSSSSCeFe 


PROPERTY 4 


{ 

PR_HPSEL *hpsel; 
PR_VASTR *contexts; 
PR_TIME *date; 
PR_VASTR *tags; 
PR_VASTR **ptags; 
PR_ROOT *next; 
UWORD locmask; 
UWORD flags; 

WORD parent; 

WORD thisdir; 
P_FPARSE crk; 
WORD derr; 


file list generator 

contexts for all nodes encountered 
for file date display 

which files are tagged 

where to write back tags 

next filelist in list 

mask for locchg 


index of parent (if any) in list 
index of current directory in list 
parse info on wildcard string 

disc error (if any) 


PR_PILELIST_X *x; 
ULONG dfree; 


extra data 
size of free space on disc 


TEXT wild[P_FNAMESIZE]; holds wildcard string used by psel 
TEXT subd[P_FNAMESIZE]; used to generate subdir names 


TEXT scr ([P_FNAMESIZE] ; 


miscellaneous scratch buffer 


TEXT targ[P_FNAMESIZE]; where to position initial highlight 


} 


Property 
filelist.hpsel 


filelist.contexts 


filelist.date 


filelist.tags 


filelist.ptags 


filelist.next 


filelist .locmask 
filelist.flags 


filelist .parent 


filelist.thisdir 


filelist.crk 


filelist.derr 


The handle of an instance of the upsz1 class. This is used to create and store a list 
of files and subdirectories. The full path and filename pattern that control the 
search for files and directories is in filelist .hpsel->psel.fspec. A full path 
and filename pattern of Loc: :M:\wvE\* would list all files in the Loc: :m:\WvE\ 
directory. 


The handle of an instance of the vastr class. There is one record for each node 
holding the most recent scanning context for that node i.e. the most recent full 
path and filename pattern. 


The handle of an instance of the rrmz class. This is used to convert system time 
into textual representations of the time and date as required for the file list 
display. 


The handle of an instance of the vastr class. This is used to store details of the 
tagged files. The first record is used to store the full path. The remaining records 
hold the filenames. Thus the tagged files lie in the same directory as each other. 


A pointer to the handle of an instance of the vaste class: this is for use when 
seeding the file list, in which case the vaste array contains details of the 
currently tagged files. The user may supply the handle of this array on 
initialisation. Otherwise it is created by the wn_sense method if required. 


May be used to store the handle of the next FrLELrsT object in order to create a 
linked list of FrLELIST objects. 


A mask that is for internal use only. 
An ored combination of flags indicating the state of the file list. 


The index of the parent directory item. This is the first item in the main list 
unless the current directory is at the root. The user moves to the parent directory 
by highlighting this item and pressing the Enter key. 


The index of the current directory item. This is the second item in the main list 
unless the current directory is at the root. In this case the item is not included. 


This contains information about the length of the components and the presence 
of wildcards in the file specification pointed to by filelist .wild. The 
information is obtained by calling p_fparse witha file specification of 
filelist.wild and a nut related file specification. 


An error code indicating the status of the current device. The current device is in 
filelist .wild. The error code is generated using the p_dinfo routine. 


14-4 


14 THE FILELIST WINDOW CLASS 


— rn EAD 


filelist.x 


filelist.dfree 


filelist.wild 


filelist.subd 


filelist.scr 


filelist.targ 


A pointer to a PR_FILELIST_x struct the definition of which is machine specific. 
The following members may be accessed: 


vadev the handle of an instance of vapev which is used to store a list of 
the available devices e.g. Loc: :M:, LOC: :A: and Loc: :B: - may 
be read by a subclass. 

ascoff the offset of the path component from asc - may be read by a 
subclass. 

dtype stores the ID of a system resource: this resource contains 


information about the media type in the current device - may be 
read by a subclass. The system resource ID corresponds to an 
error message or to one of the following: 


SYS_MTYPE_FLOPPY specifies that the media is a floppy 
disk. 

SYS_MTYPE_HARD specifies that the media is a hard disk. 

SYS_MTYPE_RAM specifies that the media isa RAM 
disk. 

SYS_MTYPE_FLASH specifies that the media is a flash disk. 

SYS_MTYPE_ROM specifies that the media is a ROM disk 


and is thus read-only. 


SYS_MTYPE_PROTECTED _ specifies that the media is read-only. 


SYS_MTYPE_UNKNOWN specifies that the media type is 
unknown. 
tagoff the horizontal offset to the tag indicator - for internal use only. 
sizeoff the horizontal offset to the file size - for internal use only. 
timeoff the horizontal offset to the file time of last modification - for 


internal use only. 


dateoff the horizontal offset to the file date of last modification - for 
internal use only. 


dateendoff the horizontal offset to the end of the file date of last 
modification - for internal use only. 


asc points to the full path specification of the parent directory - 
stored as a zero terminated string - for internal use only. 


the amount of free space on the current device in units of Kb rounded to the 
nearest Kb. The current device is in £ilelist .wild - for internal use only. 


the current path and filename pattern - stored as a zero terminated string - for 
internal use only. The current path and filename pattern for a file list showing all 
files in Loc: :M:\WVE\ would be Loc: :M: \wvE\*, whereas the current path and 
filename pattern for a file list showing all files with extension wve in 

LOC: :M: \WVE\ would be Loc: :M: \WVE\*.WVE. 


a format string used internally to generate the full file specification of a directory 
in the current directory - for internal use only. The format string for a file list 
showing files in Loc: :m:\wve\ would be Loc: :m: \WVE\$s. 


a scrap buffer that is used internally - for internal use only. 


see the description of the wn_init method for details - for internal use only. 


14-5 


HWIM REFERENCE 
a 


FILELIST methods 

VOID destroy (VOID) ; 

Destroy the filelist. 

If filelist .flags contains PR_FILELIST_SET_UNMARKED, Calls p marka. 
Sends a WS_REMOVE_FILELIST message to w_ws and then calls wcance1BusyMsg. 


Supersends a DESTRoy message. 


VOID wn_init (INT flags, TEXT *fname,PR_VASTR **ptags) ; 


Initialise the file list according to the content of £1ags, the file specification pointed to by fname and the 
handle of the vastr array pointed to by ptags: the latter may be NULL. 


The flags argument may contain an ored combination of the following flags: 


IN_FILELIST ALLOW_DIRS specifies that directories are inlcuded in the file list. 
IN_FILELIST_JUST_DIRS specifie that only directories are included in the file list. 
IN_FILELIST_CAN TAG specifies that file tagging is allowed. 


IN_FILELIST_CAN WILDCARD __ specifies that wildcards are allowed. 


IN_FILELIST_NO_FORCE_WILD specifies that the filename pattern is not automatically wildcarded i.e. it 
is not automatically replaced with an asterisk. 


Writes ptags tO filelist .ptags and writes flags to filelist. flags. 


Defines the style of the file list window by setting 1n_BwrN_sHADOW_1, IN_BWIN_CUSHTON and 
PR_WIN_EMPHASISED in win. flags. 


Connects to the window server by sending se1£ a wN_connecr message specifying a width of 
FILELIST_WIDTH and a height of FILELIST_HEIGHT whilst ensuring that the file list is centred in the screen. 


On the Workabout, following connection to the window server, ors PR_LISTBOX_SMALL_FONT into 
win.flags. 


Creates an instance of the vmarcuer class - the incremental matcher class - and writes the handle to 
listbox.match. Initialises the vmarcuer component by sending an 1m_INIT message to 1istbox.match 
passing as arguments the address of 1istbox.matchlen and P_FNAMESIZE. 


Creates an instance of the vastr class and writes the handle to £ilelist .contexts. Initialises the vasTR 
component by sending an va_INIT message to filelist .contexts specifying a granularity of 32. 


Creates an instance of the Time class and writes the handle to filelist..date. Sets the format for the TrME 
instance (by sending To_sET_FoRMAT messages) so that the time is expressed in hours and minutes e.g. 
14:32 or 2:32 pm and the date is expressed as the day, the month and the year e.g. 5/8/94. 


Sets PR_LISTBOX_KEEP_ARRAY and PR_LISTBOX_FORCE_WIDE in listbox. flags. 


Allocates a cell of sufficient size for a PR_FILELIST_x struct and writes the address of the cell to 
filelist.x. 


Creates an instance of the vapev class and writes the handle to filelist .x->vadev. Initialises the vastR 
component by sending an vA_inrT message to filelist.x->vadev. 


Builds a full file specification from fname using the f_fparse PLIB routine with a nut related file 
specification, writes the result to £ilelist .wild, and writes the associated P_FPARSE struct to 
filelist.ecrk. 


SSE 
14-6 


14 THE FILELIST WINDOW CLASS 
eee FILELIST WINDOW CLASS | 


If £ilelist .wild contains wildcards, copies the current filename pattern in £ilelist.wild to 
filelist.targ and, if filelist. flags does not contain IN_FILELIST_NO_FORCE_WILD, replaces the 
filename pattern in £ilelist .wild with an asterisk. 


Creates an instance of the HpsEx class and writes the handle to filelist .hpsel. Initialises the upsEL 
component by sending an ao_INIT message to filelist .hpsel with arguments of filelist.wild and 
self. 


Initialises items of Ltstsox property concerned with the display including the width which is 
FILELIST_INTERN_W1DTH and the cursor offset which is L1sTBOX_LEFT_EDGE plus LISTBOX_OBLOID_INDENT. 


If the current node in filelist .wild is Loc: :, sets PR_FILELIST LOCAL in filelist.flags. 
Otherwise, clears pR_FILELIST_LOCAL in filelist. flags. 


Writes an appropriate error code for the device specified by £ilelist .wild to filelist .derr - the error 
code is the return value from a call to p_dinfo thus zero corresponds to a useable device. 


Writes the ID of an appropriate strinc resource giving information on the status of the device to 
filelist .x->dtype and, if the device is invalid, returns. 


Writes the number of free bytes on the media, rounded to the nearest kilobyte, to filelist .dfree. 


Sets PR_FILELIST_SCANNING iN filelist .flags and displays the text in the sys_SCANNING system resource 
using the wsetBusymMsg window server routine. On English language machines this is "Scanning". 


Makes the file list visible by calling hinitvis, set PR_FILELIST_SET_UNMARKED in filelist.flags and 
calls p_unmarka. 


INT wn_key (INT keycode, INT modifiers) ; 
Handle a keypress that may lead to a change in the current scanning context and hence file list. 
If keycode is less than 27 and modifiers contains W_CTRL_MODIFIER: 

e displays a scanning busy message. 


e if keycode corresponds to a device - e.g. m or a or B, Searches filelist.contexts for a record 
which matches the device and copies the path and filename pattern in the record to 
filelist .wild. (If there is no matching record, add a record containing the device specification 
to filelist.contexts.) If the device is Loc: :, set PR_FILELIST LOCAL in filelist.flags, 
otherwise, clears PR_FILELIST_LOCAL in filelist.flags. 


¢ writes information about the status of the device to filelist .derr, filelist.x->dtype and 
filelist.dfree. 


e creates a list of the files which match the path and filename pattern in filelist .wild as described 
in later paragraphs and returns wN_KEY_NO_CHANGE. 


If filelist . flags contains either PR_FILELIST_NOSCAN OF PR_FILELIST_SCANNING and the keypress is 
neither W_KEY_LEFT, Nor W_KEY_RIGHT, nor W_KEY_TAB, nor W_KEY_ESCAPE, beeps and returns 
WN_KEY_NO_CHANGE. 


If keycode is equal to w_ws->wserv.sc[H_SC_TPLUS] i.e. the special character that on English language 
machines is '+': 
e if filelist. flags does not contain IN_FILELIST_caNn_tac, or the current item is a directory, 
returns WN_KEY_NO_CHANGE. 


© sets PR_FILELIST_TAGS_CHANGED in filelist . flags and tags the current item by sending a 
PS_SETTAG message to filelist .hpsel, redraws the item and returns WN_KEY_NO_CHANGE. 


If keycode is equal to w_ws->wserv.sc [H_SC_TMINUS] i.e. the special character that on English language 
machines is '~': 


e if filelist..flags does not contain IN_FILELIST_caNn_Tac, or the current item is a directory, 
returns WN_KEY_NO_ CHANGE. 


14-7 


HWIM REFERENCE 
ae eee 


¢ setS PR_FILELIST_TAGS_CHANGED in filelist. flags, untags the current item by sending a 
PS_SETTAG message to filelist .hpsel, redraws the item and returns wN_KEY_NO_CHANGE. 


If keycode is equal to w_ws->wserv.sc {H_SC_TSTAR) i.e. the special character that on English language 
machines is '*': 


e if £ilelist.flags does not contain IN_FILELIST_cCAN TAG, returns WN_KEY_NO_CHANGE. 


° sets PR_FILELIST_TAGS_CHANGED in filelist . flags and tags each file in the file list by sending 
PS_SETTAG Messages to filelist .hpsel, redraws the display and returns wN_KEY_NO_CHANGE. 


If keycode is equal to w_ws->wserv.sc[H_SC_TSLasu] i.e. the special character that on English language 
machines is ‘/’: 


e if £ilelist.f1ags does not contain In_FILELIST_CAN_TAG, returns WN_KEY_NO_CHANGE. 


¢ sets PR_FILELIST_TAGS_CHANGED in filelist .flags, untags each file in the file list by sending 
PS_SETTAG messages to filelist .hpsel, redraws the display and returns wN_KEY_NO_CHANGE. 


If keycode is either w_kEY_UP OF W_KEY_DOWN 


e ifmodifiers contains W_SHIFT MODIFIER, filelist.flags contains IN_FILELIST_CAN_TAG, and 
the current item is a file then sets pR_FILELIST_TAGS_CHANGED in filelist. flags. Toggles the 
tag status of the file by sending a ps_seTTac message to filelist .hpsei. Redraws the file and 
file details. 


e  supersends a wN_KEY message with arguments of keycode and modifiers. 
¢ cancels any scanning busy message and clears pR_FILELIST_SCANNING from filelist. flags. 
e returms WN_KEY_NO_CHANGE. 
If keycode is W_KEY_LEFT: 
¢ searches filelist contexts for a record which matches the current device in filelist .wild. 


¢ moves to the previous record and copies the scanning context - i.e. path and filename pattern - to 
filelist.wild. (If there is no previous record, moves to the last record and repeats the process.) 


¢ creates a list of the files which match the path and filename pattern in filelist .wild as described 
in later paragraphs. 


e returns WN_KEY_NO_CHANGE. 
If keycode is W_KEY_RIGHT: 
e searches filelist.contexts for a record which matches the current device in filelist .wild. 


* moves to the next record and copies the scanning context - i.e. path and filename pattern - to 
filelist .wiid. (If there is no next record, moves to the first record and repeats the process.) 


* creates a list of the files which match the current path and filename pattern in filelist .wild as 
described in later paragraphs. 


e returns WN_KEY_NO_CHANGE, 
If keycode is W_KEY_TAB: 


¢ — allows the user to edit the current path and filename pattern - stored in filelist .wild - by 
presenting a File list dialog : if the user modifies neither the full path nor the filename pattern, 
returns WN_KEY NO CHANGE. 


¢ validates the full path in £i1e1ist .wi1a by removing trailing directories until the path exists. 


e searches filelist .contexts for a record which matches the current device in filelist .wild 
and copies the current scanning context - i.e. current path and filename pattern - to the record. (If 
there is no matching record, appends a record containing the path and filename pattern in 
filelist.wild.) 


¢ if on exiting the file list dialog the Control modifier was pressed, and filelist. flags contains 
IN_FILELIST_CAN_WILDCARD, Sets PR_FILELIST_WILDCARDED in filelist.flags and returns 


eS ee a ee 
14-8 


14 THE FILELIST WINDOW CLASS 


—_—_— OO rr eee eee 


WN_KEY_ CHANGED. (The last key press is stored in w_ws->wserv.ws.u.key.keycode and the 
modifiers are in w_ws->wserv.ws.u.key.modifiers.) 


displays a scanning busy message and if the current path is on Loc: :, sets PR_FILELIST_LOCAL in 
filelist.flags, otherwise clears PR_FILELIST LOCAL in filelist. flags. 


writes information about the current device in filelist .wild to filelist.derr, filelist.x- 
>dtype and filelist.dfree. 


creates a list of the files which match the current path and filename pattern in filelist .wild as 
described in later paragraphs. 


returns WN_KEY_NO_CHANGE. 


If keycode is W_KEY_RETURN: 


if the current item is the parent directory, displays a scanning busy message, and writes the full 
path specification of the parent directory followed by the current filename pattern to 

filelist .wild. Creates a list of the files which match the current path and filename pattern in 
filelist .wild as described in later paragraphs. Returns wN_KEY_NO_CHANGE. 


if the current item is a directory file, modifiers contains w_PSION_MODIFIER and filelist.flags 
contains IN_FILELIST_ALLOW_DIRS, returns WN_KEY_ CHANGED. 


if the current item is the current directory, and filelist. flags contains 
IN_FILELIST_ALLOW_DIRS, returns WN_KEY_NO_CHANGE. 


if the current item is the current directory, and filelist. flags does not contain 
IN_FILELIST_ALLOW_DirRs, calls hinfoprint with an argument of sys_cHOosE_FILENAME and 
returns WN_KEY NO CHANGE. 


if the current item is a file, and filelist. flags contains IN_FILELIST_JUST_DIRS, calls 
hInfoPrint with an argument of sys_cHOOSE_DIRECToRY. Writes zero to listbox .matchlen and 
moves the focus to the current directory by sending self a LB_TAKE_Focus message. Returns 
WN_KEY_NO_ CHANGE. 


writes the current path and filename pattern to filelist.wild. 


displays a scanning busy message and creates a list of the files which match the current path and 
filename pattern in filelist .wild as described in later paragraphs. 


retumms WN_KEY NO CHANGE. 


If keycode is none of the above: 


if modifers contains W_SHIFT_MODIFIER and keycode is an alphanumeric character, searches the 
file list for a directory the first character in the name of which matches keycode and moves the 
focus to the matching directory by sending self an LB_TAKE_Focus message. If no matching 
directory is found, beeps. In either case returns wN_KEY_NO_CHANGE. 


supersends a wN_KEY message with arguments of keycode and modifiers. If the return value is 
non-zero indicating that the display has changed, clears pR_FILELIST_SCANNING in 
filelist.flags and cancels any scanning busy message. 


returns WN_KEY_NO_CHANGE. 


Creating a list of files matching the current path and filename pattern 


If filelist .flags contains PR_FILELIST TAGS CHANGED and filelist.flags contains 
IN_FILELIST_CAN_TAG: 


clears PR_FILELIST_TAGS_CHANGED in filelist. flags. 


ensures that filelist.tags contains the handle of an instance of the vastr class containing zero 
records of granularity 32. 


adds the current path and filename pattern in filelist .hpsel->psel. fspec to the tags array by 
sending a VA_APPEND message to filelist.tags. 


14-9 


HWIM REFERENCE 
eee eS 


* adds the name of each tagged file to the tags array by sending va_APPEND messages to 
filelist.tags. 


Writes information about the current path and filename pattern in £ilelist.wild to filelist.crk and 
writes zero to filelist.targ. 


If the current device is not useable - thus filelist.derr is non-zero: 
e calls hInfoprint with an argument of filelist .x->dtype. 


¢ sets PR_FILELIST_NoScAN and Clear PR_FILELIST_SCANNING in filelist.flags and cancels any 
scanning busy message. 


* cancels any outstanding read request by sending an ao_caNcEL message to filelist .hpsel. 
Otherwise creates a list of files and directories as follows: 

* cancels any outstanding information message and displays a scanning busy message. 

¢ set PR_FILELIST_SCANNING and Clear PR_FILELIST_NOSCAN in filelist. flags. 


¢ — generates a list of files matching the full path and filename pattern in filelist .wild by sending a 
PS_SET_PATH message to filelist.hpsel. 


Sets PR_LISTBOX_UNSTABLE in listbox. flags. 
Resets the indices and redraws the file list. 


Returns WN_KEY_NO_CHANGE, 


Retur 


INT wn_sense (TEXT *buf) ; 
Sense the current item by writing a full file specification for the current item to but. 


If filelist. flags contains either pR_FILELIST_NOSCAN oF PR_FILELIST_SCANNING, beeps and calls 
p_leave with an argument of RUN_ACTIVE_USED. 


If £ilelist.flags contains IN_FILELIST_CAN TAG: 


e ensures that filelist.ptags points to the handle of an instance of the vastr class containing zero 
records of granularity 32. 


e adds the current path in filelist .npse1->psel. spec to the tags array by sending a vA_APPEND 
message to the array whose handle is pointed to by filelist .ptags. 


e adds the name of each tagged file to the tags array by sending a VA_APPEND message to the array 
whose handle is pointed to by £ilelist.ptags. 


If £ilelist . flags contains PR_FILELIST_WILDCARDED, copies the current path and filename pattern in 
filelist .wiid to buf. Returns zero. 


If the current item is neither the parent directory (i.e. listbox. current is not filelist -parent) nor the 
current directory (i.e. listbox. current is not filelist.thisdir) writes the full file specification for the 
current item to but. If the file is a directory file, returns 1_FILE_1s zr, otherwise returns zero. 


If the current item is the current directory (i.e. listbox .current is equal to filelist parent) copies the 
current path in filelist .wild to buf. 


If the current item is the parent directory (i.e. listbox. current is equal to filelist.thisdir) copies the 
full path of the parent directory in filelist .x->asc to buf. 


If the path in bug is at the root directory, returns H_FILE_1IS_ Root. Otherwise returns H_FILE_IS_ DIR. 


LB DRAW ITEM Draw an item 
VOID 1lb_draw_item(TEXT *txt,INT index, P RECT *parea) ; 


Draw the item specified by txt and index in the rectangle specified by parea. 
14-10 


14 THE FILELIST WINDOW CLASS 


If index is zero draws the zero terminated string specified by txt in a box specified by «parea. The text is 
drawn in normal style with centre alignment. The text should be the title. Returns. 


If index is one draws the zero terminated string specified by txt in the box specified by *parea. The text is 
drawn in a bold style with centre alignment. The text should be the current path and filename pattern e.g. 
\wve\*. Returns. 


If index is filelist .thisdir draws the zero terminated string specified by txt in the box specified by 
*parea. The text is drawn in a bold style with centre alignment. The text should be the name of the current 
directory e.g. \wve\. Returns. 


If index is filelist.parent draws the zero terminated string specified by txt in the box specified by 
parea. The text is drawn in a normal style with left alignment. The text should be the path for the parent 
directory e.g. "\". Returns. 


Otherwise draws the zero terminated string specified by txt in the box specified by parea. The text is 
drawn in a normal style with left alignment. The text should be the file/directory name. 


If filelist.flags contains PR_FILELIST_ISFILE the txt argument should point to the name member of a 
PSEL_REC struct. 


The PsEL_REc struct is defined as follows: 
typedef struct 
{ 
UWORD flags; 
UWORD namlen; 
P_INFO info; 
UBYTE name [P_FNAMESIZE] ; 
} PSEL_REC; 
The significance of the members of the psEL_rec struct is as follows: 
flags contains PSEL_FLAG_Tac to indicate that the file is tagged, and zero otherwise. 
namlen the offset of the file extension in name. 


info additional file information including the time and date of last modification: see the PLJB 
Reference manual for details of the p_rnro struct. 


name the filename stored as a zero terminated string. 


Draws additional file information to the right of the filename - this consists of a tag symbol if required, the 
size of the file in bytes, and the time and date of last modification. 


TEXT *lb inquire_item(INT index) ; 


Return a pointer to the text of the item specified by index where the title has index zero. 
Clears PR_FILELIST_ISFILE from filelist. flags. 
If index is zero, returns a pointer to the title. 


If index is equal to one, returns a pointer to the current path and filename pattern - e.g. \app\+. Note the 
absence of the device specification. 


If index is equal to filelist .parent, returns a pointer to the path of the parent directory e.g. \. Note the 
absence of the device specification. 


If index is greater than or equal to self->1istbox.vastart and the item is a file sets PR_FILELIST_ISFILE 
in filelist.flags and retums a pointer to the name of the file e.g. "Chess.app". Note that the name forms 
part of a psEL_rRc struct as described in the description of the 1b_draw_item method. 


If index is greater than or equal to self->1istbox.vastart and the item is a directory returns a pointer to 
the name of the directory e.g. Loc: :M: \APP\CHESS. 


14-11 


HWIM REFERENCE 


FLL OMPLETE - __List has been generated 


VOID £1_list_complete (VOID) ; 


Complete the processing of the file list generated by the filelist .hpsel component. 
Cancels any scanning busy message and clears pR_FILELIST_SCANNING iN filelist. flags. 


If the paths in filelist .wild and filelist.hpsel->psel. fspec do not match - indicating that the file list 
has been reset for some reason: 


e calls htnfoprint with an argument of sys_FLIST_RESET. 
© copies the content of filelist .hpsel->psel.fspec to filelist.wild. 


e if the current node is Loc: :, sets PR_FILELIST_LOCAL in filelist .flags, otherwise clears 
PR_FILELIST_LOCAL in filelist. flags. 


® writes information about the status of the device to filelist. derr, filelist.x->dtype and 
filelist.dfree. 


Ensures that the file list displays the list of file names generated by the HpsEL component by writing 
filelist .hpsel->psel.pfile to listbox.va. 


Enables incremental matching to the list of file names by writing filelist .hpsel->psel.pfile to 
listbox.match.vmatcher.va and sending an IM_SET_RANGE message to listbox .match. 


If the current path and filename pattern in £ilelist .hpsel->psel.pfile is the NULL string indicating that 
the machine is out of memory: 


® sets PR_FILELIST_NOSCAN in filelist. flags. 


* — clears the file list by writing appropriate values to property - see the Property section for details - 
then redraws the display and returns. 


If the current directory is at the root e.g. REM: :D:, writes zero to f£ilelist .parent - since there is no parent 
directory - and writes two to filelist .thisdir. 


Writes appropriate values to the remaining items of property - see the Property section for details. 


If the name of a file in the current directory matches the zero terminated string in filelist.targ, sets the 
focus to that file. 


Otherwise if £i1e1ist.f1ags contains H_FILE_JuST_prrs, sets the focus to the current directory by 
sending self an LB_TAKE_FOCUS message. 


Otherwise sets the focus to the first file in the file list by sending se1f an LB_TAKE_Focus message. If there 
are no files then sets the focus to the last directory. If the focus is now at the last item, moves the focus to 
the preceding item. 


If f£ilelist . flags contains IN_FILELIST_can_Tac and the path stored in the tags array matches the path in 
filelist.wild:: 


e for each tagged file sets pseL_FLac Tac in the flags member of the PSEL_REC Struct stored in 
filelist.hpsel. 


Note that the method redraws the file list before sending an LB_TAKE_Focus message. 


nge in LOC:: 


VOID £1_locchg (VOID) ; 


Check for any changes on Loc: :. 


If filelist.flags contains PR_FILELIST_SCANNING OF filelist.flags does not contain 
PR_FILELIST_LOCAL, return. 


Determines whether the toc: : device has changed by calling p_locchg and if it has not changed, returns. 


14-12 


14 THE FILELIST WINDOW CLASS 


a pe 


If the current node in filelist .wild is Loc: :, sets PR_FILELIST_LOCAL in filelist .flags. Otherwise 
clears PR_FILELIST_LOCAL in filelist. flags. 


Writes information about the status of the device to filelist.derr, filelist.x->dtype and 
filelist.dfree. 


Sets PR_LISTBOX_UNSTABLE iN listbox. flags. 
If £ilelist .derr is non-zero - thus the current device is not useable: 

e moves the current path in filelist .wild to the root - €.g. Loc: :M:*. 

e calls hinfoprint with an argument of filelist .x->dtype. 

e sets PR_FILELIST_Noscan and clear PR_FILELIST_SCANNING in filelist. flags. 

e cancels any scanning busy message filelist. flags. 

e cancels any outstanding read request by sending an ao_cANCEL message to filelist.hpsel. 
Otherwise creates a list of files matching the path and filename pattern in fi1elist .wild as follows: 


© writes the current device specification to f£ilelist .wild and to the appropriate record in the 
filelist.contexts afray. 


e cancels any outstanding information message and display a scanning busy message. 
e sets PR_FILELIST_SCaNNING and clear PR_FILELIST_Noscan in filelist. flags. 
© sends a PS_SET_PATH message to filelist.hpsel. 

Sets PR_LISTBOX_UNSTABLE in listbox. flags. 


Resets the display and redraws the file list. 


14-13 


CHAPTER 15 


GENERAL SYSTEM DIALOGS 


This chapter describes a number of dialog classes that are supplied, ready for use, by HWIM. The classes 
are as follows: 


the ERRORDLG class which provides a dialog containing an error message. 


the queryDLc class which provides a dialog containing one or two lines of text and an action list 
prompting the user for a Yes/No response. 


the rLisTpuc class which provides a dialog containing an editable path and filename pattern. 


the ronTsEL class which provides a dialog that allows the user to select the required font and font 
style. 


the EvaLp.c class which provides a dialog that allows the user to select the system Calculator and 
Evaluate settings. 


the seTPoRTDLG Class which provides a dialog that allows the user to select the serial port settings. 


the sETHSHKDLG class which provides a dialog that allows the user to select the serial port 
handshake settings. 


For details of the dialling dialogs see the Dialling Dialogs chapter of the HWIM Reference manual. 


Precursors 


Familiarity with the following topics would aid understanding of this chapter: 


the piGBox class which is described in the Dialog Boxes chapter of the HWIM Reference manual. 
the wor class which is described in the Printing chapter of the FORM Reference manual 


WDR files which are described in the WDR Printing chapter of the Additional System Information 
manual 


15-1 


HWIM REFERENCE 


Class diagram 


¢ if 
Ns 1 
SY 4 
i gare 
ae, Sin 
‘ i sy, 
c win : 
‘ , 
c 
x. 


ae citaess ' ett ene 
roi os Ly” 2 


- /setportdlg yi / evald lg ae 


rome. one 


é os, [ne a Lis 
_sethshkdlg 5 / fonidig "> 
oe in ie ( 

\ ow, amet . eae) ’ eed Se \ Phe } 

ae me querydig ; ee flistdig ; ee 
SAL be L a u 
A ae MD) 
7 etrordig 


ERRORDLG 


DLGCHAIN | DLGBOX 


next count 


current 
underline 
absorb 
changed 


destroy 
wn_key 
wn_emphasise 
wn_sense_help 
wn_set 
wn_sense 
wn_draw 
di_item_lock 
dl_item_dim 
dl_set_item_flags 
dl_set_prompt 
dl_take_focus 


dl_item_replace 
dl_item_append 
dli_init 
di_dimmed_message 
dl_item_add 
dl_set_size 
dl_ing_minsize 


dl_key 


dl_changed 
dl_focus 


dl_handle_to_index dl_launch_sub 
dl_index_to_handle dl_item_new 


The ERorDLG class implements the Error dialog which presents the user with two lines of text followed by 
an action list containing a Continue button. An example Error dialog is shown in the following picture: 


eee 
15-2 


15 GENERAL SYSTEM DIALOGS 


The argument is 12 units 
Invalid arguments 


Continue 


SSS 


The simplest method of launching an Error dialog is to use the ws_error_dialog method of the wsERV 
object as described in the WSERV Class chapter of the HWIM Reference manual. 


Class definition 
Defined in sub-category file digbox.c/ (generated header file digbox.g). 


CLASS errordlg dlgbox 
{ 
REPLACE dl_dyn_init 
TYPES 


{ 


typedef struct 


{ 


WORD error; 
TEXT message [50] ; 
} RBUF_ERROR; 


} 
Resources 
Defined in system resource file s_.rss. 


RESOURCE DIALOG sys_error_dialog 


{ 


£lags=DLGBOX_RBUF_FILLED|DLGBOX_NO_DDP; 
controls= 
{ 
CONTROL 
{ 
class=C_TEXTWIN; 
£1ags=DLGBOX_ITEM_CENTRE |DLGBOX_ITEM_DEAD|DLGBOX_ITEM_ UNDERLINED; 
info=TXTMESS 
{ 
flags=IN_TEXTWIN_AL CENTRE; 
}; 
} ’ 
CONTROL 
{ 
class=C_TEXTWIN; 
£1lags=DLGBOX_ITEM_CENTRE|DLGBOX_ITEM_DEAD; 
info=TXTMESS 
{ 
flags=IN_TEXTWIN_AL CENTRE; 
}; 
} t 
CONTROL 


{ 


class=C_ACLIST; 
info=ACLIST 
{ 
rid=sys_ac_continue; 


}; 


15-3 


HWIM REFERENCE 


Property 
None. 


= eee eee eee ee) 
ERRORDLG methods 


initi 


isation 
VOID dl_dyn_init (vozD) ; 


Initialise the items in the error dialog. It is assumed that a1gbox.rbuf contains the address of an 
RBUF_ERROR Struct. 


Writes -1 to dlgbox.helprid indicating that there is no associated help resource. 


Sets the TExTwzn control with index zero to display the text message specified in dlgbox. rbuf->message. 
The control is set by sending self a wN_SET message. 


Sets the rextwin control with index one to display the error message that corresponds to the error code in 
digbox. rbuf ->error. The error code is converted to an error message using the hzrrs utility routine. The 
control is set by sending self a wN_SET message. 


QUERYDLG 


flags next 
id 
destroy wa-draw 


wn_position 
wn_redraw 


wn—sense—heip 


wn_visible 


DLGBOX 


item count 
rbuf current 
dimrid underline 
helprid absorb 
changed 


destroy di_item_replace 
wn_key dl_item_append 
wn_emphasise dl_init 
wn_sense_heip dl_dimmed_message 
wn_set di—ttem_add 
wn_sense dl_set_size 
wn_draw dl_ing_minsize 
dl_item_lock di —dyn—init 
dl_item_dim dl_key 
dl_set_item_flags 

dl_set_prompt dl_changed 
dl_take_focus dl_focus 
dl_handle_to_index dl_launch_sub 
dl_index_to_handle dl_item_new 


dl_item_add 
dl_dyn_init 


The queryp1c class implements the Query dialog which presents the user with two lines of text followed by 
an action list containing Yes and No buttons. An example Query dialog is shown in the following picture: 


This is the first line of text 
This is the second line of text 


No Yes 


a 


15 GENERAL SYSTEM DIALOGS 


A query dialog as its name suggest is most often used to request user confirmation as in the following 
example from the system screen: 


j Delete all files on "[B]"? 
No Yes 


Pa eee 


The simplest method of launching a Query dialog is to use the ws_query_dialog method of the wsERV 
object as described in the WSERV Class chapter of the HWIM Reference manual. 


Class definition 
Defined in sub-category file digbox.cl (generated header file digbox.g). 
CLASS querydlg dlgbox 


REPLACE dl_item_add 
REPLACE dl_dyn_init 
TYPES 
{ 
typedef struct 
{ 
WORD result; 
TEXT message [50] ; 
} RBUF_QUERY; 


} 


Property 
None. 


Resources 
Defined in system resource file s_.rss. 


RESOURCE DIALOG sys_query_dialog 
{ 
flags = DLGBOX_ACTION_LIST|DLGBOX_REPORT_ACT_HORIZ; 
controls= 


{ 


CONTROL 
{ 
flags=DLGBOX_ITEM_CENTRE|DLGBOX_ITEM_DEAD|DLGBOX_ITEM_UNDERLINED; 
info=TXTMESS 
{ 
flags=IN_TEXTWIN_AL CENTRE; 
}; 
}, 
CONTROL 
{ 
class=C_ACLIST; 
info=ACLIST 
{ 
rid=sys_ac_no_yes; 


be 


‘3 
} 


RESOURCE CONTROL sys_txtmess 


{ 


class=C_TEXTWIN; 
£lags=DLGBOX_ITEM_CENTRE |DLGBOX_ITEM_DEAD; 
info=TXTMESS 

{ 

flags=IN_TEXTWIN_AL CENTRE; 


}i 


15-5 


HWIM REFERENCE 


a a Se EE EI 
QUERYDLG methods 


VOID dl_dyn_init (vorD) ; 


Initialise the items in the dialog. It is assumed that digbox.rbuf contains the address of an RBUF_QUERY 
struct. 


Sets the TexTwrn control with index zero to display the text message specified by algbox. rbuf- omessage. 
The control is set by sending se1f a wN_SET message. 


Sets the TExTw1n control with index one to display the text in the resource whose id is dlgbox. rbuf - 
>result: no text is displayed if the ID is zero. The control is set by sending se1f a wN_SET message. 


Writes zero to digbox. rbuf->result. 


VOID di_item_add(AD_DLGBOX *par) ; 
Add textwrn controls for the text message and the resource text if specified. 
Adds the dialog item specified by par by supersending a pL_1T=m_app message with par as argument. 


If dlgbox. count is unity and digbuf .rbuf->result is non-zero, appends the TExTwrN control specified by 
the sys_txTmEss system resource. The control is appended by sending sei a DL_ITEM_APPEND message. 


FLISTDLG 


flags 
id 
desezey 


wn_position 
wn_redraw 


wn—sense—hetp 


wn_visible 


pew DLGCHAIN | DLGBOX 


next item count 
rbuf current 
dimrid underline 
helprid absorb 
changed 
whe-draw 


destroy dl_item_replace 
wn_key di_item_append 
wn_emphasise dl_init 
wn_sense_help dl_dimmed_message 
wn_set dl_item_add 
wn_sense dl_set_size 
wn_draw dl_ing_minsize 
dl_item_lock di—dyn—init 
di_item_dim di-key 
dl_set_item_flags 

dl_set_prompt dl_changed 
dl_take_focus di_focus 
dl_handle_to_index dl_launch_sub 
di_index_to_handle dl_item_new 


The FLIstTDLc class implements the File list dialog which presents the user with an editable file name 
pattern and an editable full path. An example File list dialog is illustrated in the following picture: 


15-6 


15 GENERAL SYSTEM DIALOGS 


Specify filelist 


‘Filename pattern] 
‘Full path LOC::B:\APP. 


An example of a File list dialog may be obtained while the file selector is present by pressing the Tab key. 
Class definition 
Defined in sub-category file digbox.c/ (generated header file digbox.g). 


CLASS flistdlg dlgbox 


{ 
REPLACE dl_dyn_init 
REPLACE dl_key 


} 


Property 

None. 

Resources 

Defined in system resource file s_.rss. 


RESOURCE DIALOG sys_flist_dialog 
{ 
title="Specify filelist"; 
£lags=DLGBOX_NOTIFY_ENTER | DLGBOX_RBUF_FILLED; 
controls= 
{ 
CONTROL 
{ 
class=C_EDWIN; 
prompt="Filename pattern"; 
info=EDWIN 
{ 
maxlen=P_FNAMESIZE; 
vulen=18; 
flags=IN_EDWIN_VULEN_CHARACTERS; 
hi 
}, 
CONTROL 
{ 
class=C_EDWIN; 
prompt="Full path"; 
info=EDWIN 
{ 
maxlen=P_FNAMESIZE; 
vulen=18; 
flags=IN_EDWIN_VULEN_CHARACTERS; 


}; 


= ee A a 
FLISTDLG methods 


VOID dl_dyn init (VOID) ; 
Initialise the items in the dialog. 


Builds a full file specification from the file specification pointed to by digbox. rbuf, using the £_fparse 
PLIB library routine, and a wuz related file specification. 


If neither the filename, nor the extension, in the full file specification are wild carded, removes both the 
filename and the extension and appends a zero terminated asterisk. 


SSeS 
15-7 


HWIM REFERENCE 


Displays the filename component of the full file specification in the Filename pattern control. 


Displays the full path components of the full file specification in the Full path control. 


INT dl_key(INT id, INT keycode) ; 
Handle a key press. 


Builds a full file specification from the text displayed in the control with index ia, using the p_fparse 
PLIB library routine. The related file specification is the text displayed in the Epwrw control with index 3- 
id. 


If one or more components of the full file specification are invalid, displays an appropriate error message 
using the hinfoPrinterr utility function and retums wN_KEY_NO_CHANGE. 


If the full file specification does not contain wild cards, and both filename and extension are absent, 
appends a zero terminated asterisk. 


Writes the full file specification to the address in digbox.rbuf and returns WN_KEY CHANGED. 


FONTSEL 


flags next 
id 
destrey wh—draw 


wn_position 
wn_redraw 


wh—sense—heip 


wn_visible 


count 
rbuf current 
dimrid underline 
helprid absorb 
changed 


dl_item_replace 
wn_key dl_item_append 
wn_emphasise dl_init 
wn_sense_help dl_dimmed_message 
wn_set dl_item_add 
wn_sense dl_set_size 
wn_draw di_ing minsize 
dl_item_lock di—dyn—tnit 
dl_item_dim di—key 
dl_set_item_flags 

dl_set_prompt di—-changed 
dl_take_focus dl_focus 
dl_handle_to_index dl_launch_sub 
dl_index_to_handle dl_item_new 


The Fonts class implements the Font selector dialog which presents the user with selectable font, font 
size, font style and print position items. An example Font selector dialog is shown in the following picture: 


Font 


¢Pica> 
‘Size 12 


‘Underline No 
‘Bold Yes 
‘Italic No 
‘Print position Normal 


(Note that the Font control displays typefaces and not fonts, although the meaning is clear.) 


15-8 


15 GENERAL SYSTEM DIALOGS 


Another example of a font selector dialog is provided by the Word application as illustrated in the 
following picture (the dialog is obtained by selecting the Font item from the Paragraphs menu): 


Font 
‘Font Proportional 
‘Size 
‘Underline 


‘Bold 

‘Italic 

¢ 

‘Alter Superscript EG, 
Subscript 


The dialog also illustrates the pop-up menu for the Print position item: the user may select Normal, 
Superscript or Subscript. Notice the extra item that has been appended to the dialog. 


The dlgbox.rbuf property must point to a FonrsEL_pata struct defined as follows: 


typedef struct 


{ 


VOID *wdr; 
SCRLAY_FONT *pf; 
UWORD ret; 

} FONTSEL_DATA; 


The significance of the members of the ronrsEL_para struct is as follows: 
wdr specifies the handle of the current wor object. 
pf specifies the address of a scrLay_Fonr struct containing the font data to be edited. 


ret the return value set by the di_key method - it is set to a non-zero value if any of the font 
characteristics have been edited and to zero otherwise. 


Class definition 
Defined in sub-category file fontdlg.cl (generated header file fontdlg.g). 


CLASS fontsel dlgbox 
{ 
REPLACE dil_dyn_init 
REPLACE di_changed 
REPLACE dl_key 
TYPES 
{ 
typedef struct 
{ 
VOID *wdr; 
SCRLAY_FONT *pf; 
UWORD ret; 
} FONTSEL_DATA; 


} 


PROPERTY 
1 
PR_ROOT *names; font names list 
PR_ROOT *sizes; size list for current name 
VOID *wdr; printer queries 
SCRLAY_FONT *pf; target for new font data 
SCRLAY_FONT f; copy of original input font data 
} 
} 
Property 
fontsel.names | @ VASTR array containing the names of the typefaces supported by the current printer 
model 


fontsel.sizes | @ VASTR afray containing font heights in points for the current typeface 


15-9 


HWIM REFERENCE 


the handle of an instance of wor that accesses the current wor file: a wor file contains 
printer specific data including font details. (See the description of the wor class for 


further details.) 
a pointer to a ScRLAY_FonT struct which contains the edited font data 


fontsel.wdr 


fontsel.pf 
fontsel.f a SCRLAY_FONT struct which contains the input font data 


Resources 
Defined in system resource file s_.rss. 


RESOURCE DIALOG sys_font_dl 
{ 
title="Font"; 
flags=DLGBOX_NOTIFY_ENTER | DLGBOX_RBUF_FILLED; 
controls= 
{ 
CONTROL 


{ 


£flags=DLGBOX_ITEM_NOTIFY_CHANGED; 
class=C_CHLIST; 

prompt="Font"; 

info=CHLIST{}; 


CONTROL 
{ 
class=C_CHLIST; 
prompt="Size"; 
info=CHLIST{}; 


CONTROL 
{ 
class=C_CHLIST; 
prompt="Underline"; 
info=CHLIST{rid=sys_no_yes;}; 
). 

CONTROL 
{ 
class=C_CHLIST; 
prompt="Bold"; 
info=CHLIST{rid=sys_no_yes;}; 
}. 

CONTROL 
{ 
class=C_CHLIST; 
prompt="Italic"; 
info=CHLIST{rid=sys_no_yes;}; 
}. 

CONTROL 
{ 
class=C_CHLIST; 
prompt="Print position"; 
info=CHLIST{rid=sys_prn_pos;}; 
} 

}; 

} 


RESOURCE MENU sys_prn_pos 

{ 

items= 
{ 
CHOICE_ITEM {str="Normal";}, 
CHOICE_ITEM {str="Superscript";}, 
CHOICE_ITEM {str="Subscript"; } 
}; 

} 


Additional items may be appended by sending one or more pb_tTEmM_App and/or DL_ITEM_APPEND messages 
during the initialisation of the dialog: see the Dialog Boxes chapter for further details. 


15 - 10 


15 GENERAL SYSTEM DIALOGS 


ee PR SR 
FONTSEL methods 


DL_DYN_INIT — 


VOID dl_dyn_init(vozp) ; 


lisation 


Initialise the items in the dialog. It is assumed that dlgbox. rbuf contains the address of a FONTSEL_DATA 
struct. 


Writes dlgbox. rbuf ->wdr to fontsel.wdr, Writes dlgbox.rbuf->pf to fontsel .pf and writes 
*dlgbox.rbuf->pf to fontsel.f. 


Creates an instance of the vastr class, writes its handle to font se1 .names, and initialises by sending a 
VA_INIT message to fontsel .names specifying a granularity of sixteen. 


Creates a second instance of the vastr class, writes its handle to fontsel.sizes, and initialises by sending 
a VA_INIT message to fontsel.sizes specifying a granularity of sixteen. 


Obtains the number of typefaces by sending a woR_SENSE_MODEL message to fontsel .wdr. Obtains the 
name of each typeface by sending a woR_TYPEFACE message to fontsel.war and adds to the names array 
by sending va_APPEND messages to fontsel .names. 


Sets the fontsel .names array as the data for the Font contro] by sending self a wN_SET message. 
Sets the fontsel . sizes array as the data for the Size control by sending self a wN_SET message. 


Obtains the index for the typeface with RTF/Word typeface index fontsel .pf->typeface by sending a 
WDR_SEARCH_TYPEFACE Message to fontsel .wdr, and sets as the selected item in the Font control by 
sending self a WN_SET message. 


Scans the current wor file for the available sizes in the current typeface and adds each size to the sizes array 
by sending va_APPEND messages to fontsel.sizes. (The steps are as described for the a1_changed 
method.) 


Sets the selected item in the Underline control to Yes if the least significant bit in fontsel -pf->style is 
set. Otherwise sets the selected item to No. 


Sets the selected item in the Bold control to Yes if the second least significant bit in gontse1 .p£- >style is 
set. Otherwise sets the selected item to No. 


Sets the selected item in the /talic control to Yes if the third least significant bit in fontsel .p£->style is 
set. Otherwise sets the selected item to No. 


Sets the selected item in the Print position control. This may be Normal, Superscript or Subscript 
depending on whether or not the wor_sTYLE_SUPER OF WDR_STYLE_sus flags are set in fontsel .pf->style: 
note that these flags are mutually exclusive. 


INT dl_key(INT index, INT keycode) ; 
Handle a key press. 


Senses the index of the item selected in the Font control, converts the index to an RTF/Word index by 
sending a WOR_TYPEFACE message to fontsel .wdr and then writes the result to gontsel.p£->fid. 


Senses the index of the item selected in the Size control, obtains the font height in twips by sending a 
WDR_FONT_HEIGHT message to fontsel.wdr and then writes the twips height to fontsel ._pf->height. 


Writes zero to fontsel.pf->style. 

If the selected item in the Underline control is Yes, sets the least significant bit in fontsel -pf->style. 
If the selected item in the Bold control is Yes, sets the second least significant bit in fontsel .pf->style. 
If the selected item in the Italic control is Yes, sets the third least significant bit in fontse1 -pf->style. 


Compares fontsel .pf and sfontsel.f using the p_bemp PLIB library routine writing the return value to 
digbox.rbuf->ret: zero indicates identical data. 


ee ee 
15-11 


HWIM REFERENCE 


Returns WN_KEY_CHANGED. 


DLE 


VOID dl_changed(INT changed) ; 


Set the data and the selected item for the Size control. 


Obtains the index of the item selected in the Size control and then resets the sizes array by sending a 
VA_RESET message to fontsel.sizes. 


Obtains the number of font heights by sending a wor_TYPEFACE message to fontsel. war. 


Obtains each font height in twips by sending wor_FonT_HEIGHT messages to fontsel .wdr, convert into 
points by dividing by twenty, and adds to the sizes array by sending a va_APPEND message to 
fontsel.sizes. 


Obtains the index of the font with twips height fontse1 .pf->height by sending a wOR_SEARCH_HEIGHT 
message to fontsel .wdr and then sets this as the index of the selected item in the Size control. 


EVALDLG 


flags next 
id 
destrey wa-draw 


wn_calc_position |wn—emphasise 


DLGBOX 


item count 
rbuf current 
dimrid underline 
helprid absorb 
changed 


destroy dl_item_replace 
wn_key dl_item_append 
wn_emphasise dl_init 
wn_sense_help dl_dimmed_message 
wn_set dl_item_add 
wn_sense di—set—size 
wn_draw dl_ing_minsize 
dl_item_lock éi—dyn—init 
dl_item_dim di—key 
dl_set_item_flags 4i—changed 
di_set_prompt 

di_take_focus di_focus 
di_handle_to_index di_launch_sub 
dl_index_to_handle dl_item_new 


dl_dyn_init 
dl_set_size 


wn_position 
wn_redraw 


wa_sense—heip 


wn_visible 


The EvaLDLG Class implements the Set Calculator format and Set "Evaluate" format dialogs. 


The Set Calculator format presents the user with the format, number of significant digits and trigonometry 
units as used by the calculator and which are stored in the system wide msv environment variable. An 
example Set Calculator format dialog is illustrated in the following picture: 


Set Calculator format 
‘Format Scientific 


‘Significant digits 


‘Trigonometry units Degrees 


The Ser "Evaluate" format dialog presents the user with the format, number of decimal places and 
trigonometry units as used by the evaluator and which are also stored in the system wide msv environment 
variable. An example Set "Evaluate" format dialog is illustrated in the following picture: 


15-12 


15 GENERAL SYSTEM DIALOGS 


Set "Evaluate" format 


‘Format Fixed 
‘Decimal places 2 


‘Trigonometry units Ba eeulk iets 


The simplest method of launching either of the above dialogs is to use the ws_format_dialog method of 
the wsERv object as described in the WSERV Class chapter of the HWIM Reference manual. 


Class definition 
Defined in sub-category file evaldlg.cl (generated header file evaldlg.g). 


CLASS evaldlg dlgbox 


{ 

REPLACE dl_dyn_init 
REPLACE dl_set_size 
REPLACE dl_changed 
REPLACE dl_key 


CONSTANTS 


{ 
EVALDLG_CALCULATOR_EVALUATOR 0 /* set this flag in rbuf for calc evaluator */ 
EVALDLG_GENERAL_EVALUATOR 1 /* set this flag in rbuf for general evaluator */ 


} 


PROPERTY 


{ 


WORD isEval; 
EXTENDED_MEM_VALUES eMem; 


} 
} 


Property 


evaldlg.isEval contains either EVALDLG_GENERAL_EVALUATOR for a Set "Evaluate" format dialog, or 
EVALDLG_CALCULATOR_EVALUATOR for a Set Calculator format dialog 


evaldlg.eMem an EXTENDED_MEM_VALUES struct that contains the current data 


15-13 


HWIM REFERENCE 
ee SSeSeSSSSeSeeSSeSeeSSSSSSSeeSSSSSSS 


Resources 


Defined in system resource file s_.rss. 


RESOURCE DIALOG sys_eval_dialog 


{ 


title="Set Calculator format"; 
flags=DLGBOX_NOTIFY_ENTER |DLGBOX_RBUF_FILLED; 
controls= 

{ 


CONTROL 


{ 


flags=DLGBOX_ITEM_NOTIFY_CHANGED; 
class=C_CHLIST; 
prompt="Format"; 
info=CHLIST { rid=sys_format_chlist; }; 
}, 

CONTROL 


{ 


class=C_NCEDIT; 
prompt="Significant digits"; 
info=NCEDIT 


{ 
high=12; 
low=0; 
}: 
ys 
CONTROL 
{ 


class=C_CHLIST; 
prompt="Trigonometry units"; | 
info=CHLIST { rid=sys_rad_deg; }; 
} 
yi 
} 


RESOURCE MENU sys_format_chlist 

{ 

items = 
{ 
CHOICE_ITEM { str="Fixed";}, 
CHOICE_ITEM { str="Scientific";}, 
CHOICE_ITEM { str="General";}, 
CHOICE_ITEM { str="Hexadecimal"; } 
}; 

} 


RESOURCE MENU sys_rad_deg 


{ 


items = 


{ 


CHOICE_ITEM { str= "Radians";}, 
CHOICE_ITEM { str= "Degrees"; } 
}; 

} 


RESOURCE STRING sys_evaldlg title 


{ 


str="Set \"Evaluate\" format"; 


} 


BS ee ee ee a a a Sy 
EVALDLG methods 


Dynamic initialisation 


VOID dl_dyn_init (VOID) ; 


Initialise the items in the dialog and, if necessary, the msv environment variable. 


15-14 


15 GENERAL SYSTEM DIALOGS 
—_. $$ GENERAL SYSTEM DIALOGS 


Writes dlgbox.rbuf to evaldig.isEval: it is assumed that this points to an EXTENDED_MEM_VALUES struct 
which is defined as follows: 


typedef struct 


{ 


UBYTE evalDegrees; 
UBYTE calcDegrees; 
MEM_VALUES memVal; 
} EXTENDED_MEM_VALUES; 


typedef struct 


{ 

UBYTE evalFormat; /* Dtob format code for all except calc */ 
UBYTE evalDPlaces; /* Decimal places for all except calc */ 
UBYTE calcFormat; /* Dtob format code */ 

UBYTE calcDPlaces; /* Decimal places, if relevant */ 

DOUBLE values [MAX_MEMORIES] ; 

} MEM_VALUEs ; 


If no msv environment variable exists, creates one with the following default values: 
p_bfil(p, sizeof (MEM_VALUES) , 0) ; 
p->evalFormat= (EVAL_DEFAULT_FMT_TYPE|DEGREES MODE) ; 
p->calcFormat= (CALC_DEFAULT_FMT_TYPE|DEGREES MODE) ; 
p->evalDPlaces=EVAL_DEFAULT_PLACES; /* 2 for evaluator */ 
p~->calcDPlaces=CALC DEFAULT_PLACES; /* 14 for cale */ 

Writes the contents of the msv environment variable to evaldlg.eMem.memval. 

Initialises the remaining members of evaidig.eMem as follows: 
evaldig.eMem.evalDegrees=evaldlg.eMem.memVal.evalFormat&DEGREES MODE; 
evaldlg.eMem.calcDegrees=evaldlg.eMem.memVal.calcFormat&DEGREES MODE; 
evaldlg.eMem.memVal.evalFormat&=(~DEGREES_ MODE) ; 
evaldlg.eMem.memVal .calcFormat&=(~DEGREES_MODE) ; 

For the Set Calculator format dialog: 
e sets the Format control to display the item with index evaldig.eMem->memVal.calcFormat 


e — sets the Significant digits control to display the integer value in evaldig.eMem- 
omemVal .evalDPlaces 


¢ — sets the Trigonometry units control to display either the item with index one, if evaldig.eMem- 
>memVal .calcDegrees is non-zero, or the item with index zero if it is zero 


For the Set "Evaluate" format dialog: 
e sets the Format control to display the item with index evaldlg.eMem- >memVal.evalFormat 


e — sets the Decimal places control to display the integer value in evaldig.emem- 
>memVal .evalDPlaces 


¢ — sets the Trigonometry units control to display the item with index one if evaldig .emMem- 
>memVal .evalDegrees is non-zero. Otherwise sets the control to display the item with index zero. 


© — sets the dialog title from the text in the sys_EVALDLG_TITLE system resource. 


e key input 
INT dl_key(INT index, INT keycode) ; 
Write the current selection into the evaldig.eMem property and the msv environment variable. 


For the Set "Evaluate" format dialog: 


e writes the index of the item selected in the Format control to 
evaldlg.isEval.memVal .evalFormat 


¢ if the format is either Fixed or Scientific, writes the value in the Significant digits/Decimal places 
control to evaidlg.isEval .memVal.evalDPlaces 


15-15 


HWIM REFERENCE 
——— See SSS 


© writes the index of the item selected in the 7rigonometry units control to 
evaldig.isEval .memVal.evalDegrees 


For the Set Calculator format dialog: 


® writes the index of the item selected in the Format control to 
evaldlg.isEval.memVal .calcFormat. 


¢ if the format is either Fixed or Scientific, writes the value in the Significant digits/Decimal places 
contro] to evaldlg.isEval .memVal.calcDPlaces 


e writes the index of the item selected in the Trigonometry units control to 
evaldlg.isEval .memVal.calcDegrees 


Sets the content of evaldlg.isEval.memval: 


pV=&self->evaldlg.isEval; 

pV->memVal .calcFormat&=~DEGREES MODE; /* clear top bit before or'ring */ 
pV->memVal .calcFormat | =pV->calcDegrees; 

pV->memVal . evalFormat&=~DEGREES MODE; 

pV->memVal .evalFormat | =pV->evalDegrees; 


Writes the content of evaldig.isEval .memval to the sv environment variable: if this does not exist it is 
created. 


Returns wN_KEY_CHANGED. 


essages 
VOID dl_changed(INT changed) ; 
Set the prompt for the Significant digits/Decimal places control and dim or un-dim as appropriate. 


If the item selected in the Format control is either General or Hexadecimal, dims the Significant 
digits/Decimal places control. 


Otherwise if the item selected in the Format control is Scientific, sets the the sys_sIc_p1crTs system 
resource as the prompt for the Significant digits/Decimal places control and then un-dims the Significant 
digits/Decimal places control. 


Otherwise if the item selected in the Format control is Fixed, sets the sys_DEC_PLACEs system resource as 
the prompt for the Significant digits/Decimal places control and then un-dims the Significant 
digits/Decimal places control. 


_ Setn 


VOID dl_set_size (VOID) ; 
Supersend a pL_SET_SIZE message. 


Sets the prompt for the Significant digits/Decimal places control and dims or un-dims the control as 
appropriate. 


Reads the format specified in evaldig.eMem.memval .evalFormat if the dialog is a Set "Evaluate" format 
dialog, or evaldig.eMem.memval.calcFormat otherwise. 


If the format is either General or Hexadecimal, dims the Significant digits/Decimal places control. 


If the format is Scientific, sets the the sys_stc_p1c1Ts system resource as the prompt for the Significant 
digits/Decimal places control and then un-dims the Significant digits/Decimal places control. 


If the format is Fixed, sets the sys_pEc_PLACES system resource as the prompt for the Significant 
digits/Decimal places control and then un-dims the Significant digits/Decimal places control. 


15 - 16 


13 GENERAL SYSTEM DIALOGS 


SETPORTDLG 


flags 
id 
destrey whedraw 


wn_position 
wn_redraw 


wrh—sense—heip 


wn_visible 


SETPORTDLG 


next item count 
rbuf current 
dimrid underline 
helprid absorb 
changed 


destroy di_item_replace 
wn_key dl_item_append 
wn_emphasise dl_init 
wn_sense_help dl_dimmed_message 
wn_set di_item_add 
wn_sense dl_set_size 
wn_draw di_ing_minsize 
di_item_lock di—dyn—tnit 
dl_item_dim di-key 
dl_set_item_flags 

dl_set_prompt dl_changed 
dl_take_focus dl_focus 
dl_handle_to_index dl_launch_sub 
dl_index_to_handle dl_item_new 


The setportois class implements the Set serial port dialog which presents the user with editable serial 
port characteristics i.e. baud rate, number of data bits, number of stop bits, parity and parity mode. An 
example Set serial port dialog is shown in the following picture: 


Set Serial port 


+9686 
‘Data bits 8 


‘Stop bits 1 
‘Parity None 
‘Ignore parity Yes 


The example dialog may be obtained by entering the Comms application and selecting the Port item in the 
Special menu. 


The digbox.rbuf property must point to a P_sRcuaR struct which is described in the Serial port chapter of 
the 1/O Devices Reference manual. 


Class definition 
Defined in sub-category file serdlgs.cl (generated header file serdigs.g). 


CLASS setportdlg dlgbox 


{ 
REPLACE dl_dyn_ init 
REPLACE dl_key 


} 


Property 
There is no property associated with the sETpoRTDLG class. 


15-17 


HWIM REFERENCE 
ee See 


Resources 


Defined in system resource file s_.rss. 
The Series 3 version of the sys_BAUD_RATE_CHLIST system resource is as follows: 


RESOURCE MENU sys_baud_rate_chlist 

{ 

items = 
{ 
CHOICE_ITEM { str= "9600";}, 
CHOICE_ITEM { str= "4800";}, 
CHOICE_ITEM { str= "2400";}, 
CHOICE_ITEM { str= "1200";}, 
CHOICE _ITEM { str= "600";}, 
CHOICE_ITEM { str= "300";} 
He 

} 


The Series 3a version of the sys_BAUD_RATE_CHLIST system resource is as follows: 


RESOURCE MENU sys_baud_rate_chlist 
{ 


items = 


{ 
CHOICE_ITEM { str= "19200"; }, /* new for S3a */ 
CHOICE_ITEM { str= "9600";}, 
CHOICE_ITEM { str= "4800";}, 
CHOICE _ITEM { str= "2400";}, 
CHOICE_ITEM { str= "1200";}, 
CHOICE_ITEM { str= "600";}, 
CHOICE_ITEM { str= "300"; } 
}; 
} 


The remaining resources are common to both machines: 


RESOURCE MENU sys_data_bits_ chlist 

{ 

items = 
{ 
CHOICE_ITEM { str="5";}, 
CHOICE_ITEM { str="6";}, 
CHOICE_ITEM { str="7";}, 
CHOICE_ITEM { str="8";} 
}; 

} 


RESOURCE MENU sys_stop_bits chlist 
{ 
items = 
{ 
CHOICE_ITEM { str="1";}, 
CHOICE_ITEM { str="2";} 
}; 
} 


RESOURCE MENU sys_parity_chlist 
{ 
items = 
{ 
CHOICE_ITEM { str="None";}, 
CHOICE_ITEM { str="Even";}, 
CHOICE_ITEM { str= "Odd"; } 


}; 


15-18 


15 GENERAL SYSTEM DIALOGS 


RESOURCE MENU sys_no yes 
{ 
items = 


{ 


CHOICE_ITEM { str= "No";}, 
CHOICE_ITEM { str="Yes";} 
}; 

} 


RESOURCE DIALOG sys_set_port_dialog 


{ 
title="Set Serial port"; 
flags=DLGBOX_NOTIFY_ENTER|DLGBOX_RBUF_FILLED; 


controls= 


{ 


CONTROL 


{ 


class=C_CHLIST; 
prompt="Baud rate"; 
info=CHLIST 


{ 


rid=sys_baud_rate_chlist; 
nsel=0; 
}; 
}, 
CONTRO 
{ 


class=C_CHLIST; 
prompt="Data bits"; 
info=CHLIST 
{ 
rid=sys_data_bits_chlist; 
nsel=0; 
}; 
ys 
CONTROL 


{ 


class=C_CHLIST; 
prompt="Stop bits"; 
info=CHLIST 


{ 


rid=sys_ stop bits chlist; 
nsel=0; 
}i 
- 
CONTROL 


{ 


class=C_CHLIST; 
prompt="Parity"; 
info=CHLIST 


{ 


rid=sys_parity_chlist; 
nsel=0; 
); 
}, 
CONTROL 


{ 


class=C_CHLIST; 
prompt="Ignore parity"; 
info=CHLIST 


{ 
rid=sys_no_yes; 
nsel=0; 


}i 


15-19 


HWIM REFERENCE 


ee en ee eS ee ee ED 
SETPORTDLG methods 


D INT : Initialise dialog items 


VOID dl_dyn_init (VOID) ; 


Initialise the content of the dialog. 


Sets the index of the item selected in the Baud rate control according to the flag in dlgbox .rbuf->tbaud. 
The flags and the corresponding indices are as follows: 


Series 3 flag Series 3a flag 


P_BAUD_9600 P_BAUD_19200 


P_BAUD_4800 P_BAUD_9600 


P_BAUD_2400 


P_BAUD_ 4800 


P_BAUD_2400 P_BAUD_2400 


P_BAUD_600 


P_BAUD_2400 


P_BAUD_300 P_BAUD_600 


none P_BAUD_300 


If dlgbox.rbuf ->frame is non-zero, sets the index of the item selected in the Data bits control to 
P_DATA_8. 


Otherwise, sets the index of the item selected in the Data bits control to zero. 


If digbox. rbuf ->frame contains p_Two_stop, sets the index of the item selected in the Stop bits control to 
one. 


If digbox. rbuf->frame contains the p_parrry flag, sets the index of the item selected in the Parity control 
to dlgbox.rbuf.parity. 


If dlgbox. rbuf->frame contains the p_IGNORE_PARITY flag, sets the index of the selected item in the 
Ignore parity control to one i.e. Yes. 


Handle key input 
INT dl_key(WORD id, INT event) ; 
Handle a keypress. 


Senses the index of the item selected in the Baud rate control and then writes the corresponding flag to 
both digbox.rbuf->tbaud and dlgbox.rbuf->rbaud. The possible indices and the corresponding flags are 


as follows: 
Series 3a flag 


P_BAUD_19200 


P_BAUD_9600 


P_BAUD_4800 


P_BAUD_9600 


P_BAUD_2400 P_BAUD_4800 


P_ BAUD 2400 


P_BAUD_2400 


P_BAUD_600 P_BAUD_2400 


P_BAUD_300 


P_BAUD_600 


none 


P_BAUD_300 


15 GENERAL SYSTEM DIALOGS 
|) —< << KOE NERAL STO TEM DIALOGS | 


Writes the index of the item selected in the Data bits control to digbox.rbuf->frame. 


If the index of the item selected in the Stop bits control is non-zero, ors the P_twosTop flag into 
digbox.rbuf->frame. 


Writes the index of the item selected in the Parity control to digbox.rbuf->parity, and, if the index is 
NnON-ZETO, ORS P_PARITY into dlgbox.rbuf->frame. 


Writes the index of the item selected in the Ignore parity control to digbox. rbuf->flags. 


Returns wN_KEY_CHANGED. 


SETHSHKDLG 


flags next 
id 
destroy wh—draw 


DLGBOX 


item count 
rbuf current 
dimrid underline 
helprid absorb 
changed 


SETHSHKDLG 


destroy dl_item_replace 
wn_key dl_item_append 
wn_emphasise di_init 
wn_sense_help di_dimmed_message 
wn_set dl_item_add 
wn_sense dl_set_size 
wn_draw dl_ing_minsize 
dl_item_lock di—dyn—inie 
dl_item_dim ai—key 
dl_set_item_flags 

dl_set_prompt di_changed 
@l_take_focus dl_focus 
d@l_handle_to_index dl_launch_sub 
dl_index_to_handle dl_item_new 


dl_dyn_init 


wn_cale position |wn-emphasise dl_key 


The sETHSHKDLG class implements the Set serial handshake dialog which present the user with editable 
serial port handshake settings i.e. the Xon/Xoff, Rts/Cts, Dsr/Dtr and Ded settings. An example Set serial 
handshake dialog is shown in the following picture: 


Set serial handshake 
‘Ron Xoff On 


‘Rts/Cts ¢+Off> 
‘Dsr/Dtr Off 
‘Ded Off 


Each control may be set to either On or Off. 


The digbox.rbuf property must point to a uBYTE containing an ored combination of handshake flags - the 
allowed flags are described in the Serial port chapter of the J/O Devices Reference manual. 


Class definition 
Defined in sub-category file serd/gs.cl (generated header file serdlgs.g). 


CLASS sethshkdlg dlgbox 


{ 
REPLACE dl_dyn_init 
REPLACE dl_key 


} 


SSS 
15-21 


HWIM REFERENCE 
ee eee 


Property 

None. 

Resources 

Defined in system resource file s_.rss. 


RESOURCE DIALOG sys_set_hshk_dialog 
{ 
title="Set serial handshake"; 
flags=DLGBOX_NOTIFY_ENTER |DLGBOX_RBUF_FILLED; 
controls= 


{ 


CONTROL 


{ 


class=C_CHLIST; 

prompt="Xon/Xoff"; 

info=CHLIST 
{ 
rid=sys_offon_menu; 
nsel=0; 
}e 

}, 

CONTROL 


{ 


class=C_CHLIST; 
prompt="Rts/Cts"; 
info=CHLIST 
{ 
rid=sys_offon_menu; 
nsel=0; 
}i 
}, 
CONTROL 


{ 


class=C_CHLIST; 
prompt="Dsr/Dtr"; 
info=CHLIST 
{ 
rid=sys_offon_menu; 
nsel=0; 
a 
he 
CONTROL 


{ 


class=C_CHLIST; 
prompt="Ded"; 
info=CHLIST 


{ 


rid=sys_offon_menu; 
nsel=0; 


}; 


}; 
} 


RESOURCE MENU sys_offon_menu 


{ 


items = 


{ 


CHOICE_ITEM { str="0ff";}, 
CHOICE ITEM { str= "On";} 


}; 


15 - 22 


15 GENERAL SYSTEM DIALOGS 


a a oe a ar a ay a a] 
SETHSHKDLG methods 


DL_DYN_INIT ___—is.. _ _ dnitialise items 
VOID dl_dyn_init (VOID) ; 

Initialise the items in the dialog. 

If sel£->dlgbox.rbuf contains P_oBEY_xoFF, sets the Xon/Xoff control to display On. 

If sel£->dlgbox.rbué does not contain p_ien_crs, sets the Rts/Cts control to display On. 


If self->dlgbox.rbuf contains p_oBEY_pskr, sets the Dsr/Dtr control to display On. 


If self£->dlgbox.rbuf contains p_oBEY_pcp, sets the Ded control to display On. 


_ Handle key input 
INT dl_key(WORD id, INT event) ; 

Handle key input. 

Write zero to *dlgbox. rbuf. 


If the index of the item selected in the Xon/Xoff control is non-zero, ors P_OBEY_XOFF and P_SEND_XOFF 
into *dlgbox. rbuf. 


If the index of the item selected in the Rts/Cts control is zero, oRS P_IGN_CTS into *dlgbox. rbuf. 
If the index of the item selected in the Dsr/Drr control is non-zero, ors P_OBEY_DSR into *digbox. rbuf. 
If the index of the item selected in the Ded control is non-zero, ors P_OBEY_DsD into *dlgbox. rbuf. 


Retums wN_KEY_CHANGED. 


15 - 23 


— 


CHAPTER 16 


PRINT CLASSES 


This chapter describes the xwim printing, print preview and print dialog classes which provide a convenient 
means of accessing the current printer parameters and performing a printing or print preview operation. 
Although these dialog classes are described in this chapter, the descriptions are included mainly for 
completeness since there will generally be no need for an application to subclass or to explicitly create any 
of them. 


The classes that are described in this chapter are as follows: 


e the LpRinTeR class which provides the basic framework for a printing operation and may be used, 
for example, to print multiple columns with a specific font and font style for each column. The 
class must be subclassed to be useful. 


e the ppgvpte class which implements the Printer configuration dialog allowing the user to edit the 
current printer settings. The edited settings are stored as environment variables so that they may 
be accessed by other applications. 


e the prnprev class which implements the Preview settings dialog allowing the user to edit the print 
preview settings. It is not available on the Series 3 machine. 


e the prncrri class which implements the Print setup dialog allowing the user to edit the current 
page layout settings. The edited settings are stored in the current PRINTER object so that they may 
be accessed by other objects used by the application. 


e the pacecrrt class which implements the Paging control dialog allowing the user to edit the page 
number style. The edited settings are stored in the current pRinTER object so that they may be 
accessed by other objects used by the application. 


e _ the marcins class which implements the Margins dialog allowing the user to edit the page 
margins. The edited settings are stored in the current printer object so that they may be accessed 
by other objects used by the application. 


e the HEapFoor class which implements the Header details and Footer details dialogs allowing the 
user to edit the header and the footer respectively. The edited settings are stored in the current 
PRINTER Object so that they may be accessed by other objects used by the application. 


e the prNMopEL class which implements the Set printer dialog allowing the user to select the printer 
model and default font. The edited settings are stored in the current PRINTER object so that they 
may be accessed by other objects used by the application. . 


e the pacrszze class which implements the Page size dialog allowing the user to edit the page size 
and orientation. The edited settings are stored in the current PRINTER object so that they may be 
accessed by other objects used by the application. 


e the printine class which provides the Printing dialog allowing a printing operation to be started, 
monitored and cancelled. A Printing dialog is launched by the LpRInTER class. 


e the pmopiocs class which is used as a component by the prwmopet class. This class is highly 
specialised and is thus unlikely to be used elsewhere. 


Any application may create and use the Print setup or Printer configuration dialogs by sending 
WS_EDIT_PRINT_CONTEXT OF WS_EDIT_PDEV_SETUP messages to the application's instance of (a subclass of) 
wseERV. All the dialogs described in this chapter are, directly or indirectly, components of either or both of 
these two dialogs. 


16-1 


HWIM REFERENCE 


The differences in screen size between the Series 3, Series 3a and Workabout result in different limits on 
the number of items that may appear in a dialog. In consequence, there are some differences of 
implementation of the print dialog classes between the different machine types. On the Series 3a, for 
example, the dialogs are related as shown below: 


Page size (inches) 
‘Page size MRT ED 
Width 


‘Number for first page 
‘Allow widows/ 
‘Page number style 


¢HP LaserJet IIl+ 
12 


kon’ xXott ¢0n* 
‘Rts/Cts Off 
‘Dsr/Otr 

‘Ded 


Gossen} +2 pages> 
‘Margins _ Off 


All the dialogs are available from the Print setup dialog, which would normally be accessed via a Print 
setup option in one of the menus (generally the Special menu) of an application that can print data. 


Note that some of these dialogs, for example, the Set serial port and Set serial handshake dialogs, are 
described in other chapters of this manual. 


On the Workabout, the dialogs are again all accessible from the Print Setup dialog, but the organisation is 
somewhat different, as illustrated below: 


Pave setup 


T25y 1.25) 1.25) 1.25 


Preview settings 
Wee ¢Z pages > 
‘Margins Off 


[Set serial handshake | 


/Xon/Xott ¢One 
*htst ry 


Heprore ‘Sclect printer Rieter wry 
+Footer... -~ ‘Dofauit font. Pica 12 } 
\*Paging control. 1+ Nor 1529 Es 


f Set Serlotport 
36887 
8 


Boud tate 


(Page size (inches) 


Italic No 
sPrint position Normal __ 


16-2 


16 PRINT CLASSES 
—_——— SSO CLASSES 


The main differences in appearance are in the Print setup and Page setup dialogs. The Print setup dialog is 
implemented on the Workadbout by an additional scprncti class. The Page setup dialog contains most of 
the items that appear in the Series 3a Print control dialog. In fact, it is implemented by another new class - 
ScPGSETUP. This subclasses the prNcTRL class, replacing only the a1_dyn_init method to change the title 
text and then supersend the pL_pyn_1nrT message. These two additional classes are not further documented 


in this chapter. 


Precursors 
Familiarity with the following topics will aid the understanding of this chapter: 


e the PRINTER class which supplies methods for both editing the current printer settings and starting 
a printing, pagination or print preview operation. 


e the paces active object class which is responsible for the printing. 
e the Locs class described in the OLIB Reference manual. 


The PRINTER and pacss classes are described in the Document Printing Classes of the FORM Reference 
manual. 


Class diagram 


c / 
Sieh M 
| a 
/ bwin ; 
f / pom as ee, 
SAL 1 ws . Sh. pipe eee 
“i : / Pinter >’ wser > 
V Pd VES Ln { ¢ fd 
aad oat 4 ~S, ‘ 
‘digchain ~> the / 
‘4 ( 
i. \ 
f- pdevdlg - aed i printing ; / Iptinter - 
ae \ en 9 POR Doras ; oe ( 
‘ oe. Sides oe di b x > : i seh OE ; be ene } 
se i iad 
sa © 
//headfoot 3 margins ,/pagectrl “> ~~>pmnmodel 


ee 
16-3 


HWIM REFERENCE 


5 a A a i Oy ie 
LPRINTER 


LPRINTER 


defer 
wtab 
Lheight 
width 
subsqind 


destroy 
lpr_init 
lpr_read 
ipr_sense_buf_width 


ipr_sense_text 


The LPRinTER class provides the basic framework that allows an application to print one or more copies of 
a document using the services provided by the printer and paczs classes. 


The document is represented as a sequence of one or more print elements. The print elements are supplied 
by the 1pr_read method of the Lprinrer object and printed by the pacgs object. 


The 1pr_read method sets the print element in three steps as follows: 


e sets defaults for the line height, the line indentation, the line spacing and the font and ensures that 
the print element appears on a new line. 


¢ sends self an LPR_SENSE_TEXT message: the LPR_SENSE_TEXT message may set the text and any 
other characteristics of the print element. 


* if the print element is too long for one line, it wraps the text onto the next line(s) thus creating two 
or more shorter print elements. 


The 1pr_sense_text method is deferred and - unless the 1pr_read method is replaced - must be supplied 
by the subclasser. 


Print elements 


Each print element is represented by a woR_PRINT struct defined as follows: 


typedef struct 
{ 
WORD flags; 
WORD typf; 
WORD fheight; 
WORD style; 
WORD down; 
WORD indent; 
WORD height; 
WORD right; 
TEXT *buf; 
UWORD blen; 
} WDR_PRINT; 


The significance of the members of the wor_PRINT struct is as follows: 

flags an ored combination of the following flags: 
WDR_PRINT_START _ this flag indicates that the printer is to be initialised to allow printing. 
WDR_PRINT_PAGE _ this flag indicates that the print element is on a new page. 


WDR_PRINT_LINE this flag indicates that the print element is on a new line. 


16-4 


16 PRINT CLASSES 
——$—$—$ ee CLASSES 


WDR_PRINT_FonT this flag indicates that the current printer font is to be set to the font 
specified by the typ£, height and style members. The current font is 
set before any text is printed. 


WDR_PRINT_RIGHT _ this flag indicates that the current print position is to be moved right by 
the number of printer units specified by the right member. The current 
print position is moved before any text is printed. 


WDR_PRINT_TExT this flag specifies that the text specified by the buf and 1en members is 


to be printed. 
WDR_PRINT_END this flag specifies that the print element is the last. 
typf£ this is the typeface index and uniquely identifies the typeface. This member is ignored unless 


the flags member contains WOR_PRINT_FONT. 


fheight this is the height of the font in units of twips. This member is ignored unless the flags 
member contains wOR_PRINT_FONT. 


style this specifies the font style and may contain an ored combination of the following flags: 
WDR_PRINT_NORMAL plain text. 


WDR_PRINT_UNDERLINE the text is to be printed as underlined text. 


WDR_PRINT_BOLD the text is to be printed as bold text. 
WDR_PRINT_ITALIC the text is to be printed as italic text. 
WDR_STYLE_SUPER the text is to be printed as superscripted text. 
WDR_PRINT_SUB the text is to be printed as subscripted text. 


This member is ignored unless the flags member contains woR_PRINT_FONT. 


down this is the downwards displacement of the print head in printer units. It is automatically set to 
zero by the pacss object if the print element is at the top of the page. This member is ignored 
unless the £1ags member contains woR_PRINT_LINE. 


indent this is the right indent of the print head in printer units. This member is ignored unless the 
flags member contains woR_PRINT_LINE. 


height this is the line height in printer units. When moving to a new line the print head is moved 
down by the sum of the height and down members. This member is ignored unless the flags 
member contains wOR_PRINT_LINE. 


right this is the right displacement of the print head in printer units. This member is ignored unless 
the flags member contains WOR_PRINT_RIGHT. 


buf this is the address of a buffer containing the text to print. This member is ignored unless the 
flags member contains woR_PRINT_TEXT. 


blen this is the length of the text to print. This member is ignored unless the £1ags member 
contains WOR_PRINT_TEXT. 


Class definition 
Defined in sub-category file /printer.cl (generated header file /printer.g). 


CLASS Ilprinter root 
{ 
REPLACE destroy 
ADD lpr_init 
ADD lpr_read 
ADD lpr_sense_buf_width 
DEFER lpr_sense_text 


16-5 


HWIM REFERENCE 
SK eee 


PROPERTY 
{ 
VOID *pages; Copy for reference only 
VOID *wdr; Copy for reference only 
SCRLAY_FONT f; The default font 
WDR_PRINT defer; In case previous data was too wide 
UBYTE *wtab; Width table 
UWORD lheight; Line height in printer units 
UWORD width; Width of region to print to 
UWORD subsqind; Indent for subsequent lines (if wrapped) 
} 
} 
Property 
lprinter.pages the handle of an instance of the paces class which is responsible for the printing. 
A description of the pacgs class may be found in the FORM Reference manual. 
lprinter.wdr the handle of an instance of the wor class. This class provides access to the 
current printer resource file. A description of the wor class may be found in the 
FORM Reference manual. 
lprinter.f a pointer to a scrLAY_Font struct which contains details of the default font. The 
SCRLAY_FONT struct is defined as follows: 
typedef struct 
{ 
UWORD fid; 
UWORD style; 
UWORD height; 
} SCRLAY_FONT; 
The significance of the members of the above struct is as follows: 
fid this is the default font ID. 
style this is the default font style. 
height this is the default font height in units of twips. 
The default font characteristics are obtained from the current PRINTER object. 
lprinter.defer a WDR_PRINT struct containing details of deferred text. Deferred text results from 
the lpr_sense_text method providing too much text for one line. The deferred 
text is printed on subsequent line(s) with a line indentation of 
iprinter.subsqind. 
lprinter.wtab a pointer to the current printer width table. 
A monospace font table contains two bytes. The first byte is always equal to 
zero. The second byte specifies the width of a character . 
A proportional font table contains one byte per character. The width of the 
character with code c is specified by the byte with offset c. 
lprinter.lheight specifies the default line height in printer units used by the 1pr_read method. 
lprinter.width specifies the width of one line in printer units used by the 1pr_read method. 
lprinter.subsgind specifies the line indentation to be used when printing deferred text. 


ni Se SS EE 
LPRINTER methods 


STROY 3 Destroy 


VOID destroy (VOID) ; 


Destroy the LPRINTER instance. 


16-6 


16 PRINT CLASSES 


If w_ws->wserv.printer is non-zero, sends a PR_CLOSE_WDR Message tO w_ws->wserv. printer. 


Supersends a pEsTRoy message. 


LPR_INIT o ee Start printing dialog 
VOID lpr_init (VOID) ; 
Initialise the LpRINTER object property and then start the printing operation. 


Ensures that an instance of the prinrer printer manager class exists by sending a WS_ENS_PRINT_CONTEXT 
message to w_ws. 


Obtains a pointer to a PRINTER_PARAMS struct - which contains the current printer parameters - by sending a 
PR_GET_PARAMS message to w_ws->wserv.printer. 


Stores the width of the printing region in property by writing the p.pg.body. width member of the 
PRINTER_PARAMS Struct to lprinter.width. 


Stores the default printer font in property by writing the a. member of the pRINTER_PARans struct to 
lprinter.f. 


Not on the Series 3: if iprinter . subsqind is non-zero, writes FALSE to lprinter. subsqind and returns. A 
non-zero value for lprinter.subsqind indicates that the LpRINTER object is being used for a print preview 
operation. 


Specifies the paces active object that is to handle the printing by writing iprinter.pages to the ppages 
member of an RBUF_PRINTING struct. 


Specifies the call-back handle for reading the next line of text - in the form of a wor_pRInT struct - by 
writing se1£ to the calls hread member of the above rBUF_PRINTING struct. 


Specifies the call-back message for reading the next line of text by writing o_LpR_reap to the calls hread 
member of the above RBUF_PRINTING struct. 


Starts the printing operation by launching a Printing dialog with the address of the above RBUF_PRINTING 
struct as the data - details of the Printing dialog and the RBUF_PRINTING struct may be found in the 
description of the PRINTING class. 


ead call-back 


VOID lpr_read(INT x,WDR_PRINT *pr) ; 

Write to the wor_PRINT struct specified by pr details of the next portion of text to print. 

This call-back method is called by the pacgs active object when it requires the next print element. 
The first step is to ensure that all property has been initialised. Thus if iprinter.wdr is zero: 


e — sets the default line height as specified by lprinter.1height to be equal to the height of the 
default font specified by iprinter.£.height. 


e converts the default line height - iprinter.1height - into vertical printer units. 
e converts the default line width - iprinter .width - into horizontal printer units. 


e — sets the handle of the wor printer resource object specified by printer .wdr to the pages. in.wdr 
member of lprinter.pages - this is assumed be the handle of a wor object used by the current 
PAGES object. 


e writes the address of the printer width table for the default font specified by printer. to 
lprinter.wtab - the method obtains the address by sending a woR_GET_WIDTH_TABLE message to 
lprinter.wdr. 


If lprinter.defer.blen is non-zero, the content of the wor_PRINT struct pointed to by pr is set from the 
deferred text specified by printer. defer: 


e writes lprinter.defer to «pr. 


e — sets the line indentation specified by pr->indent to printer. subsqind. 


16-7 


HWIM REFERENCE 
SSS eee 


Otherwise the content of the wor_PRINT struct pointed to by pr is set as follows: 


*  writtes default values for the font, line height, line indentation and line separation and indicates 
that the print element is to appear on a separate line: 


pr->flags=WDR_PRINT_FONT|WDR_PRINT_LINE|WDR_PRINT_TEXT; 
pr->typf=self-slprinter.f.fid; 
pr->fheight=self->lprinter.£.height; 
pr->style=self->lprinter.f.style} 
pr->height=self->lprinter.lheight; 

pr->down =0; 

pr->indent=0; 


e sends self an LPR_SENSE_TEXT Message with an argument of pr. 


¢ ifthe LPR_sENSE_TExT message indicated that the printing is complete - i.e. the return value is 
FALSE - Writes WOR_PRINT_END to pr->flags and then returns. 


Writes «pr to lprinter. defer. 


If the line indentation specified by pr->indent exceeds the line width specified by lprinter .width, the 
indentation is reset to zero. 


Determines the number of characters in the buffer pointed to by pr->bug that will fit on the current line 
assuming the current font and line width. The current line is broken at a word boundary if at all possible. 


The difference between the result and the value specified by pr->1en defines the length of any deferred 
text i.e. text that wraps onto one or more subsequent lines. 


Writes the length of the text that will fit on the current line to pr->bien. 

Writes the length of the deferred text to lprinter.defer.blen. 

If there is deferred text: 
® writes the address of the first deferred character to iprinter.defer. buf. 
e writes the length of the deferred text to lprinter.defer.blen. 
e not on the Series 3: sets WDR_PRINT_LINE in iprinter. defer. flags. 


¢ — obtains the address of a pRinreR_PARaMs struct containing the current printer parameters by 
sending a PR_GET_PARAMS message to w_ws->wserv.printer. 


e ifthe ¢.wo_control member of the PRINTER_PARAMs struct is zero - indicating that widows and 
orphans are not allowed - sets WoR_PRINT_KEEP in pr->flags. 


INT Ipr_sense_buf_width(TEXT *buf,INT len); 
Return the width in printer units of the first 1en characters pointed to by buf. 


The method evaluates the length of the text using the current printer width table at address lprinter.wtab. 


Sa a a ET 
Deferred LPRINTER methods 


SE TEXT : — Get text to print 


INT lpr_sense_text (WDR_PRINT *pr) ; 


Get the next portion of text to print - this method is called by the 1pr_read method 


For the simplest printing requirements the replaced method should write the address and length of the text 
to print to pr->buf and pr->1en respectively. 


16-8 


16 PRINT CLASSES 
_  — OOENINTE GLASSES 


For more sophisticated printing requirements the default line height, line indentation, line spacing and font 
may be overridden by writing appropriate values to the appropriate members of the wor_PRINT struct 
pointed to by pr. 


In all cases the replaced method should return rause if no more text remains. 


Note that it may be better to replace the 1pr_read method, and ignore the 1pr_sense_text method, ifa 
significant amount of processing would otherwise have to be carried out in the lpr_sense_text method. 


PDEVDLG 


flags next 
id 
destroy wa—draw 


wn_position 
wn_redraw 


wa—sense—heip 


wn_visible 


DLGBOX 


item count 
rbuf current 
dimrid underline 
helprid absorb 
changed 


destroy dl_item_replace 
wn_key dl_item_append 
wn_emphasise qdl_init 
wn_sense_help dl_dimmed_message 
wn_set dl_item_add 
wn_sense di—set—size 
wn_draw dl_ing_minsize 
dl_item_lock di—dyn—init 
dl_item_dim di—key 
dl_set_item_flags 

dal_set_prompt di—changed 
dl_take_focus dl_focus 
dl_handle_to_index 42—tauneh—sub 
dl_index_to_handle dl_item_new 


dil_launch_sub 
dl_dyn_init 


The ppevoie class implements the Printer configuration dialog allowing the user to select the printer 
device and edit the associated settings. 


An example Printer configuration dialog for the Series 3 is shown in the following picture: 


Printer configuration 


“Printer device ¢ Parallel + 
Serial characteristics .. 
Serial handshaking ... 
File: Name 
Disk 
*Units Inches 


and examples of the equivalent dialogs for the Series 3a and Workabout are shown below: 


Printer configuration 


‘Printer device ¢Parallel+ 


Serial characteristics ... 
Serial handshakins ... 


File: Name 
Disk 
‘Units Inches 
‘Print preview... 2 pages, Margins off 


Series 3a Printer configuration dialog 


16-9 


HWIM REFERENCE 
eee 


Printer configuration 
"Printer device Parallel» 
Serial characteristics .. 


Serial handshaking... 
File? Name 
Disk 


Workabout Printer configuration dialog 


For the Series 3a dialog, the important difference is the extra Print preview control which allows the user to 
edit the print preview settings. On the Workabout, this additional facility is provided from the Print setup 
dialog, as indicated at the beginning of this chapter. 


The edited values - with the exception of the printer units - are stored in system-wide environment 
variables as follows: 


P$D 


PSF 


PSS 


PSP 


this stores the printer port type and may be set to one of the following values: 
PRINTER_PORT_PARALLEL indicates that the current printer device is the parallel port. 
PRINTER_PORT_SERIAL indicates that the current printer device is the serial port. 
PRINTER_PORT_ FILE indicates that the current printer device is a file. 
PRINTER_PORT_FAX indicates that the current printer device is the fax. 


this stores the full file specification of a file to which printing may be directed. The name is 
stored as a zero terminated string 


this stores the serial port characteristics organised as a P_SRCHAR struct. 


Not used the Series 3. This environment variable, which is four bytes long, stores the print 
preview settings as a zero terminated string containing two characters. 


The first character specifies the print preview mode as follows: 


‘0' specifies that print preview operations are to display facing pages. 
‘T' specifies that print preview operations are to display one page. 

‘2"_ specifies that print preview operations are to display two pages. 
‘3' specifies that print preview operations are to display three pages. 


‘4' specifies that print preview operations are to display four pages. 
The second byte specifes the margins mode as follows: 
‘0 specifies that print preview operations are not to display the margins. 


‘l' specifies that print preview operations are to display the margins. 


The printer units is stored as a system wide setting - for details see the p_getcta and p_setcta PLIB 
routines in the PLIB Reference manual. 


Class definition 


Defined in sub-category file prntdlgs.cl (generated header file prntdlgs.g). 


16-10 


CLASS pdevdlg dlgbox 


{ 


REPLACE destroy 
REPLACE dl_launch_sub 
REPLACE dl_dyn_init 
REPLACE dl_key 
REPLACE dl_set_size 
REPLACE dl_changed 


16 PRINT CLASSES 


rE ES 


PROPERTY 1 


{ 


PR_ROOT *printer; 
P_SRCHAR srchar; 

WORD filechanged; 
WORD own_printer; 
PVV_DISPLAY Disp; 


} 
} 


Property 
pdevdlg.printer 


pdevdlg.srchar 


pdevdlg.filechanged 


pdevdlg.own_printer 


pdevdlg.Disp 


Resources 


The handle of an instance of the printer class. This object supports the setting 
and sensing of data required for print, pagination and print preview operations. 


A P_SRCHAR struct containing the current serial port characteristics. These are 
either copied from the psr environment variable, or, if this does not exist, set to 
default values. 


Set to Trus if the user has edited either the characteristics associated with one or 
more devices or the printer units - selecting a new printer device does not set 
this property to TRUE. The default value is FALSE. 


Set to True if the ppzvpic object creates its own PRINTER object on 
initialisation. Set to Fause if the ppevp.e object uses the PRINTER object with 
handle W_ws->wserv.printer. 


This property is not available on the Series 3. 


Contains the current print preview settings stored as a pvv_DIspay struct - see 
the description of the prwerev class for details. 


This property is not available on the Series 3. 


Defined in the system resource file s_.rss. 


RESOURCE CONTROL sys_print_preview_settings 


{ 


Class=C_TEXTWIN; 
prompt="Print preview"<WS_SYMBOL_ELLIPSIS>; 


info=TXTMESS 


{ 


str="Facing pages,Margins off"; /* widest possible text */ 
flags=IN_TEXTWIN_POPOUT; 


}; 
} 


RESOURCE DIALOG sys_printer_ config dialog 


{ 


title="Printer configuration"; 
flags=DLGBOX_NOTIFY_ENTER; 


controls= 


{ 


CONTROL 


{ 


class=C_CHLIST; 

prompt="Printer device"; 
flags=DLGBOX_ITEM_NOTIFY_CHANGED; 
info=CHLIST 


}, 


{ 


rid=sys_printer_device_chlist; 


i 


16-11 


HWIM REFERENCE 
eee SSSeSSSSSeSeeSeeeeeSSSSSSSSFSSSSSSSSSSSSSFSsee 


CONTROL 
{ 
class=C_TEXTWIN; 
prompt="Serial characteristics "<WS_SYMBOL_ELLIPSIS>; 
info=TXTMESS 


{ 


str="19200 "<WS SYMBOL _ELLIPSIS>; /* changed for S3a */ 
flags=IN_TEXTWIN_POPOUT; 
}; 
}, 
CONTROL 


{ 


class=C_TEXTWIN; 
prompt="Serial handshaking "<WS_SYMBOL ELLIPSIS>; 
info=TXTMESS 
{ 
str="Xon/Xoff Off "<WS_SYMBOL_ELLIPSIS>; 
flags=IN_TEXTWIN_POPOUT; 
}; 
}, 


CONTROL 


{ 


£lags=DLGBOX_ITEM_NEEDS_PACK|DLGBOX_ITEM_NOTIFY_CHANGED; 
class=C_FNEDIT; 

prompt="File:"; 

info=FNEDIT { flags=IN_FNEDIT_NO_AUTOQUERY; }; 


}, 


CONTROL 


{ 
class=C_CHLIST; 
prompt="Units"; 
info=CHLIST 


{ 
rid=sys_printer_units chlist; 


: 


}; 
} 


Note: on the Series 3, the text "19200" in the Serial characteristics contro] is replaced by "9600". 


See ee ee en a en ee a a eT 
PDEVDLG methods 


Destroy 
VOID destroy (VOID) ; 

Destroy the ppEvpic object. 

If pdevdlg.own_printer is non-zero, sends a destroy messsage to pdevdlg. printer. 

Supersends a DESTRoy message. 


This method is not replaced on the Series 3. 


Launch sub-dialog 
VOID dl_launch_sub(INT index) ; 
Launch either a Set serial port dialog or a Set serial handshake dialog according to the value of index. 


If index is two, launches a Set serial port dialog - details of this dialog may be found in the General 
dialogs chapter of the HWIM Reference manual - in order to edit some of the serial port characteristics 
stored in pdevdlg.srchar. 


16-12 


16 PRINT CLASSES 
———————$S—.:s $e ENNE CLASSES 


Otherwise, launches a Set serial handshake dialog - details of this dialog may be found in the General 
dialogs chapter of the HWIM Reference manual - in order to edit the serial port handshake settings stored in 
pdevdlg.srchar.hand. 


Stores the new serial port settings in the ps environment variable by sending a PR_STORE_CHAR message to 
pdevdlg.printer specifying the address of pdevdig.srchar as argument. 


Sets the Serial characteristics control to display appropriate text: the text is either the nut string, or the 
appropriate item in the sys_BAUD_RATE_CHLIST system resource followed by an ellipsis symbol. 


Sets the Serial handshake control to display appropriate text: the text is either the nu string, or the 
concatenation of the sys_xoNxXOFF_STRING, an appropriate item from the sys_oFFoN_MENU system resource 
and an ellipsis symbol. 


The following actions are not performed on the Series 3. 


If index is seven, allows the user to edit the print preview settings stored in pdevalg. Disp by launching a 
Preview settings dialog. 


Stores the edited print preview settings as a zero terminated string containing two characters in the psp 
environment variable. See the introduction for details of the psp environment variable. 


Sets appropriate text in the Print preview control. 


VOID dl_dyn_init (VOID) ; 
Dynamically initialise the content of the dialog. 
The following actions are not performed on the Series 3: 
e enables appropriate context sensitive help by writing -sys_HELP_PRINT to dlgbox.helprid. 


e if w_ws->wserv. printer is non-zero - and is thus assumed to store the handle of the current 
printer object - writes w_ws->wserv.printer tO pdevdlg. printer. 


e otherwise writes TRUE to pdevdlg.own_printer, creates an instance of the pRInTER class, writes 
its handle to pdevdig.printer and then initialises the prinreR object by sending a PR_INIT 
message to pdevdlg.printer. 


The following actions are only performed on the Series 3: 


® creates an instance of the printer class, writes its handle to pdevdig.printer and then initialises 
the PRINTER object by sending a pR_INIT message to pdevdlg. printer. 


Obtains the current serial port characteristics - in the form of a p_sRcuar struct - and the name of the 
current file to which printing is directed by sending a pR_poRT_DATA message to pdevdlg. printer. 


Writes the current serial port characteristics to pdevdlg.srchar. 
Sets the File name control to display the name of the file to which printing is directed. 


Obtains the current system wide units - i.e. either = METRIC or E_IMPERIAL - and sets this as the index of 
the item selected in the Units control - for further details see the description of the E_conrze struct in the 
PLIB Reference manual. 


If the item with index one is selected in the Printer device control - i.e. the Serial item - undims the Serial 
characteristics and Serial handshaking controls and then dims the File name control. 


If the item with index two is selected in the Printer device control - i.e. the File item - dims the Serial 
characteristics and Serial handshaking controls and then undims the File name control. 


Otherwise, dims the Serial characteristics, Serial handshaking and File name controls. 
The following actions areonly performed on the Series 3. 
If w_ws->wserv. flags Contains PR_WSERV_FULLSCREEN: 


e — adds to the dialog an underline separating the Disk and Units controls, and then appends to the 
dialog the Print preview control defined by the sys_PRINT_PREVIEW_SETTINGS system resource. 


ee SSSeFeSSSSSSSSSSSSSSSSSSSSSSSSSSSSSeeSsSSSSSeSeeeeeeeeeeee 
16-13 


HWIM REFERENCE 


e retrieves the print preview settings stored in the psp environment variable and writes appropriate 
values to dpevdlg.Disp. 


DE XEY ss Handle key input 
INT dl_key(INT index, INT keycode) ; 
Store the current selections as system wide settings. 


Senses the index of the item selected in the Printer device control and sets the result into the psp 
environment variable by sending a pR_SET_PORT_TYPE message to pdevdlg. printer. 


If pdevdlg.£ilechanged is TRUE, senses the file name displayed in the File name control and sets the result 
into the p$r environment variable by sending a pR_STORE_FILE message to pdevdlg.printer. 


Senses the index of the item selected in the Units control and sets this as the system wide units - for further 
details see the description of the &_conrte struct in the PLIB Reference manual. 


Not on the Series 3: if the system units are currently set to metric, sets PR_WSERV_METRIC in w_ws- 
>wserv. flags, otherwise clears PR_WSERV_METRIC in w_ws->wserv. flags. 


Returns wN_KEY_CHANGED. 


VOID dl_set_size (VOID); 


Set the size of the dialog and the text in the Serial characteristics and Serial handshaking controls. 
Supersends a DL_SET_SIZE message. 


Sets appropriate text in the Serial characteristics control - the text is created by concatenating an 
appropriate item from the sys_BAUD_RATE_CHLIST system resource and an ellipsis symbol. 


Sets appropriate text in the Serial handshaking control - the text is created by concatenating the 
SYS_XONXOFF_STRING system string resource, an appropriate item from the sys_oFFon_MENU system 
resource and an ellipsis character. 


Not on the Series 3: sets appropriate text in the Print preview control. 


ed messages 


VOID dl_changed(INT index) ; 


Set the dim status of the Serial characteristics, Serial handshaking and File name controls according to the 
item selected in the Printer device control. 


If index is one - i.e. the content of the Printer device control has changed - senses the index of the item 
selected in the Printer device control and 


e if the index is one, i.e. the Serial item, undims the Serial characteristics and Serial handshaking 
controls and then dims the File name control. 


© if the index is two, i.e. the File item, dims the Serial characteristics and Serial handshaking 
control and undims the File name control. 


e otherwise, dims the Serial characteristics, Serial handshaking and File name controls. 


Otherwise, indicates that an item in the dialog has changed by writing TRUE to pdevdlg.filechanged. 


16-14 


16 PRINT CLASSES 


PRNPREV 


DLGBOX 


item item 
rbuf rbuf 
dimrid dimrid 
helprid helprid 
flags flags 
focus focus 
count count 
current current 
underline underline 
absorb absorb 
changed changed 


destroy dl_item_replace 
wn_key dl_item_append 
wn_emphasise dl_init 
wn_sense_help di_dimmed_message 
wn_set dl_item_add 
wn_sense dl_set_size 
wn_draw dl_ing minsize 
di_item_lock di—dyn—tnie 
dl_item_dim di—tey 
dl_set_item_flags 

dl_set_prompt dl_changed 
dl_take_focus dl_focus 
dl_handle_to_index dl_launch_sub 
dl_index_to_handle dl_item_new 


wn_position 
wn_redraw 


wnosense—hetp 


wn_visible 


The prnprev class implements the Preview settings dialog allowing the user to edit the current settings for 
print preview operations. An example Preview settings dialog is shown in the following picture: 


Preview settings 


¢2 pages > 
‘Margins Off 


The prnprev class is not available on Series 3 machines. 
Class definition 
Defined in sub-category file prntdigs.cl (generated header file prntdlgs.g). 


CLASS prnprev dlgbox 


{ 
REPLACE dl_dyn_init 
REPLACE dl_key 


} 


Property 
There is no property associated with the prnprEv class. 


Resources 


Defined in the system resource file s_.rss. 


16 - 15 


HWIM REFERENCE 
eee 


RESOURCE MENU sys_offon_menu 

{ 

items = 
{ 
CHOICE_ITEM { str="0f£";}, 
CHOICE_ITEM { str= "On";} 
}i 

} 


Defined in the system resource file sx_.ra. 


RESOURCE MENU sys_preview_options_chlist 

{ 

items= 
{ 
CHOICE_ITEM {str="Facing pages";}, 
CHOICE_ITEM {str="1 page";}, 
CHOICE_ITEM {str="2 pages";}, 
CHOICE_ITEM {str="3 pages";}, 
CHOICE_ITEM {str="4 pages"; } 
‘7 

} 


RESOURCE DIALOG sys_preview_settings_dl 


{ 


title="Preview settings"; 
£lags=DLGBOX_NOTIFY_ENTER|DLGBOX_RBUF_ FILLED; 
controls= 


{ 


CONTROL 


{ 


class=C_CHLIST; 
prompt="Display"; 
info=CHLIST{rid=sys_preview_options_chlist;}; 
}, 

CONTROL 


{ 


class=C_CHLIST; 
prompt="Margins"; 
info=CHLIST(rid=sys_offon_menu;}; 


} 


EER a ae ee a ee ee ee ee] 
PRNPREV methods 


VOID dl_dyn_init (VOID) ; 
Dynamically initialise the content of the dialog from the pvv_prspzay struct pointed to by dlgbox. rbuf. 
The pvv_pisptay struct is defined as follows: 


typedef struct 


{ 


UBYTE Mode; 
UBYTE Flags; 
} PVV_DISPLAy; 


The significance of the members of the struct is as follows: 


Mode _ this may take a value from zero to four inclusive to specify that either facing pages, one page, 
two pages, three pages or four pages are to be displayed in print preview operations. 


Flags this may be rruz to specify that the margins are to be shown in print preview operations. It 
should be rause otherwise. 


Set the index of the item selected in the Display control to digbox. rbuf - >Mode. 


16-16 


16 PRINT CLASSES 


Set the index of the item selected in the Margins control to digbox. rbuf->Flags. 


Handle key input 
INT dl_key (INT index, INT keycode) ; 

Store the edited content of the dialog in the pvv_pispuay struct pointed to by dlgbox.rbuf. 

Sense the index of the item selected in the Display control and write the result to aigbox. rbuf->Mode. 


Sense the index of the item selected in the Margins control and write the result to digbox . rbuf- >Flags. 


PRNCTRL 


E pene next item count 
rbuf current 
dimrid underline 
helprid absorb 

changed 


dl_item_replace 
wn_key dl_item_append 
iwn_emphasise q@l_init 
wn_sense_help d1_dimmed_message 
wn_set dl_item_add 
wn_sense dl_set_size 
wn_draw di—ing-minsize 
dl_item_lock di—dyn—inst 
dl_item_dim ai—key 
di_set_item_flags 

dl_set_prompt dl_changed 
dl_take_focus dl_focus 
dl_handle_to_index di—tauneh—sub 
d1l_index_to_handle d1_item_new 


The prnctru class implements the Print setup dialog allowing the user to edit the current page layout 
settings. An example Print setup dialog is shown in the following picture: 


Be S156 
‘Margins. 1,25, 1.25, 1.25, 1.25 
“F 


*Header.., 

»Footer.. “P 

"Paging control. 13 Nos 15253 
«Printer model. Canon BJ-1@e 


The user may press the Tab key after having selected: 


e the Page size control to obtain a Page size dialog - see the description of the pacrszze class in the 
current chapter for further details. 


e the Margins control to obtain a Margins dialog - see the description of the marcrns class in the 
current chapter for further details. 


e the Header control to obtain a Header details dialog - see the description of the HEapFoot class in 
the current chapter for further details. 


e the Footer control to obtain a Footer details dialog - see the description of the HEADFoot class in 
the current chapter for further details. 


16-17 


HWIM REFERENCE 


a 


e the Paging control to obtain a Paging control dialog - see the description of the pacectru class in 
the current chapter for further details. 


¢ the Printer model contro] to obtain a Set printer dialog - see the description of the PRNMODEL Class 
in the current chapter for further details. 


The members of the PRINTER_PARAMs struct relevant to the prncrru class are as follows: 


p.pdrflags 


Pp.pg.width 
P.pg. height 


Pp.pg.body.tl.x 


p.pg.body.tl.y 


p.pg. body. width 


P-pg. body. height 


P.pgnum.style 


p.pgnum.offset 


d.size_choice 


d.wo_control 


may contain WDR_PDR_LANDSCAPE to specify landscape page orientation. By default 
the page orientation is portrait. 


specifes the total page width in units of twips. 
specifies the total page height in units of twips. 


specifies the horizontal offset of the printing region from the left edge of the page 
in units of twips. 


specifies the vertical offset of the printing region from the top edge of the page in 
units of twips. 


specifies the width of the printing region - i.e. the page width minus the width of 
the left and right margins - in units of twips. 


specifies the height of the printing region - i.e. the page height minus the height of 
the top and bottom margins - in units of twips. 


specifies the index of an item in the sys_pGno_CHOICE system resource and the 
style used for page numbers. 


specifies the page number offset i.e. the value by which all page numbers are to be 
offset. 


specifies the the index of an item in the sys_paGE_s1zE system resource containing 
the name of the current page size e.g. A4. 


specifies whether widows and orphans are allowed and may be either TRUE or 
FALSE. 


Some of the above members are illustrated more clearly in the following picture: 


p.pg.height 


p.pg.width 


p.pg.body. height 


p.pg.body.width 


The outer square represents the page whilst the inner one represents the printing region i.e. the page minus 


the margins. 


The page layout settings are stored in the curent pRinTER object the handle of which must be stored in 
W_ws->wserv.printer. 


nr rr 


16-18 


16 PRINT CLASSES 
$e PO PRINT CLASSES | 


Class definition 
Defined in sub-category file prntdlgs.cl (generated header file prntdlgs.g). 


CLASS prnctrl dlgbox 


{ 

REPLACE dl_dyn_init 
REPLACE dl_launch_sub 
REPLACE dl_ing minsize 
REPLACE dl_key 


TYPES 


{ 


typedef struct 


{ 


UWORD tmarg; 
UWORD lmarg; 
UWORD rmarg; 
UWORD bmarg; 
} TMARG; 


} 


PROPERTY 


{ 


TMARG tm; 
} 
} 


Property 
prnctrl.tm a TMARG Struct used to temporarily store the page margins. The tmare struct is defined as 
follows: 


typedef struct 


{ 


unsigned short int tmarg; 
unsigned short int Ilmarg; 
unsigned short int rmarg; 
unsigned short int bmarg; 
} TMARG; 


tmarg specifies the height in twips of the top margin. 

lmarg specifies the width in twips of the left margin. 

rmarg member specifies the width in twips of the right margin. 
bmarg specifies the height in twips of the bottom margin. 


Resources 


Defined in the system resource file sx_.ra. 


RESOURCE CONTROL sys_print_control_device 
{ 
class=C_TEXTWIN; 
prompt="Printer device"<WS_SYMBOL_ELLIPSIS>; 
info=TXTMESS 
{ 
str= Witt 7 
flags=IN_TEXTWIN_POPOUT; 
}i 
} 


Defined in the system resource file s_.rss. 


16-19 


HWIM REFERENCE 
a 


RESOURCE DIALOG sys_print_control_dl 
{ 


title="Print setup"; 
£lags=DLGBOX_NOTIFY_ENTER |DLGBOX_NOTIFY_ESCAPE; 
controls= 


{ 
CONTROL 


{ 


class=C_TEXTWIN; 
prompt="Page size "; 
info=TXTMESS 


{ 


str=""; 
flags=IN_TEXTWIN_POPOUT; 
}; 
}, 
CONTROL 
{ 


class=C_TEXTWIN; 
prompt="Margins "; 
info=TXTMESS 


{ 


str= imi ; 
flags=IN_TEXTWIN_POPOUT; 
}; 
}, 
CONTROL 


{ 


class=C_TEXTWIN; 
prompt="Header "; 
info=TXTMESS 


{ 


str= mt ; 
flags=IN_TEXTWIN_POPOUT; 


}; 
}, 


CONTROL 


{ 


class=C_TEXTWIN; 
prompt="Footer "; 
info=TXTMESS 


{ 


str=" "Ww i: 
flags=IN_TEXTWIN_POPOUT; 


}; 
}, 
CONTROL 


{ 


class=C_TEXTWIN; 
prompt="Paging control "; 
info=TXTMESS 


{ 


str= uit : 
flags=IN_TEXTWIN_POPOUT; 


}; 
}, 
CONTROL 


{ 


class=C_TEXTWIN; 
prompt="Printer model "; 
info=TXTMESS 


{ 


str= nu 7 
flags=IN_TEXTWIN_POPOUT; 


}; 


16 - 20 


16 PRINT CLASSES 


aa Oe ae) 
PRNCTRL methods 


DE_DYN_INIT | _ . Dynamic initialisation 
VOID di_dyn_init (VOID); 
Dynamically initialise the content of the dialog. 


Obtains a pointer to a PRINTER_PARAMS struct containing the current printer parameters by sending a 
PR_GET_PARAMS Message tO w_ws- >wserv.printer. 


Writes the page margins to prnctrl. tm. 


Sets the text in the Page size control according to the value stored in the d.size_choice member of the 
PRINTER_PARAMS struct. 


Sets the text in the Margins control according to the content of prnctr1.tm. 


Sets the header text in the Header control: the header text is obtained by sending a pR_GET_HD message to 
W_wS->wserv.printer. 


Sets the footer text in the Footer control: the footer text is obtained by sending a pR_GET_HD message to 
W_wsS- >wserv.printer. 


Sets the text in the Paging control control according to the values stored in the p. pgnum. offset, 
d.wo_control and p.pgnum. style members of the PRINTER_PARAMS struct. 


Opens the current wor file by sending pr_s=NSE_MODEL and PR_OPEN_WDR messages to the PRINTER object 
and then senses the name of the printer model by sending a woR_SENSE_MODEL_NAME message to the wor 
object. 


Sets the name of the printer model as the text in the Printer model control and then closes the current wor 
file by sending a pR_cLOSE_wpR message to the PRINTER object. 


The following actions are not performed on the Series 3. 
If w_ws->wserv. flags contains PR_WSERV_FULLSCREEN: 
e adds a horizontal line between the Paging control and Printer model controls. 
e appends a Printer device control as defined by the sys_PRINT_CONTROL_DEVICE system resource. 


e if the Printer device displays neither Parallel, nor Serial, nor File, locks the Printer device control 
using the hDlgItemLock utility routine. 


Enables content sensitive help by writing -sys_HELP_PRINT to dlgbox.helprid. 


lalog 
VOID di_launch_sub (INT index) ; 


Launch an appropriate sub-dialog. 


If index is one, launches a Page size dialog - for details see the description of the pacEs1z= class in the 
current chapter. 


If index is two, launches a Margins dialog - for details see the description of the marczns class in the 
current chapter. The dialog edits the content of prnctr1.tm. 


If index is three, launches a Header dialog - for details see the description of the HEADFoot class in the 
current chapter. 


If index is four, launches a Footer dialog - for details see the description of the yzaproor class in the 
current chapter. 


If index is five, launches a Paging control dialog - for details see the description of the pAGECTRL class in 
the current chapter. 


16-21 


HWIM REFERENCE 
———eSeeSSSSSSSSSFSSSeSeSSsSSSSeeeeeeSSSFSSESSSSSS 


If index is six, launches a Printer model dialog - for details see the description of the prNmopeEt class in the 
current chapter. 


Sets the text in the Page size control according to the value stored in the d. size_choice member of the 
PRINTER_PARAMS struct. 


Sets the text in the Margins control according to the content of prnctr1.tm. 


Sets the text in the Header control: the header text is obtained by sending a PR_GET_HD message to w_ws- 
>wserv.printer. 


Sets the text in the Footer control: the footer text is obtained by sending a pR_GET_HD message to w_ws- 
>wserv.printer. 


Sets the text in the Paging control control according to the values stored in the p.pgnum. offset, 
d.wo_control and p.pgnum.style members of the PRINTER_PARaMs struct. 


Opens the current wor file by sending PR_sENSE_MODEL and PR_OPEN_WDR messages to the PRINTER object 
and then senses the name of the printer model by sending a woR_SENSE_MODEL_NAME message to the WOR 
object. 


Sets the name of the printer model as the text in the Printer model control and then closes the current wor 
file by sending a pR_CLOSE_wDR message to the PRINTER object. 


VOID dl_inq_minsize(INT *pOverallWidth, INT *pPromptWidth, INT *pControlWidth) ; 
Write the width of the control to the int pointed to by pcontrolwidth. 

If w_ws->wserv. flags contains PR_WSERV_FULLSCREEN, writes 160 to address pcontrolwidth. 
Otherwise writes 120 to address pcontrolwidth. 


The poverallwidth and ppromptWidth arguments are not used. 


_ Handle key input 


INT dl_key(INT index, INT keycode) ; 


Store the edited content of the dialog in the pRInTER object. 


Obtains a pointer to a PRINTER_PARAMS Struct containing the current printer parameters by sending a 
PR_GET_PARAMS Message tO w_ws->wserv.printer. 


Writes the offset of the printing region to the p.pg.body.ti member of the PRINTER_PARAMS struct. 
Writes the width of the printing region to the p.pg. body. width member of the PRINTER_PARAMS Struct. 
Writes the height of the printing region to the p.pg.body. height member of the PRINTER_PARAMS struct. 
Not on the Series 3: if the margins are too wide/high for the page: 


© — sets the width of the printing region equal to the width of the page: writes the p .pg. width member 
of the PRINTER_PARaMs Struct to the p.pg. body. width member. 


e _ sets the height of the printing region equal to the height of the page: writes the p.pg. height 
member of the PRINTER_PARAMS struct to the p.pg.body .height member. 


¢ asks the user to confirm the resetting of the margins to zero by calling hconfirm with an argument 
of -SY¥S_INVALID_MARGINS. 


e if the user confirms the resetting of the margins: 
writes zero to each member of prnctri.tm. 
writes the page height to the p.pg.body.height member of the PRINTER_PARAMS Struct. 


writes the page width to the p.pg.body.width member of the PRINTER_PARAMS struct. 


16 - 22 


16 PRINT CLASSES 


sets appropriate text in the Margins control. 
e returns WN_KEY_NO_CHANGE. 
If either the width or the height of the printing region is less than 720 twips: 


e asks the user to confirm the resetting of the margins to zero by calling hconfirm with an argument 
of -syS_INVALID_MARGINS. 


writes zero to each member of prnctri.tm. 
writes the page height to the p.pg. body. height member of the PRINTER_PARAMS struct. 
writes the page width to the p.pg.body.width member of the PRINTER_PARAMS struct. 
sets appropriate text in the Margins control. 
e = returms WN_KEY_NO_CHANGE. 
Returns wN_KEY_CHANGED. 


Otherwise returns wN_KEY_CHANGED. 


PAGECTRL 


flags next item count 
id rbuf current 
dimrid underline 
helprid absorb 
changed 
Eesesey WEdaw 


destroy dl_item_replace 
wn_key dl_item_append 
wn_emphasise dl_init 
wn_sense_help dl_dimmed_message 
wn_set dl_item_add 
wn_sense dl_set_size 
wn_draw di_ing_minsize 
dl_item_lock di—dyn—init 
dl_item_dim di—-key 
dl_set_item_flags 

dal_set_prompt di_changed 
dl_take_focus dl_focus 
dl_handle_to_index di_launch_sub 
dl_index_to_handle di_item_new 


wn_calc_position |wnh-emphasise 


wn_position 
wn_redraw 


wn-sense—heip 


wn_visible 


The pacectrt class implements the Paging control dialog allowing the user to edit the current page control 
settings. An example Paging control dialog is shown in the following picture: 


Paging control 
‘Number for firstpage 1 


‘Allow widows/orphans No 


‘Page number style €1,2,3% 


The Series 3 and Series 3a Paging control dialogs are identical apart from the different border style. 


The members of the prinTER_PaRans struct relevant to the pRNcrRx class are as follows: 


16 - 23 


HWIM REFERENCE 
ee Sse 


p.pgnum.style specifies the style used for the page numbering. It also provides an index into the 
SYS_PGNO_CHOICE system resource. 


p.pgnum.offset specifies the page number offset i.e. the value by which all page numbers are to be 
offset. 

d.wo_control specifies whether widows and orphans are allowed and may be either rrvE or 
FALSE. 


The page control settings are stored in the current printer object the handle of which must be stored in 
W_wsS->wserv.printer. 


Class definition 
Defined in sub-category file prntdigs.cl (generated header file prntdlgs.g). 


CLASS pagectrl dalgbox 


{ 
REPLACE dl_dyn_init 
REPLACE dl_key 


} 


Property 
There is no property associated with the pacEcTrt class. 


Resources 


Defined in the system resource file s_.rss. 


RESOURCE DIALOG sys_paging_ control_dl 
{ 
title="Paging control"; 
£lags=DLGBOX_NOTIFY_ENTER|DLGBOX_RBUF_FILLED; 
controls= 
{ 
CONTROL 
{ 
class=C_NCEDIT; 
prompt="Number for first page"; 
info=NCEDIT 
{ 
low=1; 
high=9999; 
}i 
} ' 
CONTRO: 


{ 

class=C_CHLIST; 

prompt="Allow widows/orphans"; 
info=CHLIST(rid=sys_no_yes;}; 


CONTROL 


{ 

class=C_CHLIST; 

prompt="Page number style"; 
info=CHLIST({rid=sys_pgno_choice;}; 


[aS SS eS a ee ee a ee Se 
PAGECTRL methods 


DL OYN INIT _ Dynamic initialisation 
VOID dl_dyn_init(vozp) ; 


Dynamically initialise the dialog using current values stored in the PRINTER object. 


16 - 24 


16 PRINT CLASSES 


Obtains the address of a PRINTER_PARAMS Struct containing the current printer parameters by sending a 
PR_GET_PARAMS message tO w_ws->wserv.printer 


Sets the content of the Number for first page control to the p.pgnum.offset member of the 
PRINTER_PARAMS Struct plus one. 


Sets the index of the item selected in the Allow widows/orphans control to the d.wo_contro1 member of 
the PRINTER_PARAMS struct. 


Sets the index of the item selected in the Page number style control to the p.pgnum. style member of the 
PRINTER_PARAMS struct. 


Returns wN_KEY_CHANGED. 


ey input 
INT dl_key (INT index, INT keycode) ; 
Store the edited content of the dialog in the printer object. 


Obtains the address of a pRINTER_PARAMs struct containing the current printer parameters by sending a 
PR_GET_PARAMS Iessage to w_ws- >wserv.printer. 


Senses the value in the Number for first page contro] and writes the result less one to the p. pgnum.offset 
member of the PRINTER_PARAMS struct. 


Senses the index of the item selected in the Allow widows/orphans control and writes the index to the 
d.wo_control member of the pRINTER_PARAMs struct. 


Senses the index of the item selected in the Page number style control and writes the index to the 
p.pgnum.style member of the PRINTER_PARAMs struct. 


MARGINS 


flags next item count 
id rbuf current 
dimrid underline 
helprid absorb 
changed 
destrey whedray 


destroy dl_item_replace 
wn_key dl_item_append 
wn_emphasise dil_init 
wn_sense_help dl_dimmed_message 
wn_set di_item_add 
wn_sense di_set_size 
wn_draw dl_ing minsize 
dl_item_lock 4i—dyn—tnit 
dl_item_dim di-key 
dl_set_item_flags 

dl_set_prompt dl_changed 
dl_take_focus dl_focus 
dl_handle_to_index di_launch_sub 
dl_index_to_handle dl_item_new 


wn_position 
wn_redraw 


wh—-sense—heip 


wn_visible 


The marcins clas implements the Margins dialog allowing the user to edit the current page margins. An 
example Margins dialog is shown in the following picture: 


16-25 


HWIM REFERENCE 


Margins (inches) 


1.25 


‘Left 1.25 
‘Right 1.25 
‘Bottom 1.25 


The margins in shown in the current printer units. 


The page margins are effectively stored in the current pRinTER object the handle of which must be stored in 


W_WS->wserv.printer. 


Class definition 
Defined in sub-category file prntdigs.cl (generated header file prntdlgs.g). 


CLASS margins digbox 


{ 


REPLACE di_dyn_init 
REPLACE dl_key 


} 


Property 
There is no property associated with the marcins class. 


Resources 
Defined in the system resource file s_.rss. 


RESOURCE DIALOG sys_margins_dl 
{ 
title="Margins"; 
£1ags=DLGBOX_NOTIFY_ENTER|DLGBOX_RBUF_FILLED|DLGBOX_APPEND_UNITS TITLE; 
controls= 
{ 
CONTROL 


{ 


class=C_FLTEDIT; 
prompt="Top"; 
info=FLTEDIT 
{ 
low=0; 
high=9.99; 
ndec=2; 
}; 
}, 


CONTROL 


{ 


class=C_FLTEDIT; 
prompt="Left"; 
info=FLTEDIT 
{ 
low=0; 
high=9.99; 
ndec=2; 
}; 
te 


CONTROL 


{ 


class=C_FLTEDIT; 
prompt="Right"; 
info=FLTEDIT 


{ 

low=0; 
high=9.99; 
ndec=2; 


hs 


16 - 26 


16 PRINT CLASSES 
——_—$——— SSS NE EO 


CONTROL 
{ 


class=C_FLTEDIT; 
prompt="Bottom" ; 
info=FLTEDIT 


{ 

low=0 3 
high=9.99; 
ndec=2; 


); 


arr a a a ee 
MARGINS methods 


Dynamic initialisation 
VOID dl_dyn_init (VOID); 
Dynamically initialise the content of the dialog. 
It is assumed that algbox.rbuf stores the address of a Tare struct defined as follows: 
typedef struct 


{ 


unsigned short int tmarg; 

unsigned short int Ilmarg; 

unsigned short int rmarg; 

unsigned short int bmarg; 

} TMARG; 

The significance of the members of the mare struct is as follows: 
tmarg specifies the height in twips of the top margin. 
lmarg specifies the width in twips of the left margin. 
rmarg specifies the width in twips of the right margin. 
bmarg specifies the height in twips of the bottom margin. 


Converts the margins into the current printer units and then sets them as the content of the dialog controls. 


key input 
INT dl_key (INT index, INT keycode) ; 
Write the content of the dialog to the Tare struct pointed to by digbox. rbuf. 


Senses the margins in the dialog controls, converts them into units of twips and then writes the results to 
the Tmare struct pointed to by dlgbox. rbuf. 


Returns WN_KEY_CHANGED. 


16-27 


HWIM REFERENCE 


HEADFOOT 


flags 
id 


wn_calc_position |wn—emphasise 
wn_connect 
wn_dodraw 


IDLGCHAIN |DLGBOX 


next item count 
rbuft current 
underline 
helprid absorb 
changed 


dl_item_replace 
wn_key dl_item_append 
wn_emphasise qadl_init 
wn_sense_help di_dimmed_message 
wn_set dl_item_add 
wn_sense dl_set_size 
wn_position wn_draw di_ing_minsize 
wn_redraw idi_item_lock di—dyn—tnit 
Sense hetp al_item_dim di-key 
dl_set_item_flags 
dl_set_prompt dl_changed 
ase d@l_take_focus di_focus 
A—SenSe @1_handle_to_index di—launek—sub 


dl_index_to_handle dl_item_new 


The HEapFoor Class implements the Header details and Footer details dialogs allowing the user to edit the 
the header and the footer respectively. An example Header details dialog is shown in the following picture: 


Enter header details <inches) 


this is aheader| 
‘Alignment Left 


‘On first page No 
"Font... Pica 12 
‘Uertical offset 6.58 


An example Footer details dialog is shown in the following picture: 


Enter footer details (inches) 


‘Alignment Centred 
‘On first page No 
‘Font... Pica 12 
‘Vertical offset 9.58 


The header and the footer are stored in the current prinTER object the handle of which must be stored in 
w_wS->wserv.printer. 


16 - 28 


16 PRINT CLASSES 
—_— OS PRINT CLASSES 


Class definition 
Defined in sub-category file prntdigs.cl (generated header file prntdlgs.g). 


CLASS headfoot dlgbox 
{ 
REPLACE dl_dyn_init 
REPLACE dl_key 
REPLACE dl_launch_sub 


PROPERTY 
{ 
VOID *ph; points to PAGES_HEADER 
UWORD *offset; points to positional offset value 


} 
} 


Note: on the Series 3 the offset property is declared as a signed word i.e. worn. 


Property 
headfoot .ph a pointer to a PAGES_HEADER struct stored by the prrnTER object. The PAGES HEADER 
struct is defined as follows: 


typedef struct 


{ 


SCRLAY_FONT f; 
unsigned char align; 
unsigned char first_page; 
} PAGES_HEADER; 


the £ member specifies the default font. 


the align member contains a value between zero and five inclusive specifying either 
left, right, centred, justified, two column or three column alignment respectively. 


the £irst_page member contains a value which specifies whether or not the 
header/footer is to appear on the first page. A non-zero value indicates that it is to 
appear on the first page. 


headfoot.offset a pointer to a worn stored by the prrnTER object. Specifies the vertical offset of the 
header/footer. 


Resources 

Defined in the system resource file s_.rss. 
RESOURCE STRING sys_header_str { str="Enter header details"; } 
RESOURCE STRING sys_footer_str { str="Enter footer details"; } 


RESOURCE DIALOG sys_headfoot_dl 


{ 


titles"*",; 
£lags=DLGBOX_NOTIFY_ENTER |DLGBOX_RBUF_FILLED|DLGBOX_APPEND_UNITS TITLE; 


controls= 
{ 
CONTROL 


{ 


class=C_EDWIN; 
prompt="Text"; 
info=EDWIN 


{ 


flags=IN_EDWIN_VULEN_CHARACTERS | IN_EDWIN_ACCEPT_TABS; 
maxlen=80; 
vulen=20; 
}; 
} ' 


CONTROL 


{ 


class=C_CHLIST; 
prompt="Alignment"; 
info=CHLIST{rid=sys_headfoot_align;}; 


}, 
16 - 29 


HWIM REFERENCE 
SS SSS 


CONTROL 
{ 


class=C_CHLIST; 
prompt="0n first page"; 
info=CHLIST{rid=sys_no_yes;}; 


}, 


CONTROL 


{ 
class=C_TEXTWIN; 
prompt="Font "; 
info=TXTMESS 


{ 


flags=IN_TEXTWIN POPOUT; 
a 
} ’ 


CONTROL 


{ 


class=C_FLTEDIT; 
prompt="Vertical offset"; 
info=FLTEDIT 


{ 

low=0; 
high=9.99; 
ndec=2; 


}; 


ESS ee ee ee ae er SE 
HEADFOOT methods 


DL_D 


VOID dl_dyn_init (VOID) ; 


Dynamic initialisation 


Dynamically initialise the content of the dialog. 


Note that for a header, digbox.rbuf should point to an integer value set to PRINTER_HDR_ToP, whilst for a 
footer, it should point to an integer value set to PRINTER_HDR_BOT. 


Obtains the address of a PRINTER_PARAMS struct containing the current printer parameters by sending a 
PR_GET_PARAMS message tO w_ws->wserv.printer. 


If the integer pointed to by digbox.rbuf is equal to pRINTER_HDR_TOP, writes the address of the p.top and 
P-pg-hdtop members of the PRINTER_PARAMS struct to headfoot .ph and headfoot .offset respectively 
and then sets the dialog title from the sys_HEADER_sTR system resource. 


Otherwise, writes the address of the p.bot and p.pg.hdbot members of the PRINTER_PARAMS struct to 
headfoot .ph and headfoot .offset respectively and then sets the dialog title from the sys_FooTEeR_sTR 
system resource. 


Sets the header/footer text in the Header/Footer control: the header/footer text is obtained by sending a 
PR_GET_HD message tO w_ws->wserv.printer. 


Sets the index of the selected item in the Alignment control to headfoot .ph->align. 
Sets the index of the selected item in the On first page control to headfoot .ph->first _page. 
Sets the text in the Font control according to the font details in headfoot .ph. £. 


Converts the value pointed to by headfoot .offset to the current printer units and sets this value in the 
Vertical offset control. 


16 - 30 


16 PRINT CLASSES 


DL_KEY 


INT dl_key(INT index, INT keycode) ; 


ie key input 


Store the edited content of the dialog in the prinrEr object. 


Senses the text in the Header/Footer control as appropriate, and then sets this as the header/footer by 
sending a PR_SET_HD message to w_ws->wserv. printer. 


Senses the index of the item selected in the Alignment control and then writes the result to head£oot . ph- 
>align. 


Senses the index of the item selected in the On first page control and then writes the result to 
headfoot .ph->first_page. 


Senses the value in the Vertical offset control, converts it from current printer units to twips and then writes 
the result to the address pointed to by headfoot .offset. 


Returns WN_KEY_CHANGED. 


dialog 


VOID dl_launch_sub(INT index) ; 
Allow the user to edit the current font by launching a Font selector dialog. 
Opens the current printer resource file by sending a pR_OPEN_wDR message tO w_ws->wserv. printer. 
Writes appropriate values to a FONTSEL_pata struct defined as follows: 
typedef struct 

{ 

VOID *wdr; 

SCRLAY_FONT *pf; 

UWORD ret; 

} FONTSEL_DATA; 
The significance of the members of the ronrsEL_pata struct is as follows: 


wdr set to the handle of the current wor object opened by sending a pR_oPEN_wDR message to w_ws- 
>wserv.printer. 


pf the address of headfoot .ph->f i.e. a scRLAY_Fonr struct containing default font data. 
ret set to zero - the Font selector dialog sets this to a non-zero value if the font data has been edited 


Launches a Font selector dialog as described in the General dialogs chapter of the HWIM Reference 
manual with as the argument a pointer to the above ronTsEL_pata struct. 


Closes the current printer resource file by sending a pR_CLOSE_wDR message to w_ws->wserv.printer. 


Sets the text in the Font control according to the font specified by headfoot .ph->£. 


16 - 31 


HWIM REFERENCE 


PRNMODEL 


a next count 
current 


destroy di_item_replace 
wn_key dil_item_append 
wn_emphasise dl_init 
wn_sense_help dl_dimmed_message 
wn_set dl_item_add 
wn_sense di_set_size 
wn_draw dl_ing minsize 
dl_item_lock 
dl_item_dim 
dl_set_item_flags 
dl_set_prompt 
dl_take_focus 


wn_position 
wn_redraw 


wa—sense—heip 


wn_visible 


di_index_to_handle |dl_item_new 


The PRNMODEL Class implements the Set printer dialog allowing the user to select the desired printer and 
default font. An example Set printer dialog is shown in the following picture: 


Set printer 


Sane diiiad ¢ Canon BJ-16e> 
‘Default font... Pica 12 


The selected printer and the default font are both stored in the curent pRinTER object the handle of which 
must be stored in w_ws->wserv.printer. 


Class definition 
Defined in sub-category file prntdlgs.c/ (generated header file prntdlgs.g). 


CLASS prnmodel digbox 
{ 
REPLACE dl_key 
REPLACE dl_launch_sub 
REPLACE dl_changed 
REPLACE dl_dyn_init 


TYPES 


{ 


typedef struct 


{ 

INT path; entry containing file path in pf 
INT index; index of printer model info in file 
} MLIST_ITEM; 


16 - 32 


16 PRINT CLASSES 
—_—— ——s— eeeeeeeSSSSSSOERINE GLASSES 


PROPERTY 3 


{ 


PR_VASTR *pm; handle of object used to store printer models 
PR_VASTR *pf; stores names of files where model data is stored 
PR_VAFLAT *pi; info for each printer model: where stored 

UWORD model; 

WORD nsel; index of current model in overall list 
SCRLAY_FONT sf; 

TEXT wdrfile [P_FNAMESIZE] ; 


} 
} 


Property 


prnmodel.pm the handle of an instance of the vastr class - this stores the names of the available 
printer models and provides the data for the Select printer control. 


prnmodel .pf the handle of an instance of the vastr class - this stores the names of the WDR files 
from which the printer models were obtained. 


prnmodel.pi the handle of an instance of the varuat class - this is used to store the index of each 
printer model in its parent WDR files. 


The n™ record stores a cross reference for the n"* printer model in the prnmodel .pm 
array. 


Each record is organised as an Murst_para struct defined as follows: 


typedef struct 


{ 

INT path 

INT index 

} MLIST_ITEM; 


the path member specifies the index of the parent WDR file in the prnmodel . pf 
array. 


the index member specifies the index of the printer model within the WDR file. 
prnmodel .model specifies the model number of the current printer. 
prnmodel .nsel specifies the index of the current printer model in the prnmode1 .pm array. 
prnmodel.sf @ SCRLAY_FONT struct containing current default font data. 
prnmodel.wdrfile a buffer containing the name of the current printer resource file. 


Resources 


Defined in the system resource file s_.rss. 


RESOURCE DIALOG sys_printer_model 
{ 
title="Set printer"; 
flags=DLGBOX_NOTIFY_ENTER | DLGBOX_RBUF_FILLED; 
controls= 
{ 
CONTROL 
{ 
prompt="Select printer"; 
flags=DLGBOX_ITEM_NOTIFY_CHANGED; 
class=C_CHLIST; 
info=CHLIST{}; 


’ 


16 - 33 


HWIM REFERENCE 
TE 


CONTROL 


{ 

class=C_TEXTWIN; 
prompt="Default font "; 
info=TXTMESS 


{ 


flags=IN_TEXTWIN_POPOUT; 


Hy 


I a a ae TS) 
PRNMODEL methods 


VOID dl_dyn_init (VOID) ; 
Dynamically initialise the content of the dialog. 


Obtains the address of a PRINTER_PARAMs struct containing the current printer parameters by sending a 
PR_GET_PARAMS Message tO w_ws->wserv.printer. 


Obtains the current printer model number and the name of the associated WDR file by sending a 
PR_SENSE_MODEL message tO w_ws->wserv.printer and writes the results to prnmodel.model and 
prnmodel .wdrfile respectively. 


Writes the d.£ member of the pRInTER_PaRams struct to prnmodel sf. 
Sets suitable text, based on the content of prnmodel. sé, in the Default font control. 


Creates an instance of the vastr class and writes its handle to prnmode1 .pm. Initialises the vastR 
component by sending a va_INIT message to prnmodel .pm specifying a granularity of 20. 


Creates an instance of the vastr class and writes its handle to prnmodel . pf. Initialises the vastR 
component by sending a va_INIT message to prnmodel .p£ specifying a granularity of 32. 


Creates an instance of the varuat class and writes its handle to prnmodel .pi. Initialises the vaFLAT 
component by sending a va_INIT message to prnmodel .pi specifying records of length equal to the size of 
an MLIST_ITEM struct and a granularity of four. 


Creates an instance of the pmopiocs class and then sends an Ls_scan message to the pmopLocs object: this 
scans the rom device and the root and WDR directories of all devices on the Locs: : node for WDR printer 
resource files. This message adds records: 


* containing the names of the located WDR files: these records are appended to the variable array 
whose handle is stored in the prnmodel . pf property. 


¢ containing the names of the printer models listed in the located WDR file: these records are added 
to the variable array whose handle is stored in the prnmode1 . pm property. Note that on the 
Series 3a the records are ordered alphabetically and that a duplicate printer model located on a 
flash pack will replace the rom version. 


¢ containing a cross reference for each printer model in the WDR file: these records are appended to 
the variable array whose handle is stored in the prnmode1 .pi property. The n™ record stores a 
cross reference for the n"* printer model in the prnmodel . pm array. 


Each printer.pi record is organised as an MLIST_ITEM struct. 
The MLIsT_ITEM struct is defined as follows: 
typedef struct 
i path 


INT index 
} MLIST_ITEM; 


16 - 34 


16 PRINT CLASSES 


The significance of the members of the mu1st_1TeEm struct is as follows: 
path specifies the index of the parent WDR file in the prnmodel .p£ array. 
index specifies the index of the printer model within the parent WDR file. 


Sets the Select printer control to display the data in prnmodel . pm array with the current selection set to 
prnmodel .nsel. 


If w_ws->wserv. flags Contains PR_WSERV_OWN_DEFAULT_FonT then the method locks the Default font 
control - in consequence the text is visible but may not be edited by the user. 


ile key input 


INT dl_key (INT index, INT keycode) ; 
Store the edited content of the dialog in the printer object. 


Obtains the address of a PRINTER_PARaMs struct containing the current printer parameters by sending a 
PR_GET_PARAMS message tO w_ws->wserv.printer. 


Senses the index of the item selected in the Select printer control and then copies the name of the 
corresponding printer resource file to prnmodel . wdrfile. 


Writes the current printer model number to prnmode1 .modei and then sets this as the current printer model 
by sending a PR_SET_MODEL message to w_ws->wserv.printer. 


Stores the default font in the prinTER object by writing prnmodel.sf to the a. £ member of the 
PRINTER_PARAMS struct. 


sub-dialog 
VOID dl_launch_sub(INT index) ; 
Allow the user to modify the default font characteristics by launching a Font selector dialog. 


Senses the index of the item selected in the Select printer control and then obtains a pointer to the 
corresponding mLIsT_TTem item in the prnmodel .pi array. 


Copies the name of the printer resource file associated with the selected printer model to 
prnmodel .wdrfile. 


Writes the index member of the mursT_1rTem struct to prnmodel .model. 


Creates an instance of the wor class and then sends a wor_rnrT message specifying prnmodel .wdrfile and 
prnmodel .model. as the name of the current wor file and the current printer model number respectively. 


Allows the user to modify the default font characteristics stored in prnmode1.sf by launching a Font 
selector dialog: for further details of the Font selector dialog see the description of the rowtsEt class in the 
General dialogs chapter of the HWIM Reference manual. 


Sets appropriate text in the Default font control. 


VOID dl_changed(INT changed) ; 


m changed messages 


Update the content of the dialog according to the content of the Select printer control. 


Senses the index of the item selected in the Select printer control and then obtains a pointer to the 
corresponding MLISsT_ITEM item in the prnmodel . pi array. 


Writes the name of the selected printer resource file to prnmodel . wdrfile and then writes the index 
member of the MLIST_ITEM struct to prnmodel.model. 


Sets appropriate text for the Default font control. 


16-35 


HWIM REFERENCE 


ay 


fawrw—_fpccua IN |DLGBOX 


a aoe next item count 
rbuf current 
dimrid underline 
helprid absorb 

changed 


destroy dl_item_replace 
wn_key dl_item_append 
wn_emphasise dl_init 
wn_sense_help dl_dimmed_message 
wn_set dl_item_add 
wn_sense dl_set_size 
wn_draw di_inq_minsize 
dl_item_lock di—dyn—taie 
dl_item_dim di—key 
dl_set_item flags 

dal_set_prompt di—-ehanged 
dl_take_ focus dl_focus 
dl_handle_to_index di_launch_sub 
dl_index_to_handle dl_item_new 


wn_position 
wn_redraw 


wnrsense—heip 


wn_visible 


The paces1zz class implements the Page size dialog allowing the user to specify the desired page size and 
orientation. An example of a Page size dialog is shown in the following picture: 


Page size Cinches} 


+Ad> 


Width 8.27 
Height 11.69 
‘Orientation Portrait 


The page size and orientation are stored in the current PRINTER object the handle of which must be stored in 
W_wS->wserv.printer. 


Class definition 
Defined in sub-category file prntdigs.cl (generated header file prntdlgs.g). 


CLASS pagesize dlgbox 


REPLACE dl_dyn_init 
REPLACE dl_changed 
REPLACE dl_key 


} 
Resources 
Defined in the system resource file s_.rss. 
The following is defined in hwim.rh: 


STRUCT PAGE SIZE 


{ 
WORD width; 
WORD length; 


} 


The following is defined in s_.rss: 


16 - 36 


16 PRINT CLASSES 
eee OEE ELAS SED 


RESOURCE PAGE_SIZE_ARRAY sys_page_dimensions 


{ 


page_size= 
{ 
PAGE_SIZE {width=PAGE_WIDTH_A4; length=PAGE_LENGTH_A4;}, 
PAGE_SIZE {width=PAGE_WIDTH_A4; length=PAGE_LENGTH_A4;}, 
PAGE_SIZE {width=PAGE_WIDTH_EXECUTIVE; length=PAGE_LENGTH EXECUTIVE; }, 
PAGE_SIZE {width=PAGE_WIDTH_LEGAL; length=PAGE_LENGTH_LEGAL; }, 
PAGE_SIZE {width=PAGE_WIDTH_ LETTER; length=PAGE_LENGTH_LETTER;}, 
PAGE_SIZE {width=PAGE_WIDTH_MONARCH; length=PAGE_LENGTH MONARCH; }, 
PAGE_SIZE {width=PAGE_WIDTH_DL; length=PAGE_LENGTH_DL; } 


}; 
} 


RESOURCE DIALOG sys_pagesize_dl 
{ 
title="Page size"; 
£1ags=DLGBOX_NOTIFY_ENTER | DLGBOX_RBUF_FILLED|DLGBOX_APPEND_UNITS TITLE; 
controls= 
{ 
CONTROL 
{ 
class=C_CHLIST; 
£lags=DLGBOX_ITEM_NOTIFY_CHANGED; 
prompt="Page size"; 
infosCHLIST{rid=sys page_size;}; 
}, 
CONTROL 
{ 
class=C_FLTEDIT; 
prompt="Width"; 
info=FLTEDIT 
{ 
low=1; 
high=45; 
ndec=2; 
}; 
} ' 
CONTRO: 
{ 
class=C_FLTEDIT; 
prompt="Height"; 
info=FLTEDIT 
{ 
low=1; 
high=45; 
ndec=2; 
1s 
}, 
CONTROL 
{ 
class=C_CHLIST; 
prompt="Orientation"; 
info=CHLIST{rid=sys_orient;}; 


} 


eS ee ee ee er LT 
PAGESIZE methods 


Dynamic initialisation 


VOID dl_dyn_init (VOID) ; 
Dynamically initialise the content of the dialog. 


Obtains a pointer to a PRINTER_PARAMS Struct containing the current printer parameters by sending a 
PR_GET_PARAMS message tO w_ws->wserv.printer. 


16 - 37 


HWIM REFERENCE 
ee SeeeSSSSSSSSSSSSSSSSSSee 


Sets the index of the item selected in the Page size control to the d. size.choice member of the 
PRINTER_PARAMS struct. 


Not on the Series 3: if w_ws->wserv. flags contains PR_WSERV_METRIC, sets the upper and lower bounds for 
the Width and Height controls to one hundred units and two units respectively. 


If the d. size. choice member of the pRINTER_PARAMs struct is set to the value 1 (corresponding to the 
second item - the string "Custom" - in the sys_pacE_s1zE system resource) specifying the custom page 
size: 


¢ converts the p.pg.width member of the PRINTER_PaRams struct from twips to the current printer 
units, and then sets this as the value in the Width control. 


e converts the p.pg.height member of the pRINTER_PaRaws struct from twips to the current printer 
units, and then sets this as the value in the Height control. 


Otherwise sets the content of the Width and Height controls as described for the DL_CHANGED message. 


If the p.pdr£1ags member of the PRINTER_PARAMS struct contains wOR_PDR_LANDSCAPE, sets the index of 
the item selected in the Orientation control to one. 


Otherwise sets the index of the selected item in the Orientation contro] to zero. 


DE KEYS 


INT dl_key(INT index,INT keycode) ; 


Handle key input 


Store the selections in the dialog in the printer object. 


Obtains a pointer to a PRINTER_PARAMs struct containing the current printer parameters by sending a 
PR_GET_PARAMS Message tO w_ws->wserv.printer. 


Senses the index of the item selected in the Page size control and then writes the index to the 
d.size_choice member of the pRInTER_PARAms struct. 


Senses the width in the Width contro], converts the value to the current printer units - i.e. cm or inches - 
and then writes the value to the p.pg.width member of the PRINTER_PARAMS Struct. 


Senses the height in the Height control, converts the value to the current printer units - i.e. cm or inches - 
and then writes the value to the p.pg.height member of the PRINTER_PARAMS struct. 


Senses the index of the item selected in the Orientation control and then writes the index to the p -pdrflags 
member of the PRINTER_PARams struct. 


Returns wN_KEY_CHANGED. 


VOID dl_changed (INT changed) ; 
Set the content of the Width and Height controls according to the item selected in the Page size control. 


The s¥S_PAGE_DIMENSIONs system resource contains a list of PAcE_s1zE structs. The method loads the 
PAGE_S1ZE Struct having the same index as the item selected in the Page size control. 


The PAGE_szzz struct is defined as follows: 
STRUCT PAGE_SIZE 
{ 
WORD width; 
WORD length; 


} 


The significance of the members of the above struct is as follows: 
width specifies the width of the page in units of twips. 


length specifies the height of the page in units of twips. 


16-38 


16 PRINT CLASSES 


Converts the width member of the above struct into the current printer units and then sets the result into the 
Width control. 


Converts the height member of the above struct into the current printer units and then sets the result into 
the Height control. 


PRINTING 


flags next 
id 


destroy wn_draw 


count 


rbuf current 
dimrid underline 


helprid absorb 


flags changed 


destroy dl_item_replace dl_dyn_init 


wn_cale_ position |wn_emphasise wn_key di_item_append di_set_size 


wn_emphasise dl_init 


Printing set_title 


wn connect 


wn_dodraw wn_sense_help d1_dimmed_message Printing do_print 


wn_emphasise wn_set dl_item_add iorinting done 


wn_key wn_sense dl_set_size 


wn_position wn_draw dl_ing_minsize 


@l_item_lock dl_dyn_init 
di_item_dim di_key 


dl_set_item_flags 


dal_set_prompt dl_changed 
dl_take_focus dl_focus 
dl_handle_to_index dl_launch_sub 
di_index_to_handle 


dl_item_new 


The PRINTING Class supports the Printing dialog allowing the starting, monitoring and cancelling of 
printing. An example Printing dialog is shown in the following picture: 


Printing to Plis 
(page 2) 


Abandon 


{_ 


The handle of the current prinTER object must be stored in w_ws->wserv.printer. 


The digbox.rbuf property must point to an RBUF_PRINTING struct which is defined as follows: 


typedef struct 


{ 


PAGES CALLS calls; 
VOID **ppages; 
} RBUF_PRINTING; 


16 - 39 


HWIM REFERENCE 
eee 


The significance of the members of the above struct is as follows: 
calls a PAGES_CALLS struct which specifies the call backs required by the pacgs object. 
The Paces_cauus struct is defined as follows: 


typedef struct 


{ 


VOID *hread; 
WORD mread; 
VOID *hdone; 
WORD mdone; 


} 


the hread member specifies the handle of the object that is to receive read call-back messages 
from the paczs active object. 


the mread member specifies the read call-back message that is to be sent by the paczs active 
object when it requires the next line of text. 


the hdone member specifies the handle of the object which is to receive completion call-back 
messages from the pacss active object. 


the mdone member specifies the completion call-back message that is to be sent by the pacEs 
active object when it has completed either the current page or the entire document. 


ppages either nu or a pointer to the handle of the pacss active object. 
(The hread and mread members of the above paGES_caLLs struct must be set by the owning application.) 


Class definition 
Defined in sub-category file printing.cl (generated header file printing g). 


CLASS printing dlgbox 


{ 


REPLACE dl_dyn_init 
REPLACE dl_set_size 
ADD printing_set_title 
ADD printing do print 
ADD printing_done 


CONSTANTS 


{ 


PR_WIN_WILL SKIP 0x4000 Re-use this bit 


} 


TYPES 


{ 


typedef struct 


{ 


PAGES_CALLS calls; 
VOID **ppages; 
} RBUF_PRINTING; 


} 


PROPERTY 1 


{ 


VOID *pages; pages active object 


} 


Property 


printing.pages the handle of an instance of the paces active object class - this handles the printing 
operation. A description of the paces class may be found in the Document Printing 
Classes chapter of the FORM Reference manual. 


16 - 40 


16 PRINT CLASSES 
$$$ Se OEIINT CLASSES 


Resources 


Defined in the system resource file s_.rss. 


RESOURCE DIALOG sys_ printing dialog 
{ 
flags=DLGBOX_RBUF_FILLED; 
controls= 


{ 


CONTROL 
{ 
class=C_TEXTWIN; 
£lags=DLGBOX_ITEM_CENTRE|DLGBOX_ITEM_DEAD|DLGBOX_ITEM UNDERLINED; 
info=TXTMESS 
{ 
flags=IN_TEXTWIN_AL CENTRE; 
}i 
} ' 
CONTROL 
{ 
class=C_TEXTWIN; 
£lags=DLGBOX_ITEM_CENTRE|DLGBOX_ITEM_DEAD; 
info=TXTMESS 
{ 
flags=IN_TEXTWIN_AL CENTRE; 
}; 
} e 
CONTROL 
{ 
class=C_ACLIST; 
info=ACLIST 
{ 
rid=sys_ac_abandon; 


}; 


SS ee ee ee Oe een a a a ey 
PRINTING methods 


VOID dl_dyn_init (VOID) ; 


Dynamically initialise the content of the dialog and start the printing. 
Note: dlgbox.rbuf must point to an appropriately initialised raur_PRINTING struct. 


Sets the text in the Page number control - the text is created from the format string in the sys_PaGE_1s 
system resource and an argument of 9999. 


Sets the dialog title by sending self a PRINTING_SET_TITLE message. 
Specifies the completion call-back method by writing o_pRINTING_DONE to dlgbox.rbuf->calls.mdone. 
Specifies the completion call-back handle by writing se1£ to dlgbox. rbuf->calls.hdone. 


Starts the printing by sending self a PRINTING_DO_PRINT message with as argument the address of 
dlgbox.rbuf->calls. 


Writes the handle of the current pacgs active object to printing.pages. 


If digbox. rbuf->ppages is non-zero, writes printing.pages to the address pointed to by digbox.rbuf- 
>ppages. 


16-41 


HWIM REFERENCE 
DLLSET SE Set size of dialog 


VOID dl_set_size (VOID) ; 

Set the size of the dialog and the content of the Page number control. 
Supersends a DL_SET_s1zE message. 

Sets the text in the Page number control: 


¢ ifwin.flags contains PR_WIN_WILL_sKIP and the printer.p -p.pgbeg member of w_ws- 
>wserv.printer is greater than one, the text is created from the SYS_SKIPPING_PAGE system 
resource with an argument of one. 


e otherwise the text is created from the sys_pacE_zs system resource with an argument of one. 
The sys_SKIPPING_PAGE and sys_PaGE_Is system resources are defined as follows: 
RESOURCE STRING sys_skipping_ page 


{ 


str="(skipping page tu)"; 


RESOURCE STRING sys_printing_to 


{ 


str="Printing to ts"; 


} 
“Setttitie 


VOID printing_set_title (VOID) ; 


Set the title and the content of the control with index one. 


Obtains the name of the printer device - i.e. Serial, Parallel or a filename - by sending a 
WS_SENSE_PDEV_TEXT message to w_ws. 


Sets the text in the dialog title - the title is created from the SYS_PRINTING_TO system resource and the 
name of the printer device. 


If the printer.p.p.pgbeg member of w_ws->wserv.printer is not equal to one: 
* — indicates that the first page(s) is (are) to be skipped by setting PR_WIN_WILL_SKIP in win. flags. 


e _ sets the text in the Page number control - the text is created from the SYS_SKIPPING_PAGE system 
resource and an argument of 9999. 


PRINTING_DO_PRINT 


VOID *printing_do_print (PAGES CALLS *pcalls) ; 


Start the printing operation. 


Starts the printing operation by sending a pR_PRINT message to w_ws->printer with an argument of 
pcalls. 


Returns the handle of the pacgs active object which is handling the printing. 


INT printing_done (PAGES_DONE *d) ; 
Handle page and document completion. 


If the event member of the paces_pone struct pointed to by a is PAGES _DONE_PAGE - indicating that printing 
of the current page is complete - sets the text in the Page number control and then retums FALSE: 


¢ ifwin. flags contains pR_WIN_WILL_sxrp and the page number of the first page to be printed i.e. 
w_ws->.printer->printer.p.p.pgbeg is greater than the current page number i.e. d- >page, the 
text is created from the sys_sKIPPING_PAGE system resource and the current page number. 


a SSeeeeeeeSSeSSSSSFSSFSFSSeEEeeeee 
16 - 42 


16 PRINT CLASSES 
eS PRINT CLASSES 


¢ — otherwise the text is created from the sys_pacE_1s system resource and the current page number 
in d->page. 


If the event member of the paczs_pone struct pointed to by d is PAGES_DoNE_poc - in which case the 
printing of the document is complete - indicates that no further copies of the document are to be printed by 
retuming FALSE. 


If the event member is none of the above - in which case either the printing is complete or an error has 
occurred while printing - writes NULL to printing.pages, destroys the PRINTING object by sending selfa 
destroy message and then returns FaLseE. 


For a more detailed explanation of the completion call-back method see the description of the 
pagedoc_mdone method in the Formatted Document Content Classes chapter of the FORM Reference 
manual. 


(This method is called by the paczs active object when it finishes printing the current page/document.) 


PMODLOCS 


PMODLOCS 


dl 


flags 
peb 
pname 
match 
info 


name 
wildname 


is_matchname 
1ls_scan 


1ls_filename 


ds—Sleseme 


The pmoptocs class is provided for use by the prnmopeL class (or a subclass thereof) described in the 
current chapter. The class may be used to scan the desired devices and directories for WDR printer resource 
files and extract the names of the printer models supported. 


The scan adds records: 


* containing the names of the located WDR files. These records are added to the variable array 
whose handle is stored in the prnmode1 .pf property of the owning class. 


e containing the names of the printer models listed in the located WDR files. These records are 
added to the variable array whose handle is stored in the prnmodel. pm property of the owning 
class. 


¢ containing for each printer model the index of the record storing the name of the printer model 
and the index of the printer model in the parent WDR file. These records are added to the variable 
array whose handle is stored in the prnmodel .pi property of the owning class. 


Class diagram 


/ los > _/ pmodlocs + 


16 - 43 


HWIM REFERENCE 
eo  SSSSSSSSSSSSMSSSSSSSSS 


Class definition 
Defined in sub-category file pmodlocs.cl (generated header file pmodlocs.g). 
CLASS pmodlocs locs 
REPLACE ls filename 
PROPERTY 


{ 


PR_PRNMODEL *dl; Owning dialog 
} 
} 
Property 


pmodlocs.dl the handle of the object which uses the pmopLocs component. 


PMODLOCS methods 
LS FILENAME = = |. Process matching filename 


INT ls_filename (TEXT *buf) ; 
Process a matching filename. 


This method is called when a matching file has been located: the matching file is assumed to be a WDR 
printer resource file the name of which is specified as a zero terminated string by buf. 


The method adds records: 


* containing the name of the located WDR file. This record is appended to the variable array whose 
handle is stored in the prnmode1 .pf property of the owning class. 


® containing the names of the printer models listed in the located WDR file. These records are added 
to the variable array whose handle is stored in the prnmode1 . pm property of the owning class. Note 
that on the Series 3a the records are ordered alphabetically and a duplicate printer model located 
on a flash pack will replace the rom version. 


e containing a cross reference for each printer model in the WDR file. These records are appended 
to the variable array whose handle is stored in the prnmode1 .pi property of the owning class. The 
n® record stores a cross reference for the n* printer model in the prnmodel . pm array. Each record 
is organised as an MLIST_ITEM struct. 


The mutstT_ITEM struct is defined as follows: 
typedef struct 
INT path 
INT index 
} MLIST_ITEM; 
The significance of the members of the murst_rrem struct is as follows: 
path specifies the index of the parent WDR file in the prnmode1 . pé array. 


index specifies the index of the printer model within the parent WDR file. 


Returns FALSE. 


16-44 


CHAPTER 17 


DIALLING DIALOGS 


This chapter documents classes associated with tone dialling. These classes are: 
e the HarpuE class which provides an idle active object especially suited for use with tone dialling. 


e the prazao class which supports tone dialling and which is used as a component by the praLpLG 
class. 


e the praupic class which provides a common base for the rpraLpLc and spraxpuc classes. 
e the rreEprat class which provides a dialog control that allows free-form tone dialling. 
e the rpraxotc class which provides a dialog that supports free-form tone dialling. 


e — the cwrrypxe class which provides a dialog that allows the user to select a country from the list 
supported by the World database. 


e the spranpuc class which provides a dialog that allows editing and tone dialling one or more 
dialling string. 


Precursors 
Familiarity with the following topics will aid the understanding of this chapter: 
e the AIDLE active object class described in the OLIB Reference manual. 


e the picox class described in the Dialog Boxes chapter of the HWIM Reference manual. 


HAIDLE 


q 
priority 
isactive 
peb 

stat 


destroy ao_init 
ao_init ao_run 
ao_cancel 

ao_abrun 

ao_queue 

ao_run 


The HAIDLE class provides an idle active object, and is used by for example, the prazao class described 
later in this chapter. The Hazpzé class allows the idle active object to be cancelled at any time by pressing 
the Escape key. 


The following illustrates the use of the yazpze class: 


17-1 


HWIM REFERENCE 
es ESSE 


/* compute intensive loop starts here */ 
WORD stat; 


haidle=f_newsend(CAT_DEMO_HWIM,C_HAIDLE,O_AO_INIT); 
for (i=0;i1<=1000;i++) 


{ 


psend (haidle,AO_ QUEUE, &stat) ; 


The ao_QuEUE message returns once all active objects in the queue have run thus ensuring that the compute 
intensive loop does not monopolise the processor. An example of the use of the HarpzE class is tone 
dialling thus ensuring that the tone dialling does not interfere with other tasks and may be cancelled at any 
moment. 


Class diagram 


active) / aidle ~} “ haidle 


Class definition 
Defined in sub-category file hactive.c/ (generated header file hactive.g). 


CLASS haidle aidle 


{ 


REPLACE ao_queue 
ADD hai_key 


PROPERTY 
{ 
VOID *rbuf; 
} 
} 
Property 


haidel.rbuf used to store the status word for the idle active object. 


Ee ee ee ee ee ee ee eer 
HAIDLE methods 


idle object 
INT ao_queue (VOID *xbuf) ; 

Allow queued active objects to run by starting an idle object. 

Writes rbuf to haidle.rbuf. 


If the unsigned word pointed to by rbuf contains zero, signals the process i/o semaphore - i.e. call 
p_iosignal. 


Writes TRUE to active.isactive. 


Directs all future keypresses to its own key method by writing self to w_ws->wserv. filter and writing 
O_HAI_KEY tO w_ws->wserv.filmethod. 


Ensures that queued active objects have an opportunity to run by sending an am_sTaRT message to w_am- 
this message send only returns once all queued active objects have run. 


Writes the original key filter and filter method to w_ws->wserv. filter and w_ws->wserv.filmethod 
respectively. 


The Series 3a version returns active.stat. 


The Series 3 version does not return a value. 


——eeSSSeSeeSeSSSSSSSSeSSSSSSSSSESESE 
17-2 


17 DIALLING DIALOGS 


INT hai_key (INT keycode, INT modifiers) ; 

Handle a keypress that may potentially terminate the Harpzz idle active object. 

If keycode is W_KEY_ESCAPE, cancels the idle object as follows: 
¢ indicates that the request was cancelled by writing E_FILE_ CANCEL to haidle.rbuf. 
e — ensures that the last am_starT message send returns by sending an am_sTop message to w_am. 
e indicates that the Harpe active object is not active by writing FALSE to active .isactive. 


Returns wN_KEY_CHANGED. 


DIALAO 


priority 
isactive 
pcb 

stat 


destroy ao_init 
ae-init ao_run 


ao_cancel 
ao_abrun 


The pzaxao class may be used to make an asynchronous request to generate a sequence of dialling tones. 
The class allows the user to cancel the dialling at any time after the request has been made by pressing the 
Escape key. Note that the class directs all keypresses to its own hai_key method. 


For a description of the sound device see the 1/O Devices Reference manual. 


Class diagram 


/ ative / aidle “> / haidle~; / dialao 


Class definition 
Defined in sub-category file hactive.c/ (generated header file hactive.g). 


CLASS dialao haidle 
Active object supervising dialling 


{ 


REPLACE ao_queue 
REPLACE hai_key 


} 


Property 
None. 


17-3 


HWIM REFERENCE 


i ee eee SS ee 
DIALAO methods 


ig object 
INT dialao_ao_queue (VOID *pcb,TEXT *str,E DIAL *c); 
Queue a request to write a tone sequence to the sound channel. 


Makes an asynchronous request to the sound channel to play the required tone sequence using 
active.stat as the status word. 


The handle of the sound channel should be stored in peb - note that an invalid handle will panic the calling 
process. 


The tone sequence should be stored as a zero terminated string specified by str. The timing for the tone 
dialling is specified by the E_prax struct pointed to by c. 


The £_pzaz struct is defined as follows: 
typedef struct 


{ 


UBYTE toneLengthTicks; 

UBYTE delayLengthTicks; 

UWORD pauseLengthTicks; 

} E_DIAL; 
The members of the &_prau struct have the following significance: 
toneLengthTicks the length of a dial tone in units of 1/32 seconds. 
delayLengthTicks _ the time between dial tones in units of 1/32 seconds. 


pauseLengthTicks _ the length of the pause corresponding to the comma and space characters in units of 
1/32 seconds. 


Further details of the tone dialling may be found in the Sound chapter of the /O Devices Reference 
manual. 


Supersends an ao_QUEUE message with an argument of pcb. 
The Series 3a version returns the value returned by the ao_QuEUE message. 


The Series 3 version does not return a value. 


INT dialao_hai_key(INT keycode, INT modifiers) ; 
Handle a keypress that may potentially cancel the prazao idle active object. 
If keycode is W_KEY_ESCAPE: 


e cancels any outstanding write request on the sound channel the handle of which is assumed to be 
in haidle.rbuf. 


e waits for the cancel request to complete by calling p waitstat with the address of active.stat 
as the argument. 


* ensures that the last am_sTarT message send retums by sending an am_sTop message to w_am. 
e indicates that the pranao active object is not active by writing FALSE to active.isactive. 


Returns wN_KEY_CHANGED. 


17-4 


17 DIALLING DIALOGS 


DIALDLG 


flags next 
id 
destrey wh-draw 


DLGBOX 


item count 
xvbuf current 
dimrid underline 
helprid absorb 
changed 


destroy dl_item_replace 
wn_key dl_item_append 
wn_emphasise di_init 
wn_sense_help dl_dimmed_message 
wn_set dl_item_add 
wn_sense di—set—size 


dl_set_size 


wn_position wn_draw dl_ing_minsize 
wn_redraw dl_item_lock al_dyn_init 
wh—sense—heip dl_item_dim dl_key 


wn_visible dl_set_item flags 

dl_set_prompt dl_changed 
dl_take_focus dl_focus 
dl_handle_to_index d1_launch_sub 


dl_index_to_handle dl_item_new 


The prazpue class provides a common base class for the rpraLpic and sptaxpie classes. It provides the 
basic functionality required by a dialog that supports tone dialling. 


Class diagram 


oes ans. ony - ons, atts 


/ in > (4 bwin} / digchain’ |/ digbox; / dialdig > 


Class definition 
Defined in sub-category file dialdlgs.cl (generated header file dialdlgs.g). 


CLASS dialdlg dlgbox 
Add active object to appman 


{ 


REPLACE dl_set_size 
PROPERTY 1 


{ 


VOID *dialao; 


} 
} 


Property 
dialdig.dialao handle of an instance of the pranao class - this is used to play a tone sequence. 


17-5 


HWIM REFERENCE 


Ez eT EE eS ee] 
DIALDLG methods 


DL_SET SIZE = Create a dial active object 
VOID d@l_set_size (VOID) ; 

Initialise the help resource and create and initialise a dial active object. 

Supersends a pL_SET_SIZE message. 

Writes -syS_HELP_DIALLING to dlgbox.helprid. 


Creates an instance of praLao and writes the handle to dialdlg.dialao. Initialises the pranao component 
by sending an ao_INIT message tO dialdlg.dialao. 


FREEDIAL 


FREEDIAL 


current 
str 


landlord 
offset 
width 


destroy 
wn_calc_positio wn_init 
n wn_visible wn_draw 
wn_connect lg_draw wn_key 


wn_dodraw lg_self_check 


ig_sense_width 


wn_emphasise lg_set_id_pos 


orakey 


wn_position 
wn_redraw lig_update 
wn_sense_help 


The FREEForM class provides a dialog control that supports free-form tone dialling - thus the corresponding 
tone is generated when a key is pressed. An example of a FREEFORM control used as a dialog component is 
shown in the following picture: 


Free-form dialling 


where the FREEFoRM control is the second item in the dialog. 


Class diagram 


Hao Fre se (rm ee ‘ os 
f Hy ‘ * , 4 = 
F, i ‘ / | ry / freedial > 
4 é ta ia f 
. 


17-6 


17 DIALLING DIALOGS 
——__———<$S—_. eS IALLING DIALOGS 


Class definition 
Defined in sub-category file dialdlgs.cl (generated header file dialdlgs.g). 


CLASS freedial lodger 


{ 


REPLACE destroy 
REPLACE wn_init 
REPLACE wn_draw 
REPLACE wn_key 
REPLACE lg _sense_width 
PROPERTY 


{ 


WORD current; /* index of current cursor */ 
TEXT str (WR_MAX_DIAL STRING+2] ; /* +2 for ZTS. Max of 24 char */ 


} 
} 


Property 
freedial.current the length of the number to tone dial. 


freedial.str the number to tone dial - stored as a zero terminated string. 


See the Sound chapter of the /O Device Reference manual for details of the 
allowed characters. 


ats Se a SS a a ay 
FREEDIAL methods 


_ Destroy 
VOID destroy (VOID) ; 

Destroy the FREEDIAL instance. 

Ensures that the key click is re-enabled by calling woisablekeyClick with an argument of FALSE. 


Clears PR_WSERV_FREEFORM_DIALLING in w_ws->wserv. flags and supersends a DESTROY message. 


dialling 
VOID wn_init (UBYTE *init,PR_WIN *landlord) ; 

Initialise the FREEDIAL instance. 

Writes an underscore character - '_' - to the first wR_MAX_DIAL_STRING elements of freedial.str. 

Writes zero to freedial. current. 

Writes landlord tO lodger. landlord. 

Sets PR_WSERV_FREEFORM_DIALLING in w_ws->wserv. flags. 


Disables the key click by calling woisablekeyclick with an argument of TRUE. 


“Draw dial string 


VOID wn_draw (VOID) ; 
Draw the dial string. 
Draws the dial string stored in the first wR_MAX_DIAL_sTRING elements of freedial.str. 


The width of the control is taken from the width of the lodger window. The offset of the control is taken 
from the offset of the lodger window. 


The text is drawn in a monospace font with left alignment. 


17-7 


HWIM REFERENCE 


WN_KEY ~ oS : _ Add input and dial 


INT wn_key (INT keycode, INT modifiers) ; 


Add keycode to the dial string and play the corresponding tone. 
If keycode is greater than or equal to 0x100, returns wn_KEY_NO_CHANGE. 
If keycode is neither a comma, an asterisk, a hash - i.e. #, nora digit: 

e converts the character to uppercase. 


e if keycode is not in the range 'A' to 'F' inclusive, calls hrnfoprint with an argument of 
-SYS_INVALID_CHAR and returns WN_KEY_NO_CHANGE. 


If freedial.current is equal to wR_MAX_DIAL_STRING, resets the dial string by writing an underscore 
character to the first wR_MAX_DIAL_STRING elements of freedial.str and writing zero to 
freedial.current. 


Writes keycode to freedial.str[freedial. current), increments freedial .current and then draws the 
control by sending self an LG_DRAW message. 


Clears &_SOUND_DISABLE and sets E_SOUND_DEVIcE in the current sound flags: see the description of the 
p_getsnd and p_setsnd routines in the PLIB reference manual for details. 


Attempts to open a channel to the sound device (snp: ) and on success writes the handle of the sound 
channel to peb. On failure restores the sound flags to their original state, calls hinfoprint with an 
argument of -sys_sounD_Fart and then calls p_leave with an argument of 
RUN_ACTIVE_CLEANUP_NONOTIFY. 


Makes an asynchronous request to the sound channel to play the tone specified by keycode using the 
timing paramters stored in the psx environment variable - these are the system wide timing parameters and 
are stored in the form of an E_pzat struct. Details of the z_pzax struct may be found in the Sound chapter 
of the I/O Devices Reference manual. 


Closes the sound channel and restores the sound flags to their original state. 


Returns wN_KEY_CHANGED. 


LG 


INT lg_sense_width (VOID) ; 


se lodger width 


Sense the width in pixels of the lodger window. 


Returns WR_MAX_DIAL_STRING multiplied by the maximum width of a character in the system font. 


17-8 


17 DIALLING DIALOGS 


FDIALDLG 


flags item count dialao 
id rbuf current 
dimrid underline 
helprid absorb 
flags changed 
destrey wn-draw destroy dl_item_replace dl_set_size| ||dl_key 


wn_calc_position |wn—emphasise wn_key dl_item_append 


wn_emphasise dl_init 


wn_sense_help dl_dimmed_message 


wn_set dl_item_add 
wn_sense di—set—size 


wn_position wn_draw di_ing minsize 
di_item_lock dl_dyn_init 
dl_item_dim di_key 


dl_set_item_flags 


wn_redraw 


wh-sense—heip 


wn_visible 


al_set_prompt dl_changed 


dl_take_focus dl_focus 
dl_handle_to_index dl_launch_sub 
dl_index_to_handle dl_item_new 


The FDIALDLc class provides a dialog that supports free-form tone dialling. An example of a rp1atptc is 
shown in the following picture: 


Free-form dialling 


Redial 


Cea = 


where the second item in the dialog is a FREEFoRM control as described in the previous section. 


Class diagram 


.. eee orn a ao Sricioes gern Mente Pain bs . 
> . ee’ por ’ see eee 


/ win “7 bwin; / dlgchain —_’ digbox™; = / dialdig™-_” fdialdig™> 
t—. +, — \ 


Ris 1 


ion oe 
eres 


/ dialao ~> 


Class definition 
Defined in sub-category file dialdlgs.cl (generated header file dialdlgs.g). 


CLASS fdialdlg dialdlg 
dialog for freeform dial 


{ 


REPLACE di_key 


} 


Property 
None. 


17-9 


HWIM REFERENCE 
aS eee 


Resources 


Defined in system resource file s_rss. 


RESOURCE ACLIST_ARRAY sys_freedial_aclist 


{ 


button = 

{ 

PUSH_BUT 
{ 
keycode=W_KEY_DELETE_LEFT; 
str="Clear"; 
} ' 

PUSH_B 
{ 
keycode=W_KEY_ TAB; 
str="Redial"; 
} 

}; 


}RESOURCE DIALOG sys_freedial_dialog 
{ 
title="Free-form dialling"; 
flags = DLGBOX_NO_WAIT|DLGBOX_NO_DDP; 
controls= 
{ 
CONTROL 
{ 
class=C_FREEDIAL; 
prompt=<WS_ SYMBOL PHONE>; 
} ’ 
CONTROL 
{ 
class=C_ACLIST; 
info=ACLIST 
{ 
vid=sys_freedial_aclist; 


}; 


a ee ae a ee eee 
FDIALDLG methods 


INT dl_key(INT id, INT keycode) ; 
Handle a keypress. 
If keycode is W_KEY_DELETE LEFT: 


¢ if freedial current is equal to wR_MAX_DIAL_STRING, resets the dialling string by writing an 
underscore character to the first wR_MAX_DIAL_sTRING elements of freedial.str and writing zero 
to freedial.current. 


¢ draws the reset dial string by sending an L¢_uppaTE message to the FREEDIAL item with index one. 
e returns WN_KEY_NO_ CHANGE. 
If keycode is mot W_KEY_TAB, retumms WN_KEY_NO CHANGE. 


Clears £_souND_DISABLE and sets E_SOUND_DEVICE in the current sound flags: see the description of the 
p_getsnd and p_setsnd routines in the PLIB reference manual for details. 


Attempts to open a channel to the sound device and on success writes the handle of the sound channel to 
peb. On failure restores the sound flags to their original state, calls hinfoprint with an argument of 
-SY¥S_SOUND_FAIL and calls p_leave with an argument of RUN_ACTIVE_CLEANUP_NONOTIFY. 


eee 
17-10 


17 DIALLING DIALOGS 


The dialling string is stored in dlgbox.item(1] .hand->freedial.str whilst its langth is stored in 
dlgbox.item(1) .hand->freedial.current. 


If the length of the dialling string is one or zero, makes an asynchronous request to the sound channel to 
play the dialling sequence. 


Otherwise plays the dialling sequence, whilst ensuring that the user may at any time cancel the playing, as 
follows: 


e disables exit and task switch messages by entersending a ws_LocK message to w_ws. 
® sends an AO_QUEVE message to dialdlg.dialao. 
e removes the extra level of locking by sending ws_Lock message to w_ws. 


In either case the timing parameters are read from the psx environment variable - this contains the system 
timing parameters stored in the form of an £_prax struct. 


Closes the snp: channel and restores the sound flags to their original state. 
Calls £_leave: the argument is either zero or the return value from the ws_Locx entersend. 


Returns WN_KEY_NO_CHANGE. 


CNTRYDLG 


flags next item count 
id rbuf current 
dimrid underline 
helprid absorb 
changed 
destroy wa-draw 


destroy dl_item_replace 
wn_key dl_item_append 
wn_emphasise dl_init 
wn_sense_help dl_dimmed_message 
wn_set dl_item_add 
wn_sense dl_set_size 


CNTRYDLG 


dl_key 


wn_calc_ position |wnh-emphasise 


wn_position wn_draw dl_ing_minsize 
wn_redraw dl_item_lock dal_dyn_init 
wh—-sense—heip dl_item_dim di-key 


wn_visible dl_set_item_flags 

dl_set_prompt dl_changed 
dl_take_focus dl_focus 
dl_handle_to_index dl_launch_sub 


di_index_to_ handle dl_item_new 


The cyrryb.c class allows the user to select a country from the extensive list stored in the World database. 
An example country selector dialog is shown in the following picture: 


Append country 
¢ Izbekistan> 


Append 


PaaS 


The second item in the dialog is a wwpsELwn control which supports selection using the arrow keys or via 
incremental matching. Further details of the wLpseLwn class may be found in the Incremental Matchers 
chapter of the HWIM Reference manual. 


17-11 


HWIM REFERENCE 
TT n— ees 


Class diagram 


Class definition 
Defined in sub-category file dialdlgs.cl (generated header file dialdlgs.g). 


CLASS cntrydlg digbox 


REPLACE dl_key 


} 


Property 
None. 


Resources 


RESOURCE ACLIST_ARRAY sys_append_aclist 
{ 
button = 
{ 
PUSH_BUT 
{ 
keycode=W_KEY RETURN; 
str="Append"; 
} 
}; 
} 


RESOURCE DIALOG sys_country_selector_dialog 
{ 
title="Append country"; 
flags=DLGBOX_NOTIFY_ENTER|DLGBOX_ACTION_LIST|DLGBOX_RBUF_FILLED; 
controls= 


{ 


CONTROL 


{ 


class=C_WLDSELWN; 

prompt="Country"; 

info=WLDSELWN {flags=IN_WLDSELWN_COUNTRY | IN_WLDSELWN_SETHOME; }; 
}, 


CONTROL 


{ 
class=C_ACLIST; 
info=ACLIST 


{ 


rid=sys_append_aclist; 


}; 


i a Se en a 
CNTRYDLG methods 


_ Handle key 


INT dl_key(INT id, INT key); 
Senses the name of the country selected in the w.psELwn control with index one. 


Senses the wLDSELwn dialog control with index one and writes the name of the selected country to 
digbox.rbuf - the name is enclosed in square brackets with a leading space asfollows " [Germany]". 


Returns WN_KEY_CHANGED. 


— eee 


17-12 


17 DIALLING DIALOGS 


SDIALDLG 


flags next item count 

id rbuf current 
dimrid underline 
helprid absorb 
flags changed 

destroy watdraw 


DIALDLG 


dialao 


destroy dl_item_replace dl_set_size 


wn_key dl_item_append 


wn_emphasise dl_init 


wn_sense_help al_dimmed_message 
wn_set di—item—add 
wn_sense di—set—size 
wn_draw dl_ing_ minsize 
dl_item_lock 4i—dyn—init 
dl_item_dim di—tey 
dl_set_item_flags 


wn_position 
wn_redraw 


wn-sense—heip 


wn_visible 


d@l_set_prompt dl_changed 
di_take_focus dl_focus 

dl_handle_to_index dl_launch_sub 
dl_index_to_handle dl_item_new 


The spra.pic class supports tone dialling, editing of dial strings, and free-form tone dialling. An example 
SDIALDLG dialog is shown in the following picture: 


Dial 


4815218521 
‘'R 6712196189 
Cancel Free input Dial Dial out 


SS Ge Ges Ee) 


Note that pressing the menu key launches an rpraupic dialog as described in an earlier section of this 
chapter. 


On the Series 3a and the Workabout the Dial dialog may contain up to six dial items - i.e. phone numbers - 
whilst on the Series 3 it may contain up to four dial items. 


Class diagram 


ant, ea ane 


/ no} “ bwin 3 |/digchain> “ digbox + / dialdig > _” sdialdig > 
S) 3K, i. ~—. eee Mee i 


‘ eed 1 es ‘ ert! 4 Lorne ¢ i es teem meee! 7 


‘i = 


/ dialao ~s 


Bantonk [renee - [or ee 


Class definition 
Defined in the sub-category file dialdigs.cl (generated header file dialdlgs.g). 


CLASS sdialdlg dialdlg 
{ 
REPLACE dl_item_add 
REPLACE dl_dyn_init 
REPLACE dl_key 


17 - 13 


HWIM REFERENCE 
ESS 


CONSTANTS 
{ 
PAN_TONE_LENGTH_TICKS 4 
PAN_DELAY _LENGTH_TICKS 4 
PAN_PAUSE_LENGTH_TICKS 32 
PC_TONE_LENGTH_TICKS 6 
PC_DELAY_LENGTH TICKS 4 
PC_PAUSE_LENGTH_TICKS 18 
SMART_DIAL_MAX_PROMPT 11 /* max prompt length */ 


} 


TYPES 
{ 


typedef struct 


{ 


TEXT pmt [SMART_DIAL_MAX PROMPT+1] ; 
TEXT str {WR_MAX_IN_STRING+2] ; 
} SMART DIAL ITEM; 

typedef struct 


{ 


WORD count; how many separate numbers 
SMART_DIAL_ ITEM it [DLGBOX_MAX_ITEM-3] ; 
} SMART_DIAL_DATA; 

typedef struct 


{ 

WORD count; equals 1 

SMART_DIAL ITEM it; 

} SMART_DIAL_DATA_S; uses less stack than SMART_DIAL DATA 


typedef struct 


{ 


UWORD toneLengthTicks; 

UWORD delayLengthTicks; 

UWORD pauseLengthTicks; 

UBYTE dialoOutCode [6] ; to access an external line 
} DIAL_ENVAR; 


} 


Note: on the Series 3 some of the constants are assigned slightly different values. The Series 3 versions are 
as follows: 


PAN_TONE_LENGTH_TICKS 8 
PAN_DELAY_LENGTH TICKS 8 
PAN_PAUSE_LENGTH TICKS 48 


Property 
None. 


Resources 


Defined in the system resource file s_rss. 


RESOURCE CONTROL sys_smart_dial_item 
{ 
class=C_EDWIN; 
prompt=<WS_SYMBOL_PHONE>; 
info=EDWIN 


{ 


maxlen=WR_MAX_DIAL_ STRING; 
vulen=20; 
flags=IN_EDWIN_VULEN_CHARACTERS | IN_EDWIN_NO_AUTOSELECT; 


}; 


17-14 


17 DIALLING DIALOGS 


RESOURCE ACLIST_ ARRAY sys_smart_dial_aclist 
{ 
button = 
{ 
PUSH_BUT 
{ 
keycode=W_KEY_ESCAPE; 
str="Cancel"; 
}, 
PUSH_BUT 
{ 
keycode=W_KEY_ MENU; 
str="Free input"; 
} ' 
PUSH_BUT 
{ 
keycode=W_KEY_ TAB; 
str="Dial"; 
} # 
PUSH_BUT 
{ 
keycode=W_KEY_RETURN; 
str="Dial out"; 
} 
}i 
} 


RESOURCE DIALOG sys_smart_dial_dialog 
{ 
flags=DLGBOX_NOTIFY_ENTER | DLGBOX_ACTION_LIST|DLGBOX_RBUF_ FILLED; 
controls= 
{ 
CONTROL 
{ 
class=C_TEXTWIN; 
flags=DLGBOX_ITEM_CENTRE | DLGBOX_ITEM_DEAD |DLGBOX_ITEM_UNDERLINED; 
info=TXTMESS; 
{ 
flags=IN_TEXTWIN_AL CENTRE; 
str="Dial"; 
}; 
} ’ 
CONTROL 
{ 
class=C_ACLIST; 
info=ACLIST 
{ 
rid=sys_smart_dial_aclist; 


}; 


SDIALDLG methods 
DL_ITEM_ADD _ Add one or m 


INT dl_item_add(AD_DLGBOX *par); 


0 the dialog 


Add one or more items to the dialog. 


If dlgbox.count is non-zero, adds an item to the dialog by sending seif a pL_ITEM_ADD message with an 
argument of par - this item must specify an appropriate action list. Returns. 


If dlgbox .rbuf->count is greater than six on the Series 3a or four on the Series 3, then set it equal to either 
six or four respectively. 


17-15 


HWIM REFERENCE 


If dlgbox. rbuf->count is less than than six on the Series 3a or four on the Series3, adds the first item 
which must specify a title to the dialog by sending se1f a pL_ITEM_ADD message with an argument of par. 


Adds digbox.rbuf->count EDWIN controls by sending digbox. rbuf->count DL_ITEM_APPEND messages to 
self with an argument of -sys_SMART DIAL ITEM. 


VOID dl_dyn_init (VOID); 
Initialise the content of the dialog controls. 


Note that the digbox.xbuf property must point to either a sMaRT_DIAL_ pata struct, or a 
SMART_DIAL_DATA_s struct followed by zero or more sMART_DIAL_rTeEM structs, containing the initialisation 
data. 


The sMART_DIAL_pata struct is defined as follows: 
typedef struct 
ee count; 
SMART_DIAL_ITEM it [DLGBOX_MAX_ITEM-3]; 
} SMART_DIAL DATA; 
The significance of the members of the smart_pzaL_pata struct is as follows: 
count the number of smart dial items in the dialog. 
it an array of sMART_DIAL_1ITEM structs which stores the data required by the smart dial items. 
The sMART_DIAL_ITEM struct is defined as follows: 
typedef struct 


{ 


char pmt [SMART _DIAL MAX _PROMPT+1] ; 

char str {WR_MAX_IN_STRING+2] ; 

} SMART_DIAL ITEM; 
The significance of the members of the smarT_pIAL_1TeEM struct is as follows: 
pmt the prompt text for the smart dial item - stored as a zero terminated string. 
str the dialling string stored as a zero terminated string. 


The dialling string may contain, the digits 0 to 9, upper or lower case alphabetic characters in 
the range A to F, the characters # (0x23) and * (0x2A) which are converted to F and E 
respectively and space and comma characters which are interpreted as pauses while dialling. 


A space followed by the name of a country enclosed in square brackets e.g. [Germany] may be 
appended to the dialling string - e.g. 41 35 25 84 [France] - in place of the country code. 


Opens a channel to the World database and for each smarT_p1AL_rvTem item in the sMaRT_praL pata struct: 


¢ converts the str member into a dialling string using the World database wR_GET_DIAL_STRING 
service. 


e if the conversion succeeds, sets the dialling string into an epwrn control - the order of the 
SMART_DIAL_ITEm structs matches the order of the EDwrn controls. 


e if conversion fails, sets the text in the sys_INVALID_NuM resource into the corresponding EDWIN 
control and ensures that pLGBox_ITEM_DEAD is set in the control flags. 


SS ”FF”—e———“ “ROU 
INT dl_key(INT id, INT keycode) ; 

Handle a keypress. 

If one of the dialog control holds keyboard focus - i.e. dlgbox. focus is non-zero: 


e obtains a dialling string by sensing the content of the epwzn control with index id. 


17 - 16 


17 DIALLING DIALOGS 


Otherwise if keycode is either W_KEY_RETURN OF W_KEY_TAB: 


calls hInfoPrint with an argument of -sys_INVALID_Num and returns WN_KEY_NO_CHANGE. 


If keycode is W_KEY_MENU, Creates, initialises and makes visible the free-form dialling dialog by sending a 
WS_FREE_DIAL message to w_ws and then returns wN_KEY_NO_CHANGE. 


If keycode is either w_KEY_RETURN OF W_KEY_Tas, tone dials the dialling string as follows: 


if keycode is W_KEY_RETURN, prepends the content of the sys_pIAL_our system resource to the 
dialling string - this defines the dial-out code. 


clears —_SOUND_DISABLE and sets E_SOUND_DEVIcE in the current sound flags: see the description 
of the p_getsnd and p_setsnd routines in the PLIB reference manual for details. 


attempts to open a channel to the sound device and on success writes the handle of the sound 
channel to pcb. On failure restores the sound flags to their original state, calls htnfoprint with an 
argument of -sys_sounD_FAIL and calls p leave with an argument of 
RUN_ACTIVE_CLEANUP_NONOTIFY. 


if the length of the dialling string is one or zero, makes an asynchronous request to the sound 
channel to play the dialling sequence. 


otherwise, disables exit and task switch messages by entersending a ws_LocK message to w_ws, 
plays the tone sequence for the dialling string by sending an ao_QuEvE message to 
dialdig.dialao and removes the extra level of locking by sending a ws_Lock message to w_ws. 


in either case the timing parameters are read from the psx environment variable - this contains the 
system timing parameters stored in the form of an £_prat struct. 


closes the swp: channel and restores the sound flags to their original state. 


calls £ leave: the argument is either zero or the return value from the ws_Locx entersend. 


If keycode is W_KEY_ESCAPE: 


returns WN_KEY_CHANGED. 


17-17 


CHAPTER 18 


HELP CLASSES 


This chapter describes the HELPLIsT and HELPDLG classes that support the built-in help mechanism: note 
that these classes are described for interest only since the help mechanism is managed by the system. It is 
thus unlikely that an application would directly use either class. 


The first level of help list may be obtained by simply pressing the Help key and usually contains just a title 
and a list of help topics as illustrated in the following picture: 


Help: first example 


A second level of help list may be obtained from the first level by selecting a topic (with the exception of 
the index topic) and pressing the Return key. The second level of help list usually includes a title and one 
or more lines of text as illustrated in the following picture: 


Help: Mainframes 


>This help screen displays information 
about the mainframes topic. 


It may also include a list of topics thus allowing the user to progress to a third level. 


An index help list is a special form of help list and may be obtained by selecting the index topic and 
pressing Return. It contains a title and a list of system and application help topics. The topics are sorted 
alphabetically as illustrated in the following example: 


Help: Index 
»Mainframes 
*Menu/dialog tips 
=Micros 


«No system memory 
«On/off 
=Printing/print preview 


l=sjcreen display 


The content of the help lists is defined by the help resources in the application's resource file. The ID of the 
first such resource must be written to the wserv.help_index_id property of the wserv object. This may be 
conveniently done in the di_dyn_init method of the wserv object as follows: 


wserv.help_index_id=FIRST_EXAMPLE_HELP; 


An application can also provide context sensitive help by simply re-setting the wserv.help_index_id 
property as and when required. 


18-1 


HWIM REFERENCE 
Sv SSS 


The structure of the help resources is perhaps best illustrated by an example. The resources described in the 
following paragraphs (with one exception) were used to create the help lists shown above. 


The content of each help list is specified by means of a HELP_ARRay resource. The following example is for 
the first help list illustrated earlier and specifies the title with the topic member, and the list of topics with 


the topic_id member: 


RESOURCE HELP_ARRAY first_example_help 


{ 


topic="first example"; /* title text */ 
topic_id=example_index; /* id of topic array */ 


} 


A later example also includes some lines of text that appear between the title and the topic list: the lines of 
text are specified with the str1st member as follows: 


RESOURCE HELP_ARRAY second_example_help 


{ 


topic="second example"; /* title text */ 
topic_id=example_index; /* id of topic array */ 
strist= 

{ 


STRING {"One or more lines of text may";}, 
STRING {"preceed the bulleted items.";} 


i 


} 


The topic_id member always contains the ID of a roprc_array resource: the TOPIC_aRRay that was used 
for the first example shown earlier is as follows: 


RESOURCE TOPIC_ARRAY example_index 

{ 

id_ist= 
{ 
example_main_frames, /* ids for help screens */ 
example minis, 
example_micros 
} 

} 


The resource simply contains a list of HELP_ARRay IDs each of which defines a futher topic help list: the 
HELP_ARRAY resources for the example Topzc_ARRAY resource shown above are as follows: 


RESOURCE HELP_ARRAY example _main_frames 
{ 
topic="Mainframes"; 
strlst= 


{ 


STRING (str="This help screen displays information"; }, 
STRING {str="about the mainframes topic.";} 
} 

} 


RESOURCE HELP_ARRAY example_minis 


topic="Minis"; 
strlst= 


{ 


STRING {str="This help screen displays information";}, 
STRING {str="about the minis topic.";} 


} 


18-2 


18 HELP CLASSES 
a SSSSSSSSSSSeSSeSSsSSeSeeeeeeee EER ASSES 


RESOURCE HELP ARRAY example micros 


topic="Micros"; 
topic_id=example_micros_index; 
strist= 


{ 


STRING {str="This help screen displays information"; }, 
STRING {str="about the micros topic.";} 
} 

} 


Usually the help mechanism is used with only two levels of help list. However there is nothing preventing 
the inclusion of further levels if desired: this is illustrated by the help list defined by the above 
example_micros HELP_ARRAY resource which includes a list of topics specified by the 
example_micros_index TOPIC_ARRAY as follows: 


RESOURCE TOPIC_ARRAY example_micros_index 


{ 

id_ist= 
{ 
example_micros_386, 
example_micros_486 


} 
} 


The topics in this list are in turn defined by the following three HELP_ARRAY resources: 


RESOURCE HELP_ARRAY example_micros_386 


{ 


topic="386 micros"; 
strlst= 


{ 
STRING {str="Some text describing the";}, 
STRING {str="386 processor goes here."; } 


} 
} 


RESOURCE HELP_ARRAY example_micros_486 


{ 


topic="486 micros"; 
strlst= 


{ 
STRING {str="Some text describing the";}, 
STRING {str="486 processor goes here."; } 


} 
} 


Precursors 
Familiarity with the following topics will aid the understanding of this chapter: 


e the wserv object described in the The WSERV Class chapter. 

e the wrn and swrn classes described in the Windows chapter. 

e the LrsTsox class described in the List Boxes and Menus chapter. 

e the variart and vastr classes described in the OLIB Reference manual. 


e the vmarcuer class described in the Incremental Matchers chapter. 


18-3 


HWIM REFERENCE 


HELPLIST 


wn_calec_position 
wn_connect 
wn_dodraw 


wn_position 
wn_redraw 
wn_sense_help 
wn_visible 


wn_set 
wn_sense 


HELPLIST 


list 
ids 

firsttop 
title 


match 
va 

flags 
width 
matchien 
curofft 
offset 
current 
top 
first 
last 
vastart 
matchstart 


destroy wn_init 
ind wn_key 
ib_draw_item 

lb_draw_emphasis 
1ib_inquire_item 
1b_item_width 


wn_draw 


wn_emphasise 


1b_size_window 
lb_item_width 
lb_take_focus 
1b_inquire_focus 
13 ives 
1lb_inquire_last 


The HELPLIsT class may be used to create a help list containing a title, zero or more lines of text and a list 
of zero or more topics. An example help list is shown in the following picture: 


Help: Second example 
>One or more lines of text may 
preceed the bulleted items. 
«Mainframes 


The help list always has a title - in this case "Help: Second example”. The title always starts with "Help:". 


The help list may include zero or more lines of unbulleted text: these simply provide useful information as 
illustrated by the second and third lines in the above example. 


The help list may also include a list of one or more bulleted topics as illustrated by lines four to eight 
inclusive in the above example. The user may obtain further information in the form of a help list on a 
specific topic simply by pressing the Enter key. 


18-4 


18 HELP CLASSES 


EE 


Class diagram 


= | 4 vaflat > 
ons, 4 Weep oot, ‘ t 
(ona Loney 4 aes i { 
eer ¥ ~ \ 


e rs vmatche rT : 


af 
YO ete ee 
’ ri 1 Bd 
‘ See 
a 1 " 


a4 / helplist ~> 


Class definition 
Defined in sub-category file help.cl (generated header file help.g). 


CLASS helplist listbox 
Help topic and topic text list 
{ 
REPLACE wn_init 
REPLACE wn_key 
REPLACE lb _draw_item 
REPLACE lb draw_emphasis 
REPLACE 1b inquire_item 
REPLACE lb item width 


TYPES 
{ 


typedef struct 


{ 

UWORD topic_id; 

TEXT topic(1]; 2TS string followed by UBYTE count of ids 
} HELP_RSC; 


} 


PROPERTY 2 
{ 
PR_VASTR *list; Text for list 
PR_VAFLAT *ids; Resource ids for list 
UWORD firsttop; Index of first related topic 
TEXT title [50]; 


} 


18-5 


HWIM REFERENCE 
oa eeSeSSSSSSSSSSSSSSSSShFeeeeee 


Property 

helplist.list this stores the handle of an instance of the vastr class. The records contains the 
lines of text that follow the help list title. There is one record per line of text. 

helplist.ids this stores the handle of an instance of the vartat class. The records contain the 


IDs of HELP_ARRAY resources associated with the topics. When the user selects a 
topic and presses the return key, a help list appears. The associated HELP_ARRAY 
resource defines the content of the topic help list. 


helplist.firsttop this is an index into the helplist .1ist array of the record corresponding to the 
first topic. 


helplist.title this is the help list title text and is stored as a zero terminated string. 


SS SS SE Se ES ae ee 
HELPLIST methods 


VOID wn_init(INT start_id); 


Initialise the help list specified by the HELP_aRRay resource with ID start_id. 


The content and appearance of a help list is specified by means of a HELP_arRRay resource defined in 
hwim.rh as follows: 


RESOURCE HELP_ARRAY 


{ 

LINK topic_id=0; /* TOPIC_ARRAY id */ 
TEXT topic; /* title text +*/ 

LEN BYTE STRUCT strist[]; /* list of STRINGs */ 


} 


The significance of the members of the HELP_array resource is as follows: 


topic_id this member specifies the ID of a roprc_array resource: this resource contains a list of 
HELP_ARRAY resource IDs each of which defines a topic in the topic list. 


This member may be set to sys_HELP_1nDEx_pata for an index help list: i.e a help list 
containing application and system help topics ordered alphabetically which may be 
selected using incremental matching. 


This member may be ignored. 
topic this member specifies the title text e.g. "Word basics". 


strist this member is an array of sTRING resources: these define the lines of informative text that 
appear immediately beneath the title. 


This member may be ignored. 
The Toprc_array resource is defined in hwim.rh as follows: 
RESOURCE TOPIC ARRAY 
‘5 BYTE LINK id_lst[]; 


} 


The significance of the members of the roprc_array resource is as follows: 


id_ist this member is an array containing one or more HELP_aRRay resource IDs: each HELP_ARRAY 
resource defines the content and appearance of a topic help list. 


Creates the title from the sys_HELP_sTRiNG format string resource and the text specified by the topic 
member of the start_id resource. 


Creates an instance of the vastr class and writes its handle to helplist.1list. linitialises the vasTR 
component by sending a va_1nrIT message to helplist .list specifying a granularity of 16. 


eee 
18 -6 


18 HELP CLASSES 


Creates an instance of the varzat class and writes its handle to filelist.ids. Initialises the varLat 
instance by sending a va_in1T message to helplist .ids specifying a record length of two anda 
granularity of sixteen. 


If the topic_id member of the start_id resource is equal to sys_HELP_INDEX_DATA: 


e creates an instance of the vmarcuer class and writes its handle to 1istbox.match. Initialises the 
VMATCHER component by sending an IM_INIT message with suitable arguments. 


e loads the topics specified by the sys_HELP_INDEX_DATA system resource and then adds records to 
the helplist.list and helplist.ids arrays 


e — loads the topics in the application topic list: the wserv.help_index_id property of the wsERV 
object is assumed to specify the application help resource ID. 


Otherwise creates an unsorted help list: 


e loads the str1Nc resources specified by the start_id resource and adds the text to the 
helplist.list alray. 


e — loads the topics specified by the topic_ia member of the start_id resource and then adds 
records to the helplist.list and helplist.ids arrays. 


e ifwserv. flags does not contain pR_WSERV_BASIC_HELP, add the topics specified by the 
SYS_HELP_X_HELP system resource. This includes only the About Help topic. 


e ifwserv.flags does not contain pR_WSERV_HELP_INDEX, add the topics specified by the 
SYS_HELP_X_INDEX system resource. This includes only the Index topic. 


Writes unity to listbox. current and listbox. first. 
Writes an appropriate value to helplist. first. 


Writes the index of the last item in the help list help1ist .1ast. The index of the last item is obtained by 
sending a vA_CouNnT message to helplist.list. 


Sends an LB_SIzE_WINDow message to self with an argument of zero. 


_ Handle keys 


VOID wn_key(INT keycode, INT modifiers) ; 


Handle a keypress. 


If keycode is W_KEY_RETURN and listbox.current is greater than or equal to helplist.. firsttop, 
launches a help list for the selected topic by sending a ws_po_HELP message to the wsErv object. 


Otherwise supersends a wN_KEY message with arguments of keycode and modifiers. 


LB_INQUIRE_IT 


TEXT *lb inquire_item(INT index) ; 


Get item text 


Return a pointer to the text for the item at line index. 
If index is zero, return the address of the first character in the helplist .title property. 


Otherwise, return the address of the appropriate record in the helplist. list array. 


Get width of item 
INT lb_item_width(INT index) ; 
Return the width of the help list item at line index. 


The item width includes the left margin and the width of the text, obtained by sending self a 
LB_INQUIRE_ITEM message. 


18-7 


HWIM REFERENCE 


LE 


VOID 1b_draw_item(TEXT *text,INT index, P RECT *area) ; 


Format and draw an item 


Draw the item with index index in the box specified by area with text specified by text. 


If index is zero, the text is drawn in a bold font, with centre alignment, and a left margin of width 
LISTBOX_OBLOID_INDENT. 


If index is greater than or equal to helplist . firsttop, the text is drawn in a bold font, with left aligment 
and a left margin. A bullet character is inserted before the text. 


Otherwise, the text is drawn in a system font, with left aligment and a left margin. 


for remove emphasis on item 
VOID lb_draw_emphasis(INT index,P_RECT *area,INT flag); 
Emphasise or de-emphasise the item with index index. 


If index is greater than or equal to helplist..£irsttop, the bullet character and the text are drawn in white 
on a black background. In this case area.t1 should specify the top left corner of the item box. 


If index is less than helplist .f£irsttop and flag is rrue, emphasise the item by drawing a right arrow in 
the left gutter. Otherwise de-emphasise the item by clearing the right arrow from the left gutter. 


In either case area should specify the rectangle that encloses the item including the left margin. 


HELPDLG 


HELPDLG 


inal 


destroy 
wn_init 
wn_key 

wn_emphasise 
wn_visible 


wn_calc_position 
wn_connect 
wn_dodraw 


whremphasise 
wrrkey 


wn_position 
wn_redraw 


wh-sense—heip 


visible 


wn_set 

wn_sense 

wrhrdrayw 
en 


The description of this class is included for completeness and interest only. 


18-8 


18 HELP CLASSES 
SSS HELP CLASSES 


Class diagram 


fe WI 
aa { 
~ } 
ar | 
, eee 2 
“bwin > 
é c 
ie ft 
~~ 1 
. ; 
\ oa 
” digchain °} / helplist > 
7 ‘ 7 f 
te H M H 
har } RSs 1 
H ne ; ace 
we) Boh 
pen See 
/ helpdig > 
t 


Class definition 
Defined in sub-category file help.cl (generated header file help.g). 


CLASS helpdlg dlgchain 
Help '‘dialog' 


REPLACE destroy 
REPLACE wn_init 
REPLACE wn_key 
REPLACE wn_emphasise 
REPLACE wn_visible 
PROPERTY 1 
{ 
PR_HELPLIST *listbox; 
} 
} 


Property 
helpdlg.listbox the handle of an instance of the nELPLisrt class. 


ae Ne FR SR a SE eS See eT 
HELPDLG methods 


dialog 
VOID destroy (VOID) ; 
Destroy the HELPDLc instance. 


If win. flags contains HELPDLG_BASIC_HELP, Clears PR_WSERV_BASIC_HELP from the wserv. flags property 
of the wserv object. These flags indicate that the highest level of help is the basic help dialog. 


Otherwise, if win. £1ags contains HELPDLG_HELP_INDEX, Clears PR_WSERV_HELP_INDEX from the 
wserv.flags property of the wseRv object. These flags indicate that the highest level of help is the help 
index dialog. 


If win. flags Contains PR_WIN_INITIALISED, removes the highest level of help dialog by sending a 
WS_REMOVE_DIAL message to the wsERV object with se1f as argument, and decrements the wserv .help 
property of the wserv object. 


Supersends a DesTRoy message. 


18-9 


HWIM REFERENCE 


WNSENET 7 oe Initialise help dialog 


VOID wn_init (INT start_id); 


Initialise the help dialog whose contents are specified by start_id. 


If start_id is SYs_HELP_ON_HELP, sets PR_WSERV_BASIC_HELP in the wserv. flags property of the wSERV 
object, and sets HELPDLG_BASIC_HELP in win. flags. 


Otherwise, if start_id is sys_HELP_ON_INDEX, sets PR_WSERV_HELP_INDEx in the wserv. flags property of 
the wseRv object, and sets HELPDLG_HELP_INDEX in win. flags. 


Sets PR_WIN_NO_DDP in win. flags, creates an instance of HELPLIST and writes its handle to 
helpdlg. listbox. Initialises the HELPLIST component by sending a wn_InIT message to helpdlg. listbox 
with an argument of start_id. 


e keys 


INT wn_key (INT keycode, INT modifiers) ; 
Handle a keypress. 


If keycode is W_KEY_ESCAPE, and modifiers contains the Control modifier, destroys all levels of help 
dialog by repeatedly sending a pEstRoy message to the wserv.dial property of the wserv object until its 
wserv.help property is zero. (See the description of the wsERv property for further details). 


If keycode is W_KEY_ESCAPE, and modifiers does not contain the Control modifier, destroys the highest 
level of help dialog by sending a pestroy message to the wsERV object wserv.dial property. 


If keycode is W_KEY_HELP, and modifiers does not contain the Control modifier, adds a help screen for the 
Help topic by sending a ws_po_p1aL message to the wseRv object with an argument of sys_HELP_ON_HELP. 
The method does nothing if the help screen is already present. 


If keycode is W_KEY_HELP, and modifiers contains the Control modifier, adds an index help list by sending 
a WS_DO_DIAL message to the wsERv object with an argument of sys_HELP_1nDEX. The method does nothing 
if the index help list is already the highest level. 


Otherwise, if keycode is none of the above, passes the keypress to the HELPLIST component by sending a 
WN_KEY message to helpdlg. listbox, passing arguments of keycode and modifiers. 


Returns wN_KEY_NO_CHANGE. 


VOID wn_emphasise(UINT flag); 


Emphasise the help dialog if flag is Truz, otherwise de-emphasise the help dialog. 


Sends a wN_EMPHASISE message with an argument of flag to helpdig. listbox. 


VOID wn_visible(UINT flag); 
Make the help dialog visible if ag is true, otherwise make it invisible. 


The method simply sends a wn_v1sIBLE message to helpdlg.1istbox with flag as the argument. 


18-10 


CHAPTER 19 


OPL AND COMMs SCRIPT SUPPORT 


This chapter describes the following classes: 
e the procrran class which may be used either to translate or to locate an error in a source module. 
e the procexec class which may be used to run a translated source module. 


e the procrinp class which may be used to locate either of the OPL or Comms script translator 
modules. 


In all cases the source module may contain either OPL code or Comms script commands. 


Precursors 
Familiarity with the following topics will aid the understanding of this chapter: 


e the acrive class described in the OLJB Reference manual. 


e the sERveR class described in the OLIB Reference manual. 


PROGTRAN 


sv_run 
pt_start 


Pt_getline 
pt_complete 


The pRocTRAN class may be used to translate either an OPL or a Comms script source module. The class 
supports both translation of the source file and the location of errors, if they exist. 


Class diagram 


[Tt wee? 


¢ /SENEr } _? Progtran Z 
————s 


nes \ ~~ ‘ 
. 


19-] 


HWIM REFERENCE 
eee SSE 


Class definition 
Defined in sub-category file program.cl (generated header file program.g). 


CLASS progtran server 


{ 


REPLACE sv_init Supersend with parameters 
REPLACE sv_run Process message 

ADD pt_start Start translation of a module 
DEFER pt_getline Get line of source 

DEFER pt_complete Report completion 

CONSTANTS 


{ 

! Message types 

PT_PROGTRAN_LINE 0x10 Get a line of source 
PT_PROGTRAN_DEATH 0x11 OPL translator death 


} 


TYPES 


{ 


typedef struct 


{ 


WORD stat; Completion status 
UWORD mode; Translation mode 
UWORD line; Line number 

UWORD offset; Offset to syntax error 


} PROGTRAN_STATUS; 
! Describes the source 
typedef struct 


{ 


UWORD pid; Process id of source 
TEXT *buffer offset; Offset of buffer in source process 
PROGTRAN_STATUS *status_offset; Offset of status block in source 
process 
} PROGTRAN_SOURCE; 
} 
PROPERTY 
{ 
PROGTRAN_STATUS st; 
TEXT buf [256]; line buffer 
} 
} 
Property 


progtran.st the translator process writes to this property: the significance of the members of the 
PROGTRAN_STATUs struct is as follows: 


stat the completion status code: on success this is zero and on failure it is the 
corresponding error number. 


mode the translation mode, which may be one of: 
FULL_TRANSLATE for translation of the source module. 
ERROR_LOCATIon to locate an error in an already translated source module, 
CHECK_TRANSLATION to check the source module without translating it. 


line the line number of the line of source that contains the error: this member is 
written to by the translator process on location of an error. 


offset the offset into the line of the error: this member is written to by the 
translator process on location of an error. 


progtran.buf the full file specification of the OPL module or Comms script file that is to be 
translated. 


19-2 


19 OPL AND COMMS SCRIPT SUPPORT 


Ee ee ee ee eee 
PROGTRAN methods 


SVINT : _ Initialise 
VOID sv_init (VOID) ; 
Initialise the message server. 


Sets PT_PROGTRAN_LINE and PT_PROGTRAN_DEATH as the allowed message types by supersending an 
SV_INIT message. 


SV BUN = = _ Process message 
VOID sv_run(MESS *pmsg) ; 
Process a message. 


If pmsg->type is PT_PROGTRAN_DEATH, frees the message slot with a reply of zero by calling p_mfree. 
Writes zero to server.cid and then sends self a PT_COMPLETE message. Returns. 


If pmsg->type is PT_PROGTRAN_LINE, gets the next line of source by sending self a PT_GETLINE message 
with pmsg->1ine as argument. Then frees the message slot by calling p_mfree. The reply sent via this call 
is the return value from the pt_GETLINE message. 


of a module 


INT pt_start (INT type,TEXT *pname,PROGTRAN STATUS *pstatus) ; 


Start translation of the source module specified by pname. The type argument should be set to either 'O' or 
'C' to translate OPL or Comms script source modules respectively. The pstatus argument should point to a 
progtran.status Struct. 


Copies the source file specification pointed to by pname into progtran. buf and then obtains the full file 
specification for the translator program by creating an instance of the procrinn class and sending an 
LS_SCAN message with type as the first argument. 


Copies the contents of the procTRAN_STATUs struct pointed to by pstatus into progtran.st. 


Sets the translator program running in a suspended state by calling p_execc with appropriate command line 
arguments. Writes the id of the translator process to server .cid and ensures that on abnormal termination 
of the translator process a PT_PROGTRAN_DEATH message is sent by calling p_logon. 


Sets the process running by calling p presume. 


Returns FALSE. 


Deferred PROGTRAN methods 


Get line of source 
INT pt_getline(UWORD line); 


Copy the line of the source file with index 1ine to the buffer with address progtran buf: the line argument 
is in the range zero to 32K. 


The replacement method should return either the number of bytes copied or = _FILE_Eor if there are no 
more lines of source. 


19-3 


HWIM REFERENCE 


PT_COM: 


VOID pt_complete (VOID) ; 


“Report completion 


This method is called by the sv_run method on abnormal termination of the translator process. 


If the translator process is being used to locate an error in the source module, then the line and offset 
elements of progtran.st give the location of the error. 


PROGEXEC 


result 


priority 
stat 
isactive 


destroy ao_init 
ao_init ao_cancel 
ao_cancel 

ao_abrun 

ao_queue 

ao_run 


The procexec class may be used to run either a translated OPL module or a translated Comms script 
module. 


Class diagram 


/ active ~} // Progexec > 


Class definition 
Defined in sub-category file program.cl (generated header file program.g). 


CLASS progexec active 
Runs a process of sys$prg?.img, handling inter process communication 
Completes when sysS$prg? terminates 


{ 


REPLACE ao_init Initialise and queue 
REPLACE ao_cancel so that destroy is clean 
CONSTANTS 
{ s 
PROGEXEC_SIGNAL 0x01 signal on completion 
PROGEXEC_NOTIFY 0x02 call notifier on error 


H_COMMAND_TRANSLATE FILE 'T' 
H_COMMAND_RUN_FILE 'R! 


} 


19-4 


19 OPL AND COMMS SCRIPT SUPPORT 
ee ANE CUMIMIS SCRIPT SUPPORT 


TYPES 
{ 


! Used to receive data from sys$prg?.img, on completion 
typedef struct 


{ 


WORD error; runtime error 

UWORD line; line no of start of proc containing 
runtime error 

UWORD offset; Q code offset to runtime error 

TEXT err [40]; runtime error string 

TEXT src[P_FNAMESIZE] ; to take source module name 


} PROGEXEC_RESBUF; 

! Used to pass parameters to sys$prg?.img in p_execc() 

typedef struct 
{ 
UWORD flags; mode information for sys$prg? 
UWORD pid; requestor process id 
PROGEXEC_RESBUF *result_offset; result buffer offset 
} PROGEXEC_PAR; 


} 


PROPERTY 
{ 
PROGEXEC_RESBUF result; to take result 
} 
} 
Property 
progexec.result the result buffer that on completion contains details of the run 


aS a a ae a eT 
PROGEXEC methods 


AQ_ 


VOID ao_init (INT type, INT flags,TEXT *pname) ; 


Initialise and queue 


Queue for running the translated file specified by pname. 

The following flags may be passed to the ao_init method: 

PROGEXEC_NOTIFY indicates that the translator is to create an alert or a notify on error 
PROGEXEC_SIGNAL indicates that the translator is to signal caller of error condition 
Copies the filename specified by pname to progtran. buf. 


Obtains the full file specification of the required translator program by creating an instance of the PROGFIND 
class and sending it an ns_scan message. 


Writes & _GEN_FAIL to progexec.result.error. 


Starts the translator running by calling p_execc under the protection of £_leave with appropriate command 
line arguments including the address of progexec. result and flags. 


If flags contains PROGEXEC_SIGNAL: 
® writes PRIORITY_ACTIVE_COMPUTE tO active.priority. 
e adds seif to the task queue by sending an am_aApD_TASK message to w_an. 


¢ requests asynchronous notification of the abnormal termination of the translator process by calling 
p_logona with the address of active.stat as argument. 


Otherwise sends self a DESTROY message. 


Sets the translator process in a running state by calling p presume. 


19-5 


HWIM REFERENCE 


AO_ CANCEL irminated 


VOID ao_cancel (VOID) ; 


Ensure termination of the translator process. 


If active.isactive is TRUE, Writes FALSE to active. isactive, terminates the translator process by calling 
p_pkill with an argument of active .pcb and then waits until the process terminates by calling 
p_waitstat with an argument of active.stat. 


Write zero to active .pcb. 


PROGFIND 


PROGFIND 


flags pbuf 
pcb 

pname 

match 

info 

name 

wildname 


1s_matchname is_scan 
is—sean is_filename 


The procFinp class may be used to locate either: 
e the OPL module translator with filename syssprco. IMG. 
e the Comms script module translator with filename syssprec. Mc. 


In either case the search starts in the Rom device and then continues in the mmc directory of each node on the 
Loc: : device until the required file is located. 


Class diagram 
fogs. 7 progfind 
XY f t ae 


~s 


Class definition 
Defined in sub-category file program.cl (generated header file program.g). 


CLASS progfind locs 
Find the SYS$PRG?.IMG program translator 


{ 


REPLACE ls_scan Start the scan off 
REPLACE 1ls_filename Local/Rom file system name found 
PROPERTY 
{ 
UBYTE *pbuf; Where match name is 
} 
} 
Property 
progfind.pbuf the full file specification of the located translator program. 


19 -6 


19 OPL AND COMMS SCRIPT SUPPORT 


ae ee ee TE 
PROGFIND methods 


LS_SCAN _C | | | Start the scan 


VOID ls_scan(INT type,UBYTE *pbuf); 


Search for the translator program specified by type and write its full file specification to the buffer at 
address pbuf 


A type of either 'O' or 'C’ indicates that the method is to search for the OPL module translator 
SYS$PRGO.IMG or the Comms script translator SYS$PRGC.IMG respectively. 


Initialises the result buffer by writing zero to progfind.pbuf. 
Searches for the required file by sending se1f an LS_FILENAME message. 


Terminates the scan by sending self a DESTROY message. 
LS FRENAME = = = © Fit m name found 


INT 1s_filename(UBYTE *pname) ; 


Write the name of the located translator file to the buffer specified by pname. 
Writes pname to progfind.pbuf. 
Stores the filename in property by copying p_rwamesizeE characters from 1ocs .name to progfind.pbuf. 


Returns TRUE. 


19-7 


CHAPTER 20 


INCREMENTAL MATCHERS 


This chapter describes classes associated with incremental matchers and the World database. These classes 
are: 


e the matcuer class which provides a common base class for the vmaTCHER and wMATCHER Classes. 


e the vmartcuer class which supports searching an alphabetically ordered sequence of variable length 
text records using incremental matching, exact matching and sequential access. 


e the wwatcuer class which supports searching the World database for matching cities and countries 
using incremental matching, exact matching and sequential access. 


e — the wupseLwn class which provides a choice list control for accessing information in the World 
database. 


Precursors 
Familiarity with the following topics will aid the understanding of this chapter: 


e _ the varoor and related classes described in the Variable Array Classes chapter of the OLIB 
Reference manual. 


e the Lopcer class described in the Windows chapter of the HWIM Reference manual. 
e the pieBox class described in the Dialog Boxes chapter of the HWIM Reference manual. 


e the Series 3 World application. 


MATCHER 


im_key 


im_init 
im_set_buf 
im_sense_buf 
im_set_val 


im_sense_val 
im_try_match 
im_transition 


The MATCHER class provides a common base class for the vmMaTCHER and wmatcuer classes described in later 
sections of this chapter. The class provides the basic functionality for record retrieval via incremental 
matching, exact matching and sequential access. 


20-1 


HWIM REFERENCE 
ESSE 


Class definition 


Defined in sub-category file matcher.cl (generated header file matcher. g)- 


CLASS matcher root 
{ 
DEFER im_init 
DEFER im_set_buf 
DEFER im_sense_buf 
DEFER im_set_val 
DEFER im_sense_val 
DEFER im_try_match 
DEFER im_transition 


ADD im_key 
CONSTANTS 
{ 
IM_NEW_LEN 1 
IM_NEW_DISPLAY 2 
IM_NO_CHANGE 3 
} 
PROPERTY 
{ 
TEXT *ptyped; Pointer to the typed string 
UBYTE *plen; Pointer to length byte 
} 
} 
Property 
matcher .ptyped a pointer to the zero terminated match string 
matcher .plen a pointer to the length of the match string 


SSS ee a ee eee 
MATCHER methods 


Handle key input 
INT im_key(INT keycode, INT modifiers) ; 
Handle a key input that might lead to a new current record. 


If keycode is W_KEY_DELETE_LEFT, removes the last character from the match string at address 
matcher .ptyped, and writes the length of the match string to the length byte at address matcher.plen. 
Locates a matching record by sending an 1m_TRY_mMATCH message to sel and then returns. 


If keycode is W_KEY_ESCAPE, resets the MATCHER instance by replacing the match string with won, and 
writing zero to the length byte at address matcher .pien. Returns IM_NEW_LEN. 


If keycode is either w_KEY_RIGHT, W_KEY_LEFT, W_KEY HOME or W_KEY_END, resets the MATCHER instance by 
replacing the match string with uu, and writing zero to the length byte at address matcher .plen. Sends 
an IM_TRANSITION message to self with keycode as the argument. Returns IM_NEW DISPLAY. 


Otherwise, if keycode is a printable non-control character, adds the character to the end of the match string, 
and increments the length byte at address matcher .plen. Attempts to locate a record matching the new 
match string by sending an 1M_TRY_MATCH message to self. If the return value from the IM_TRY_MATCH 
message is IM_NO_CHANGE, beeps, then restores the match string by removing the last character and 
decrementing the length byte at address matcher .plen and returns IM_NO_CHANGE. Otherwise returns the 
return value from the IM_TRY_MATCH message. 


20-2 


20 INCREMENTAL MATCHERS 


Deferred MATCHER methods 


VOID im_init(UBYTE *plen,UINT maxlen,PR_VAROOT *va) ; 


— Initialise 
Initialise the MATCHER instance. 


Allocate buffer space as required and initialise any property. 


INT im_set_buf (TEXT *str) ; 


Set the current record by locating a record that exactly matches the text specified by str. 


_. Sense current record data 


TEXT *im_sense_buf (VOID) ; 


Return the address of the current record. 


VOID im_set_val(UINT index) ; 


Set the current record by index: the records are assumed to be uniquely indexed. 


INT im_sense_val (VOID) ; 


Return the index of the current record. 


INT im_try_match(VOID) ; 


Locate a record that matches the match string at matcher. ptyped. 


The subclass would normally allow incremental matching whereby the first record whose initial text 
matches that at matcher.ptyped would be selected. The method returns the index of the matching record. 


IM_TRANSITION = =——i(asti‘(‘é‘ ‘é‘ééé Handle transition 


VOID im_transition(UINT type) ; 
Handle a keypress that might lead to the selection of a new current record. 


The subclass may wish to add extra functionality such as limiting the range of allowed records, adding an 
offset from which the matching commences, or restricting records to those terminating with the .pic 
extension, for example. 


20-3 


HWIM REFERENCE 


VMATCHER 


index 
first 
last 
txtoff 


destroy 
im_init 
im_set_buf 
im_sense_buf 
im_set_val 
im_sense_val 
im_try_match 
im_transition 
im_set_range 


The vMaTCHER class may be used to search an alphabetically ordered sequence of variable length text 
records. Incremental matching, exact matching and sequential access are supported. 


Examples of the use of the vwarcuer class may be found in the descriptions of the rneprt and cuLrst 
classes. 


Class diagram 


ae ot ae! ~ 


, ve 


7 Mmatcher™> = / vmatcher» 


Class definition 


Defined in sub-category file matcher.cl (generated header file matcher.g). 


CLASS vmatcher matcher 
Variable array matcher 
{ 
REPLACE destroy 
REPLACE im_init 
REPLACE im_set_buf 
REPLACE im_sense_buf ; 
REPLACE im_set_val 
REPLACE im_sense_val 
REPLACE im_try_match 
REPLACE im_transition 
ADD im_set_range 


PROPERTY 


{ 


PR_VAROOT *va; Handle of associated variable array 


UWORD index; Index into array of current match 
UWORD first; Index of first item in array to match 
UWORD last; Index of last item in array to match (0 = VA_COUNT-1) 


UWORD txtoff; Offset within buffer returned by pbuf to text 


} 
} 


Property 
vmatcher.va the handle of an array of variable length text records 


vmatcher. index the index of the current record 


vmatcher.first the index of the first record in the search range 


20-4 


20 INCREMENTAL MATCHERS 


vmatcher.last the index of the last record in the search range: a zero index indicates that the 
search is to extend to the last record in the array. 


vmatcher.txtoff an offset into each record from which the matching should commence. 


ES a a eS 
VMATCHER methods 


VOID destroy(PR_VMATCHER *self) ; 


Free the match string buffer at address matcher .ptyped and supersend a pesTRoY message. 


VOID im_init(UBYTE *plen, UINT maxlen,PR_VAROOT *va) ; 
Initialise the instance of vmaTcuER. 


Initialises the records by writing va to vmatcher. va, allocates at least maxlen bytes for the match string and 
writes the address of the first byte to matcher. ptyped. 


INT im_set_buf (TEXT *str) ; 


Locate the first record that exactly matches the text specified by str excluding records outside of the 
current range: see the description of the im_set_range method for details of the range. 


If a matching record is located, writes its index to vmatcher . index and return zero. 


Otherwise return -1. 


TEXT *im_sense_buf (VOID) ; 


Return the address of the current record data offset by vmatcher. txtofé. 


Obtains the address of the current record data by sending a va_pBur message to vmatcher.va with an 
argument of vmatcher. index. 


VOID im_set_val(UINT index) ; 


Set the current record by writing index to vmatcher. index. 


CL _. Sense current record 


INT im_sense_val (VOID) ; 


Sense the index of the current record: the method does no more than return vmatcher . index. 


20-5 


HWIM REFERENCE 


IM_TRY_MATCH | ent match 


INT im_try_match (VOID) ; 


Locate the first record that matches the text at address matcher .ptyped excluding records outside of the 
current range. See the description of the im_set_range method for details of the current range. The 
matching is case insensitive. 


Searches the records to locate the first one that matches the text at address matcher .ptyped. A matching 
record is found when the first 1en characters match those stored at address matcher .ptyped. The length 
len is read from address matcher .plen. 


If there is no matching record, returns IM_NO_CHANGE. 
If the matching record is the current record, and thus has index vmatcher . index, returns IM_NEW_LEN. 


Otherwise if the matching record is not the current record, makes it the current record by writing its index 
to vmatcher. index, and returns IM_NEW_DISPLAY. 


VOID im_transition(UINT keycode) ; 


Handle a keypress that might lead to the selection of a new current record. Only records in the range are 
considered: see the description of the im_set_range method for details of the range. 


If vmatcher.1ast is invalid as it is both non-zero and less than vmatcher . first, returns. 


If keycode is either W_KEY_RIGHT, Or W_KEY_Down, and the last record has not been reached, moves to the 
next record by incrementing vmatcher . index. 


If keycode is w_KEY_HoME, moves to the first record by writing vmatcher. first to vmatcher. index. 
If keycode is W_KEY_END, moves to the last record by writing its index to vmatcher . index. 


If type is either w_KEY_LEFT, or W_KEY_up, and the first record has not been reached, moves to the previous 
record by decrementing vmatcher. index. 


VOID im_set_range(UWORD first,UWORD last,UWORD txtoff); 


.. Set range 


Set the record range to start at the record with index first and to extend to either the record with index 
last or the last record in the array. Ensure that the matching starts at an offset into each record of txtof£, 
i.e. the first txtof£ characters are skipped when matching. 


Writes first to vmatcher. first, writes last to vmatcher. last and writes txtoff to vmatcher.txtoff. 


The record range extends either to the record with index vmatcher . last, or to the last record in the array if 
vmatcher. last is zero. 


20 - 6 


20 INCREMENTAL MATCHERS 


WMATCHER 


wfcb 
iscountry 
tleng 
tbuf 

res 

resco 


im_key im_destroy 
im_init 
im—inie im_set_val 
im_set_buf im_try_match 
im_sense_buf im_transition 


The wMaTCHER Class may be used to search the World database for matching cities or countries. Incremental 
and exact matching are supported as well as sequential access. An example of the use of the wmarcuer class 
is provided by the wLpsELwn class described in the following section of this chapter. Note that the wmaTcHER 
class does not support data retrieval: it simply provides a means of navigating the World database. 


Class diagram 


a ety omke, aan 
10 a ee ss! e ee’ ~ 


/ Matcher; wmatcher} 


Class definition 
Defined in sub-category file w/dselwn.cl (generated header file widselwn.g). 


CLASS wmatcher matcher 
{ 
REPLACE destroy 
REPLACE im_init 
REPLACE im_set_val 
REPLACE im_try_match 
REPLACE im_transition 


CONSTANTS 
{ 
GEOG_MAX_NAME 22 Actually 20 but room needed for trailing zero 
PR_WMATCHER_INDETERMINATE 0x02 Neither city nor country 
} 
PROPERTY 
{ 
VOID *wficb; Control block for world 
UBYTE iscountry; TRUE for country mode 
UBYTE tleng; The current typed length 
TEXT tbuf (GEOG_MAX_NAME] ; The current typed string 
WR_FIND_RES res; Holds latest result 
WORD resco; TRUE if restricted 
} 
} 
Property 
wmatcher .wfcb the handle of a channel to the World database: for details of the World 


database see the World chapter of the I/O Devices Reference manual. 


20-7 


HWIM REFERENCE 


wmatcher.iscountry TRUE to access countries: FALSE to access cities 

wmatcher.tleng the current length of the match string: this must not exceed WR_MAX_NAME 
wmatcher.tbuf a buffer holding the current match string 

wmatcher. res The wR_FIND_REs struct is defined as follows: 


typedef struct 


{ 

TEXT city [(WR_MAX_NAME+1] ; 
TEXT country [WR_MAX_NAME+1] ; 
} WR_FIND_RES; 


The city member specifies the name of the current city as a zero terminated 
string. 


The country member specifies the current country as a zero terminated 
string. 


wmatcher. resco TRUE if the search is restricted to cities within the current country 


WMATCHER methods 


Stroy 


VOID destroy (VOID) ; 


Destroy the wMarcner instance by closing the i/o channel specified in wmatcher.wfcb and supersending a 
destroy message. 


VOID im_init (VOID) ; 


Initialise the wMATCHER instance. 


Writes the address of the match string buffer to matcher .ptyped and writes the address of 
wmatcher.tleng tO matcher.plen. 


Opens an i/o channel to the World database and writes the handle of the channel to wmatcher.w£cb. Sets 
the current record to the first city in the database and writes the names of the city and the country in which 
the city resides to wmatcher.res. 


VOID im_set_val(WR_FIND_RES *match) ; 


Set the current record by an exact match to the city, or if this is sux, the country specified in the 
WR_FIND_RES Struct with address match. The matching is not case sensitive. 


The wR_FIND_REs struct is defined as follows: 
typedef struct 
{ 
TEXT city [WR_MAX_NAME+1] ; 
TEXT country (WR_MAX_NAME+1]) ; 
} WR_FIND_RES; 
The members of the wr_FinD_REs struct have the following significance: 
city either nut or the name of the target city specified as a zero terminated string. 
country either nun or the name of the target country specified as a zero terminated string. 


Ifa matching city is found, writes the names of the city and country in which the city resides to 
wmatcher.res and returns IM_NEW_DISPLAY. 


—- eS 
20-8 


20 INCREMENTAL MATCHERS 


If a matching country is found, writes the names of the country and its capital city to wmatcher.res and 
returns IM_NEW DISPLAY. 


Ifno matching record is found, returns 1m_No_CHANGE. 


IM_TRY_MATCH  ~—|/ | Try 


INT im_try_match (VOID) ; 


lligent match 


Set the current record to the first record that matches the current match string. The matching is not case 
sensitive. 


If wmatcher.tleng is greater than wR_MAX_NAME returns IM_NO_CHANGE. 


If wmatcher .iscountry is TRUE, searches for a matching country, writes the names of the country and its 
capital city to wmatcher.res and returns IM NEW_DISPLAY. 


If wmatcher .iscountry is FALSE, searches for a matching city, writes the names of the city and the country 
in which the city resides to wnatcher .res and returns IM_NEW DISPLAY. 


If no match is found, returns IM_NO_CHANGE. 


sition 
VOID im_transition(UINT keycode) ; 

Handle the keypress specified by keycode. 

If wmatcher. resco is TRUE, sets the current record to the next city in the current country and returns. 

If keycode is W_KEY_RIGHT, and wmatcher.iscountry is TRUE, sets the current record to the next country. 

If keycode is W_KEY_RIGHT, and wmatcher.iscountry is FALSE, Sets the current record to the next city. 


If keycode is W_KEY_LEFT, and wmatcher.iscountry is TRUE, sets the current record to the previous country 
and returns. 


If keycode is W_KEY_LEFT, and wmatcher.iscountry is FALSE, sets the current record to the previous city 
and returns. 


If keycode is W_KEY_HOME, sends an IM_TRY_MATCH message to self and returns. 


Otherwise, sends an IM_TRY_MATCH message to se1f. If wmatcher. country is TRUE, sets the current record 
to the previous country. If wmatcher. country is FALSE, sets the current record to the previous city. 


20-9 


HWIM REFERENCE 


WLDSELWN 


landiord 
offset 
width 


destroy 
wn_calc_position wn_init 
wn_connect wn_visible 


wn_dodraw lg_draw 


wn_draw 

wn_set 

wn_key 
wn_sense 
wn_emphasise 
lg_sense_width 
wid_restrict 


1g_self_check 
ig_set_id_pos 
wn_position 
wn_redraw 
wn_sense_help lg_update 


The wLDsewn class provides for the retrieval of information from the World database and supports 
sequential access and incremental matching via the keyboard. An instance of the wLpsELwn class may be 
used as a control in a lodger window. 


An example of the wupsELwn class being used as a control in a dialog is shown in the following picture: 


Set home city 


¢London Inner + 
‘Country United Kingdom 


In the above picture the controls are coupled in that the current city always resides in the current country. 
The current city could also be restricted to cities in the current country. This is known as restriction. 


Class diagram 


“ Win > / ledger ~ _¢ widselwn > 
Se hi———4 a mane 1 
,/ wmatcher » 


Class definition 
Defined in sub-category file w/dselwn.cl (generated header file widselwn.g). 


CLASS wldselwn  lodger 
{ 
REPLACE destroy 
REPLACE wn_init 
REPLACE wn_draw Draw whole city/country name 
REPLACE wn_set Set current city/country to str 
REPLACE wn_key 
REPLACE wn_sense 
REPLACE wn_emphasise 
REPLACE lg_sense_width Returns max width 
ADD wld_restrict 


SE eee ee 
20-10 


20 INCREMENTAL MATCHERS 


oon nnn nn ERD 


CONSTANTS 


{ 


PR_WLDSELWN_COUNTRY 
PR_WLDSELWN_FIRST_PARTNER 
PR_WLDSELWN_NOT_IN DIALOG 
PR_WLDSELWN_RESTRICTED 


IN_WLDSELWN_CITY 
IN_WLDSELWN_COUNTRY 
IN_WLDSELWN_FIRST_PARTNER 
IN_WLDSELWN_NOT_IN_ DIALOG 
IN_WLDSELWN_SECOND_PARTNER 
IN_WLDSELWN_SETHOME 
IN_WLDSELWN_SETDFLT 


} 


TYPES 


{ 
typedef struct 
{ 
UWORD flags; 
PR_WIN *other; 
} IN_WLDSELWN; 
typedef struct 
{ 
VOID *wicb; 
WR_EXTRA_DATA data; 
} SENSE_WLDSELWN; 


} 


PROPERTY 


} 
Property 


wldselwn.mat 
widselwn.tleng 


wldselwn. flags 


{ 

PR_WMATCHER *mat; 
UBYTE *tleng; 
UWORD flags; 
PR_WIN *other; 


} 


description below. 


PR_WLDSELWN_COUNTRY 
PR_WLDSELWN_FIRST_PARTNER 
PR_WLDSELWN_NOT_IN_DIALOG 
0x10 

0x20 

0x40 


io channel 


use WR_FIND_RES for wn_set 


If non-NULL, then one of a pair 


the handle of an instance of waarcuEr. 
a pointer to the current length of the match string. 


an ored combination of flags that determine the behaviour of the component: see the 


widselwn.other 


the handle of a second instance of wLDSELWN Or NULL. 


The initial behaviour and content of a wupsELwn control is specified by oring a suitable combination of the 
following flags into the flags member of the wLpsEzwn resource struct: 


IN_WLDSELWN_FIRST_PARTNER 


IN_WLDSELWN_SECOND_PARTNER 


IN_WLDSELWN_NOT_IN_DIALOG 


IN_WLDSELWN_SETDFLT 


IN_WLDSELWN_SETHOME 


specifies that the control is the first partner in a coupled pair. If the 
control is in a dialog, then it must be placed immediately above the 
second control. 


specifies that the control is the second partner in a coupled pair. If 
the control is in a dialog, then it must be placed immediately below 
the first control. 


specifies that the control is a component in a non-dialog lodger 
window 


specifies that the control is to display the default country or city as 
appropriate. This flag must not be set for the first partner in a pair: 
setting this flag for the second partner is sufficient. 


specifies that the control is to display the home city or country as 
appropriate. This flag must not be set for the first partner in a pair: 
setting this flag for the second partner is sufficient. 


20-11 


HWIM REFERENCE 


a SR SE ee SEED] 
WLDSELWN methods 


DESTROY. : oS Destroy 


VOID destroy (VOID) ; 


Destroy the wLDSELWN component. 


If wldselwn. flags does not contain IN_WLDSELWN_FIRST_PARTNER, and wldselwn.mat is non-zero, 
destroys the wMaTcHER component by sending a DEsTRoy message to wldselwn.mat. 


Supersend a DESTROY message. 


Ww 


VOID wn_init (IN_WLDSELWN *par,PR_WIN *landlord) ; 


Initialise 


Initialise the control according to the content of the 1n_wLDSELwn struct pointed to by par. 
Write landlord to lodger. landlord and write par->flags tO wldselwn. flags. 


If the control is either an isolated wupseLwn control, or the second partner in a coupled pair, creates an 
instance of wMATCHER and writes its handle to widselwn mat. Initialises the wmaTcHER component by 
sending an IM_INIT message to wldselwn.mat and writes the matcher .plen property of the wMATCHER 
instance to wldselwn.tleng. 


If the control is the second partner in a pair, writes the handle of the first partner to wldselwn. other. The 
handle of the other control is either copied from par->other, in which case the control is not a dialog 
component, or obtained via the sending of pL_HANDLE_TO_INDEX and DL_INDEX_TO_HANDLE messages to the 
dialog. Writes the handle of the wwarcHer component to the wldselwn.mat property of both controls. 
Writes the address of w1dselwn.tleng to the wldselwn.tleng property of the first partner. 


If par->flags contains IN_WLDSELWN_SETHOME, sets the current record to the home city, or country, 
according to the content of widselwn. flags, and draws the control by sending a wn_pRaw message to self. 


If par->flags contains IN_WLDSELWN_SETDFLT, sets the current record to the default city, or country, 
according to the content of widselwn. flags, and draws the control by sending a wy_praw message to self. 


VOID wn_draw (VOID) ; 
Draw the control. 


Displays the name of the current record in the system font and, if win. flags contains PR_WIN_EMPHASISED, 
emphasizes the control. The current record is the name of the current country if widselwn. flags contains 
PR_WLDSELWN_COUNTRY, Otherwise it is the name of the current city. 


If widselwn. flags contains both IN_WLDSELWN_NOT_IN_DIALOG and PR_WLDSELWN_counTry and the control 
is one of a pair the other of which has pR_WLDSELWN_RESTRICTED Set in its wldselwn. flags property, then 
the method draws the text in the snT_space_onLy system resource after the name of the country. 


On English language machines the srt_sPACE_oNLY system resource is defined as follows: 


RESOURCE STRING srt_space_only 


{ 


str="" (only) "; 


} 


_ Set current record 
VOID wn_set (WR_FIND RES *pset) ; 
Set the current record by an exact match to the text specified in the WR_FIND_RES Struct pointed to by pset. 


The wR_FIND_REs struct is defined as follows: 


20 - 12 


20 INCREMENTAL MATCHERS 
—_ SOOO MATCHERS 


typedef struct 


{ 

TEXT city [WR_MAX_NAME+1] ; 

TEXT country [WR_MAX_NAME+12] ; 

} WR_FIND_RES; 
The members of the wR_FIND_REs struct have the following significance: 
city either NULL or the name of the target city specified as a zero terminated string. 
country either NuLL or the name of the target country specified as a zero terminated string. 


Sets the current record by sending an IM_sET_vaL message to wldselwn.mat passing as argument pset. A 
NULL city should be specified when setting the country. 


Resets the current match string by writing the nu. string to the matcher .ptyped property of 
wldselwn.mat and zero to the matcher.plen property of widselwn.mat. 


Sets PR_WMATCHER_INDETERMINATE in the wmatcher.iscountry property of the wmaTcHER component. 


Draws the contro] by sending an Lc_praw message to self, and if the control is one of a pair, draws the 
other control by sending an Lc_pRaw message to widselwn. other. 


Je key input 


INT wn_key(UINT keycode,UINT modifiers) ; 
Handle a keypress that might lead to the selection of a new current record. 


Sends an IM_KEY message to wldselwn.mat passing keycode and modifiers as arguments: the wMATCHER 
component is primed to ensure that it matches either by country if widselwn. flags contains 
IN_FNSELWN_COUNTRY, Or by city if wldselwn. flags contains IN_FNSELWN_CITY. 


If the return value is Im_NEW_LEN, draws the cursor one character to the right of its previous position and 
returns IM_NEW_LEN. 


If the return value is Im_wzw_DIsPLay, draws the new current record in the control by sending an LG_DRAW 
message to self. If the control is one of a pair and widselwn. flags contains PR_WLDSELWN_RESTRICTED, 
draws the other control by sending an L¢_praw message to wldselwn. other. Returns wN_KEY_CHANGED. 


VOID wn_sense (SENSE_WLDSELWN *psense) ; 
Sense the handle of the database channel and the data for the current record. 
The SENSE_WLDSELWN struct is defined as follows: 


typedef union 


{ 

WR_CITY_DATA ci; 
WR_COUNTRY_DATA co; 
} WR_EXTRA_DATA; 


typedef struct 


{ 


VOID *wfcb; io channel 
WR_EXTRA_DATA data; 
} SENSE_WLDSELWN; 


The wr_cITy_pata and wr_counTRy_pata structs are described under the wR_GET_crTy_para and 
WR_GET_COUNTRY_DATA services respectively in the Series 3 World Database chapter of the I/O Devices 
Reference manual. 


The significance of the members of the sznsE_wLDsELwn struct is as follows: 
wicb the handle of the channel to the World database device driver. 


data contains the data for the current record which may be either a city or a country as appropriate. 


20 - 13 


HWIM REFERENCE 


The method writes the wmatcher.wfcb property of the wmaTCHER component to psense->wfcb. 


If wldselwn. flags contains IN_WLDSELWN_COUNTRY, writes the data for the current country to the 
WR_EXTRA_DATA union pointed to by the data member of psense. 


Otherwise, if widselwn.£1ags does not contain IN_WLDSELWN_couNTRY, writes the data for the current city 
to the wR_EXTRA_DATA union pointed to by the data member of psense. 


Emphasise 
VOID wn_emphasise(UINT flag); 
Emphasise the control if f1ag is TRuE, otherwise de-emphasise it. 


If flag is TRUE, Sets PR_WIN_EMPHASISED in win. flags. Resets the match string by sending an 1m_KEY 
message to wldselwn.mat, with arguments of w_kKEy_EScAPE and zero. Draws the control by sending an 
LG_DRAW message to self. 


Otherwise, if £1ag is rans, clears the cursor from the control, clears pR_WIN_EMPHASISED from 
win.flags,and sends an LG_DRAW message to self. 


Returns required width 


UINT lg_sense_width (VOID) ; 


Return the width of the control. 
If the control is a component in a dialog, returns GEoG_MAX_NAME*SYSTEM_FONT_NUM_WIDTH. 


Otherwise, returns (GEOG_MAX_NAME-2) *SYSTEM_FONT_NUM_WIDTH. 


Set restriction 


VOID wld_restrict (INT IsRestricted) ; 
Set restriction. 
Writes IsRestricted to the wmatcher. resco property of the wMATCHER component. 


If IsRestricted is TRUE, sets PR_WLDSELWN RESTRICTED in wldselwn. flags, resets the wMATCHER 
component by writing the nuLt string to its matcher.ptyped property, and zero to its matcher.plen 
property . Draws the control by sending an Lc_pRaw message to self. 


Otherwise, if tskestricted is FALSE, Clears PR_WLDSELWN_RESTRICTED from wldselwn. flags. 
This message may be sent to either partner in a coupled pair: the effect is the same in each case. 


This message may not be sent to an isolated control whose wldselwn. flags property contains 
IN_WLDSELWN_COUNTRIES. 


20-14 


CHAPTER 21 


LINK PASTE SUPPORT 


This chapter documents the ewLnxsv class which supports extraction of text from the selected region of an 
edit window, providing a supply of data for the Link Paste mechanism. 


Precursors 
Familiarity with the following topic will aid the understanding of this chapter: 


e the Epwzn class described in the EDWIN Edit Window Class chapter of the HWIM Reference 
manual. 


EWLINKSV 


doc 
state 
pos 
parend 
posend 
buf 


ewls_ init 
ewls_ extract 


The EwLinxsv class supports the extraction of text from the selected region of an edit window as follows: 


e — the extraction of text including paragraph delimiters - the content of the selected region may thus 
be copied as one block. 


e the extraction of text up to and excluding the next paragraph delimiter - the content of the selected 
region may thus be copied and stripped of paragraph delimiters - and optionally the replacement 
of tab characters in the text with spaces. 


The class may be used when implementing an edit window as a link-paste server. 


Class diagram 


7 ewlinksv "5 / doc > 


21-1 


HWIM REFERENCE 
es SSeS 


Class definition 
Defined in sub-category file edwin.cl (generated header file edwin.g). 


CLASS ewlinksv root 
Component of linksv class, extracts data from edwin 


{ 

ADD ewls_init 
ADD ewls_extract 
PROPERTY 


{ 


VOID *doc; 
WORD state; 
UWORD pos; 
UWORD parend; 
UWORD posend; 
TEXT buf [256] ; 


} 
} 


Property 
ewlinksv.doc the handle of a document - this is usually an instance of either Eppoc or EPFDOC. 


The document is assumed to be a component in an edit window - i.e. an instance of 
EDWIN. 


ewlinksv.state see the description of the ewis_exrracr message for the significance of 
ewlinksv.state. 


ewlinksv.pos the current position in the document. 
ewlinksv.parend for use by subclassers. 
ewlinksv.posend the end position of the selected region. 


ewlinksv.buf a buffer that stores text extracted from the document. 


Se cea eT a a ny 
EWLINKSV methods 


_ Initialise 


VOID ewls_init (PR_EDWIN *edwin, INT state) ; 


Determine the position and length of the selected region in the document edited by the edit window with 
handle edwin and record the extraction mode specified by state. 


Records the handle of the document by writing edwin->edwin.doc to ewlinksv.doc. 


Writes the start position of the selected region to ewlinksv.pos and writes the end position of the selected 
region plus one to ewlinksv.posend - the method obtains the start and end positions of the selected region 
by sending an sI_GET_SELECT message to edwin->edwin. scrimg. 


Records the extraction mode by writing state to ewlinksv.state. 


INT ewls_extract (TEXT **ppb,UINT blen) ; 


Extract up to blen characters from position ewlinksv.pos in the selected region of the document and write 
the address of the extracted characters to *ppb. 


If no region is selected, returns -1. 


If the maximum number of characters that can be extracted from the document - ewlinksv.posend- 
ewlinksv.pos - is less than blen, writes ewlinksv.posend-ewlinksv.pos tO blen. 


Extracts blen characters from position ewlinksv.pos in the document by sending an EP_EXTRACT message 
to ewlinksv.doc. The characters are written to ewlinksv. buf. 


—_— SS SSS 
21-2 


21 LINK PASTE SUPPORT 


——_—-_—r—————————————XnYv—— a ee ee 


Writes sewlinksv.buf [0] to «ppb. 


If ewlinksv.state is equal to pr_EQUAL_PARAs, increments ewlinksv.pos by the number of characters 
extracted from the document and returns the number of characters extracted. 


If ewlinksv.state is equal to DF_LINK_TEXT, replaces any tab characters in ewlinksv.buf with spaces. 


If the text written to ewlinksv.buf contains no paragraph delimiters - i.e. 0x00 - increments ewlinksv.pos 
by bien and returns bien. 


Otherwise increments ewlinksv.pos by one plus the number of characters before the first paragraph 
delimiter in ewlinksv.buf and returns the number of characters before the first paragraph delimiter. 


21-3 


CHAPTER 22 


REPRESENTATIONS OF TIME AND DATE 


This chapter documentsthe nrime class which may be used to convert to and from textual representations 
of time and date. 


Precursors 
Familiarity with the following topic will aid the understanding of this chapter: 


e the rime class described in the The Time Class chapter of the OLIB Reference manual. 


HTIME 


tDay 
tMonth 


to_set 
to_set_format 
to_get_sysdat 
to_set_abbreviatio 
ns 


to_sense 


to_add_years 
to_add_months 
to_add_ days 
to_add_secs 


to_sense_format 


te—get—sysdat 


The uTIMe class supports conversion to and and from textual representations of time where time is used to 
denote time and date. While based on the trmz class in the ours object library the urime class adds the 
following functionality: 


e — the ability to truncate the day and month names after a given number of characters. 
e — the ability to sense machine specific format parameters such as time and date separator characters. 


Class diagram 


22-1 


HWIM REFERENCE 


Class definition 
Defined in sub-category file htime.cl (generated header file Atime.g). 


CLASS htime time 
{ 
REPLACE to_set 
REPLACE to_set_format 
REPLACE to_get_sysdat 
ADD to_set_abbreviations 


CONSTANTS 
{ 
PR_TIME_ABBREVIATE 0x1000 
PR_TIME_FORCE_UPDATE_FORMAT 0x2000 
HTIME_FIRST_DAY 29219L ist Jan 1980 
HTIME_LAST DAY S4786L 31st Dec 2049 
HTIME_FIRST_SEC oL 
HTIME_LAST SEC 86399L (P_NSECDAY-1) 
HTIME_FIRST_MIN OL 
HTIME_LAST_ MIN 86340L (P_NSECDAY-60) 
} 

PROPERTY 
{ 
UBYTE tDay; 


UBYTE tMonth; 
} 
} 


Property 

htime.tDay the length of the abbreviated form of the day name. Thus if htime.tDay were 3 the 
abbreviated form of "Wednesday" would be "Wed". 

htime.tMonth the length of the abbreviated form of the month name. Thus if htime.tMonth were 


3 the abbreviated form of "December" would be "Dec". 


HTIME methods 
TO 


INT to_set (INT format, UBYTE *pdata) ; 


Set the current date and time using the representation specified by format. 


If format contains SET_TIME_Now and time. f.flags contains PR_TIME_FORCE_UPDATE_FORMAT, sets as 
many as possible of the format parameters using system services by sending self a TO_SET_FORMAT 
message with an argument of nut. 


Sets the current date and time stored in the prime object by supersending a To_sET message with arguments 
of format and pdate and returns the return value. 


VOID to_set_format (SE_TIME_FORMAT *pf,UWORD mask) ; 


Set the format parameters for the conversion to and from textual representations of time. 
Sets the format parameters by supersending a To_SET_FORMAT message with arguments of pf and mask. 
Sets the following in time.£.flags if present in pf->flags: 


PR_TIME_ABBREVIATE indicates that the day of the week text is to be truncated after 
htime.tDay characters, 


and that the day of the month text is to be truncated after 
htime.tMonth characters. 


22-2 


22 REPRESENTATIONS OF TIME AND DATE 


PR_TIME_FORCE_UPDATE_FORMA _ controls the behaviour of the ro_seT message. 
T 


TO_GET_SYSDAT : Get system data 


INT to_get_sysdat (UBYTE *buf,UINT type,UINT n); 


Write a zero terminated time-related name to but or, if type is TY_TIME_FORMAT write machine specific 
format parameters in an SE_TIME_FoRMAT struct to buf. 


If type is neither ry_TIME_DAY, Nor TY_TIME_MONTH Nor TY_TIME_FORMAT, supersends a TO_GET_SYSDAT 
message with arguments of buf, type and n, and returns the return value, 


If type is Ty_TIME_SUFFIX obtains the day suffix name - e.g. "st", "nd", "rd" or "th" on English language 
machines - corresponding to the day number specified by n in the range 0 to 31. Writes the string to buf 
and returns the length of the string. 


If type is Ty_TIME_AMPM obtains the am/pm string specified by n - where 0 is am and 1 is pm. Writes the 
string to buf and return the length of the string. 


If type is Ty_TIME_pay obtain the day text - e.g. "Tuesday" - for the day number specified by n in the range 
0 to 6 inclusive where 0 is Monday. If time. £.£1ags contains PR_TIME_ABBREVIATE truncates the day text 
after htime .tDay characters. Writes the string to buf and returns the length of the string. 


If type is Ty_TIME_MonTH, obtains the month text - e.g. "March" - for the month number specified by n in 
the range 0 to 11 inclusive where 0 is January. If time. £.f£lags contains PR_TIME_ABBREVIATE truncates 
the month text after htime.tMonth characters. Writes the string to buf and returns the length of the string. 


If type is TY_TIME_FORMAT, Creates an SE_TIME_FORMAT struct and copies the content of the struct to bug. 
The sE_TIME_FoRMaT struct is defined as follows: 


typedef struct 


{ 

UWORD flags; 
UBYTE dsep; 
UBYTE tsep; 

} SE_TIME_FORMAT; 


The members of the se_TIME_Format struct are set as follows: 


flags on all machines the following flags are set: 


PR_TIME_DAY_NAME write the day name with a trailing comma before the date. 
PR_TIME_SUFFIX_NAME write the day number followed by a suffix e.g. 15th. 
PR_TIME_MONTH_NAME show the month as a name rather than a numer. 


the following flags may be set depending on the machine and the current settings: 


PR_TIME_MMDDYY set on USA machines only. 

PR_TIME_YYMMDD set on Japanese machines only. 
PR_TIME_DDMMYY set on all other machines including European. 
PR_TIME_AMPM set if the system time format is am/pm. 
PR_TIME_ABBREVIATE set if present in time.£.flags. 


PR_TIME_FORCE_UPDATE_FORMAT set if present in time. f. flags. 


dsep the system date separator character - on English language machines this is usually a backslash - 
12/3/1994 for example. 
tsep the system time separator character - on English language machines this is usually a colon - 


3:42 pm for example. 
Returns the length of the data written to bur. 


22-3 


HWIM REFERENCE 


TO_SET_ABBREVIATIO 


VOID to_set_abbreviations(INT aDay,INT aMonth) ; 


Set abbreviations 


Set the length of the day and the month strings. 


Writes aDay to htime.tDay and writes aMonth to htime. tMonth. 


22-4 


CHAPTER 23 


THE GATE CLAss 


waotstat lastmods 
concb atpid 
xadd atson 
flags today_hook 
dialres shift_txt 
x prevdisp 
getkeys dx 
lastkey g 


gt_init gt_choice_close 
gt_menu_open gt_button_open 
gt_menu_add gt_button_add 
gt_menu_run gt_button_close 
gt_menu_close gt_dial_position 
gt_dial_open gt_xw_enable 
gt_dial_add gt_return_signals 
gt_dial_run gt_check_ats_on 
gt_dial_close gt_last_key 
gt_card_open gt_wdr_print 
gt_card_add gt_wdr_print_setup 
gt_card_close gt_do_help 
gt_choice_open gt_set_rscfile 
gt_choice_add gt_dial_sopen 


The care class is essentially a private class whose principal task is to support the graphics functionality of 
OPL/w and the HWIF library. In consequence, the majority of its methods and items of property are not 
suitable for use by application programmers. This chapter documents only those aspects that could 
reasonably be of value to such programmers. 


Note that none of the features documented in this chapter are available on the Series 3. 


All HWIM applications create and initialise an instance of the cate class during the application's 
initialisation. This instance remains in existence for the lifetime of the application. The handle of the 
application's instance of the care class is written to the magic static patcate. 


In the interest of future compatibility, an application should not subclass cate. 


23-1 


HWIM REFERENCE 
a SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSsSSSSSSSSSSSSSseseseeese 


Class definition 
Defined in sub-category file gate.c/ (generated header file gate. g). 


CLASS gate root 
Gateway to hwim menus and dialogs 

{ 

ADD gt_init 

ADD gt_menu_open 

ADD gt_menu_add 

ADD gt_menu_run 

ADD gt_menu_close 

ADD gt_dial_open 

ADD gt_dial_ada 

ADD gt_dial_run 

ADD gt_dial_close 

ADD gt_card_open 

ADD gt_card_add 

ADD gt_card_close 

ADD gt_choice_open 

ADD gt_choice_add 

ADD gt_choice_ close 

ADD gt_button_open 

ADD gt_button_add 

ADD gt_button_close 

ADD gt_dial_position 

ADD gt_xw_enable 

ADD gt_return_signals 

ADD gt_check_ats_on check if process supports ATS 

ADD gt_last_key return last key used 

ADD gt_wdr_print 

ADD gt_wdr_print_setup 

ADD gt_do_help 

ADD gt_set_rscfile 

ADD gt_dial_sopen Workabout ONLY - init dlg with small font (Romans) 


CONSTANTS 


{ 


PR_XWSERV_SHUTDOWN 0x01 
PR_XWSERV_QUERY_ALERT 0x02 


PR_XWSERV_S3FS 0x04 Workabout ONLY - full-screen S3 
compatibility 

PVV_TEXT_MAX LEN 50 

OPRINTER_DO_PREVIEW 1 


OPRINTER_PRINT_AFTER 2 


} 


TYPES 

{ 

typedef struct 
{ 
WORD class; 
VOID *data; 
} DITEM_LIST; 

typedef struct 
{ 
UWORD xwim; 
UWORD nmenus; 
VOID **menus; 
UWORD ulines [16]; 
UWORD count; 
DITEM_LIST dialret [9]; 
UWORD nrec; 
VOID *orec; 
UWORD preview; 
} PURE_GATE; 

typedef struct 
{ 
UBYTE Mode; 
UBYTE Flags; 
} PVV_DISPLAY; 


23-2 


23 THE GATE CLASS 


rr EE AS 


typedef struct 


{ 


UWORD 
UWORD 
UWORD 
UWORD 
UWORD 
UWORD 
UWORD 
UWORD 
UWORD 
UWORD 
UWORD 
UWORD 
UWORD 
UWORD 
UWORD 
UWORD 


} X_CONSTANTS; 


fht; 
fds; 
fas; 
fnw; 
fmw; 
echt; 
mbht ; 
bfid; 
bulyo; 
bulht; 
ninlb; 
SSww; 
bsww; 
hlig; 
samo; 
damo; 


typedef struct 


{ 


UWORD 
UWORD 
UWORD 
UWORD 
UWORD 
UWORD 
UWORD 
UWORD 
UWORD 


fht; 
fds; 
fas; 
fnw; 
fmw; 
cht; 
bulyo; 
bulht; 
ninlb; 


height of system font 

descent of system font 

ascent of system font 

width of numeric character in system font 
width of maximum normal character 

height of a line in dialogs or listboxes 
height of menubar 

id of bold font 

y-offset to start of bullet 

height of bullet 

max number of lines in listbox 

width of small status window 

width of large status window 

help list left gutter 

menu offset for single accelerator 

menu offset for double accelerator 


height of font 

descent of font 

ascent of font 

width of numeric character 

width of maximum normal character 

height of a line in dialogs or listboxes 
y-offset to start of bullet 

height of bullet 

max number of lines in listbox 


} DLG_X_CONSTANTS; Workabout ONLY - extras for dialogs using another font 


} 


PROPERTY 


{ 


VOID *waotstat; 
VOID *concb; 
HANDLE xadd; 
UWORD flags; 
UWORD dialres; 
X_CONSTANTS x; 
VOID *getkeys; 
UWORD lastkey; 
UWORD lastmods; 
UWORD atpid; 
UWORD atson; 


VOID *today_hook; 
TEXT shift_txt [10]; 


connection pseudo-constants 

where to send copy of key received 
last key received 

last keyboard modifiers received 
pid of process attached to 

ATS supported 


PVV_DISPLAY prevdisp; 


DLG_X_CONSTANTS dx; 


dialog 


PURE_GATE g; 


} 
} 


Property 


gate.x 


gate.getkeys 


gate. lastkey 


gate.lastmods 


gate.atpid 


Workabout ONLY - constants of additional fonts of 


Pseudo-constant connection data, described below. This data may be read by 
application code. 


Either nuxu or the handle of the instance of the XADD arssv class that is sent 
a copy of each key received. 


The keycode of the last key received. This data should be read by means of 
the gt_last_key method. 


The modifiers associated with the last key received. This data should be read 
by means of the gt_last_key method. 


Either zero or the process ID of the process to which the application is 


attached. 


23-3 


HWIM REFERENCE 
EES 


gate.atson TRUE if the application supports the automatic test system (ATS) mechanism. 


gate.dx Pseudo-constant connection data, described below, for Workabout dialogs. 
This data may be read by Workabout application code. 


The remaining items of property are reserved for internal use and are not documented and should not be 
accessed by application software. 


The pseudo-constant connection data, gate .x, is a collection of values that are constant within a particular 
running application, but will, in general, vary with the type of the machine on which the application is 
running. 


The data is evaluated during the application's initialisation and is used by system code to determine the 
position and size of system-created objects, such as dialog boxes and the menu bar. Application code is 
free to read any of this data. 


The meaning of each item is given in the following table: 


DatGate->gate.x.fht The height of the system font. 
DatGate->gate.x.fds The descent of the system font. 
DatGate->gate.x.fas The ascent of the system font. 
DatGate->gate.x.fnw The width of a numeric character in the system font. 
DatGate->gate.x. fmw The width of of the widest 'normal' character. 
DatGate->gate.x.cht The height of a line in a dialog or a listbox. 


DatGate->gate.x.mbht The height of the menubar. 
DatGate->gate.x.bfid The ID of the bold font. 


DatGate->gate.x.bulyo The y-offset to the top of a bullet displayed in a text window (an instance of 
TEXTWIN). 


DatGate->gate.x.bulht The height of a bullet displayed in a text window (an instance of TExtTwrn). 
DatGate->gate.x.ninlb The maximum number of lines that can appear in a listbox. 
DatGate->gate.x.ssww The width of the small status window. 

DatGate->gate.x.bsww The width of the large status window. 

DatGate->gate.x.hllg The width of the left gutter of a help list. 


DatGate->gate.x.samo The offset, from the right hand side of a pull-down menu, to the position to 
display an unshifted accelerator. 


DatGate->gate.x.damo The offset, from the right hand side of a pull-down menu, to the position to 
display the 'Shift' text for a shifted accelerator. 


The Workabout pseudo-constant connection data, gate . dx, is a collection of values that are used to 
determine the appearance of system-crated objects, particularly dialogs, that use a font other than the 
system font. These values are constant within a particular running application. Although currently only 
defined for the Workabout, they will, in general, vary with the type of the machine on which the 
application is running. 


The data is evaluated during the application's initialisation. Application code is free to read any of this data. 


The meaning of each item is given in the following table: 


DatGate->gate.dx. fht The height of the dialog font. 

DatGate->gate.dx. fds The descent of the dialog font. 

DatGate->gate.dx. fas The ascent of the dialog font. 

DatGate->gate.dx.fnw The width of a numeric character in the dialog font. 
DatGate->gate.dx. fmw The width of of the widest ‘normal’ character in the dialog font. 


Eee 
23-4 


23 THE GATE CLASS 


DatGate->gate.dx.cht The height of a line in a dialog or a listbox. 


DatGate->gate.dx.bulyo = The y-offset to the top of a bullet displayed in a text window (an instance 
of TEXTWIN). 


DatGate->gate.dx.bulht The height of a bullet displayed in a text window (an instance of 
TEXTWIN). 


DatGate->gate.dx.ninlb | The maximum number of lines that can appear in a listbox. 


~~ Se ee ee et ee See 
GATE methods 


CHE 


INT gt_check_ats_on(INT pid) ; 
Return the ATS status of the process with process ID pia. 


Returns zero if the specified process supports ATS, otherwise a (negative) error number. A return value of 
E_GEN_NsupP indicates that the specified process does not support ATS. Other errors are possible if, for 
example, the specified process has terminated before the gt_check_ats_on method is executed. 


Note that the process with process ID pid may terminate at any time. A zero return value from the 
gt_check_ats_on is thus no guarantee that future ATS operations on that process will succeed. 


INT gt_last_key(UWORD *mods) ; 


Sense the keycode and modifiers of the last keypress received by the application. 


The method returns the keycode and writes, to «mods, the corresponding modifier flags. Both values will be 
zero if the application has not received any keypress. 


23 -5 


— 


CHAPTER 24 


HWIM UTILITY FUNCTIONS 


HWIM utility and convenience functions have been developed in response to a number of observations and 
pressures: 


e The need to minimise memory used by application code. 


¢ The observation that a large range of applications have many code fragments that are in common 
use. 


By formalising these code fragments into commonly available functions, application code can be made 
easier to read and can achieve savings in memory. 


At first sight, the use of "free standing" functions seems to violate the most basic principles of object 
oriented programming. This is not the case. They can legitimately be used where similar actions are done 
repeatedly in various parts of the application code, even if that action involves the sending of messages. 


For example, utility functions are very often used to send a standard message to system generated objects 
such as the application manager which exist throughout the lifetime of an application. 


There is nothing to stop a developer from writing his/her own utility functions and is, in fact, encouraged to 
do so. It is appropriate in a situation where similar pieces of code are used over and over again. It is 
particularly suitable where code involving the sending of a message to a particular object may be repeated. 
There is no problem involved in encapsulating the sending of messages within utility functions. 


The use of utility functions can save memory by: 


¢ - allowing a reduction in the number of parameters passed from application code. While this might 
save one or two bytes per call, the total saving in memory across a whole range of applications 
can be substantial 


e avoiding the duplication of code fragments 


The next sections describe the utility functions available for use by any HWIM application. Each section 
describes a set of functions grouped under the following headings: 


© General utilities 

e Text management 
e User notification 

e Running a dialog 

© Dialog box utilities 


In many cases, the implementation of utility functions is given in full or in skeleton form. This will assist 
developers to create their own utility/convenience functions. 


Note that the HWIM utility functions are prototyped in Awim.h. 


24-1 


HWIM REFERENCE 


General utilities 


As indicated by the title of this section, this is a group of miscellaneous functions with no connecting 
theme. 


INT p_true(VOID) ; 


This is a simple function that returns the value TRUE. 


It is particularly useful as a default method for a class where the method must return a simple TRUE or 
FALSE value. 


For example, in the definition of the HWIM comman class, p true is assigned to the method 
com_acc1_check which means that when the method com_accl_check is called, p true is executed, thus 
returning a value of TRUE. 


INT p_false (VOID) ; 


This is a simple function that returns the value rause. 


It is particularly useful as a default method for a class where the method must return a simple TRUE or 
FALSE value. 


See the earlier description of p_true for an example of how this could be implemented. 


VOID hDestroy(VOID *hand) ; 


This is a function which will destroy an object by sending it the p—esTroy message: 
psend2 (hand, O_ DESTROY) ; 


The handle of the object to be destroyed must be passed as a parameter to this function. If the handle is 
nui, the function does nothing. 


VOID hInitVis (VOID *win) ; 


This can be used in one of two ways depending on the current state of the window object with handle win: 
e if the window has not yet been initialised, then it will be both initialised and made visible 
e if the window has already been initialised, then it will be made visible. 


The function is implemented by sending a wN_vIsIBLE message to the window with handle win as shown 
below. The handle passed as a parameter must point to an object instanced from the win class ora 
subclass of win. 


psend3 (win,O WIN_VISIBLE,WV_INITVS) ; 


For further discussion on windows, see the Windows chapter. 


VOID hWservComSend(INT comid) ; 


This utility simply sends the message with message (method) number comid and the same message 
(method) number as a parameter to the command manager. This is implemented as shown below: 


P_send3 (w_ws->wserv.com, comid, comid) ; 


24-2 


24 HWIM UTILITY FUNCTIONS 
——————_—. EEE EERUUNG HONS 


The additional comida parameter that is passed with the message is for the convenience of the receiving 
command manager method, which may choose to ignore it. 


This function is particularly useful where a number of methods are implemented using the same code. 
Passing the method number as a parameter allows the code to identify the context of the call and to take 
appropriate action if it so wishes. 


For further discussion on the command manager, see the Command Manager chapter of this manual and 
the Commands and Command Menus chapter of the Object Oriented Programming Guide. 


hEnsurePath _ Ensure path exists 
VOID hEnsurePath (TEXT *fname) ; 


If the path indicated by the file specification at gname does not exist, the function attempts to create the 
required directory structure. 


The file specification is parsed using the Plib function p_fparse. If this is successful, the directory 
component of the parsed file specification is created, provided it does not already exist, using the Plib 
function p_mkdir. 


No errors are reported. If this function fails, this could be due to a bad file specification in *fname or a 
problem with the device/medium when attempting to create the directory itself. 


For example, suppose fname contains the string: 
"FILES \\DOCS\\FRED.DOC" 

and the default path is: 
LOC: :M:\ 

then the function will attempt to create the directory structure: 
\FILES\DOCS\ 

at node LOC:: on device M: 


For further information on file specifications see the files chapter in the PLIB Reference manual. 


Text management 


This group of functions is concerned with building text from various sources, displaying text in a variety of 
contexts and with text manipulation. 


INT hLoadResource (INT rid, VOID *ppdata) ; 


This is a convenience routine which allocates a cell of suitable length from the heap, loads the resource 
referenced by the resource id ria into the cell and returns the length of the loaded resource. The address of 
the cell is placed in *ppadata. 


The function is implemented by sending an am_load_resource message to the application manager as 
shown below: 


p_send4 (w_am,O_AM LOAD RESOURCE, rid, ppdata) ; 
Remember that the address of the application manager object is found in the magic static variable w_am. 


If an error occurs, the function calls p leave. 


24-3 


HWIM REFERENCE 


hLoadResBuf . Load resource into buffer 
INT hLoadResBuf (INT rid, VOID *buf); 


This is a convenience routine which loads the resource referenced by the resource id ria into the buffer 
pointed to by bug and returns the length of the loaded resource. 


The function is implemented by sending an am_load_res_buf message to the application manager as 
shown below: 


p_send4 (w_am,O AM _LOAD RES BUF, rid, buf) ; 


It is similar to the previously described function hLoadresource except that it is the caller's responsibility 
to provide the buffer and to ensure that it is large enough to contain the loaded resource. 


If an error occurs, the function calls p_ leave. 


As an example, consider the following code fragment that could come from any typical window subclass 
drawing method which, as part of its functionality, loads a resource string and prints it at a given point 
within the window: 


hLoadResBuf (self->resid, &buf[0]); 
p_supersend2 (self,O_WN_DRAW) ; 
gPrintText (50,50, &buf[0],p_slen(&buf[0]); 


4 


The important point to note here is that buf must be large enough to hold the loaded resource String. 


hLoadChlistResB 


TEXT *hLoadChlistResBuf (INT rid, INT choice, TEXT *buf); 


oice list item into buffer 


This is a convenience routine which loads a single choice list item from a choice list resource into a buffer. 


The choice list resource is identified by the parameter ria within a resource file while the parameter 
choice identifies the particular choice list item within the resource. 


The function returns a pointer to the string's terminating zero. 


The function is implemented by sending a ws_load_chlist_res message to the window server object as 
shown below: 


return ( (TEXT *)p_sendS(w_ws,O_WS_LOAD CHLIST_RES, rid, choice, buf) ; 


It is the caller's responsibility to ensure that the buffer provided is large enough to contain the loaded 
choice list item. 


If an error occurs, the function calls p_leave. 


_ Generate error text 


VOID hErrs(TEXT *buf, INT err); 


This is a convenience routine that writes the error text specified by the error number err to the buffer at 
buf. 


If err is negative it is interpreted as a system error number and the text is obtained by calling the Plib 
function p_errs; the buffer must be at least E_MAX_ERROR_TEXT_SIZE bytes. 


If err is non-negative it is assumed to refer to a resource string which is loaded from a resource file with 
resource id err-ERROR_RID_oFFsET (see the wrn class definition). The buffer supplied must be large 
enough to contain the maximum size string expected. 


Because the resource id is given as err-ERROR_RID_OFFSET, then this must evaluate to a number greater 
than 1 in order to access resources within the application resource file. Consequently, err must be greater 
than ERROR_RID OFFSET + 1. 


SNS 
24-4 


24 HWIM UTILITY FUNCTIONS 


EIN 


The function is implemented as follows: 


{ 
if (err<0) 
p_errs(buf,err); 
else 
hLoadResBuf (err-ERROR_RID_OFFSET, buf) ; 
} 


If an error occurs, the function calls p_ leave. 


For further detail on resource files, see the chapter on Resource Files in this manual. 


RAtob = = ~==©~©~©6—— Generate formatted string 
INT hAtob(TEXT *buf, INT rid, INT *pargs) ; 


This is a useful function which generates a zero terminated string in the buffer pointed to by buf and 
returns its length. The string is generated from a format string and a number of arguments pointed to by 
pargs. The format string is loaded from the resource ria in a resource file. 


For more detail on the structure of the format string, see the description of the PLIB function p_atob in the 
PLIB Reference manual. 


There are a number of important points to note: 
e — the length of the format string in the resource file, when loaded, must not be greater than 80 bytes. 


* — it is the caller's responsibility to ensure that the buffer pointed to by buf is large enough to contain 
the generated string. 


If an error occurs, the function calls p_ leave. 


The following routine and code fragment together provide a simple example of the use of this function. For 
the sake of argument, assume that file is a static variable that contains the channel of an opened text file. 


GLDEF_C CDECL SampleRoutine (INT rid,INT arg,...) 


{ 

INT len; 

TEXT buf [25]; 

len = hAtob(&buf [0] , rid, &arg) ; 
p_write (file, &buf [0] ,len); 


INT rid; 
INT num; 


num = 65; 
rid = MY_FORMAT_ STRING; 
SampleRoutine (rid, num, num, num, num, num, num) ; 


Given that the string resource referenced by the resource ID my_FoRMAT_sTRING is defined as: 
RESOURCE STRING my_format_string {str="[tb tc %d %o tu %x]";} 
then the the following string of characters would be written to the text file: 


[1000001 A 65 101 65 41] 


24-5 


HWIM REFERENCE 


hAtos —s Generate formatted string, vari iment count 


TEXT *hAtos(TEXT *buf, INT rid, ...); 


This is a useful function which generates a zero terminated string in the buffer pointed to by buf and 
retums a pointer to its zero terminator. The string is generated from a format string and a number of 
arguments. The format string is loaded from the resource rid in a resource file while the arguments are 
interpreted as for the PLIB function p_atos. 


For more detail on the structure of the format string, see the description of the PLIB functions p_atob and 
p_atos in the PLIB Reference manual. 


As with the function hatob, described earlier, the same important points must be noted. To recap: 
¢ — the length of the format string in the resource file, when loaded, must not be greater than 80 bytes. 


* it is the caller's responsibility to ensure that the buffer pointed to by bug is large enough to contain 
the generated string. 


If an error occurs, the function calls p leave. 

For example, given that the string resource referenced by the resource ID my_ForMAT_sTRING is defined as: 
RESOURCE STRING my_format_string {str="%b %c %d to %u &x";} 

the effect of the following code fragment: 
INT num; 


TEXT buf [23]; 
INT rid; 


num = 65; 
rid = MY_FORMAT_ STRING; 
hAtos (&buf [0] , rid, num, num, num, num, num, num) ; 


is to build the string: 


12000001 A 65 101 65 41 


in the buffer at but. 


Append ellipsis to text 
VOID hAppendEllipsis(TEXT *p) ; 


This is a simple convenience function that writes the ellipsis character, WS_SYMBOL_ELLIpsis, followed by 
a zero terminator into the two bytes pointed to by p. 


The ellipsis character is commonly used as an appendage to a choice list prompt to indicate that a 
subsidiary dialog is available. 


For example the code fragment: 


TEXT buf[5] = {'A','B','¢'}; 
hAppendEllipsis (&buf [3]); 


would result in buf containing the four characters ABC... followed by the zero terminator. 


Set text mode 
VOID hSetGTmode(UINT tmode) ; 


This simple convenience function uses the window server function gsetcc to set the text mode of the 
current graphics context to that specified by tmode. Possible values of tmode are defined in the Graphics 
Output chapter of the Window Server Reference manual. 


For example, as part of the drawing method of a win subclass, the following code fragment would create a 
a permanent graphics context with default values and then change the textmode so that when writing text, 
the 1's and 0's of the font characters overwrite the destination area: 


24-6 


24 HWIM UTILITY FUNCTIONS 
—_—__—$ eee ML YE FUNCTIONS 


‘ 


wValidateWin (self->win.id) ; 
p_supersend2 (self,O WN_DRAW) ; 
self->mywin.gcid = gCreateGCo0 (self->win.id) ; 
hSetGTmode (G_TRMODE_REPL) ; 

gPrintText (50,50, &buf[0],p_slen(&buf[0]); 
wFree (self->mywin.gcid) ; 


hSetGFont : __ Set font 
VOID hSetGFont (UINT fid); 


This simple convenience function uses the window server function gsetcc to set the text font of the current 
graphics context to that specified by ¢id. Possible values of fia are defined in the Graphics Output chapter 
of the Window Server Reference manual. 


For example, as part of the drawing method of a win subclass, the following code fragment would create a 
a permanent graphics context with default values and then change the text font to the ROM based 
monospaced font wS_FONT_BASE+3: 


wValidateWin (self->win.id) ; 

Pp_supersend2 (self,O_WN_DRAW) ; 
self->mywin.gcid = gCreateGCo0 (self->win.id); 
hSetGFont (WS_FONT_BASE+3) ; 

gPrintText (50,50, &buf (0],p_slen(&buf[0]); 
wFree (self->mywin.gcid) ; 


VOID hSetGStyle(UINT style) ; 


This simple convenience function uses the window server function gsetcc to set the text style of the 
current graphics context to that specified by style. Possible values of style are defined in the Graphics 
Output chapter of the Window Server Reference manual. 


For example, as part of the drawing method of a win subclass, the following code fragment would create a 
a permanent graphics context with default values and then change the text style so that text characters are 
displayed in bold: 


wValidateWin (self->win.id) ; 

p_supersend2 (self,O_WN_DRAW) ; 
self->mywin.gcid = gCreateGC0 (self->win.id) ; 
hSetGStyle (G_STY_BOLD) ; 

gPrintText (50,50, &buf[0],p_slen(&buf [0]); 
wFree (self->mywin.gcid) ; 


GetBV 


INT hGetBWid (TEXT *buf, INT len); 


This function uses the window server function grextwidth to calculate and return the width, in pixels, of 
the first 1en characters in the buffer pointed to by but . This function assumes that the text would be 
displayed using the current system font (i.e system_ronT_rp) and a normal style (i.e G_STY_NORMAL ). 


This is useful for planning the size and positioning of text in relation to surrounding text and graphic 
objects. 


24-7 


HWIM REFERENCE 


hGetSWid _ Get normal text width for string 
INT hGetSWid (TEXT *pzts) ; 
This is similar to the function hcetBwid. 


It calculates and returns the width, in pixels, of the zero terminated string pointed to by pzts. Like 
hGetBwid, this function assumes that the text would be displayed using the current system font (i.e 
SYSTEM_FONT_ID) and a normal style (i.e G_stTy_ NORMAL ). 


This function is useful for planning the size and positioning of text in relation to surrounding text and 
graphic objects. 


for buffer 


INT hGetBBWid (TEXT *buf, INT len); 


This is similar to the function hcetBwid in that it uses the window server function gTextwidth to calculate 
and return the width, in pixels, of the first 1en characters in the buffer pointed to by but . This function 
assumes that the text would be displayed using the font with id Bo.p_FowrT_rp and a normal style (i.e 
G_STY_NORMAL ). 


This is useful for planning the size and positioning of text in relation to surrounding text and graphic 
objects. 


User notification 


This group of functions is concerned with informing, warning and alerting the user in a variety of ways. 


VOID hIinfoPrint (INT rid, ...); 


ay ani information message 


This function prints an information message window in the bottom right hand corner of the screen for 2 to 
2.5 seconds or until cancelled. 


The zero terminated text of the message is generated from a format string and the arguments which follow 
the parameter rid. The format string is loaded from the resource rid in a resource file. 


For more detail on the structure of the format string, see the description of the PLIB function p_atob in the 
PLIB Reference manual 


There are a number of important points to note: 
e the length of the format string in the resource file, when loaded, must not be greater than 80 bytes 


e if the generated text is greater than w_INFo_MsG_MAX_LEN bytes then the message will appear 
truncated 


e the generated text including the zero terminator must not, in any event, be greater than 80 bytes. 
If an error occurs, p_leave is called. 
The following code fragment provides a simple example of the use of this function. 


The string in the resource file referenced by the resource id RID_OF_MY_FORMAT_STRING contains the 25 
character sequence: 


The numbers are td and %d 


the effect of the following code fragment: 


24-8 


24 HWIM UTILITY FUNCTIONS 
—.— EE ILI YY BUNCTIONS 


INT numl,num2; 


INT rid; 
numl = 65; 
num2 = 66; 


rid = RID_OF_MY_FORMAT_ STRING; 
hInfoPrint (rid, numl,num2) ; 


is to display the message: 
The numbers are 65 and 66 


in the bottom right hand corner of the screen. 


VOID hInfoPrintErr(INT err) ; 


This function prints an error information message window in the bottom right hand comer of the screen for 
2 to 2.5 seconds or until cancelled. 


The text of the message is related to the error number in err and is obtained in exactly the same way as 
described in the function hErrs; see the description of herrs for more information. 


If an error occurs, p_leave is called. 


a ge 


VOID hBusyPrint (INT delay, INT rid, ...); 


This function prints a flashing message window in the bottom left hand corner of the screen. The display of 
the message can be delayed by the number of half-seconds specified in the delay parameter; this can range 
from 0 to 63. 


The zero terminated text of the message is generated from a format string and the arguments which follow 
the parameter rid. The format string is loaded from the resource rid in a resource file. 


The message may be removed by a call to the window server function wcancelBusyMsg. 


For more detail on the structure of the format string, see the description of the PLIB function p_atob in the 
PLIB Reference manual 


There are a number of points to note: 


© the generated text including the zero terminator must not be greater than 30 bytes. (Note that this 
is less than the 80 bytes common for other functions) 


e the length of the format string in the resource file, when loaded, must not be greater than 80 bytes 
If an error occurs, p_leave is called. 


A common use of a flashing message area in the bottom left hand comer of the screen is to display a 
"busy" type messge to inform the user that the work in progress could take some time to complete. 


hBeep 


VOID hBeep (VOID) ; 


This is a convenience function that makes a short beep sound suitable for accompanying an error 
notification. It can, of course, be used wherever an application sees fit. 


The function is implemented by making the following call: 
P_sound(-5,320); 


The beep is sounded for a duration of 5 system ticks (that is 5/32 sec) at a frequency of 512/320 KHz (that 
is 1.6 KHz). 


24-9 


HWIM REFERENCE 


SS a ae a a) 
Run a dialog 


This group of functions is concerned with starting some standard dialogs and launching dialogs in general. 


hLaunchDial oe Launch a dialog 
INT hLaunchDial(P_CATID cat, INT class, DL_DATA *data); 


This is a convenience routine which loads, initialises and runs a dialog. The parameter cat is the category 
number of the dialog class while the parameter class is its class number. 


The pi_para struct is defined in hwimman.g as: 


typedef struct 


{ 


UWORD id; /* resource id of a DIALOG resource*/ 

VOID *rbuf; /* address of result buffer, or NULL */ 

PR_DLGBOX **pdlg; /* address of where to write handle of dialog, or NULL */ 
} DL_DATA; 


The function is implemented as shown below by sending a o_ws_po_pIaL message to the wseRv object. 
p_sends (w_ws,O_WS_DO DIAL,p_getlibh(cat) ,class, data) ; 


hLaunchDial returns whatever value that the method o_ws_po_prau returns. This will be zero for dialogs 
cancelled without the intervention of application code. 


INT hConfirm(INT rid,...); 


This is a convenience routine which presents a standard one line query dialog which returns a TRUE or 
FALSE value. This type of dialog is often used to ask a user to confirm an intended action. 


The text of the dialog is generated from a format string and (optionally) a number of arguments. The 
format string is loaded from the resource rid in a resource file while the arguments (if any) are interpreted 
as for the PLIB function p_atos. More information on p_atos can be found in the PLIB Reference manual. 


The function is implemented as shown below by sending a o_ws_QUERY_DIALOG message to the WSERV 
object. 


p_sends (w_ws,O_ WS QUERY _DIALOG,0,rid,&rid+1l) ; 


hConfixrm returns whatever value that the method o_ws_QuERY DIALOG retims. This will be rruz if the user 
confirms the action. 


There are a number of points to note: 
e — the length of the format string in the resource file, when loaded, must not be greater than 80 bytes. 
e the resulting text string must not be greater than 100 bytes. 


If the resulting text string is sufficiently large to force the width of the resulting dialog box to exceed the 
width of the window, then a panic will result. 


_ Run a two: n dialog 


INT h2LineConfirm(INT secondrid, INT rid, ...); 


This is a convenience routine which presents a two line query dialog which returns a TRUE or FALSE value. 
This type of dialog is often used to ask a user to confirm an intended action. 


The function is very similar to the function hconfirm described earlier. The first line of text of the dialog 
is generated from a format string and (optionally) a number of arguments. The format string is loaded from 
the resource rid in a resource file while the arguments (if any) are interpreted as for the PLIB function 
p_atos. The second line of text is basic text and is loaded from the resource secondrid in a resource file. 


24-10 


24 HWIM UTILITY FUNCTIONS 
2 —S$S ee EI MITT POUNCTIONS | 


The function is implemented as shown below by sending a o_ws_QUERY_DIALOG message to the wSERV 
object. 
p_sends (w_ws,O_WS_QUERY_DIALOG, secondrid, rid, &rid+1) ; 


h2LineConfirm returns whatever value that the method o_ws_QueRY_praLoc retums. This will be rRus if 
the user confirms the action. 


There are a number of points to note: 
e the length of the format string in the resource file, when loaded, must not be greater than 80 bytes. 
e the resulting text string must not be greater than 100 bytes. 
e the second line of text in the resource file must not be greater than 100 bytes. 


If either of the resulting text strings is sufficiently large to force the width of the resulting dialog box to 
exceed the width of the window, then a panic will result. 


INT hErrorDialog(INT err, INT rid, ...); 


This is a convenience routine which presents an error dialog with text derived from the error number and a 
string resource. It returns a zero if the dialog was presented successfully. It returns a non-zero value if the 
dialog presentation failed due to an out of memory error, in which case the dialog remains to be cleaned up 
(use the OLIB convenience function ci_clean_level, described in The CLEANUP Class chapter in the 
OLIB Reference manual). 


The text derived from the resource file is generated from a format string and (optionally) a number of 
arguments. The format string is loaded from the resource with ID ria, while the arguments (if any) are 
interpreted as for the PLIB function p_atos. 


The function is implemented as shown below by sending a o_ws_ERROR_DIALOG message to the WSERV 
object. 


p_sends (w_ws,O WS_ERROR_DIALOG, err, rid, &rid+1) ; 

There are a number of points to note: 
e the length of the format string in the resource file, when loaded, must not be greater than 80 bytes. 
e the resulting formatted text string must not be greater than 80 bytes. 


This type of dialog is often used for the reporting of errors of a moderately serious nature; minor errors 
should use hinfoprintError described earlier and more serious errors should use the application 
manager's am_notify method. 


Dialog box utilities 


The following utility functions are available for performing standard operations on the component controls 
of a dialog. They may be used directly by an application, or used as models for the construction of 
application-specific utilities. 


The code of each used utility function is included in the application. These functions have optimised 
calling conventions and therefore offer a modest saving over the equivalent function supplied by the 
application itself. 


Note that these utilities assume that the dialog handle is stored in the magic static patpialogPtr. Thus they 
may not be used with any dialog which contains the pL¢Box_no_pnp flag in dlgbox. flags. 


_ Set an item 


VOID hDigSet (UBYTE index, VOID *pset); 


This function is a generalised way of setting data (or property) into the control of one of the components of 
the current dialog and is used in the more specialised dialog box utility functions described later. 


24-11 


HWIM REFERENCE 


As stated in the introduction to this section, it is assumed that patpialogPtr points to the current dialog 
object. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). The parameter pset is assumed to point to the appropriate structure 
containing the information to be set . The class which defines the referenced dialog box component 
control, will have defined a o_wn_seT method and will "know" how to interpret the data pointed to by 
pset. 


The function is implemented by sending a o_wn_seT message to the current dialog object as shown below: 


p_send4 (DatDialogPtr,0O_WN_SET, index, pset) ; 


hbigsé 


VOID hDlgSetText (UBYTE index, TEXT *buf) ; 


This function sets text into the control of one of the current dialog's components. The control is assumed to 
be an instance of rextwrn or a subclass. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). The parameter bu is assumed to point to a zero terminated string 
containing the text to be set. 


This function is implemented as shown below. Note that it uses the more generalised function npigset 
described earlier. 


GLDEF_C VOID hDigSetText (UBYTE index, TEXT *buf) 


{ 


SE_TEXTWIN settxt; 


settxt .buf=buf; 

settxt.len=p slen(settxt.buf); 
settxt.flags=<SE_TEXTWIN_TEXT; 
hDigSet (index, &settxt) ; 


VOID hDlgSetEdwin(UBYTE index, Text *buf) ; 


This function sets text into the control of one of the current dialog's components. The control is assumed to 
be an instance of Epwrn or a subclass. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). The parameter but is assumed to point to a zero terminated string 
containing the text to be set. 


This function is implemented as shown below. Note that it uses the more generalised function hpigset 
described earlier. 


GLDEF_C VOID hDlgSetEdwin(UBYTE index, TEXT *buf) 


{ 


SE_EDWIN set; 


set.buf=buf; 
set.len=p_slen(set.buf) ; 
hDlgSet (index, &set) ; 


} 


VOID hDlgSetPrompt (UBYTE index Text *buf) ; 


This function sets text into the prompt of one of the current dialog's components. 


Note that the component's prompt must exist prior to a call to hD1gSet Prompt. This function merely 
replaces the text of the prompt and can not be used to add a prompt to a component, if one was not 
originally specified in the dialog's resource. 


24-12 


24 HWIM UTILITY FUNCTIONS 
TOTO rN 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). The parameter buf is assumed to point to a zero terminated string 
containing the prompt text to be set. 


This function is implemented as shown below. It may be of interest to point out that the 0 _pL_SET_PROMPT 
method uses the more generalised function hp1gset described earlier. 


GLDEF_C VOID hDlgSetPrompt (UBYTE index, TEXT *buf) 


{ 


SE_TEXTWIN settxt; 


settxt.buf=buf; 

settxt.len=p_slen(settxt.buf) ; 
settxt.flags=SE_TEXTWIN_TEXT; 

p_send4 (DatDialogPtr,O_DL_SET_PROMPT, index, &settxt) ; 


} 


VOID hDlgSetChlist (UBYTE index, INT nsel); 


This function sets the choice number in a choice list control within one of the current dialog's components, 
ultimately causing that item in the list to be displayed (or highlighted if the whole list is shown). The 
parameter nsel holds the number of the choice to be set (where a value of 0 refers to the first item in the 
choice list). 


The particular component within the current dialog is identified by the index parameter (the first 
component is identified by an index value of 0) and is assumed to be an instance of (or a subclass of) 
CHLIST. 


This function is implemented as shown below. Note that it uses the more generalised function npigset 
described earlier. 


GLDEF_C VOID hDlgSetChlist (UBYTE index, INT nsel) 


{ 


SE_CHLIST set; 


set .nsel=nsel; 
set.set_flags=SE_CHLIST_NSEL; 
hDlgSet (index, &set) ; 


VOID hDigSetChlistOn(UBYTE index) ; 
This function is a specialised version of the function hp1gsetchlist described earlier. 
It sets the choice number in a choice list control to 1. 


The particular component within the current dialog is identified by the index parameter (the first 
component is identified by an index value of 0) and is assumed to be an instance of cuurst or a subclass. 


This function can be used with any choice list but is especially useful if used in conjunction with an Off/On 
choice list (using the system resource sys_oFFoN_MENU) . If the current dialog has a component containing 
this choice list, then using this function (with the appropriate index) will set the choice list to On. 


This function is implemented as shown below. Note that it uses the more generalised function 
hDlgSetChlist described earlier. 


GLDEF_C VOID hDlgSetChlistOn(UBYTE index) 


{ 


hDigSetChlist (index,1) ; 


} 


24-13 


HWIM REFERENCE 


hi 


VOID hDlgSetNcedit (UBYTE index, UINT value) ; 


Set value of numeric editor 


This function sets a value into the control of one of the current dialog's components. The control is 
assumed to be an instance of the numeric editor (wceprr) or a subclass. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). 


The value passed to the function in the parameter value can be any valid urnt type. 


This function is implemented as shown below. Note that it uses the more generalised function npigset 
described earlier. 


GLDEF_C VOID hDlgSetNcedit (UBYTE index, UINT value) 


{ 


SE_NCEDIT set; 
set.value=value; 


set.flags=SE_NCEDIT_VALUE; 
hDigSet (index, &set) ; 


2 editor 


nigituc 


VOID hDlgSetLledit (UBYTE index, INT value); 


This function sets a value into the control of one of the current dialog's components. The control is 
assumed to be an instance of the latitude/longitude editor (LueprT) or a subclass. Whether the dialog 
control represents a latitude or a longitude depends on the way the editor is initialised. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). 


The value passed to the function should represent the number of minutes of latitude or longitude. A 
positive value represents the number of minutes North or West while a negative value represents the 
number of minutes South or East, respectively. 


For a latitude, the magnitude of the value should be no greater than 5399 minutes ( that is, 89 degrees and 
59 minutes).For a longitude, the magnitude of the value should be no greater than 10799 minutes ( that is, 
179 degrees and 59 minutes). Larger values may be passsed but the editor will assume the appropriate 
maximum value. 


This function is implemented as shown below. Note that it uses the more generalised function nplgset 
described earlier. 


GLDEF_C VOID hDlgSetLledit (UBYTE index, UINT value) 


{ 


SE_LLEDIT set; 


set.value=value; 
hDlgSet (index, &set) ; 


} 


For example, if the third dialog component in the current dialog box contains a longitude editor control and 
the fourth component contains a latitude editor control, then the code fragment: 


hDlgSetLledit (2,5110) ; 
hDlgSetLledit (3, -2010); 


will set the respective editor values to: 


85° 10' West and 33° 30' South. 


24-14 


24 HWIM UTILITY FUNCTIONS 


hDigSetPtedit oe Set punctuation editor 
VOID hDigSetPtedit (UBYTE index, UBYTE ch); 


This function sets a value into the control of one of the current dialog's components. The control is 
assumed to be an instance of the punctuation editor (puNcTuED) or a subclass. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). 


The function allows the single character, passed in the parameter ch, to be set. Although an instance of a 
PUNCTUED Class restricts user-keyed input to a valid punctuation character, the value passed in ch can be any 
valid character acceptable to epwin, the immediate superclass of puncruED. 


This function is implemented as shown below. Note that it uses the more generalised function 
hD1lgSetEdwin described earlier. 


GLDEF_C VOID hDlgSetPtedit (UBYTE index, UBYTE ch) 


{ 


INT chx; 
chx=ch; 
hDlgSetEdwin (index, (TEXT *) (&chx)) ; 


} 


For example, if the third dialog component in the current dialog box contains a punctuation editor control, 
then the following call would set the punctuation character to a comma: 


+ 


hDigSetPtedit(2,','); 


hDigSetFledit 


VOID hDlgSetFledit (UBYTE index, DOUBLE *pvalue) ; 


_ Set floating 


This function sets a value into the control of one of the current dialog's components. The control is 
assumed to be an instance of the floating point editor (FLEDIT) or a subclass. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). 


The function allows the floating point number, pointed to by the parameter pvaiue, to be set. This must be 
a valid double value otherwise the function does nothing. 


This function is implemented as shown below. Note that it uses the more generalised function nplgset 
described earlier. 


GLDEF_C VOID hDlgSetFiedit (UBYTE index, DOUBLE *pvalue) 


{ 


SE_FLTEDIT set; 
p_fld(&set.current,pvalue) ; 

set. set_flags=SE_FLTEDIT_CURRENT . 
hDlgSet (index, &set) ; 


} 
SetDiedit = = . Set date editor 


VOID hDigSetDtedit (UBYTE index, ULONG value) ; 


This function sets a value into the control of one of the current dialog's components. The control is 
assumed to be an instance of the date editor (pTeprT) or a subclass. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). 


24-15 


HWIM REFERENCE 


The function allows the value passed in the parameter value, to be set. The interpretation of the value 
depends on the nature of the data displayed by the control, as specified during its initialisation (see the 
description of preprt in the Numeric Editors chapter). The possible cases are summarised in the following 


table. 
Date editor IN_DTEDIT_DDMMYYYY Days elapsed since 01/01/1900. Note that the 
control can not display dates before 01/01/1980. 


Time of day editor IN_DTEDIT_HHMMSS Seconds elapsed since midnight. 
IN_DTEDIT_HHMM 


Time duration editor IN_DTEDIT_HHMMSS_D 
IN_DTEDIT_HHMM_D 
IN_DTEDIT_HHMMSS_ND 
IN_DTEDIT_HHMM_ND 


This function is implemented as shown below. Note that it uses the more generalised function hpigset 
described earlier. 


GLDEF_C VOID hDlgSetDtedit (UBYTE index, ULONG value) 


{ 


SE_DTEDIT set; 


set .value=value; 
set.flags=SE_DTEDIT_VALUE; 
hDlgSet (index, &set) ; 


} 


hDig 


VOID hDigSetRgedit (UBYTE index, UINT valuel, UINT value2); 


_ Set range editor 


This function sets values into the control of one of the current dialog's components. The control is assumed 
to be an instance of the range editor (RcEprT) or a subclass. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). 


The function allows the upper and lower limits for the range passed in the parameters value1 and value2 
respectively, to be set. The range editor is a subclass of the Mrwe (multiple field numeric editor) class. 


This function is implemented as shown below. Note that it uses the more generalised function hp1gset 
described earlier. 


GLDEF_C VOID hDlgSetRgedit(UBYTE index, UINT valuel, UINT value2) 


{ 


SE_RGEDIT set; 
set .value [IX_RGEDIT_VALUE_1] =valuel; 
set.value [IX_RGEDIT_VALUE_2] =value2; 


set .flags=SE_RGEDIT_VALUE_1|SE_RGEDIT_VALUE_2; 
hDlgSet (index, &set) ; 


The symbols 1x_RGEDIT_vALUE_1 and IX_RGEDIT_vALUE_2 are defined in the include file rgedit.g. 


Set dialog title 


VOID hDlgSetTitleByRid(INT rid) ; 


The function sets the title of the current dialog box to the zero terminated text referenced by the resource id 
rid in a resource file. 


This function is implemented as shown below. The title of a dialog box is always the first component of 
that dialog box and, therefore, is always referenced by an index value of zero as demonstrated in the 
implementation of hplgSetTitlebyRid, shown below. 


24 - 16 


24 HWIM UTILITY FUNCTIONS 
i a NW EEE ENC TIONSE 


GLDEF_C VOID hDlgSetTitleByRid(INT rid) 


{ 


TEXT buf [60] ; 


hLoadResBuf (rid, &buf[0)); 
hDlgSetText (0, &buf [0] ); 


} 


A few points to note: 
e the appropriate text string in the resource file, when loaded, cannot be greater than 60 bytes. 


e if the text string is sufficiently large to force the width of the resulting dialog box to exceed the 
width of the window, then a panic will result. 


hDigSense an item 


VOID hDigSense(UBYTE index, VOID *psense) ; 


This function is a generalised way of sensing or retrieving data (or property) from the control of one of the 
components of the current dialog and is used in the more specialised dialog box utility functions described 
later. 


As stated in the introduction to this section, it is assumed that patbialogPtr points to the current dialog 
object. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). The parameter psense is assumed to point to the appropriate structure in 
memory into which the information is to be placed. The class which defines the referenced dialog box 
component control will have defined a o_wN_seNsE method and will "know" how to interpret the data 
structure pointed to by psense. 


The function is implemented by sending a o_wN_SENSE message to the current dialog object as shown 
below: 


p_send4 (DatDialogPtr,0O _WN_SENSE, index, psense) ; 


"Sense edit window 


TEXT *hDlgSenseEdwin(UBYTE index) ; 


This function senses the text from the control of one of the current dialog's components. The control is 
assumed to be an instance of EDWIN or a subclass. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). 


The function returns a pointer to a zero terminated string representing the text in the edit window. 


This function is implemented as shown below. Note that it uses the more generalised function hplgSense 
described earlier. 


GLDEF_C TEXT *hDlgSenseEdwin(UBYTE index) 


{ 


SE_EDWIN sense; 


hDlgSense (index, &sense) ; 
return (sense.buf) ; 


} 
For example the following code fragment copies the text sensed from an edit window into another buffer; 
the example assumes that the edit window is contained in the second component in the current dialog box: 


TEXT buf [100]; 


p_scpy (&buf [0] , hDlgSenseEdwin (1) ); 


24-17 


HWIM REFERENCE 


hDigSenseChlist _ . Sense a choice list 
INT hDlgSenseChlist (UBYTE index) ; 


This function senses the choice number of the currently highlighted/selected choice item in a choice list 
control in a component of the current dialog and returns that value. A value of 0 refers to the first item in 
the choice list. 


The particular component within the current dialog is identified by the index parameter (the first 
component is identified by an index value of 0). The contro] is assumed to be an instance of cunzst ora 
subclass. 


This function is implemented as shown below. Note that it uses the more generalised function np1gsense 
described earlier. 


GLDEF_C INT hDlgSenseChlist (UBYTE index) 


{ 


SE_CHLIST sense; 


hD1lgSense (index, &sense) ; 
return (sense .nsel) ; 


} 


For example, the following code fragment sets text in an edit window depending on the current item 
selected in the choice list; the choice list and the edit window being (for the sake of the example) in the 
current dialog: 


#define CHOICE _TEXT_YES 1 
#define CHOICE TEXT_NO 2 


TEXT buf [2]; 


buf£[1] = '\0'; 

if (hDlgSenseChlist (2) == CHOICE_TEXT_YES) 
buf[0) = 'Y'; 

else 
buf[0] = 'N'; 

hDlgSetText (3, &buf[0]); 


UINT hDlgSenseNcedit (UBYTE index) ; 


This function senses the value from the control of one of the current dialog's components. The control is 
assumed to be an instance of the numeric editor (ceprr) or a subclass. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). 


The function returns the value currently held by the editor. 


This function is implemented as shown below. Note that it uses the more generalised function np1gsense 
described earlier. 


GLDEF_C UINT hDigSenseNcedit (UBYTE index) 


{ 


SE_NCEDIT sense; 
hDlgSense (index, &sense) ; 


return (sense.value) ; 


} 


24-18 


24 HWIM UTILITY FUNCTIONS 


nseRgedit _ _ Sense a range editor 


VOID hDlgSenseRgedit (UBYTE index, UWORD *pvalues) ; 


This function senses values from the control of one of the current dialog's components. The control is 
assumed to be an instance of the range editor (RcEpIT) or a subclass. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). 


The function senses the upper and lower limits of the range and places the two values into the first two 
words of memory pointed to by pvalues. It is the caller's responsibility to supply the two words of 
memory. The range editor is a subclass of the mene (multiple field numeric editor) class. 


This function is implemented as shown below. Note that it uses the more generalised function hp1gsense 
described earlier. 


GLDEF_C VOID hDligSenseRgedit (UBYTE index, UWORD *pvalues) 
SE_RGEDIT sense; 
hDlgSense (index, &sense) ; 


*pvalues++=sense.value [IX_RGEDIT_VALUE_1]; 
*pvalues=sense.value [IX_RGEDIT_VALUE_2] ; 


The symbols 1x_RGEDIT_VALUE_1 and 1x_RGEDIT_VALUE_2 are defined in the include file rgedit.g. 


VOID hDlgSenseFledit (UBYTE index, DOUBLE *pvalue) ; 


This function senses the value from the control of one of the current dialog's components. The control is 
assumed to be an instance of the floating point editor (FLEDIT) or a subclass. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). 


The function senses the floating point value and places it in the memory pointed to by pvalue. It is the 
caller's responsibility to supply this memory location. 


This function is implemented as shown below. Note that it uses the more generalised function npigset 
described earlier. 


GLDEF_C VOID hDigSenseFledit (UBYTE index, DOUBLE *pvalue) 


hD1lgSense (index, pvalue) ; 


hDigSenseLledit 


INT hDlgSenseLledit (UBYTE index) ; 


ide editor 


This function senses a value from the control of one of the current dialog's components. The control is 
assumed to be an instance of the latitude/longitude editor (LLED1T) or a subclass. Whether the dialog 
component represents a latitude or a longitude depends on the way the editor is initialised. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). 


The function returns the number of minutes of latitude or longitude. A positive value represents the number 
of minutes North or West while a negative value represents the number of minutes South or East 
respectively. 


For example, a returned latitude value of -2010 means 33° 30' South while a returned longitude value of 
5110 means 85° 10° West. 


24-19 


HWIM REFERENCE 
ee a SSSSSSSSSFSSeSeeSSSSFSSSSSSSSSSSSshehe 


This function is implemented as shown below. Note that it uses the more generalised function np1gset 
described earlier. 


GLDEF_C INT hDlgSenseLledit (UBYTE index) 


{ 


SE_LLEDIT sense; 


hDlgSense (index, &sense) ; 
return (sense.value) ; 


Sense a punctuation editor 
INT hDlgSensePtedit (UBYTE index) ; 


This function senses a value from the control of one of the current dialog's components. The control is 
assumed to be an instance of the punctuation editor (puNcTUED) or a subclass. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). 


The function returns two bytes: the character currently contained within the punctuation editor and a 
terminating zero. 


This function is implemented as shown below. Note that it uses the more generalised function 
hDigSenseEdwin described earlier. 


GLDEF_C UINT hDlgSensePtedit (UBYTE index) 


{ 


return (*hDlgSenseEdwin (index) ) ; 


} 


Sense a date editor 


ULONG hDigSenseDtedit (UBYTE index) ; 


This function senses a value from the control of one of the current dialog's components. The control is 
assumed to be an instance of the date editor (ptEprr) or a subclass. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). 


The function returns the current value of the date editor. The interpretation of the return value depends on 
the nature of the data displayed by the control, as specified during its initialisation (see the description of 
DTEDIT in the Numeric Editors chapter). The possible cases are summarised in the following table. 


Date editor IN_DTEDIT_DDMMYYYY Days elapsed since 01/01/1900. Note that the 
control can not display dates before 01/01/1980. 
Time of day editor IN_DTEDIT_HHMMSS Seconds elapsed since midnight. 
IN_DTEDIT_HHMM 


Time duration editor IN_DTEDIT_HHMMSS D 
IN_DTEDIT_HHMM _D 

IN_DTEDIT_HHMMSS_ND 
IN_DTEDIT_HHMM_ND 


Seconds. 


This function is implemented as shown below. Note that it uses the more generalised function np1gSense 
described earlier. 


GLDEF_C ULONG hDlgSenseDtedit (UBYTE index) 


{ 


SE_DTEDIT sense; 


hDigSense (index, &sense) ; 
return (sense.value) ; 


24 - 20 


24 HWIM UTILITY FUNCTIONS 


hDightemDim 


VOID hDlgItemDim(UBYTE index, INT flag); 


This function changes an aspect of one of the current dialog's components. No assumption is made about 
the type of component. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). 


The function sets the dim status of the dialog box component if a value of TRUE is passed in parameter 
flag, otherwise it sets the undimmed status. 


The dialog box class pLczox implements dimming by removing the bullet which normally precedes the 
component's prompt and blanks out the component's control. 


This function is implemented as shown below by sending the current dialog a O_DL_ITEM_DIM message. 
p_send4 (DatDialogPtr,O_DL_ITEM_DIM, index, flag) ; 


VOID hDigItemLock(UBYTE index, INT flag); 


This function changes an aspect of one of the current dialog's components. No assumption is made about 
the type of component. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). 


The function behaves in a similar fashion to hpigItempim in that it sets the locked status of the dialog box 
component if a value of rruz is passed in parameter flag, and sets the unlocked status otherwise. 


The dialog box class picBox implements locking in a similar way to dimming by removing the bullet 
which normally precedes the component's prompt However, it does not blank out the component's control 
but does prevent it from being emphasised . 


This function is implemented as shown below by sending the current dialog a O_DL_ITEM_LOCK message. 


p_send4 (DatDialogPtr, O_DL_ITEM_LOCK, index, flag) ; 


hDigtakeF 


VOID hDigTakeFocus (UBYTE index) ; 


us 


je foc 


This function changes an aspect of one of the current dialog's components. No assumption is made about 
the type of component. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). 


The function changes the focus to the dialog box component identified by the index parameter. In general, 
this causes most keyboard activity to be directed to that component (with the usual exception of key and 
modifier combinations set to be captured by other processes). 


This function is implemented as shown below by sending the current dialog a DL_TAKE_ FOCUS message. 
p_send4 (DatDialogPtr,O DL TAKE FOCUS, index) ; 


This function, like the al_take_focus method itself, is not suitable for being called from the 41_dyn_init 
method. If an application wishes to set the focus on initialisation, it should do so from a replaced 
di_set_size method. It may be called from any other method (such as d1_key) once the dialog has been 
made visible. 


24-21 


HWIM REFERENCE 


hDigSetTwips — 


VOID hDlgSetTwips(UBYTE index, UINT value); 


t editor from twips value 


This function sets a value into the control of one of the current dialog's components. The control is 
assumed to be an instance of the floating point editor (FLEDIT) or a subclass. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). 


The number in the parameter value is assumed to be in twip units (that is, 1/1440 inch or 1/567 cm and 
generally relevant to word processing type applications). The function converts this value into a floating 
point measurement in the current measurement units, either inches or centimetres. The resulting floating 
point number is set in the floating point editor. 


UINT hDlgSenseTwips (UBYTE index) ; 


This function senses the value from the control of one of the current dialog's components. The control is 
assumed to be an instance of the floating point editor (FLEDIT) or a subclass. 


The particular component within the dialog is identified by the index parameter (the first component is 
identified by an index value of 0). 


The function senses the floating point value. This is assumed to contain a measurement in the current 
measurement units, either inches or centimetres. This floating point value is converted into twip units (that 
is, 1/1440 inch or 1/567 cm) and is returned by the function. 


24 - 22 


INDEX 


AM_CLEAN UP, 2-6 
AM_ENSURE IPCS, 2-8 

AM_FINDIMG, 2-7 

AM_INIT, 2-3 

AM_NEW_FILENAME, 2-7 
AM_NOTIFYERR, 2-7 

AM_RSCNAME, 2-5 

AM_WAIT, 2-6 

AM_YIELD, 2-7 

AO_ABRUN, 3-30 

AO_CANCEL, 3-10, 19-6 

AO_INIT, 3-9, 3-29, 13-3, 19-5 

AO_QUEUE, 3-10, 13-4, 17-2, 17-4 

AO_RUN, 3-11, 3-30 

COM_ACCL CHECK, 4-3 

COM_EXIT, 4-5 

COM_FILE_CHANGE, 4-4 

COM_INIT, 4-3 

COM_MENU, 4-3 

COM_MODE_CHANGE, 4-4 
COM_STATWIN, 4-3 

DESTROY, 5-4, 5-12, 6-6, 6-14, 7-11, 7-24, 8- 
10, 8-19, 8-26, 10-6, 12-13, 14-6, 16-6, 16-12, 
17-7, 18-9, 20-5, 20-8, 20-12 

DL_CHANGED, 7-21, 15-12, 15-16, 16-14, 16- 
35, 16-38 

DL_DIMMED MESSAGE, 7-19 
DL_DYN_INIT, 7-21, 7-24, 15-4, 15-6, 15-7, 
15-11, 15-14, 15-20, 15-23, 16-13, 16-16, 16-21, 
16-24, 16-27, 16-30, 16-34, 16-37, 16-41, 17-16 
DL_FOCUS, 7-21 

DL_HANDLE_TO_INDEX, 7-19 
DL_INDEX_TO_HANDLE, 7-20 

DL_INIT, 7-11 

DL_INQ_MINSIZE, 7-20, 16-22 
DL_ITEM_ADD, 7-12, 7-24, 15-6, 17-15 
DL_ITEM_APPEND, 7-13 

DL_ITEM_DIM, 7-19 

DL_ITEM_LOCK, 7-19 

DL_ITEM_NEW, 7-22 
DL_ITEM_REPLACE, 7-13 

DL_KEY, 7-16, 7-25, 15-8, 15-11, 15-15, 15-20, 
15-23, 16-14, 16-17, 16-22, 16-25, 16-27, 16-31, 
16-35, 16-38, 17-10, 17-12, 17-16 
DL_LAUNCH_SUB, 7-21, 16-12, 16-21, 16-31, 
16-35 

DL_SET_ITEM FLAGS, 7-20 

DL_SET_ PROMPT, 7-14 

DL_SET_SIZE, 7-18, 15-16, 16-14, 16-42, 17-6 
DL_TAKE FOCUS, 7-17 

EW_BRING_IN, 10-22 

EW_EP_ INSERT, 10-23 

EW_EVALUATE, 10-21 

EW_FIND, 10-20 


EW_INIT_STYLE, 10-24 
EW_INSERT, 10-19 
EW_LEAVE, 10-20 
EW_PASTE CLIP, 10-22 
EW_READONLY, 10-24 
EW_REPLACE, 10-20 
EW_REPLACE CLIP, 10-22 
EW_RETURN_KEY, 10-23 
EW_SENSE, 10-18 
EW_SENSE SIZE, 10-16 
EW_SET, 10-17 
EW_SET_FONT, 10-19 
EW_SET_SIZE, 10-16 
EW_SNUGGLE_INSERT, 10-19 
EW_TAB KEY, 10-24 
EWLS_EXTRACT, 21-2 
EWLS_INIT, 21-2 

FL_LIST COMPLETE, 14-12 
FL_LOCCHG, 14-12 
FN_LIST, 13-2 
FNS_EXTRACT_TAGS, 12-18 
FNS_INSERT_TAGS, 12-18 
FNS_SUBSET, 12-18 
FNS_VALIDATE _ FLIST, 12-18 
FS_FSCAN, 13-4 
GT_CHECK_ATS ON, 23-5 
GT_LAST_KEY, 23-5 
h2LineConfirm, 24-10 
HAI _ KEY, 17-3, 17-4 
hAppendEllipsis, 24-6 
hAtob, 24-5 

hAtos, 24-6 

hBeep, 24-9 

hBusyPrint, 24-9 

hConfirm, 24-10 

hDestroy, 24-2 
hDigItemDim, 24-21 
hDlgItemLock, 24-21 
hDigSense, 24-17 
hDigSenseChlist, 24-18 
hDlgSenseDtedit, 24-20 
hDlgSenseEdwin, 24-17 
hDlgSenseFledit, 24-19 
hDlgSenseLledit, 24-19 
hDigSenseNcedit, 24-18 
hDigSensePtedit, 24-20 
hDigSenseRgedit, 24-19 
hDlgSenseTwips, 24-22 
hDlgSet, 24-11 
hDigSetChlist, 24-13 
hDigSetChlistOn, 24-13 
hDlgSetDtedit, 24-15 
hDlgSetEdwin, 24-12 
hDigSetFledit, 24-15 
hDigSetLledit, 24-14 
hDlgSetNcedit, 24-14 
hDlgSetPrompt, 24-12 
hDigSetPtedit, 24-15 
hDigSetRgedit, 24-16 
hDigSetText, 24-12 
hDlgSetTitleByRid, 24-16 
hDlgSetTwips, 24-22 
hDlgTakeFocus, 24-21 
hEnsurePath, 24-3 
hErrorDialog, 24-11 


———__—____—_-_-_-_-_—————————— eee 


HWIM REFERENCE 


a 


hErrs, 24-4 
hGetBB Wid, 24-8 
hGetBWid, 24-7 
hGetS Wid, 24-8 
hInfoPrint, 24-8 
hInfoPrintErr, 24-9 
hInitVis, 24-2 
hLaunchDial, 24-10 
hLoadChlistResBuf, 24-4 
hLoadResBuf, 24-4 
hLoadResource, 24-3 
hSetGFont, 24-7 
hSetGStyle, 24-7 
hSetGTmode, 24-6 
hWservComSend, 24-2 
IM_INIT, 20-3, 20-5, 20-8 
IM - | KEY, 20-2 
IM | "SENSE | BUF, 20-3, 20-5 
IM | | SENSE _ __VAL, 20-3, 20-5 
IM_SET_BUF, 20-3, 20-5 
IM_SET_RANGE, 20-6 
IM_SET_VAL, 20-3, 20-5, 20-8 
IM_TRANSITION, 20-3, 20-6, 20-9 
IM_TRY_MATCH, 20-3, 20-6, 20-9 
LB_DRAW_EMPHASIS, 6-10, 6-18, 6-19, 18-8 
LB_DRAW_ITEM, 6-9, 6-17, 14-10, 18-8 
LB ; INQUIRE _ FOCUS, 6-10 
LB_INQUIRE_ITEM, 6-10, 14-11, 18-7 
LB_INQUIRE_LAST, 6-11 
LB_ITEM_WIDTH, 6-10, 6-18, 18-7 
LB_SIZE_WINDOW, 6-9 
LB_TAKE FOCUS, 6-10 
LG_DRAW, 5-12 
LG_SELF_CHECK, 5-13, 9-6, 9-27, 10-29, 12- 
§, 12-10, 12-17 
LG_SENSE_WIDTH, 5-13, 8-7, 8-12, 8-15, 8- 
21, 9-6, 10-16, 10-30, 11-3, 12-17, 17-8, 20-14 
LG_SET_ID POS, 5-12, 8-11, 10-16 
LG_UPDATE, 5-13, 12-11, 12-17 
LPR_INIT, 16-7 
LPR_READ, 16-7 
LPR | SENSE _BUF_WIDTH, 16-8 
LPR. SENSE | TEXT, 16-8 
LS_FILENAME, 16-44, 19-7 
LS_SCAN, 19-7 
MB_ADD MENU, 6-16 
MF_RANGE BEEP, 9-7 
p_false, 24-2 

) true, 24-2 
PRINTING_DO_PRINT, 16-42 
PRINTING_DONE, 16-42 
PRINTING | SET_TITLE, 16-42 
PS_NEW LIST, 13-4 
PT_COMPLETE, 19-4 
PT_GETLINE, 19-3 
PT_START, 19-3 
SV_INIT, 19-3 
SV. _RUN, 19-3 
TO. GET_SYSDAT, 22-3 
TO. SET, 22-2 
TO. SET_ABBREVIATIONS, 22-4 
TO_SET FORMAT, 22-2 
top-level windows, 5-5 
VA_COMPRESS, 8-25 
VA_COPY, 8-24 


VA_DELETEM, 8-24 

VA_INIT, 8-24, 12-2 

VA_INSERTM, 8-25 

VA_PBUF, 8-25, 8-27, 12-2 

VA_PREC, 8-25 

VA_RECLEN, 8-24 

VA_SEARCH, 12-2 

VAN_SET_MAX, 8-27 

WLD_RESTRICT, 20-14 

WN_CALC POSITION, 5-6 
and WN_POSITION, 5-7 

WN_CONNECT, 5-5, 6-19 
and WN_POSITION, 5-7 

WN_DODRAW, 5-5 

WN_DRAW, 5-8, 5-9, 6-8, 6- 

17, 8-5, 8-11, 8-15, 8-20, 9-6 

3.177.20619 

WN_EMPHASISE, 5-6, 5-10, 6-8, 7-20, 8-7, 8- 

21, 9-6, 9-27, 10-16, 10-31, 12-10, 18-10, 20-14 

WN_INIT, 5-7, 5-12, 6-6, 6-14, 6-20, 8-5, 8-10, 

8-15, 8-19, 8-22, 9-14, 9-17, 9-20, 9-25, 9-30, 9- 

33, 10-6, 10-27, 11-2, 12-4, 12-8, 12-14, 14-6, 

17-7, 18-6, 18-10, 20-12 

WN_KEY, 5-7, 6-7, 6-15, 6-17, 7-15, 8-6, 8- 

8-19, 9-5, 9-27, 10-10, 10-25, 10-30, 12-5, 1 

12-16, 14-7, 17-8, 18-7, 18-10, 20-13 

WN_POSITION, 5-7 

WN_REDRAW, 5-5 

WN_SENSE, 5-8, 7-14, 8-6, 8-11, 8-21, 8-23, 9- 

15, 9-18, 9-21, 9-26, 9-31, 9-33, 10-15, 10-28, 

10-31, 12-9, 12-16, 14-10, 20-13 

WN_SENSE_ HELP, 5-6, 7-20, 10-15 

WN_SET, 5-8, 7-14, 8-5, 8-21, 8-23, 9-6, 9-15, 

9-18, 9-21, 9-26, 9-30, 9-33, 10-15, 10-28, 10- 

31, 11-3, 11-5, 12-5, 12-9, 12-14, 20-12 

WN_VISIBLE, 5-6, 5-12, 6-14, 18-10 

WS_ADD DIAL, 3-15 

WS_ADD_FILELIST, 3-22 

WS_ALERT, 3-21 

WS_ANIM_TICK, 3-23 

WS_APPEND_COUNTRY, 3-21 

WS_ATTACH_APP, 3-26 

WS_BACKGROUND, 3-23 

WS_CANCEL, 3-10 

WS_CHANGE_CLIWIN, 3-14 

WS_DATE_CHANGED, 3-24 

WS_DEFINE_FNBAR, 3-24 

WS_DIAL_ENV, 3-20 

WS_DO DIAL, 3-15 

WS_DO_HELP, 1-2, 3-16 

WS_DO_REMOTE_DIAL, 3-27 

WS_DO_SUBMENJU, 3-18 

WS_DYN_INIT, 3-9 

WS_EDIT_PDEV_SETUP, 3-22 

WS_EDIT_PRINT_CONTEXT, 3-22 

WS_ENS_PRINT_CONTEXT, 3-22 

WS_ERROR_DIALOG, 3-19 

WS_EVAL ENV, 3-19 

WS_EVALUATE, 3-19 

WS_FILE_ INFO PRINT, 3-27 

WS_FOREGROUND, 3-23 

WS_FORMAT DIALOG, 3-20 

WS_FREE DIAL, 3-17 

WS_GET_ALLOC_INFO, 3-25 

WS_GET_ PRINT_CONTEXT, 3-25 


6-19, 6-20, 7- 
1 


15; 
, 10-15, 10-31, 11- 


11, 
2-9, 


ae SS 


WS_HIDE_APP, 3-26 
WS_LAUNCH_DYL, 3-24 
WS_LOAD_CHLIST RES, 3-16 
WS_LOCK, 3-17 
WS_PROCESS KEY, 3-12 
WS_QUERY_DIALOG, 3-18 
WS_REMOVE_DIAL, 3-16 
WS_REMOVE FILELIST, 3-23 
WS_RESET_MENUBAR, 3-17 
WS_RUN_MEMO, 3-27 
WS_SELF_CHECK, 3-26 
WS_SENSE_ ACCEL, 3-15 
WS_SENSE_PDEV_TEXT, 3-22 
WS_SET_MENUBAR, 3-17 
WS_SMART DIAL, 3-21 
WS_SWITCH_FILES, 3-17 
WS_UNKNOWN_ WM, 3-23 
WS_USER_ABANDONED, 3-28 
WS_WRAP_PARA, 3-16 


INDEX 


