sibo-playground/docs/4-03 XADD Reference 2.11_djvu.txt

SIBO 'C' Software Development Kit 


XADD 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, Psion MC, Psion HC, Psion Series 3, Psion 
Series 3a amd 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 


M Van CeO ue tO an seis a sccazg oS vos ca casa sanseacssiccatceases oattesostveisavdesaatesciseens tee Sctacdin ieee ES 1-1 
MISIN ADDClasSes teseic:t 9 cbasats tec cores Aad Oi cciea sth ohaals eae cect cg mee ee 1-1 
DOTA Ns 5 8222s gest GE Neots te cue, Senses ics aoa ged dees Mae he get cace anita, SOR ct 1-2 
INAMIES 5 sus ctaresranesss tsspasteesacttat scoala 2 tawileet vases tesa eee aMie et m 1-2 
Method fumetion prototypes . sccc.censiniedsccceavseasovcteeoesiasdvatdeaveee nl Oe aA cs >. 1-2 

Tile MOP edvie- SYM x. 2202: cs, sors cyeue bndiacnaeachcoreeavees SUA weld, ote ke MN 1-2 
CTBSS eA TATE costs cys cainaageedes op uacshuesses tony es outesdena leans aa RN NM, 1-3 
GlASS METAL CW an acssseineqerbiascne ss Gverciiisanasiusesyecdc ee ac ee 1-3 
Siuichuredse ror Recovery 271... 2065 see tvssts da cdsssnd ce eestlonesiniaseteeseoteteedene: Galen cach, samtecks 1-4 
Use: of theip leave mechamisinn...5- cic) ccndssscscoecsksstetvacsccectuseatvitvessecsscaceecisatgestiasievevescs 1-4 
FPBIVIC TOMI daeg tae gaatn sscec ance uae vaesrt va acd inseie tacts aha RON ee 1-4 


SO OO eo 


2 Brant Preview CLASSES secs neaisesonsseeosccctssenscasine yuseati cases besa satesivesestosehtisesies tina Ae 2-1 
BPE CUT GOS acs overs p tin cds toc Shar peeissst cousin 'eatedib Gattasos see Anan coun tase eae Ne oc 2-1 
Classidid gram «0... icics tects ances sxereetireicerestrstee eet oNo TTC e aT 2-2 

TS PPRUIN TER oes feet insect ils acd docu rin de vrueha canes tery seta oot tis cc nae oe ets eo 2-2 
ELAS 5 CEPT OM 36s sasisiived Ae cosstcatans wp eagencesst AG dees Maced tcciaadesiwea orivatiene atone See 2-3 
PRODGMY cxdis cactstaas sass Phissn atau ca naceectinns es ited vpicas viaabccsiilings tla piece hag d MME es otis 2-3 

PIE V DGG eno dS scictecc ht iatie eects gis Manes tere alee chat ce tren Beeee pace fs 2-3 
DGS TROY ida ante carta Irenaita ac tesa abet ee Mat cl tac eh to A Eh oa eh, OG 2-3 
TIWELGNS sc Sietateestczisiguse sean sayac sonicated luli a ticked ecas edithnss pdag athe amie ah oxo eRe ea a 2-3 

BRYN UE Wide setcay oy ccutatstd tedtteiesssccsesa ee enn Mya lol Ne Gioia a ene ee eet on. 3 2-4 
PASS He Mtg ENON 35st co eta ncadeseeitrlcd vines Mecsas Shag AON AMRE ets 2-5 
ROBT eh oieta Secenh et tncasctaista ctukate cS ENG sik vaste pieat shes dotoga cei tealuieie: cone pula ng 2-6 
ESOMICES uta nec ee ee ete ann tt iettiiiae 2-10 

TPIS V VEE Ws OV CUA aon tn chans Ove ase Se vasdistt nas cucusasac ch aod easier imcacteanvstvar tive Machen, 2-10 
WD OSOY 9 erase BRITE se oak erate es caldulet Mth ita can Lah Sayan ha le ek te St ete 2-10 
Wann ese RES Sse c2etac a at oa cetera sade cas cevadicssdenabsad Mee teats etl che clacton 2-11 
TOGA cs cnthatacwcst ist oll wages eases less, wena ta Mei lava elaohd pubs enceasan aaa es AO 2-12 
SEE GISPIAY MOE fe :caa2, Fete teciasccncisaats stop dan aves goth saa settee anes due MO ROE ke 2-12 
PAVED MTS a sass ah aan eua les taal cae abavaittandinetAosaete cata saeuennrenican mavcsooce ith cite aeeics 2-12 
COMPpleMOn Cal DACK: occa jcsdvusns-cishsesseaeayieoneodivins nanan sie aaumncanlas Sc ilecieso state 2-14 
CoOninpletroni:c all DAC 2.65 cata ncn-se-ecgst cogent pyseed sonata si avdovpactseestecustuation at actibeacssale hes 2-15 
MiG Geman S:5728. 6 Stata oaise Nata es OI i eco ee eth Mae Pe ete a 2-15 
MOVE TODA vcev certs cecasts Gist dint orks hateraua oa obtain Bias tdi Gnas dan teed amieade ee eae 2-15 
Tine oy fees wes. pees tpesnatesasr vacate catego tastier, Slabs echo sheteetatiaiad SR eam sco otis! 2-15 

RS VAINE Ostet nese ac so aad a OT a asuhsbat oud oa ee ie ta ce oe een 2-16 
TASS GEMMA OM rates vis Haste sat on dstah oes ctec ceacna hance adel aaah oa teh teak 2-16 
TOP GIy eM sere cardiandclabinttidnatharwntieae we eai cuca ada Ravinia eA ein CER, DARA 2-17 
WRESO MICO Sin aScrascreeecesce dite ve pctasates vy tail cas eae eater ae tatiana eV: 2-17 

RW DINE O iC BO sas inch Best tuebts casesaiancauva ioe ao decteaiviatiloalown taba sco aes tacengee 2-17 
1 Ly) C DES aren y A oN ean RPE ND EOE OO rte ERR RED Anas aaa 2-17 
DOUUIMDER OF PARES sa: erat crscatce leacivocnatsravcioer Denso vidas tawdddnslaeseotatkoon ec ookeosnacde atdes 2-17 
DNA W ie, cress scan ek Mts MEAT, Muiiabe gee vii sc oe ta et ne maa 2-17 


CEVASS se TIME ON cata tts os Mana ben aragthGoindicls luo dessMndsleniessased adenec' ei, We ee gk oer 2-19 
PMO PUL cose estat: d2s hu panies ed cupetoenee pesevte vise testnasicedce sant ccxah sees’ cea ae aa 2-19 
BROLIN CES 5c cs races auasatgeiaussrs isan acacidet mncsrauvittalaacat toa emia ae ae ee 2-19 
PRY PAGE re MOds izle 2 bic cetenesd, At teacd cde UB aa eaeTks vecige nari eee helenae 2-20 
MNO TANG EE Ws Siesta te tees ache th ce EN Peres iti io ee a Serre Leesa NEDEIR Sj oatrh 2-20 
Ma Week sscessevaisittd tee ine peas intense eGcieeatent a Mh a een ee Re Re eta 2-20 
PROMI S Gots si cseeho Meche tacraasetes canadtyaaulscees nadeasaat halted cabs ae adocsisnc ee le Peaks 2-21 
PUTA LIN Seca cs ccs ie cast wig cpdcanbsean ee a eitaa ab atactase ie css nenassd hese Rude heist ananete 2-21 
RVC OMIM 4 sucess cesessuniy puashaclultee ts ite was aasete statue tans Rlgettee repceatne ala wsia cas wy, uate 2-21 
Ae TSS yA CHIMAENONE dc ccc tesa cides a osece ah das Oavncl otis viandrascaus meee each ee edhe. Deed 2-22 
PU OI Scrat cs Ua vianntencl aida hh ae GAC atigets on ot Sees Mua cchins tact stasuese meals 2-22 
FPSO COS enuf wwszrns Mo buvanuacens Pics sts We azas neuicna tenant sees aa ep can ee 2-22 
PRY COMM Methods 2 tannins Aamo atid nese cea uti esata 2-22 
Ta pet LIS 6 25 scarce soe: castndaess ende var tae Soceses sei rsniienlnidinchceseed deem: Oe ok ee ee 2-22 
GL MGM EMD LENE 22h caida loca savant sins vores waclvcssaate eesti adatercied meee. 2-22 
ERIE OPPMCAUOM 9g soya sets ccttcskatteetes attiss edd ads heal oe ee ss 2-23 
IPA ses sak Bi hiantea cai nap cans hoe bugiasstityase vedas ce ayers krack oe OI eM fe OR 2-23 
MOG BLE MAR SANS 5s Soveiyb ts siecose ice ywlgssayegiahyacasvencescaTsanaviiotsa lac ckvs ciel SR oes 2-23 
Launch Preview options dialog ............cessscsssssssesesssssssssessecssesesesssessesesucsessssesssecscseasans 2-23 
Launch Jumip to. page lala sc. aiesos2dcass: doAaiasasnlus tavensreotpaaseaavane@ccost tatecteesa ns 2-23 
ERIDPMIME PLEVIEW sncceh et ieestc ctor esate anal Gotti tease os sentence akc lars 2-24 
PR VOR TIOINS TOG ics cas couse bspeshaet sta sign telecastaxcRiaresasadsiatdh dist os desae eee ROO teers 2-24 
TASS GE LIM EMOM cts s5, dese x vacua loc ecoacuseonavteSea cvedtaecds cui vaoahne ecgetices A Peecvede nas esecee, , b 2-24 
PL ODOREY Seccrscsaiee hiserbscpssbcvon tr tases arstaslavertvsonlecous seeing basmeianee tent ie Gawain a 2-25 
FR SOUE COS cae saccneit canes rst re eggs nat are sassy. <t-esgics sn facuessanconseatasclssdeapsitvsk are ae Oe 2-25 
PRVORTIONS: DEG mretnOds:. i ssc.is 26 Shieh canst eaenetesan in aatacetae et ius 2-25 
ID Yrarnic ally ANITA MSE sets. ccicsadirsec aden aeds aust eotsaioieh et eae ket eee ehaes 2-25 
TAN GIG Key WAU is ccas oc eivciascacatsta yh iaiee x scsavhctateNerauiivaviens bed aceerareae adore te eee. 2-25 
EY TONE SUES fo ecpedesabsttvatec ee scaeis caer eaten ear aarateed, solccieie e Aceot caeite acthc 2-26 
CRASS AG PAINTED css er eea dca as tvac esky teaas ye sas alee sass wre duct twet cues ie twee Re ors Manes 2-26 
PROP RUEY <ccaustshd Gators tease evs ia suablanssn Stele 85h ivnerna fcainateeatbedagieeests tice keene Mt aie 2-26 
PRES OUNCES 4.02 aeciia nist dopants taster int cater, cainrs aia tanusaics Sattar Ca ivaashvetign Semen a8 2-27 
PROV JIMIP aI 1SG Meth OGS asi ciias hretvesninas a ade dete oluind tee sen Sidharth eb 2-27 
Dyribraric ally Waa MSC acess puyacdtarsdechaaceseuscutziianien- dacisbeasieacn ds aecacinadeds wiekecu Maceo 2-27 
Plan le Key iam sista laisse Gas daguetect Vent ne pieaih ees atic Dia eet pa eee tely, mao 2-27 
5, Calendar Glasses 23,202.25. aictcpinccctiastores-ueasossgesadinons nates auachtoaR tclasiithaed. vi evckodaaw el hic ee 3-] 
PTS CUPS OLS itis cain iaa delet atoasctaedsais ai taaadalesntloarncatea Wau Mteu as iedehcuad awe eetahees 3-1 
MLAS Ciaran Acsloraiee svat et Ata caves ac au Wecesleantad a grea nceialce micas mites: 3-1 
ROPING WIN eaten satis case taste reettanuataatteea tivity Reed neha a meme  ) SOME 3-2 
RVASS AST UEON 9 22 ccesnacs Seed ecas evans peta stitaaddualip tiatinanids Ha eteadladoc a ate ero aot eae 3-2 
IPO POLY ces cep coeds ci iasnicev casi cataean tacit naa dus euwtusivecaateaiietanes wan ane uieh Uae ae Ae 3-2 
CAE TIVUG WIN SOS is epktsas spd ost as acs saedsn stele ucts t Rs patee desks ooh at, Deane RAE MENG ecco 3-2 
Rednaw the: calendar sisibctcscis tao: tcscctsccdss cious reluiasescsavlactugpianatenietasee vind we haces 3-2 
PTL WING 2 sacha snceuh apt ctl t icra tea tae tc cian ae Ld cca a ete See oe 3-3 
CTS She TRAIN la Ssctete Pa ceieies a Ooh ane oth es scat acetal edMievcasouctn oe Mom nla 3-4 
EEO PETRY, 525 ta cosine eahacdoch sss sane haben aista tet tu aan ad ti apheh ad dt Racal tee tn 3-4 
SAIL WIIN SEN OGS: coh actirassnanatesnupietnte ila Ai chatsacs nea Rn ee ea de 3-4 
Diestysoy thtecal etna toy isi ce sedcc ected te sovaeatacyeolinsgesoesch oe pute so oe es see 3-4 
MCIANSE the ‘ealen dat seco h atescscaticl io latsecdemeravat wtruransscnniodeleagesmaccatinst teak 3-5 
Plane a Rey ress: coisa ligt ecicgcnexsactonsaien ee ettasesgch dhdessresush iecebeneciee ten Mate ngtthak Mocc 0S 3-7 
SETS CUNO mnt Mabe S51 tas anwies oltelsucdh abu tbawdavog cisaiybin cia aise Vere aeiadiidennsd RR Mee 3-9 
BP WASIS Os fess Avegeasvices eater cstyd seasteausencoioty picts nda cal eaten immu MEMS ee wcts 3-9 
Examplescr oss Mee Aiact tit sa ak eo hte kee hy) ae Ce 3-10 
Creating. a CAL WIN Componentii.3 tue aedatesviadiea cts earn ick icudhilee abe. 3-10 
Plandlinprkeypr esses: 26 c.ieMees octet che hans ies ren essa eae ga ale 3-10 


or eee 
4 


Altoniatic Test System Classes isescdise.cc:sisscsdeavechucissinanectastioessitnuasssciacresdeincisien le hon 4-1 
PTE CUIS ODS sccrcsres Cue, Cactl any esteet esad enw Baca Sed ie eA cotta 4-1] 
NMG AI Fe ssc, eat cs Durie te orcipatctoeadsM s ttsnck OY me oe  na stg 4-] 

POLSON ee Natit A tase ha bene a betes Eat at eats (eatin Meee a le oe 4-2 
CS NaSSAEAMEOM Fe secectaccoapatort ces telat ae tohiocas a ek tel ce cen OG oe Ue ate Manee 4-2 
PLOY RC Cie ty all od nthe hati tee Le ons, Sam Ost eA ola!) seaman hans Meg 4-3 
URINE Y SIMU CLUES jedcesitint eM cals OR A oe re. ct Wee, et Ve ee als 4-3 

POTS S Vette OS 26 2dr todays Zadenaaca dia auto chee Maca Meena ees 4-4 
EMCI ALIS iaseeeh ots os ac aceon eae Masten dial et iene ea eee ea eae 4-4 
PIOCESSra A TS ESSERE i. .cin, cee saystytetcacecapus exis voskesandssutsd tsedien @racialseivaba thee dee ace 4-4 
BY OCOSS GR ERDOR 0B sMaitti rah sti telicvasustect ct eens rctkactr aon ita cnet ape ee dette 4-6 
Bree Miter Process MieSSa Ber. 5-24 c.suis ccsiertt.teivecssovsrvnay auelss cvansdoveosaiadousica ion ces Meboacaats 4-6 
RGDONt a KEV PEESS 03 ciccicc-c cuasieecrenientas asvasrntion aiefidiereth alee noah oesttenabnecad, eee’ 4-6 

OT SS BUI M ss Sis cttecatas Sensei segtita tt anv Me cM Ati ite on tem Gh eS eo a ie NUS 4-7 
TASS A CTUNT ON fio css dearespastanid cesta: dubale cores cocaabivyaeiioit dudwpeatslastaecd Lat ticren tu inte ton, 4-7 
PORE LUY 28-080 sap Oconee aladieales Mavcace etal st dngite tar Me al, ian iihee yee rar. 4-7 

PT eM ane GOS Be Gite. cree ienitettba, ttre te OE son nlp as aidodsae amen iatee tol oe oes 4-7 
ANGLAIS rs eco ae aati nets ra nc te ome, Pita ace anccadle 4-7 
BIGCeSS COMPIENON 2 5: ituavact ce tesitca Mantes ue pied cd cieice -apschaas Noclon, Suatrctoriosacctyee’, 4-7 


5 Additional Active Object Classes 


ovsavensoosesessoneasentnassnssovescsasseussvosscsusssesessacnsacsarscsscocssnssccenseacescensas 5-1 

PRCCUPSORS M ciacese conti tia ISM ates sans iatlincte dnd Untualinincide: wcslstiatnaddecgedinee 5-1 

4. CIS LC UE Toa: eRe ear Peo na SOO RE 5-1 

TO OTN sry con ae avis alse sk Rat consol Meets wea dea ba a al easih Sc tanta 5-2 
FASS AC MANION y oe caecesit eo uncenteren cine erased robe de eesti eq tot bea hdc eons 5-2 
TENOR eee Fa cee bac a dancer ted pau ohsghiav is OSs ob boos Homhoc 5-2 
LOGONA Methods sccraccsine faiad aps Ate cuca d basalt Ridhadedope vscllRa doedec tua eceaantameecteatle 5-2 
PGI © cease vactseechi teas S atrssreib aaa eee teas Ocak iad Maa ieg MpcStar At ean tn 5-2 
NS Be RS INES a cas wiasecaaacha sas ok ana alnencenat tee eee ea dtad ca sunnier corto tegtacsed he ache 5-3 
CANCEL TeQ US tit hais sec sctinn taei satiate, Wala dees eet os pes geno chi tgs 5-3 
Report process temmimation  .c.sscssssancueveasssunchacivssevataslouessbives dseedechaeuvscacscssolccicescaccecy 5-3 
TINT OBI ree ei le acon snarls Dale Ai eckson Meche alalancleS cs Bien auton asst 8 5-3 
CASS LOMO 53 dons yodassc As caeasgsdasgend eiivececst nach caarsetuaadell ail ahid rcessia tieccae aca Mt 5-4 

BY GPE UEY seis cits crates savcawscastavasediehccaueae eitina unit deo hlag cates IM ie ck eects iM att acne 5-4 
WIND OAD tise Od Sica ccssscseniacesteiclen abot aianh tte a Sates e Soice ola an MT 5-4 
eS) 5-4 
NOMS estas Pte ten nk salinsesctidaas ace epesanonesicasd sscesaex taki payeatesack ie tabaoudteecsdatea ts eceton sed 5-4 
PROCESS COMIPIE TION ia, cirssietd stabs aca Suadh ccstsaacsth cbcasatgnou deta hiutesaoeostss Shee devel faldatnachet 5-4 


CHAPTER 1 


INTRODUCTION 


This manual is a reference document for Psion's XKADD library. It provides a 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 
XADD Reference manual. 


The XADD library is supplied as the xadd.dy/ dynamic link library in the ROM of the Series 3a and 
Workabout machines. It is not present on Series 3 machines. 


Because of their different screen sizes, the Series 3a and Workabout machines contain slightly differing 
versions of the XADD library. The only difference, however, is in the implementation of the cawin 
calendar window class. On the Series 3a , this can be set to display one, three or twelve months, but on the 
Workabout the display is restricted to a single month. 


XADD contains classes that extend the functionality of the HWIM and FORM user interface, notably to 
provide print preview facilities. 


Some classes in the XADD library are designed solely for internal use by system code and are not 
documented in this manual. The undocumented classes are: 


OPRINTER Implements WDR printing for OPL. 

OHELPDLG Implements Help dialogs for OPL. 

RUNMEMO Implements Memo editing from the Agenda application. 

IPCSTAT Used for inter-process communicaton of status data during Memo editing. 


Some of the documented XADD 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 XADD classes 


An application (or DYL) that either subclasses or creates an instance of an XADD class must declare an 
external reference to the XADD 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 xadd 


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


XADD REFERENCE 
eS eee 


Since the XADD library contains extensions to FORM and HWIM, it is likely that access will also be 
needed to these libraries, so the category file will also need to contain exrERNAL references to one or both 
of the FORM and HWIM libraries. 


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


p_new(CAT_MYPROG_HWIM, C_LOGONA) ; 


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


P_new(CAT_MYPROG_MYPROG, C_SUBLOGONA) ; 


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


a SS a ee ee a aaa 
Notation 


Names 


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


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 DESTROY 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 prvview with the title line: 


and prototyped as: 


INT pvv_done (INT event) ; 
would be invoked by, for example: 
p_send3 (hand, 0_PVV_DONE, PAGES _DONE_PAGE) ; 
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 INT prvview_pvv_done (PR_WSERV *self, INT event) 


{ 


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_1eave is called outside a p_enter harness, the process will be panicked with panic 
number 47, 


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


SSS 
1-2 


1 INTRODUCTION 


___, eee oh — Ne a aa 


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, 


¢ 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 BBBB 


which itself is subclasses aaaa. 

a ieee 4 
property 4 
property 5 


property _1 property _3 
property 2 


method_a methed—b 
methed—b methed—e 
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_c, is introduced in class pass but replaced in 
cece, and so on. Note that method_u is a deferred method. 


The roor 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. 


XADD 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_leave, 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_1eave being 
called. 


In the event of an error (such as out of system memory) occurring a method may: 
© 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_leave (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_leave 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. 


XADD 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 


PRINT PREVIEW CLASSES 


The classes described in this chapter are as follows: 


the xPRINTER Class which provides the basic framework for both printing and print preview 
operations. The xpRINTER class must be subclassed to be useful. 


the pRvview class which implements print preview operations. A PRVvIEw object is used as a 
component by the xprintER class. 


the prvinro class which implements an information window indicating the number of pages being 
print previewed. A prvINFo object is used as a component by the prvvzew class. 


the prvpace class which decompresses a page image stored in an external memory segment and 
then draws the page image in a print preview window. Multiple prvpace objects are used as 
components by the prvvrew class. 


the pRvcomm class which provides the print preview command manager. The print preview 
command manager is installed by the prvvzew class. 


the PRvopTIons_puc class which implements the Preview options dialog: this allows the user to 
select the number of pages displayed during the print preview operation. A Preview options dialog 
is used by the prvcomm class. 


the prvsumPp_puc class which implements the Jump to page dialog: this allows the user to select 
the first page displayed on screen during the print preview operation. A Jump to page dialog is 
used by the prvcomm class. 


Note that an application would normally only create an instance of the xPRInTER class (and perhaps 
exceptionally, of the prvvzew class): the other component classes are intimately associated with the 
PRVVIEW Class and are thus not expected to be either directly instanced or subclassed. 


Precursors 


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


the LPRinTER Class described in the Print Classes chapter of the HWIM Reference manual. 


the paces class described in the Document Printing Classes chapter of the FORM Reference 
manual. 


the pRvppr class described in the Print Preview Class chapter of the FORM Reference manual. 


the pi¢sox class described in the Dialog Boxes chapter of the HWIM Reference manual. 


XADD REFERENCE 


Class diagram 


: rvoptions’ 
dig: Ce pcdigics uf 


oe Pees ae oe pod, i eal! 
a — xprinter ; ¥, peeomin: ake a 


XPRINTER 


defer 
wtab 
lheight 
width 
subsqind 


destroy 
lpr_init 
lpr_read 
lpr_sense_buf_width 
lpr_sense_text 


The xpRInTER Class provides the basic framework that allows an application to perform both printing and 
print preview operations using the services provided by the prrwrer and paces classes. 


The xpRINTER Class provides a deferred method - the 1pr_sense_text method - which is supplied as a call- 
back to the pacgs active object: this method must be replaced so that it obtains the next fragment of text to 
print. 


For further details of printing see the prinTer class in the Print Classes chapter of the HWIM Reference 
manual and the Printing chapter in the Object Oriented Programming manual. 


2 PRINT PREVIEW CLASSES 
ee ENINT PREVIEW CLASSES | 


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


CLASS xprinter lprinter 


{ 


REPLACE destroy 
REPLACE lpr_init 
PROPERTY 


{ 


WORD locked; 


} 
} 


Property 


xprinter.locked TRUE if an extra level of locking has been added to the application by tbe xPRINTER 
object, otherwise raLse. 


eae Se a ee eee 
XPRINTER methods 


Destroy 


VOID destroy (VOID) ; 


Destroy the xPRINTER object. 


If xprinter . locked is non-zero, removes one level of locking by sending a ws_Lock message to w_ws with 
an argument of FALSE. 


Supersends a DESTROY message. 


Initialise 


VOID lpr_init (INT commid) ; 


Initialise the xPRINTER component and, if commid is zero, start a printing operation, otherwise start a print 
preview operation. 


If commid is zero, adds a level of locking by sending a ws_Locx message to w_ws with an argument of TRUE 
and then writing TRUE to xprinter. locked. 


Either starts a printing operation, or initialises a print preview operation, by writing commid to 
lprinter.subsqind and then supersending an LPR_INIT message. 


If commid is zero, returns. 


Otherwise creates an instance of the prvvrew class and initialises the pRvvrew object by sending a pvv_init 
message with an argument of self, commid and the address of iprinter. pages: 


¢ the se1f argument specifies that the 1pr_read call-back method required by the pacEs active 
object is to be supplied by the xPrrnTER object. 


® the commid argument should specify the method number of a print method in the current 
application manager. 


e the address of 1printer. pages is supplied so that it may receive the handle of the paces active 
object which is handling the print preview. 


XADD REFERENCE 


PRVVIEW 


wn_calc_position 
wn_connect 
wn_dodraw 


wn_position 
wn_redraw 


wn—-sense—heip 


wn_visible 


pPages 
pPrviInfo 
pPageView 
pOldMenu 
pOldComman 
Started 
PrintMethod 
hdone 

mdone 
NoPageViews 
MaxNoPageViews 
ScrollArea 
Pv 


destroy 
wn_key 
wn_draw 
wn_set 
wn_init 
wn_sense_help 
pvv_done 
pvv_pages_done 
pvv_new_page 
pvv_Margins 
pvv_init 
pvv_false 


The prvview class supports the print preview of one or more pages in a document. An example print 


preview display is shown in the following picture: 


The number of pages that may be displayed is determined by the dimensions of the screen up to a limit of 
PVV_MAX_PAGEVIEWwS. The page images are drawn to the screen by an array of PRVPAGE components. 


The text in the top left of the screen is an information window that indicates the number of pages in the 
preview range. This information window is provided by a prvINFo component. 


The print preview is carried out by means of paces and prvepr objects. These treat the pages as a sequence 
of fragments or print elements each of which contains no more than one line of text. 


The print elements are passed to the paces object by means of a so-called read-call-back: when the pacEs 
object requires the next print element it sends an LPR_READ message to the supplier object. The handle of 
the supplier object is passed to the paces object on initialisation and in turn must be passed to the PRVVIEW 
object on its initialisation. This object is usually an instance of an xpRINTER subclass. 


The prvview object is notified by the paces object of the completion of each stage of the print preview by 
means of a so-called completion call-back: when the next stage is complete the pacss object simply sends a 


2-4 


2 PRINT PREVIEW CLASSES 
RIN PREVIEW CLASSES 


PVV_PAGES_DONE message to the prvvrEw object. This message is only significant when the preview is 
about to terminate. 


The prvvrew object is also notified by the prvppr object of the completion of each stage of the print 
preview by means of a completion call-back: when the next stage is complete the PRvPDR object simply 
sends pvv_DONE messages to the pRvvrew object. In this case the message updates the page count and then 
updates the display to include any newly created page image. 


The paces class is described in the Document Printing Classes chapter of the FORM Reference manual. 
The prvppr class is described in the Print Preview Class chapter of the FORM Reference manual. 


It is assumed that the global variable patcate specifies the handle of an instance of the cars class. In the 
description of the methods this cars instance is simply referred to as the caTz object. 


It is also assumed that w->am.appman.spare1 contains the handle of an instance of the printer class: the 
PRINTER Class automatically writes its handle to w->am. appman. spare1 on initialisation. 


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


CLASS prvview digchain 
{ 
REPLACE destroy 
REPLACE wn_key 
REPLACE wn_draw 
REPLACE wn_set 
REPLACE wn_init 
REPLACE wn_sense_help 
ADD pvv_done 
ADD pvv_pages_done 
ADD pvv_new_page 
ADD pvv_margins 
ADD pvv_init 
ADD pvv_false=p_ false 


CONSTANTS 
{ 
PVV_INTERPAGE_GAP 6 
PVV_TOP_GAP 4 
PVV_FOOTER_GAP 12 
PVV_PAGE_SHADOW 1 
PVV_SIDE_GAP 12 
PVV_PAGENO_DISP GAP 60 
PVV_DISP_FACING 0 
PVV_DISP1 1 
PVV_DISP2 2 
PVV_DISP3 3 
PVV_DISP4 4 
PVV_MARGINS_ON 0x01 
PVV_PREVIEW_SET 0x80 
PVV_VIEW_MAX PAGEVIEWS 4 


} 


XADD REFERENCE 
—— ee SSSSSSSSSSSSSsSssssssSSSSSSSsssssssssesssesee 


TYPES 

{ 

typedef struct 
{ 
PAGES_CALLS Calls; 
WORD PrintMethod; 
WORD Sparel; 
WORD Spare2; 
} IN_PRVVIEW; 

typedef struct 


{ 


P_RECT Margins; Margin area 

INT HeadTop; 

INT HeadBot; 

P_RECT Border; area in which to draw greeked page 
P_RECT Footer; area in which to print page number 


} PVV_PAGE_DATA; 
typedef struct 


{ 

PR_ROOT *pArray; varray containing page index into preview segment 

INT NoPages; number of pages (so far) 

INT FirstPage; zero for FACING PAGES, one otherwise 

INT LastPage; =NoPages if not FACING _PAGES, or rounded up to odd number 
INT PageOffset; page number of first page displayed 

INT PageNo; current page no 


PVV_DISPLAY Disp; 
INT UseGrey; 
INT LeftOffset; 
INT PageViewWidth; width of PageView (pixels) 
PVV_PAGE_DATA Page; 

! Following are scratch areas used by all pageviews 
UBYTE *pBitRow; current row from bitmap 
UBYTE *pLastRow; previous row from bitmap 
BMP_RASTER_ROW_REC *pRowRec; compressed data from preview segment 
HANDLE PrvSegHandle; handle of preveiw segment 
PRV_BITMAP Bmp; bitmap, loaded from preview segment 
} PVV_PAGEVIEW_DATA; 


} 


PROPERTY 6 
{ 
PR_PAGES *pPages; Pages active object, destroy on error 
PR_PRVINFO *pPrvinfo; Info window 
PR_ROOT *pPageView[PVV_VIEW_MAX PAGEVIEWS]; PageView objects 
WSERV_INFO *pOQldMenu; holds ptr of old Menu when in preview mode 
PR_COMMAN *pOldComman ; holds ptr of old Comman when in preview mode 
WORD Started; set if am_start called 
WORD PrintMethod; command manager print method 
VOID *hdone; Callback handle for tdone & completion 
WORD mdone; Callback method for %done & completion 
INT NoPageViews; number of PageViews on display 
INT MaxNoPageViews; max no of PageViews that will fit in view 
P_RECT ScrollArea; area in which pages are displayed 
PVV_PAGEVIEW_DATA Pv; property that can be peeked by constituent pageviews 


} 
} 


Property 


prvview.pPages The handle of a paces active object, used to create compressed page images 
for all pages in the print preview range. For details see the Document 
Printing Classes chapter of the FORM Reference manual. 


prvview.pPrvinfo The handle of a prvinro object that provides an information window 
indicating the total number of pages in the print preview range. 


2 PRINT PREVIEW CLASSES 
—.——S eS PREVIEW CLASSES 


prvview.pPageView An array of up to Pvv_MAX_PAGEVIEWs elements, each of which may be a 
PRVPAGE object handle. The prvpace objects are used to draw the page 
images in the print preview window - the page images are read from an 
external memory segment whose handle is stored in 
prvview. Pv. PrvSegHandle 


On initialisation of each prvpacE object: 
the win. id property is set to that of the parent prvvrew object, 


the prvpage .init.Pos property is set to the index of the object in 
the prvview.pPageView alTay, 


the prvpage. init .pPrvview property is set to the handle of the 
parent pRvvieEw object. 


prvview.pOldMenu The address of a memory cell containing the original command manager 
menu data: this is organised as a WSERV_INFo resource struct. 
prvview.pOldcomman The handle of the original command manager of the application: the 
PRVVIEW Class installs a print preview command manager on initialisation. 
prvview.Started Set to TRUE if an AM_START message was sent to w_am on initialisation. 
prvview.PrintMethod The method number of a print method in the original command manager: it 


is used to allow printing during print preview operations. 


prvview.hdone The handle of the object to which the pvv_pacEs_pone method sends a 
prvview.hdone message on completion of either a page or the document. 


prvview.mdone The method number of the message sent by the pvv_pacEs_pong method on 
completion of either a page or the document. 


prvview.NoPageViews The number of page images displayed in the print preview window. 


prvview.MaxNoPageViews The maximum number of page images that may be displayed in the print 
preview window. It is set to four on initialisation. 


prvview.ScrollArea Specifies a rectangle enclosing the page views and the page numbers. 
prvview. Pv Contains information about the page views, as described below. 
The pvv_PAGEVIEW_para struct is defined as follows: 


typedef struct 

{ 

PR_ROOT *pArray; 

INT NoPages; 

INT FirstPage; 

INT LastPage; 

INT PageOffset; 

INT PageNo; 
PVV_DISPLAY Disp; 
INT UseGrey; 

INT LeftOffset; 

INT PageViewWidth; 
PVV_PAGE_DATA Page; 
UBYTE *pBitRow; 
UBYTE *pLastRow; 
BMP_RASTER_ROW_REC *pRowRec; 
HANDLE PrvSegHandle; 
PRV_BITMAP Bmp; 

} PVV_PAGEVIEW_DATA; 


The significance of the members of the pvv_pacEvIew_ pata struct is as follows: 


pArray The handle of a variar object, used to store the offsets in an external memory 
segment of the compressed page images: the memory segment handle is stored in 
prvview.Pv.PrvSegHandle 


Each offset is stored as Lone data. 


OOO rr SSS 


XADD REFERENCE 


NoPages The number of pages in the print preview range: may be less than the number of 
pages in the document. 

FirstPage For internal use only. 

LastPage For internal use only. 

PageOffset The page offset of the first page in the print preview range. It is zero when the 


preview range starts from the first page in the document. 


PageNo The page offset of the first page displayed in the print preview window. The offset is 
with respect to the first page in the preview range and is thus zero when the first 
page is visible. 


Disp The current print preview settings. 
The pvv_pisp.ay struct is defined as follows: 
typedef struct 


{ 


UBYTE Mode; 
UBYTE Flags; 
} PVV_DISPLAY; 
the Mode member may contain one of the following: 


PVV_DISP_FACING specifies that an odd page is to be displayed first followed by 


an even page. 
PVV_DISP1 specifies that one page is to be displayed. 
PVV_DISP2 specifies that two pages are to be displayed. 
PVV_DISP3 specifies that three pages are to be displayed. 
PVV_DISP4 specifies that four pages are to be displayed. 


the Flags member may contain: 


PVV_MARGINS_ON specifies that margins are to be visible during print preview 


operations. 
UseGrey set to TRUE to specify that the grey plane may be used, set to rauss otherwise. 
Leftoffset specifies the horizontal separation of the left edge of the first page view from the left 


edge of the window. 


PageViewWidth — specifies the width of a page view in units of pixels. 


2 PRINT PREVIEW CLASSES 
——————_—. $$ Na eee ERINT PREVIEW CLASSES 


Page specifies the layout of a generic page view on the screen: this generic page view has 
zero horizontal offset from the left edge of the main window. 


The pvv_pace_pata struct is defined as follows: 
typedef struct 
{ 
P_RECT Margins; 
INT HeadTop; 
INT HeadBot; 
P_RECT Border; 
P_RECT Footer; 
} PVV_PAGE_DATA; 
Margins - specifies the rectangle that is enclosed by the page margins. 
HeadTop - specifies the distance of the header text from the top margin. 
HeadBot - specifies the distance of the footer text from the bottom margin. 


Border - specifies a rectangle enclosing the page view i.e. the physical page 
border. 


Footer ~- specifies a rectangle enclosing the page number. 


Note: in all cases the units are pixels. 


pBitRow for internal use. 

pLastRow for internal use. 

pRowRec for internal use. 

PrvSegHandle specifies the handle of an external memory segment that is used to store compressed 
page images. 


The memory segment is created and written to by pR_PREVIEW_START and 
PR_PREVIEW messages that are sent on initialisation. 


Bmp contains information about an external bitmap that is used internally when 
transferring compressed page images to the print preview window. 


The prv_Brrmap struct is defined as follows: 


typedef struct 
{ 
INT Id; 
HANDLE SegHandle; 
UPOINT Size; 
UWORD ByteWidth; 
UWORD BitWidth; 
} PRV_BITMAP; 


The significance of the members of the above struct is as follows: 


Id specifies the ID of the bitmap. 
SegHandle specifies the handle of a memory segment that contains the bitmap. 
Size the x member specifies the width of the bitmap in units of pixels. 


the y member specifies the height of the bitmap in units of pixels. 


ByteWidth specifies the number of bytes required to store one horizontal line from the bitmap i.e. 
size.x divided by eight, plus one. 


BitWidth specifies the number of horizontal bits needed to draw a page in the correct proportion. 


XADD REFERENCE 
eee 


Resources 


Defined in the system resource file sx_.ra. 


RESOURCE WSERV_INFO sys_preview_acc 
{ 
menbar_id=sys_preview_menubar; 
first_com=0_PVC_PREVIEW_PRINT; 
accel= 


{ 


‘p', /* Print */ 


'm', /* Margins */ 

'a', /* Pages to display */ 
'j', /* Jump to page */ 

ter /* Exit preview */ 


}; 


BS a ee a, a 
PRVVIEW methods 


ow 


INT wn_sense_help (VOID) ; 


Sense print help resource 


Sense the ID of the print help resource. 


The method simply returns -sys HELP PRINT. 


‘Destroy 
VOID destroy (VOID) ; 

Free any resources and destroy the prvvrew object. 

Cancels any busy messages. 


If prvview.poldMenu is non-zero, resets the application's menu bar by sending a ws_RESET_MENUBAR 
message to w_ws specifying an argument of prvview.oldmenu. 


If prvview.pOldcomman, destroys the print preview command manager by sending a pEsTRoy message to 
w_ws->wserv.com and then writes prvview.pOldComman to w_ws->wserv.com. 


Terminates the print preview by sending a pR_PREVIEW_END message to w_am->appman.sparel. 
Frees the bitmap specified by prvview.Pv.Bmp.Id. 


If prwview. Pv. Bmp.SegHandle is non-zero, closes the memory segment with handle 
prvview.Pv.Bmp.SegHandle. 


Frees the memory cell at address prvview.Pv.pBitRow. 
If prvwview. Pv.parray is non-zero, sends a DESTROY message to prvview. Pv.pArray. 
If win. flags contains PR_WIN_INITIALISED, sends a WS_REMOVE_DIAL message to w_ws. 
If prvview. Started is non-zero: 

e sends self a DESTROY message. 

e sends an AM_sToP message to w_am. 
Otherwise: 


® sends self a DESTROY message. 


2 PRINT PREVIEW CLASSES 


WN KEY > 


INT wn_key (INT keycode, INT modifiers) ; 


Handle a keypress that might terminate the print preview, or scroll the page view. 

If keycode is W_KEY_ESCAPE: 
¢ ifprvview.pPages is non-zero, sends a DESTROY message to prvview.pPages. 
® writes NULL tO prvview.pPages. 
e returns TRUE. 

If keycode is W_KEY_UP: 


¢ attempts to scroll backwards prvview.NoPageViews pages by sending self a PVV_NEW_PAGE 
message with as argument prvview.Pv.PageNo minus prvview.NoPageViews. 


If keycode is W_KEY_DOWN: 


¢ attempts to scroll forwards prvview.NoPageViews pages by sending self a PVV_NEW_PAGE 
message with as argument prvview.Pv.PageNo plus prvview.NoPageViews. 


If keycode iS W_KEY_PAGE_DOWN: 


¢ ifmodifiers contains W_CTRL MODIFIER, attempts to display the last pages in the allowed preview 
range by sending self a Pvv_NEW_PAGE message with as argument prvview. Pv.LastPage minus 
prvview.NoPageViews plus one. 


e otherwise, if prvview. Pv.Disp.Mode contains Pvv_DISP_FACING, attempts to move forwards by 
prvview.Pv.PageNo pages by sending self a PVV_NEW_PAGE message with as argument 
prvview.Pv.PageNo plus prvview.NoPageViews. 


¢ otherwise, attempts to moves forward one page by sending self a pvv_NEW_PAGE message with as 
argument prvview. Pv. PageNo plus one. 


If keycode iS W_KEY_RIGHT: 


¢  ifprvview.Pv.Disp.Mode contains Pvv_DISP_FACING, attempts to move forwards by 
prvview.Pv.PageNo pages by sending self a Pvv_NEW_PAGE message with as argument 
prvview.Pv.PageNo plus prvview.NoPageViews. 


¢ otherwise, attempts to moves forward one page by sending self a Pvv_NEW_PAGE message with as 
argument prvview. Pv. PageNo plus one. 


If keycode iS W_KEY_PAGE_UP: 


¢ ifmodifiers contains w_CTRL_MODIFTER, attempts to display the first pages in the allowed preview 
range by sending self a pvv_NEW_PAGE message with as argument zero. 


e otherwise, if prvview.Pv.Disp.Mode contains Pvv_DISP_FACING, attempts to move forwards by 
prvview.Pv.PageNo pages by sending self a PVV_NEW_PAGE message with as argument 
prvview.Pv.PageNo minus prvview.NoPageViews. 


¢ otherwise, attempts to moves backwards one page by sending self a PvV_NEW_PAGE message with 
as argument prvview.Pv.PageNo minus one. 


If keycode is W_KEY_LEFT: 


¢ if prvview.Pv.Disp.Mode contains Pvv_DISP_FACING, attempts to move forwards by 
prvview.Pv.PageNo pages by sending self a pvv_NEW_PAGE message with as argument 
prvview.Pv.PageNo minus prvview.NoPageViews. 


¢ otherwise, attempts to moves backwards one page by sending self a Pvv_NEW_PAGE message with 
as argument prvview.Pv.PageNo minus one. 


If keycode is W_KEY_HOME: 


¢ moves to the first page(s) in the preview range by sending self a Pvv_NEW_PAGE message with as 
argument zero. 


XADD REFERENCE 


If keycode is W_KEY_END: 


* moves to the last pages in the preview range by sending self a Pvv_NEW_PAGE message with as 
argument prvview. Pv. LastPage minuUS prvwview.NoPageViews plus one. 


Retums FALSE. 


VOID wn_draw(VOID) ; 


Draw 


Draw the page views on screen. 
Draws a border by calling gsorder with as argument win. flags. 


Sends a wN_pRaw message to each pRvpacE object - the handles of the prvpacE objects are stored in the first 
prvview.NoPageViews elements of prvview -pPageView. 


Set display made 
VOID wn_set (INT mode) ; 

Set the number of pages to display during the print preview as specified by mode. 

The allowed values of mode are as follows: 


PVV_DISP_FACING specifies that two facing pages are to be displayed i.e. the first page must always 
have and odd page number. 


PVV_DISP1 specifies that one page is to be displayed. 
PVV_DISP2 specifies that two pages are to be displayed. 
PVV_DISP3 specifies that three pages are to be displayed. 
PVV_DISP4 specifies that four pages are to be displayed. 


If mode is equal to prvview.Pv.Disp.Mode, and thus the display mode is already set, returns. 


Writes appropriate values into property including prvview.NoPageviews: note that if mode specifies more 
pages than can be displayed, mode is reset to the limit. 


Writes mode to prvview. Pv.Disp.Mode. 
Sets Pvv_PREVIEW_SET in prvview.Pv.Disp.Flags. 
Writes prvview.Pv.Disp tO DatGate->gate.prevdisp. 


If necessary the print preview window is resized whilst ensuring that it remains centred on screen. 


Si te 
_ Initialise 
VOID wn_init(IN_PRVVIEW *pIn, INT DoAmStart) ; 
Initialise the pRvvrew object and then start the print preview operation. 
The In_PRVvIEw struct is defined as follows: 
typedef struct 
{ 
PAGES_CALLS Calls; 
WORD PrintMethod; 
WORD Sparel; 
WORD Spare2; 
} IN_PRVVIEW; 
The members of the 1n_pRvview struct have the following significance: 
Calls .hread specifies the handle of an object that is to be sent read call-back messages by the 


PAGES active object when it requires the next print element. 


2 PRINT PREVIEW CLASSES 
——_— eee RINT PREVIEW CLASSES 


Calls.mread specifies the read call-back message that is sent by the paczs active object when it 
requires the next print element. 

Calls .hdone specifies the value that is written to prvview.hdone. 

Calls.mdone specifies the value that is written to prvview.mdone. 

PrintMethod specifies the value that is written to prvview. PrintMethod. 

Sparel this member is not used. 

Spare2 this member is not used. 


If the gate. prevdisp.Flags property of the cars object is non-zero, writes the gate .prevdisp property to 
prvview.Pv.Disp. 


Writes a default display mode to prvview. Pv.Disp .Mode: the default is PVV_DISP2, 
If the psp environment variable exists - this environment variable is four bytes long: 
¢ — subtracts '0' from the value in the first byte and writes the result to prvview. pv.Disp .Mode. 


e if prvview.Pv.Disp.Mode is greater than pvv_prsp4, resets prvview. Pv.Disp.Mode to 
PVV_DISP_FACING. 


e if the second byte contains '1', writes pvv_MARGINS_oN to prvview.Pv.Disp.Flags. 
e otherwise writes zero to prvview.Pv.Disp. Flags. 


Writes TRUE to prvview.Pv.UseGrey and then connects to the window server by sending self a 
WN_CONNECT message. Sets the dimensions of the print preview window ensuring that it is centred on 
screen. 


Creates an instance of the prvinro class and writes its handle to prvview.pPrvinfo. Connects the PRVINFO 
object to the window server and then initialises it. 


Sets various items of property as follows: 


© — sets property associated with the page range: this property is prvview. Pv. PageOffset, 
prvview.MaxNoPageViews, prvview.NoPageViews and prvview.Pv.FirstPage. 


© — sets property associated with the layout of the page views: this property is 
prvview.Pv.Page.Border, prvview.Pv.Page.Header, prvview.Pv. Page .Footer, 
prvview.Pv.Page.Margins, prvview.Pv.Page.HeadTop, prvview.Pv. Page .HeadBot, 
prvview.Pv.Scrollarea and prvview.ScrollaArea. 


e sets the content of the prvview. Pv. Bmp property. 


Creates an instance of the variar class and writes its handle to prvview.Pv.parray. Initialises and sets the 
capacity of the varLar component. 


Initialises the current printer object for a print preview operation by sending a PR_PREVIEW_START message 
tO w_am->appman.sparei with as argument the address of a PREVIEW_INIT struct initialised as follows: 


pSegName _— specifies a pointer to a buffer containing the name to be given to an external memory 
segment that will contain the page images. The name supplied is "PRV.ext" where the ext 
component is the extension in the name of the current process. 


pArray this is set to prvview. Pv. pArray. 
PrvSize set tO prvview.Pv.Bmp.Size. 
BitwWidth set to prvview.Pv.Bmp.BitWidth. 


hPrvDone _ set to sel £: specifies the handle of the object to which the prvepr object sends mprvDone 
messages after the completion of each stage of the print preview operation. 


mPrvDone —_ Set to O_Pvv_DONE: specifies the message to be sent by the prvppr object after completion 
of each stage of the print preview. 


Writes the return value from the pr_PREVIEW_START message to to prvview. Pv. PrvSegHandle. 


Installs the print preview command manager as follows: 


XADD REFERENCE 
eee 


e sends a Ws_sET_MENUBAR message to w_ws with an argument of -sys_PREVIEW_ACC system 
resource and writes the address of the original menu to prvview.poldMenu. 


¢ creates an instance of the prvcomm class and writes its handle to w_ws->wserv.com and writes the 
handle of the original command manager to prvview.pOldComman. 


¢ — initialises the print preview command manager by sending a com_1nIT message to 
w_ws->wserv.com with an argument of self. 


Initialises the page images as follows: 


e creates and initialises pvv_vIEW_MAX_PAGEVIEWS instances of the prvpace class and writes the 
handles to the prvview.pPageView array. 


e draws the page images in the print preview window by sending a wn_popraw message to each 
element of prvview. pPageView. 


Starts the print preview operation by sending a PR_PREVIEW Message to w_am->appman.spare1 with as 
argument the address of a PAGES_cCALLs struct initialised as follows: 


hread set to pIn->Calls.hread: specifies the handle of an object that is to be sent read call-back 
messages by the paczs active object when it requires the next print element. 


mread set to pIn->Calls.mread: specifies the read call-back message that is sent by the pacEs 
active object when it requires the next print element. 


hdone this is set to se1£: specifies the handle of an object that is to be sent an mdone message by 
the pacgs active object after the completion of each stage of the print preview operation. 


mdone this is set to pvv_PAGES_pons. specifies the message that is to be sent the paces active object 
after the completion of each stage of the print preview operation. 


Writes the handle of the current paczs active object - i.e. the return value from the pR_pREVIEW message - 
to prvview. pPages. 


Makes the print preview window visible by sending self a wN_INITVIS message. 


Displays an information message containing the text in the sys_susy system resource: on English 
language machines this is "Busy". 


Adds the preview object as a dialog with an associated menu by sending a ws_app DIAL message to w_ws 
with an argument of self. 


Sets PR_WIN_INITIALISED, DLGCHAIN_WIH_MENU and PR_WIN_NO_ppP in win. flags. 
If DoAmstart is non-zero: 
e writes TRUE to prvview.Started. 


¢ allows queued active objects to run by sending an aM_sTART message to w_am. 


Completion call-back 


INT pvv_done (INT event) ; 


Complete procesing of the current stage in the print preview operation: this call-back method is called by 
the prvpprR object. 


If event is PAGES_DONE_PAGE indicating that the current page image has been completed: 
* increments the page count i.e. prvview. Pv.NoPages and updates prvview. Pv. LastPage. 


¢ updates the number of pages in the preview display by sending a w_sET message to 
prvview.pPrvinfo with an argument of prvview. Pv .NoPages. 


e if the page is visible, then draws the page by sending a wn_DoDRAw message to the appropriate 
element of the prvview.pPageView altay. 


Otherwise if event is either PAGES_DONE_ERROR OF PAGES_DONE_END, cancels any busy message and writes 
NULL tO prvview.pPages. 


2-14 


2 PRINT PREVIEW CLASSES 


Returns TRUE. 


PVV_PAGES Di 


INT pvv_pages_done (PAGES_DONE *d,PAGES_INIT *par) ; 


étion call-back 


Complete processing of the current stage in the print preview operation: this call-back method is called by 
the pacss active object. 


If d->event is either PAGES_DONE_ERROR OF PAGES_DONE_END, the method simply cancels any busy message 
and then writes NULL to prvview.pPages since the pags active object is about to destroy itself. 


Otherwise if prvview.hdone is non-zero, the method sends a prvview.mdone message to prvview.hdone 
with as arguments d and par and then returns the return value. 


Otherwise the method returns FALSE. 


Note: when d->event is equal to PAGES_DONE_PaGE indicating completion of the current page, it is not 
guaranteed that the page image is complete. 


“margins 
VOID pvv_margins (VOID) ; 

Toggle the visibility of the margins in the print preview display. 

If prvview.Pv.Disp.Flags contains Pvv_MARGINS_oN, clears Pvv_MARGINS_oN in prvview.Pv.Disp. Flags. 
Otherwise sets pvv_MARGINS_ON in prvview.Pv.Disp.Flags. 


Sends a PvP_MARGINS message to each of the prvpace objects specified in the prvview. ppageView array. 


to page 
VOID pvv_new_page (INT NewPage) ; 


Move to page offset Newpage in the print preview range: a page offset of zero corresponds to the first page 
in the print preview range. 


Draws the pages on screen using scrolling whenever possible to ensure speed. 


If necessary, rounds NewPage down, or up, to ensure that the pages on screen do not extend beyond the 
allowed range and then writes the possibly modified value of newPage to prvview. Pv.PageNo. 


VOID pvv_INIT(VOID *xp,INT commid, VOID **ppages) ; 
Initialise the pRvview object. 


Initialises the pRvv1Ew object and starts the print preview operation by sending self a wN_INIT message 
with as argument the address of an In_PRvvIEw Struct and FaLsE: the IN_PRVvVIEW struct is set as follows: 


Calls. hread specifies the handle of an object that is to be sent read call-back messages by the paces 
active object when it requires the next print element: set to xp. 

Calls.mread specifies the read call-back message that is sent by the pacgs active object when it 
requires the next print element: set to 0 LPR_READ. 

Calls.hdone specifies the value that is written to prvview.hdone: set to self. 

Calls.mdone specifies the value that is written to prvview.mdone: set to 0_PVV_FALSE. 

PrintMethod specifies the value that is written to prvview. PrintMethod: set to commid. 

Sparel this is set to zero. 

Spare2 this is set to zero. 


Writes the handle of the pacgs active object i.e. prvview.pPages tO *ppages. 


XADD REFERENCE 


Indicates that an aM_sTART message has been sent by writing TRUE to prvview. Started. 


Allows queued active objects to run by sending an am_sTaRT message to w_am. 


PRVINFO 


PRVINFO 


NoPages 
FontHeight 
FontAscent 


destroy 
wn_calc_position 
wn_connect 
wn_dodraw 
wn_emphasise 
wn_key 
wn_position 
wn_redraw 
wn_sense_help 


wn_visible 


The prvinro class provides a borderless window containing the page number and either "page" or "pages" 
as appropriate. An example of such a window is shown in the following picture: 


4 
pages 


The class is normally used as a component in a print preview window as shown in the following picture: 


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


CLASS prvinfo win 
{ 
REPLACE wn_draw 
REPLACE wn_set 
REPLACE wn_init 
PROPERTY 
{ 
INT NoPages; 
UWORD FontHeight; 
UWORD FontAscent; 


2 PRINT PREVIEW CLASSES 


Property 


prvinfo.NoPages specifies the number of pages: a textual representation of this value is displayed 
in the information window. 


prvinfo.FontHeight specifies the height of the boxes in which the page number and associated text 
is drawn. 


prvinfo.FontAscent specifies the ascent used when drawing text in the boxes. 
Resources 


Defined in the system resource file. 


RESOURCE STRING sys_page 


{ 


str="page"; 


RESOURCE STRING sys_pages 


{ 


str="pages"; 


} 


BS ee ee a ee ee Ee 
PRVINFO methods 


VOID wn_init (VOID) ; 

Initialise property. 

Obtains the height and ascent of the font specified by ID ronr_rp_swrss_13 and style c_sTy_NoRMAL. 
Writes the height of the font to prvinfo.FontHeight. 


Writes the ascent of the font to prvinfo.FontAscent. 


of pages 
VOID wn_set (INT NoPages) ; 


Set the number of pages. 


The method simply writes nopages to prvinfo.NoPages and then forces a redraw by invalidating the entire 
content of the window. 


ee Draw 
VOID wn_draw (VOID) ; 
Draw the entire display. 


Draws a textual representation of the decimal value in prvinfo.NoPages in a box in the top left corner of 
the window. 


Draws text in a box immediately beneath the first one. If prvinfo.NoPages is one, the text is loaded from 
the sys_PaGE system resource: on English language machines this is "page". Otherwise the text is loaded 
from the sys_PacEs system resource: on English language machines this is "pages". 


The width and height of each box are pvv_PAGENo_DIsP_cap and prvinfo.FontHeight respectively. 


In both cases the text is centre aligned with an ascent of prvinfo.FontAscent. 


XADD REFERENCE 


PRVPAGE 


destroy 
wn_calc_position 
wn_connect 
wn—dedzraw 
wn_emphasise 
wn_key 
wn_position 
wn_redraw 
wn_sense_help 


Pvp_margins 


wn_visible 
wn_set 
wn_sense 


The prvpace draws an image of a page and the associated page number. An example page view is shown in 
the following picture: 


Notice the margins and the header and footer text. Page views are used as components in the print preview 
window as shown in the following picture: 


In the above picture two prvpace objects were used as components in order to create and maintain the two 
page images. 


In normal use the prvpacE object shares the window ID of the main print preview window. The owning 
object is responsible for supplying the prvpacE object with the window ID and its position on screen. 


A PRVPAGE object loads the page image from an external memory segment the address of which is read 
from the property of the parent prvview object. 


Similarly the rectangles that define the layout of the page image are read from the property of the parent 
PRVVIEW object. 


2 PRINT PREVIEW CLASSES 
SSeS TERINE PREVIEW CLASSES | 


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


CLASS prvpage win 


REPLACE wn_dodraw 
REPLACE wn_draw 
REPLACE wn_init 
ADD pvp_margins 
TYPES 


{ 


typedef struct 


{ 


PR_PRVVIEW *pPrvView; 
INT Pos; 

UWORD wid; 

} IN_PRVPAGE; 


} 


PROPERTY 


{ 


IN_PRVPAGE init;; 
} 
} 


Property 
prvpage.init this is an IN_PRvPAGE struct which is passed on initialisation of the PRVPAGE 
object i.e. by sending it a ww_InrT message. 


The IN_PRVPAGE struct is defined as follows: 


typedef struct 


{ 


PR_PRVVIEW *pPrvView; 
INT Pos; 

UWORD wid; 

} IN_PRVPAGE; 


the significance of the members of the 1n_prvpacz struct is as follows: 
pPrvView this is the handle of a parent prvvrew object. 


Pos this is an index which determines the offset of the page image in the main window. 
The offset, in pixels, is equal to the sum of the prvview. Pv.Leftoffset property of 
the PRVVIEw object and the product of prvpage. Pos and the 
prvview. Pv. PageViewWidth property of the prvvrew object. 


wid this specifies the ID of the main window in which the page view and the page number 
are drawn. 


Resources 
Defined in the system resource file. 


RESOURCE STRING sys_page 


{ 


str="page"; 


RESOURCE STRING sys_pages 


{ 


str="pages"; 


XADD REFERENCE 


PRV 


Dodraw 
VOID wn_dodraw (VOID) ; 

Create an appropriate graphics context and then draw the page view and the page number. 

Validates the rectangles enclosing the page image and the page number. 

Creates a temporary graphics context. 

Draws the page view by sending self a WN_DRAW message. 


Releases the temporary graphics context. 


=~ Draw 
VOID wn_draw(VOID) ; 
Draw on screen the current page view and the associated page number. 


If the prvview. Pv.NoPages property of the prvview object - i.e. the number of pages to preview - is zero, 
clears the rectangle enclosing the page view and the page number. 


If the current page number is out of the preview range, clears the retangle enclosing the page view and the 
page number. 


The layout of page views is shown schematically in the following picture. 


page offset of page 2 


left offset 
page view width 
The quantities of relevance to the prvpacs class are as follows: 
left offset specified by the prwview. Pv.Leftoffset property of the parent PRvVIEW object. 


page view width _ specified by the prvview. pv. Pageviewwidth property of the parent pRvvIEw object. 


page offset equal to the sum of the left offset and prvpage.Pos multiplied by the page view 
width. 
page number equal to the sum of prvpage.init.Pos and the prvview. Pv. PageNo and 


prvview.Pv.PageOffset property of the parent prvview object. 


Draws the page number in the rectangle specified by the prvview. pv. Page. Footer property of the parent 
PRVVIEW object offset horizontally by the page offset. 


Draws the page image in the rectangle specified by the prvview. Pv. Page .Border property of the parent 
PRVVIEW object offset horizontally by the page offset. 


If the prvview. Pv. Disp. Flags property of the prvview object contains pvv_MARGINS_ON: 


2-20 


2 PRINT PREVIEW CLASSES 


e draws the margins as specified by the prvview. Pv. Page .Margins property of the parent PRVVIEW 
object offset by the page offset. 


Special note: the page image is loaded from an external memory segment - the handle of this memory 
segment is read from the prvview. Pv. PrvSegHandle property of the parent pRvVIEw object. 


WNLINIT oo Initiatise 


VOID wn_init (IN_PRVPAGE *pinit) ; 


Initialise the pRvpaGE object. 
Writes *pinit to prvpage. init. 


Writes pinit->wid tO win.id. 


PVP{MARGINS _ ) : Margins 
VOID pvp_margins (INT flag) ; 
Create a graphics context and the draw the page view and the page number. 


Sends self a WN_DODRAW message. 


PRVCOMM 


PRVCOMM 


com_init 
com_menu 
com_file_ change 


com_statwin 
com_accl_check 


Commend 


com_mode_change 


com_exit 
pvc_preview_print 
pvc_preview_margins 
pvc_preview_options 
pvc_preview_jump 
pvc_preview_exit 


The prvcomm class provides the print preview command manager. An example print preview menu is 
shown in the following picture: 


eae (Print 
Show margins 
Pages to display 


Jump to page S 
Exit preview Pe 


The menu items supplied are as follows: 


¢ Print - this allows the user to print during print preview operations: this option uses the print 
command in the original command manager of the application. 


° Show margins/Hide margins - this allows the user to simply toggle the display of margins during 
print preview operations. 


XADD REFERENCE 
eee 


¢ Pages to display - this allows the user to set the total number of pages displayed during print 
preview operations: this is a system wide setting stored in the psp environment variable. 


¢ Jump to page - this allows the user to simply set the first page displayed during the print preview 
operation. This is a local, i.e. not system wide, setting. 


e Exit preview - this allows the user to terminate the print preview operation thus restoring the 
original command manager. 


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


CLASS prvcomm comman 
{ 
REPLACE com_init 
REPLACE com_menu 
REPLACE com_file_change 
REPLACE com_exit 
ADD pvc_preview_print 
ADD pvc_preview_margins 
ADD pvc_preview_options 
ADD pvc_preview_jump 
ADD pvc_preview_exit 
PROPERTY 
{ 
PR_PRVVIEW *pPrvView 
} 
} 


Property 

prvcomm.pPrvView this stores the handle of a prvvrew object. 
Resources 

Defined in the system resource file. 


RESOURCE WSERV_INFO sys_preview_acc 


{ 


menbar_id=sys_preview_menubar; 
first_com=0_PVC_PREVIEW_PRINT; 


accel= 
{ 
'p', /* Print */ 
'm', /* Margins */ 
'd', /* Pages to display */ 
'j', /* Jump to page */ 
tet /* Exit preview */ 


}; 


a a a a eal 
PRVCOMM methods 


Initialise 


VOID com_init (PR_PRVVIEW *pPreView) ; 
Initialise the prvviEw object. 


The method simply writes pprvview to prvcomm. pPrwView. 


Set menu item text 
VOID com_menu(WORD menunum, VOID *pArray) ; 
Set appropriate text for the Margins menu item. 


If the prevview. Pv.Disp.Flags property of the prvview object contains pvv_MARGINS_ON: 


2-22 


2 PRINT PREVIEW CLASSES 
eee NNT PREVIEW CLASSES | 


¢ sets the text in the Margins menu item from the sys_HIDE_MARGINs system resource: on English 
language machines this is "Hide margins". 
Otherwise: 


e sets the text in the Margins menu item from the sys_DISPLAY_MARGINs system resource: on 
English language machines this is "Show margins". 


Note: this method is called immediately before the menu is displayed. 


Edt application 


INT com_exit (VOID) ; 


Exit the print preview and the application. 
Destroys the current prvview object by sending a pestroy message to prvcomm. pPrvView. 


Sends a com_EXIT message to w_ws->wserv.com. 


Print 


VOID pvc_preview_print (WORD menunum, VOID *pArray) ; 
Print all of the pages in the print preview range. 
If the prvview.pPages property of the pRvviEw object specified by prvcomm. pPrvview is non-zero: 


e displays an information message containing the text in the sys_PREVIEW_BUSY system resource: on 
English language machines this is "Busy, cannot print yet". 


Otherwise: 


¢ — it is assumed that the message number of an appropriate print method is specified by the 
prvview.PrintMethod property of the prvvrew object. 


* it is also assumed that the handle of the original command manager is specified by the 
prvview.pOldComman property of the prvvieEw object. 


e — starts a printing operation by sending the appropriate print message to the original command 
manager. 


Toggle margins 
VOID pvc_preview_margins (VOID) ; 
Toggle the visibility of margins in the print preview window. 


The method simply sends a pvv_marcins message to the pRvvIEw object i.e. prvcomm. pPrvview. 


PVGEPRI 


VOID pvc_preview_options (VOID) ; 


IEW_OPTIONS  —_—_—s Launch Preview options dialog 


Launch a Preview options dialog allowing the user to edit the current print preview display mode. The 
dialog is passed prvcomm. pPrvView as data. 


For details of the Preview options dialog see the description of the prvoprions_puc class. 


Laur 


h Jump to page dialog 


VOID pvc_preview_jump (VOID) ; 


Launch a Jump to page dialog allowing the user to select the number of the current page in the print 
preview operation. The dialog is passed prvcomm. pPrvview as data. 


For details of the Jump to page dialog see the description of the prvsump_puc class. 


XADD REFERENCE 


PYC PREVIEW EXIT” : Exit print preview 
VOID pvc_preview_exit (VOID) ; 
Exit the print preview operation. 


Sends a DEsTRoy message to prvcomm. pPrvView. 


PRVOPTIONS_DLG 


flags next item count 
id rbuf current 
dimrid underline 
helprid absorb 
changed 
destroy wrh—dzaw 


destroy dl_item_replace 
wn_key dl_item_append 
wn_emphasise dl_init 
wn_sense_ help dl_dimmed_message 
wn_set dal_item_add 
wn_sense dl_set_size 
wn_draw dl_ing minsize 
dl_item_lock di—dyn—init 
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 


PRVOPTIONS_DLG 


wn_position 
wn_redraw 


wa—sense—heip 


wn_visible 


The pRvoptTions_pic implements the Preview options dialog which allows the user to select the number of 
pages that are displayed during a print preview operation. An example Preview options dialog is shown in 


the following picture: 
i Display 
¢2 pages 


The allowed options are shown in the following picture: 


A 


The Facing pages option allows the display of two pages whereby the first page has an odd page number. 


The Preview options dialog is used by the prvcomm print preview command manager described in the 
present chapter. 


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


CLASS prvoptions_dlg dlgbox 


REPLACE dl_dyn_init 
REPLACE dl_key 


2 PRINT PREVIEW CLASSES 


Property 


There is no property associated with the pRvopTIoNs_puG class. 


Resources 


Defined in the system resource file. 


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"; } 
be 

} 


RESOURCE DIALOG sys_preview_options_dialog 


{ 

title="Display"; 

f£lags=DLGBOX_NOTIFY_ENTER |DLGBOX_RBUF_FILLED|DLGBOX_NO_DDP; 
controls= 


{ 


CONTROL 


{ 

class=C_CHLIST; 

prompt= ti ; 
info=CHLIST{rid=sys_preview_options_chlist;}; 


} 


PRVOPTIONS_DLG methods 


Initialise 


VOID dl_dyn_init (VOID) ; 


Dynamically initialise the content of the dialog: it is assumed that algbox. rbuf contains the handle of a 
PRVVIEW object. 


Reads the maximum number of pages from the prvview.MaxNoPageViews property of the prvvrEw object 
and if the maximum number of pages is less than pvv_vIEW_MAX_PAGEVIEWS: 


e deletes the items from the data for the Mode control that specify more than the maximum number 
of pages. 


e — sets the index of the item selected in the Mode control to the smaller of the 
prvview.Pv.Disp.Mode property of the prvview object and the maximum number of pages. 


Otherwise: 


© — sets the index of the item selected in the Mode control to the prvview.Pv.Disp.Mode property of 
the pRvview object. 


DEKEY Handle key input 
INT dl_key (VOID) ; 


Save the content of the dialog: it is assumed that aigbox. rbuf contains the handle of a prvvrew print 
preview object. 


Sets the number of pages displayed in the print preview by sending a w_seT message to dlgbox.rbuf with 
as argument the index of the item selected in the Mode control. 


Returns WN_KEY_CHANGED. 


XADD REFERENCE 


PRVJUMP_DLG 


flags next item count 
id rbuf current 
dimrid underline 
helprid absorb 
changed 
destrey wh—draw 


PRVOPTIONS_DLG 


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 dl_ing_ minsize 
dl_item_lock di—dyn—init 
dl_item_dim di—key 
di_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 


wa-sencse—heip 


wn_visible 


The prvsump_puc class implements the Jump to page dialog which allows the user to select the first page 
on the screen during the print preview operation. An example Jump to page dialog is shown in the 
following picture: 


Jump to page 


[Page number iE] 


The Jump to page dialog is used by the prvcomm print preview command manager described in the present 
chapter. 


Class definition 
Defined in sub-category file prvdigs.cl (generated header file prvdlgs.g). 
CLASS prvjump_dlg dlgbox 


REPLACE dl_dyn_init 
REPLACE dl_key 


} 


Property 
There is no property associated with the prvgump_puc class. 


2 PRINT PREVIEW CLASSES 
SSeS RINT PREVIEW CLASSES © 


Resources 


Defined in the system resource file. 


RESOURCE DIALOG sys_preview_jump_dialog 
{ 
title="Jump to page"; 
flags=DLGBOX_NOTIFY_ENTER |DLGBOX_RBUF_FILLED |DLGBOX_NO_DDP; 
controls= 
{ 
CONTROL 
{ 
class=C_NCEDIT; 
prompt="Page number"; 
infosNCEDIT 
{ 
low=1; 
high=9999; 


i 


ae re ee ae ey 
PRVJUMP_DLG methods 


VOID dl_dyn_init (VOID) ; 


Dynamically initialise the content of the dialog: it is assumed that digbox.rbuf contains the handle of a 
PRVVIEW object. 


Sets the page number of the first page in the preview range as the minimum value in the Page number 
control: this is equal to one plus the prvview. Pv. PageOffset property of the PRvvzEw object: 


Sets the page number of the first page on screen as the current value in the Page number control: this is 
equal to the sum of the prvview.Pv.Pagecffset and prvview. Pv. PageNo property of the pRvv1ew object 


INT dl_key(VOID) ; 


_ Handie key input 


Save the content of the dialog: it is assumed that digbox. rbuf contains the handle of a prvvrew object. 
If the current value in the Page number control exceeds the number of the last page in the preview range: 


® — sets the current value in the Page number control to the number of the last page in the preview 
range: this is equal to the sum of the prwiew. Pv. PageOffset and prvview. Pv.NoPages property 
of the prvvrew object. 


e displays an information message containing text from the sys_RANGE_RESET system resource: on 
English language machines this is "Out of range - reset to limit". 


© returns WN_KEY_NO_CHANGE. 
Otherwise: 


¢ — sets the first page displayed on screen by sending a pvv_NEW_PAGE message tO digbox.rbuf with 
as argument the current value in the Page number control minus the page offset i.e. the 
prvview.Pv.PageOffset property of the prvvrew object. 


e  returms WN_KEY_ CHANGED. 


o— 


CHAPTER 3 


CALENDAR CLASSES 


This chapter describes the following two classes: 
e the canimewn class which is designed to be used with the canwzn class. 
e the canwrn class which provides a convenient means to create and use a graphical calendar view. 


Note that both the ca.tmewn and canwin classes are included in the xapp category and thus an instance of 
each class should be created as follows: 


self->demo.calwin=f_new(CAT_MYAPP_XADD,C_CALWIN) ; 
self->demo.calimgwn=f_new(CAT_MYAPP_XADD,C_CALIMGWN) ; 


It is expected that applications that wish to display a calendar window are more likely to create an instance 
of cauwrn, rather than the more primitive caLIMGwIN. 


Since caLWIN's component cALIMGWIN expects to receive redraw message, an instance of caLwrn is not 
suited to being created from OPL or HWIF programs. 


Precursors 


An understanding of the caLwrn and caLImGwn classes will be helped by a knowledge of: 
e the graphical calendar display in the Series 3a Agenda application. 
e the cauime class described in The Calendar Image Class chapter of the FORM Reference manual. 
e the wn and Bwzrn classes. 


Class diagram 


calwin 


XADD REFERENCE 


CALIMGWN 


destroy 

wn_calic_ position 
wn_connect 
wn_dodraw 
wn_emphasise 
wn_key 
wn_position 
wncredzaw 


wn_sense_help 


wn_visible 


wn_set 
wn_sense 
wn_draw 
wn_init 


The caLimewn class is intended to be used by the catwrn class described in the next section. It does no 
more than provide a borderless window suitable for holding a calendar view drawn by an instance of the 
CALIMG class. 


Class definition 


The caLincwn class subclasses win and is defined in the sub-category file calwin.cl (with generated header 
file calimgwn.g). 


CLASS calimgwn win 
{ 
REPLACE wn_redraw 
PROPERTY 1 
{ 
VOID *calimg; 


} 


} 
Property 
calimgwn.calimg an instance of the canrme class responsible for drawing and maintaining a calendar 
view. A description of the cauime class may be found in the FORM Reference 
manual. 


a a ee 
CALIMGWN methods 


WN_REDRAW Redraw 
VOID wn_redraw(P_RECT *prect); 


Redraw the part of the calendar view which overlaps the region defined by the p_REct struct pointed to by 
prect. 


The code is as follows: 


wBeginRedrawGCo (self->win.id,prect) ; 
p_send3 (self->calimgwn.calimg,O_CI_REDRAW,prect) ; 
wEndRedraw () ; 


3 CALENDAR CLASSES 


CALWIN 


wn_init 
wn_emphasise 


wn_position 
wn_redraw 
wn_sense_help 
wn_visible 


wn_set 


The canwin class provides a bordered and shadowed window containing a graphical calendar view. An 
example caLwin display is shown in the following diagram, which indicates some of the components of the 
window: 


month title calendar title 


days of the week title 


Note that today's date - i.e. the fourteenth - is indicated in a bold font. 


On the Series 3a, the calendar also supports multiple rows and columns of months, as illustrated in the 
following picture: 


7 
3 
16 


GON) = 
= fw 


An owning object may allow the canwrn class to determine approriate fonts, font styles and spacings in 
which case the calendar view may contain either one, three or twelve months. Alternatively the owning 
object may explicitly specify the fonts, font styles, spacings and the number of rows and columns. Clearly 
the first mode of use is the simplest and is thus recommended. 


XADD REFERENCE 
ee 


Note that, on the Workabout, a calendar window may only display a single month. 


Class definition 


The canwrn class subclasses bwin and is defined in the sub-category file calwin.cl (with generated header 
file calwin.g). 


CLASS calwin bwin 


{ 
REPLACE destroy 
REPLACE wn_init initialise to 1 of 3 types of calendar window 
REPLACE wn_emphasise deals with cursor drawing & erasing 
REPLACE wn_key 
REPLACE wn_sense 
CONSTANTS 
{ 
IN_CALWIN_1_ MONTH 0x0001 
IN_CALWIN_3_MONTH 0x0002 
IN_CALWIN_12 MONTH 0x0004 
IN_CALWIN_STD_FLAGS 0x0007 above three ORed together 
IN_CALWIN_USER_SPEC 0x0010 none of the above but user specified 
PR_CALWIN TODAY _HOOKED 0x0020 
} 


TYPES ( 


{ 


typedef struct 


{ 
UWORD flags; 
ULONG days; 
P_POINT pos; 
VOID *calimg; in_calimg struct (see calimg.cl) 
VOID **self ptr; where to write self to (in owner's property) 
} IN_CALWIN; 
} 
PROPERTY 1 
{ 
PR_CALIMGWN *calimgwn; 
VOID *calimg; allows direct call to calimg eg goto_date() etc 
UWORD flags; 


VOID **self ptr; 


} 
} 


Property 

calwin.calimgwn the handle of an instance of the cau rmewn class described in the first section of the current chapter. 

calwin.calimg the handle of an instance of the canine class described in The Calendar Image Classes chapter of 
the FORM Reference manual. 

calwin.flags contains an ored combination of flags as described for the wn_init method. 

calimg.self ptr assumed to point to the address at which the owning application stores the canwrn object handle. 


Se eee ee ee a a ee 
CALWIN methods 


DESTROY sit a Destroy 
VOID destroy (VOID) ; 
Destroy the caLwin instance. 


If calwin. flags contains PR_CALWIN_TODAY_HOOKEn, the method sends a WS_HOOK_TODAY_CHANGED message 
to the wsErv object. 


The method then supersends a pestroy message. 


3 CALENDAR CLASSES 


Initialise 


VOID wn_init (IN_CALWIN *init); 
Initialise the instance of caLwin according to the content of the 1n_canwrn struct pointed to by init. 


If w_ws->wserv. flags does not contain PR_WSERV_FULLSCREEN, the method calls p leave with an 
argument of RUN_ACTIVE_CLEANUP_NONOTIFY. 


Otherwise the method creates, initialises and displays a calendar view. 
The appearance of the calendar view is specified by means of an 1n_caLIne struct defined as follows: 


typedef struct 


{ 

UWORD flags; 
ULONG days; 
P_POINT pos; 
VOID *calimg; 
VOID **self ptr; 
} IN_CALWIN; 


The significance of the members of the in_ca.wrn struct is as follows: 
flags the allowed values are: 


IN_CALWIN_USER_SPEC in which case the initialisation data for the caLrmc instance is read 
from init->calimg. Note that this flags takes precedence over the remaining three. 


IN_CALWIN_12_MoNnTH in which case appropriate initialisation data is created for a calendar 
view containing twelve months arranged in two rows of six months each. On the 
Workabout, this flag, if present, will be removed from the initialisation data. 


IN_CALWIN_3 MONTH in which case appropriate initialisation data is created for a calendar 
view containing three months arranged as one row of three months. On the Workabout, this 
flag, if present, will be removed from the initialisation data. 


IN_CALWIN_1_MonTH in which case appropriate initialisation data is created for a calendar 
view containing one month. On the Workabout, this flag will be forced to be present in the 
initialisation data. 


days specifies the initial value for the current date and is expressed as the number of days elapsed 
since 1/1/1900. 


pos specifies the initial position of the main bordered window and is modified if necessary to 
ensure that the calendar is not clipped by the edges of the screen. In the latter case the 
modified value is such that the calendar view is centred in the window. 


calimg the address of an In_cALIMe struct containing initialisation data for the caLIMe instance. 
This is ignored unless the flags member contains IN_CALWIN_USER_SPEC. The IN_CALIMG 
struct is described in The Calendar Image Class chapter of the FORM Reference manual. 


self ptr specifies an address in the owning application where the handle of the canwin instance is 
stored. 


Writes init->flags to calwin. flags and writes init->self->ptr tO calwin.self->ptr. 


On the Workadour, the flags IN_CALWIN_3_MONTH and IN_CALWIN_12_MONTH are cleared from the 
initialisation data and the flag 1n_caLwin_1_MonTH is forced to be set. before the data is copied to 
calwin. flags. Note that this also automatically guarantees that Iv_CALWIN_USER_SPEC is not present. 


Unless init->flags contains IN_CALWIN_USER_SPEC, an IN_CALIMG Struct is created and initialised with 
appropriate values for the required calendar view. These values are as follows: 


wid specifies the window ID of the borderless window: this is set to calwin. calimgwn->win.id. 


width specifies the width of the borderless window corresponding to the caLrimcwn component. 
This window is of the exact size required to hold the calendar view. If the calendar view is 
too wide for the screen the method calls p_leave with an argument of E_GEN_TOOwIDE. 


XADD REFERENCE 
EEE 


tl specifies the gutter dimensions. The x member specifies the width of the left and right 
gutters and is set to seven. The y member specifies the height of the top and bottom gutters. 
If init->flags contains IN_CALWIN_12_monTus, the y member is set to five. Otherwise it is 
set to seven, 


mrow specifies the number of rows. If init->£1ags contains IN_CALWIN_12 MONTHS, mrow is set to 
two, otherwise it is set to one. 


mcol specifies the number of columns. If init->£1ags contains IN_CALWIN_12_ MONTHS, mcol is 
set to six, or if init->flags contains IN_CALWIN_3_MONTHS, mcol is set to three, otherwise it 
is set to one. 


flags set to zero. 


title specifies the font characteristics of the main title. The leading, style and f£id members are 
set to one, G_STY_NORMAL and FoNT_ID_13_s respectively (on the Workabour, the title font 
ID is set to Font_1D_S3BOLD). 


month specifies the font characteristics of the month title. The 1eading and style members are set 
to one and G_sTy_norat respectively. If init->£1ags contains IN_CALWIN_12_monTus, the 
£id member is set to FoNT_ID_s3BOLD, otherwise it is set to FONT_ID_11B Ss 
(FONT_ID_s3BoLD on the Workabout). 


dow specifies the font characteristics of the days of the week title. The leading and style 
members are set to one and G_sTy_Normat respectively. If init->flags contains 
IN_CALWIN_12_MonTuS, the fid member is set to FonT_1p_s3, otherwise it is set to 
FONT_ID_11_S (FONT_ID_s3 on the Workabou?). 


day specifies the font characteristics of the day of the month numbers. The leading and style 
members are set to one and G_sTy_NorMat respectively. If init->f£1ags contains 
IN_CALWIN_12_MONTHS, the fid member is set to FonT_ID_pIGITs_s*4, otherwise it is set to 
FONT_ID_11_S (FonT_zD_s3 on the Workabout). 


daygap specifies a character the width of which in the day number font and style defines the 
spacing between the day numbers and is set to osPacE. 


mthgapx specifies the horizontal pixel separation between adjacent months. If init->£lags contains 
IN_CALWIN_12_MONTHS, mthgapx is set to six, otherwise it is set to twelve. 


hserlm specifies the default granularity for scrolling horizontally by month. If init->flags 
contains IN_CALWIN_12_ MONTHS, hscr1m is set to six, otherwise it is set to one. 


startm specifies the month number of the first month in the calendar view. If init->£1ags contains 
IN_CALWIN_12_MONTHS, startm is set to zero, otherwise it is determined from the value 
implicitly specified in init->days. 


days specifies the current date expressed as days elapsed since 1/1/1990 and is set to init->days. 


font specifies additional font information for the month, day of week, title and day text. For 
example, the ascent of the month text, which is font -mth_ascent, is calculated from the 
font ID and the style specified in month. fia and month. style respectively. 


Otherwise (i.e. if init->£1ags contains IN_CALWIN_USER_SPEC) it is assumed that init->calimg points to 
an IN_CALING struct initialised by the owner. 


Creates the main bordered window by sending se1¢ a wn_connecT message with appropriate arguments. 
The position is set to the pos member of the 1n_ca.wrn struct as described above. The width is set to the 
width of the calendar plus the width of the left and right gutters, and similarly the height is set to the height 
of the calendar plus the height of the top and bottom gutters. On the Series 3a, but not on the Workabout, if 
the window is too large to fit on the screen, the method calls p_leave(E_GEN_TOOWIDE). 


Creates an instance of the caLImGwn class and writes the handle to calwin.calimgwn. Creates the calendar 
window by sending a wN_ConnEcT message to calwin.calimgwn with a background attribute of 
W_WIN_BACK_NoNnE. The window dimensions are set to those of the calendar view. 


Creates an instance of the cane class and writes the handle to both calwin. calimg and 
calwin.calimgwn->calimgwn.calimg. 


a. 


3 CALENDAR CLASSES 


If init->flags contains IN_CALWIN_USER_SPEC, initialises the caLimc instance by sending a c1_INIT 
message to calwin.calimg with init->calimg as argument. 


Otherwise initialises the caLzMc instance by sending a c1_INIT message to calwin.calimg with the 
address of an appropriately set 1n_ca.zne struct as described above. 


If init->flags contains IN_CALWIN_12_ MONTHS: 


e loads the resource with ID sys_catenpar and sets this as the calendar title by sending a 
CI_SET_TITLE message to calwin.calimg. 


Sends a ws_HOOK_TODAY_CHANGED message to w_ws with arguments of calwin.calimg and 
O_CI_TODAY_CHANGED. 


Sets PR_CALWIN_TODAY_HOOKED in calwin. flags. 


Makes the calendar view visible by calling the htnitvis utility routine with an argument of se. 


INT wn_key(UINT keycode, UINT modifiers) ; 
Handle a keypress. 
If keycode is W_KEY_ESCAPE: 
e returns WN_KEY_CANCELLED. 
If keycode is W_KEY_RETURN: 
e  returms WN_KEY_CHANGED. 
If keycode is W_KEY_TAB: 
e ifcalwin.flags contains IN_CALWIN_USER_SPEC, the method returns wN_KEY_NO_CHANGE. 


e  ifmodifiers contains W_CTRL_MODIFIER and calwin.flags contains IN_CALWIN_12_ MONTH, the 
method returns WN_KEY_NO_CHANGE. 


e otherwise the method creates a new caLwin object and initialises it as described for the wn_init 
method. If modifiers contains w_CTRL_mMopIFIER, the new calendar contains twelve months. 
Otherwise if modifiers contains W_SHIFT_MODIFIER, and calwin. flags contains 
IN_CALWIN_1_MONTH, the new calendar contains twelve months. Otherwise if modifiers contains 
W_SHIFT_MODIFIER, the new calendar calendar contains half the current number of months. 
Otherwise if calwin. flags contains IN. CALWIN_12_MontTH, the new calendar contains one month. 
Otherwise, the new calendar contains twice the current number of months. 


e de-emphasises the current calendar view by sending self a WN_EMPHASISE message and 
emphasises the new calendar view by sending a wN_EMPHASISE message to the new CALWIN object. 


* writes the handle of the new cawrn object to the location pointed to by calwin.self_ptr and 
then destroys the current calendar view by sending self a DESTROY message. 


@ retums WN_KEY_NO_CHANGE. 


If keycode is less than ox100 and corresponds to either the special keycode stored at address 
&W_ws->wserv.sc[H_SC_ILEss] or the special keycode stored at address ew_ws->wserv.sc [H_SC_ICOMMA] 
(on English language machines these are the less than symbol and the comma respectively): 


¢ ifmodifers contains W_CTRL_MODIFIER, moves the cursor backwards in time by seven days by 
sending a CI_MOVE_CURSOR message to calwin.calimg with an argument of CALIMG_PREV_WEEK. 


e otherwise, moves the cursor backwards in time one day by sending a c1_movE_cuRsoR message to 
calwin.calimg with an argument of cALIMG PREV_DAY. 


If keycode is less than ox100 and corresponds to either the special keycode stored at address 
&w_ws->wserv.sc [H_SC_IMORE] or the special keycode stored at addess ew_ws->wserv.sc{H_SC_IDOT] (on 
English language machines these are the greater than symbol and the full stop respectively): 


XADD REFERENCE 
eee eee 


¢ ifmodifers contains W_CTRL_MODIFIER, moves the cursor forwards in time seven days by sending 
a CI_MOVE_CURSOR message to calwin.calimg with an argument of CALIMG_NEXT_WEEK. 


¢ otherwise, moves the cursor forwards in time one day by sending a cr_move_cursor message to 
calwin.calimg with an argument of CALIMG_NEXT_DAY. 


If keycode is W_KEY_UP and calwin. flags contains IN CALWIN_1_MONTH: 


* moves the cursor backwards in time one week - i.e. seven days - by sending a cl_MOVE_CURSOR 
message to calwin.calimg with an argument of cALIMG_PREV_WEEX and then returns 
WN_KEY_NO_CHANGE. 


If keycode is W_KEY_RIGHT and calwin. flags contains IN_CALWIN_1_MONTH: 


* moves the cursor forwards in time one day by sending a cr_mov=E_curRsoR message to 
calwin.calimg with an argument of caLIMc_NExT_pay and then returns wN_KEY_NO_CHANGE. 


If keycode is W_KEY_LEFT and modifiers contains W_SHIFT MODIFIER: 


¢ moves the cursor backwards in time one day by sending a cr_MovE_cURSOR message to 
calwin.calimg with an argument of cALIMG_PREV_pay and then returns WN_KEY_NO_CHANGE. 


If keycode is W_KEY_LEFT and modifiers contains W_CTRL_MODIFIER: 


¢ moves the cursor backwards in time one month by sending a c1_Move_cuRsoR message to 
calwin.calimg with an argument of caLIMG_PREV_pay and then returns wN_KEY_NO_CHANGE. 


Otherwise, if keycode is W_KEY_LEFT: 


¢ moves the cursor to the left by one day in the calendar view by sending a ct_mMovE_cURSOR 
message to calwin.calimg with an argument of caLImG_LeFr and then returns 
WN_KEY_NO_CHANGE. 


If keycode is W_KEY_RIGHT and modifiers contains W_SHIFT_ MODIFIER: 


¢ moves the cursor forwards in time one day by sending a cr_move_cuRsoR message to 
calwin.calimg with an argument of caLIMG_wexT_pay and then returns wN_KEY_NO_CHANGE. 


If keycode is W_KEY_RIGHT and modifiers contains W_CTRL_MODIFIER: 


* moves the cursor forwards in time one month by sending a cr_MovE_cURSOR message to 
calwin.calimg with an argument of CALIMG_NEXT_MONTH and then returns WN_KEY_NO_CHANGE. 


If keycode is W_KEY_RIGHT: 


¢ moves the cursor to the right one day in the calendar view by sending a cr_Move_cuRSOR message 
to calwin.calimg with an argument of caLimc_RiGHT and then returns wN_KEY_NO_CHANGE. 


If keycode is W_KEY_uP and modifiers contains W_SHIFT_MODIFIER: 


* moves the cursor backwards in time one week by sending a c1_MovE_cursoR message to 
calwin.calimg with an argument of cALIMG_PREV_WEEK and then returns wN_KEY_NO_CHANGE. 


If keycode is W_KEY_UP and modifiers contains W_CTRL_MODIFIER: 


¢ moves the cursor backwards in time one year by sending a cI_MOVE_CURSOR message to 
calwin.calimg with an argument of caLIMG_PREV_yEaR and then returns wN_KEY_NO_CHANGE. 


If keycode is w_KEY_UP: 


° moves the cursor upwards in the calendar view by one day by sending a cr_Move_cURSOR message 
to calwin.calimg with an argument of caLimc_up. 


e retumms WN_KEY_NO_CHANGE. 
If keycode is W_KEY_DowN and modifiers contains W_SHIFT_MODIFIER: 


¢ moves the cursor forwards in time one week - i.e. seven days - by sending a cr_MOVE_CURSOR 
message to calwin.calimg with an argument of caLimG_NEX?T_weExK and then returns 
WN_KEY_NO_ CHANGE. 


If keycode is W_KEY_DOWN and modifiers contains W_CTRL_MODIFIER: 


ee ee 
3-8 


3 CALENDAR CLASSES 


e moves the cursor forwards in time one year by sending a c1_MovE_cURSOR message to 
calwin.calimg with an argument of caLIMG_NEXT_YEAR and then returns wN_KEY_NO_ CHANGE. 


If keycode is w_KEY DOWN: 


e moves the cursor downwards one day in the calendar view by sending a cr_MovE_CURSOR message 
to calwin.calimg with an argument of caLIMG_pown and then returns wN_KEY_NO_CHANGE. 


If keycode iS W_KEY_SPACE: 


e moves the cursor to today's date by sending a cr_MovE_cuRSoR message to calwin.calimg with an 
argument of caLIMG_GoTO_Topay and then returns wN_KEY_NO_CHANGE. 


If keycode iS W_KEY_PAGE_UP: 


e moves the cursor to the previous calendar page by sending a c1_MovE_cursoR message to 
calwin.calimg with an argument of cALIMG_PAGEUP. 


If keycode is W_KEY_PAGE_DOWN: 


e moves the cursor to the next calendar page by sending a cr_Move_cursor message to 
calwin.calimg with an argument of CALIMG_PAGEDN. 


If keycode is W_KEY_HOME: 


e moves the cursor horizontally to the left edge of the calendar view by sending a cr_mMovE_cuURSOR 
message tO calwin.calimg with an argument of caLIMG_HomE and then returns 
WN_KEY_NO_CHANGE. 


If keycode is w_KEY_END: 


© moves the cursor horizontally to the right edge of the calendar view by sending a cI_MoVE_CURSOR 
message to calwin.calimg with an argument of caLIMGc_snp and then returns wN_KEY_NO_CHANGE. 


Otherwise the method returns wN_KEY_NO_CHANGE. 


& WN_SENS 


VOID wn_sense(ULONG *psense) ; 


rent date 


Write the current date expressed as days elapsed since 1/1/1900 to the uLonc pointed to by psense. 


Sends a cI_SENSE message to calwin.calimg. 


hasise 


VOID wn_emphasise(UINT flag) ; 
Emphasise the display if £1ag is TRUE, otherwise de-emphasise the display. 


Sets the emphasis of the calendar view by sending a c1_EMPHASISE message to calwin.calimg With an 
argument of f1ag and then sets the emphasis of the bordered window by supersending a wN_EMPHASISE 
message with an argument of flag. 


XADD REFERENCE 
es eee SSSSSeSSSSSSSSSSSSSSSSSNSe 


EE SS ee SS aay 
Examples 


The following section provides some useful information on using the cazwrn class as a component in an 
application. 


Creating a CALWIN component 


A CALWIN object may be created and initialised as follows: 
IN_CALWIN init; 


init .flags=IN_CALWIN_1_ MONTH; 

p_send (self->kalwin.time,O_TO_SENSE,SENSE_TIME_DAYSEC, &ds) ; 
init.days=ds.day; 

init .pos.x=400; 

init.pos.y=180; 

init .calimg=NULL; 

init.self_ptr=&self->kalwin.calwin; 
self->kalwin.calwin=f_newsend(CAT_KAL_XADD,C_CALWIN,O_WN_INIT, &init) ; 
p_send(self->kalwin.calwin,O WN_EMPHASISE, TRUE) ; 


The above code creates a calendar view containing one month with the current date set to the date stored in 
a TIME object. Note that large values are specified for the x and y screen coordinates to force centering of 
the image. 


A description of the rrme class may be found in the OLIB Reference manual. 


Handling keypresses 


The following wn_key method is suitable for an application that wishes to use a CALWIN component. It 
carries out the following operations: 


e if the keypress is a Tab key, and a calendar view is not present, the method launches a calendar 
window and disables the Menu and accelerator keys by writing self to w_ws->wserv. filter. 


e otherwise the method sends the keypress directly to the calendar view and the return value 
determines the next action. 


e if the return value is ww_xey_canceLLED the method destroys the catwrn object and re-enables the 
Menu and accelerator keys by writing NULL to w_ws->wserv. filter. 


e if the return value is ww_key_cHaNncep the method senses the current date is sensed and stores it in 
the TIME object. The method then destroys the canwrn object and re-enables the Menu and 
accelerator keys by writing NULL to w_ws->wserv. filter. 


3 CALENDAR CLASSES 


LOCAL_C VOID DestroyCalwin(PR_KALWIN *self) 
{ 
w_ws->wserv.filter=NULL; 
hDestroy(self->kalwin.calwin) ; 
self->kalwin.calwin=NULL; 


} 
#pragma METHOD _CALL 


METHOD INT kalwin_wn_key(PR_KALWIN *self,UINT keycode,UINT modifiers) 
{ 
IN_CALWIN init; 
P_DAYSEC ds; 
INT ret; 


if (self->kalwin.calwin) 
{ 
ret=p_send4 (self->kalwin.calwin,O_WN_KEY, keycode,modifiers) ; 
if (ret==WN_KEY_CANCELLED) 
{ 
DestroyCalwin (self) ; 
} 
else if (ret==WN_KEY_CHANGED) 
{ 
ds.sec=0; 
p_send3 (self->kalwin.calwin,O_WN_SENSE, &ds.day) ; 
if ((ret=p_send4 (self->kalwin.time,O_TO_SET,SET_TIME_DAYSEC, &ds) ) <0} 
p_exit (ret); 
DestroyCalwin (self) ; 
} 
} 
else if (keycode==W_KEY TAB) 
{ 
init .flags=IN_CALWIN_1_MONTH; 
if ((ret=p_send(self->kalwin.time,O_TO_SENSE,SENSE_TIME_DAYSEC, &ds) ) <0) 
p_exit (ret) ; 
init.days=ds.day; 
init .pos.x=400; 
init.pos.y=180; 
init .calimg=NULL; 
init.self_ptr=&self->kalwin.calwin; 
self->kalwin.calwin=f_newsend(CAT_KAL XADD,C_CALWIN,O WN_INIT, &init) ; 
p_send(self->kalwin.calwin,O_WN_EMPHASISE, TRUE) ; 
w_ws->wserv.filter=(PR_WIN *)self; 


} 


return (WN_KEY CHANGED) ; 


} 


CHAPTER 4 


AUTOMATIC TEST SYSTEM CLASSES 


This chapter documents the arssv and atst1m classes that are used to provide Series 3a automatic 
application test mechanisms, driven from another process. 


Although primarily designed for application testing, the mechanism can be used for other purposes. An 
example is its use by the Series 3a Agenda application, when using the Word application to edit a memo, to 
force Word to display the dialog shown in the following illustration: 


Appointment 


ar Normal 
This is a memo Outline 


Change memo of repeating item 


‘Change which occurrencesRwig 


Thu 23 


For examples of the use of the ATS mechanism, see the Series 3a Automatic Test System chapter of the 
Object Oriented Programming Guide. See also the description of the arsptat class in the Dialog Boxes 
chapter of the HWIM Reference manual. 


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


¢  inter-process messaging, as described in the Processes and Inter-process Messaging chapter of the 
PLIB Reference manual 


e the pcs and server classes, described in the Inter-process Communication chapter of the OLIB 
Reference manual 


e the timer class, described in the Timer Active Object Classes chapter of the OLIB Reference 
manual. 


Class diagram 


/ atssv ae a Bae 


> atstim > 


XADD REFERENCE 


ATSSV 


sv_init 
sv_run 


sv_abrun 
sv_free 
sv_key 


The arssv class subclasses server to provide an application with the ability to respond to inter-process 
messages with message types in the range Ty_ATS START_RANGE (0x30) to TY_ATS_END_RANGE (0x3f) 
inclusive. The following ATS inter-process message types are defined in the header file ats. h: 


TY_ATS_CLIENT_POS ox30 A ClientPos message, to set the application's client position in the task 


order. 

TY_ATS KEY ox31 A Key message, to send a keypress to the application. 

TY_ATS PAUSE 0x32 A Pause message, to pause the application for a specified period of 
time. 

TY_ATS_ MESSAGE ox33 An InfoPrint message, to cause the application to display 


informational text. 
TY_ATS_ DIALOG ox34 A Dialog message, to cause the application to run a specified dialog. 


TY_ATS_SELF_CHECK ox35 A SelfCheck message, to cause the application to run a self- 
consistency check. 


TY_ATS_WINDOW_xSUM 0x36 = A Checksum message, to run a checksum on the application's display. 


TY_ATS_RECORD ox37 A Record message, to start or stop external recording of keypresses 
received by the application. 


TY_ATS_GET_KEY ox38 A GetKey message, used with Record, to request notification of the 
next keypress received by the application. 


TY_ATS_ALLCOUNT ox39 An AllocCheck message, to walk the allocated cells in application's 
heap and report on the results. 


Class definition 


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


CLASS atssv server 
{ 
REPLACE sv_init 
REPLACE sv_run 
REPLACE sv_abrun 
ADD sv_free 
ADD sv_key 
PROPERTY 1 
{ 
PR_TIMER *timer; 
VOID *pm; 
WORD freed; 
VOID *pm_key; 


4 AUTOMATIC TEST SYSTEM CLASSES 


Property 

atssv.timer Either nuut or the handle of an instance of the arst1m timer class, used to implement the 
pause facility. 

atssv.pm A pointer to an ars_MEss struct, containing the current ATS message data. 


atssv.freed Set to FALSE on receipt of an inter-process ATS message, and only set to rRuE when the 
ATS message buffer is freed (by a call to p_mfree). 


atssv.pm_key Ifnot NULL, a pointer to the ATS message data for a Getkey message. 


Auxiliary structures 


As well as the ATS inter-process message types given earlier in this chapter, the header file ats.h contains 
the declarations of the following structures, used to construct the message buffer for an ATS inter-process 
message. An application (referred to here as the controlling process) can include azts.h to allow it to use the 
ATS mechanism, without having to have any knowledge of the ATS classes themselves (such as would be 
given by including atssv.g). 


The ats_DIAL_DEF struct is used to specify a dialog to be run: 


typedef struct 
{ 
UWORD main; 
UWORD mainlen; 
UWORD buts; 
WORD butslen; 
} ATS_DIAL_DEF; 


The meanings of the members of this struct are as follows: 


main The offset within the controlling process to a buffer containing the loaded resource for 
the dialog. 

mainlen The length of the main resource. 

buts Either nuuu or the offset within the controlling process to a buffer containing data for 


one of the dialog's controls. The data may be a choice list resource, a action list 
resource or a text string (up to 256 characters, including the terminating zero) for an 
edit box. 


butslen The length of the buts resource. 


See the Series 3a Automatic Test System chapter of the Object Oriented Programming Guide and the 
description of the arspzat class in the Dialog Boxes chapter of the HWIM Reference manual for further 
information on the ars_DIAL_DEF struct. 


The ats_key_per struct contains the keycode and the modifier flags for a keypress sent by means of a 
TY_ATS_KEY inter-process message: 


typedef struct 
{ 
UWORD key; 
UWORD mod; 
} ATS_KEY_DEF; 


The data of an ATS inter-process message is contained in an ats_MESS_Bopy struct: 


typedef union 
{ 
UWORD position; /* used for TY_ATS_CLIENT_POS messages */ 
ATS_KEY_DEF k; /* used for TY_ATS_KEY messages */ 
ATS_DIAL_DEF d; /* used for TY_ATS_ DIALOG messages */ 


UWORD delay; /* used for TY_ATS PAUSE messages */ 

VOID toffs; /* used for TY_ATS_MESSAGE messages */ 

WORD par; /* used for TY_ATS_SELF_CHECK and TY_ATS RECORD messages */ 
UWORD wid; /* used for TY_ATS_WINDOW_XSUM messages */ 


} ATS_MESS_BODY; 


XADD REFERENCE 
ae eee SSS 


and the ATS inter-process message buffer is an ars_mess struct: 


typedef struct 


{ 


E_MESSAGE mess; 
ATS_MESS_ BODY u; 
} ATS_MESS; 


See the following description of the sv_run method for the usage of the various message buffer members. 


When ATS is being used to record keypresses the data for each keypress, in response to a TY_ATS_GET_KEY 
message, is contained in an ats_xevy struct: 


typedef struct 


{ 


UWORD time; 
UWORD keycode; 
UBYTE modifiers; 
UBYTE count; 

} ATS_KEY; 


This struct corresponds to the keypress event part of a window server ws_EvENT_x struct, defined in wiib. h, 
starting with its time member (that is, omitting its leading handle member). 


SSS SS EE SS ey 
ATSSV methods 


Initialise 
VOID sv_init (VOID) ; 
Initialise the arssv object. 


Supersends the sv_inz7r message, passing the start and end of the range of acceptable message types as 
TY_ATS_START_RANGE and Ty_ATS_END_RANGE respectively. 


Note that the superclass method sends an 1P_app_sERvER to the instance of (a subclass of) the OLIB recs 
class whose handle is stored in w_am->appman.ipces. This object must therefore have been created before 
the instance of arssv is initialised. On the Series 3a an instance of rpcs and an instance of arssv are 
always created and initialised during the initialisation of the wrmman application manager. 


Process an 


ino sssage 
VOID sv_run(ATS MESS *pm) ; 
Process the ATS inter-process message whose message buffer is pointed to by pm. 


The value of atssv. freed is set to FALSE and the pointer pm is copied to atssv.pm. Further processing 
depends on the inter-process message type, stored in pm->mess.type: 


TY_ATS_CLIENT_POS 
Sets the application's client position by calling: 
wClientPosition(pm->u.position, 0) ; 


and then frees the ATS inter-process message by sending itself an sv_FREE message, with a return value of 
zero. 


TY_ATS_KEY 
Processes a keypress received from another process. 


The ATS inter-process message is first freed by means of an sv_FREE message, with a return value of zero. 
The method then sends w_ws a Ws_PROCESS_KEY message, with a keycode of pm->u.key keycode and a 
modifiers value of pm->u.k.mod. 


4 AUTOMATIC TEST SYSTEM CLASSES 
—— OEE PE OP STS TEM CLASSES | 


TY_ATS_PAUSE 


Pauses the application. 


If pm->u.delay is zero the method sends w_am an AM_YIELD message and then frees the ATS inter-process 
message by sending itself an sv_FREE message, with a return value of zero. 


If pm->u.delay is non-zero, atssv.timer (an instance of atsTiM) is sent an AO_QUEUE message to generate 
a relative timeout with a time interval of pm->u.delay tenths of a second. If atssv.timer is NULL, an 
instance of arst1m is created and initialised, and its handle is written to atssv. timer, before the ao_QuEvE 
message is sent. If the creation or initialisation fails, p_1eave is called, resulting in atssv receiving an 
SV_ABRUN message. Otherwise, the freeing of the ATS inter-process message is handled by arstxm, at the 
completion of the pause. 


TY_ATS_MESSAGE 


Displays an information message copied from another process. 


The message to be displayed is copied from offset pm->u.of¢s in the process with process ID 
pm->mess.pid. This message should be a zero terminated string and may be up to 128 bytes in length, 
including the terminating zero. Before being displayed in the top left corner of the screen, by means of a 
call to the window server function winfoMsgcorner, the message is padded with two leading and two 
trailing spaces. 


The method finally frees the ATS inter-process message by sending itself an sv_FREE message, with a 
retum value of zero. 


TY_ATS_DIALOG 
Runs an ATS dialog. 
Creates an instance of arsprat (see the Dialog Boxes chapter of the HWIM Reference manual). If the 


creation fails, the method frees the ATS inter-process message by sending itself an SV_FREE message, with 
a return value of &_GEN_NOMEMORY. 


Otherwise the dialog is sent, under the protection of p_enter, a DL_DYN_INIT message, passing the pointer 
pm and the handle, seif, of this instance of arssv. If the return value from the DL_DYN_INIT message is 
non-zero (indicating that p_leave was called) the return value is copied into the dialog's atsdial.ret 
property and the dialog is sent an o_DESTRoy message. 


In all cases where the instance of arspza was successfully created, the freeing of the ATS inter-process 
message is handled by arsprat on destruction of the dialog. 


TY_ATS_SELF_CHECK 


Performs an application-specific self-consistency check. 


Sends w_ws a WS_SELF_CHECK message, passing pm->u.par and then frees the ATS inter-process message 
by sending itself an sv_FREE message, with a return value of the result returned by the WS_SELF_CHECK 
message. 


It is the responsibility of the application's subclass of wseRv to provide a meaningful ws_self_check 
method. 


TY_ATS_WINDOW_XSUM 
Performs a checksum on a specific window or on the whole screen. 


Calls the window server function ginquirechecksum for the window with ID pm->u.wid (an ID of zero 
performs a checksum on the whole screen). 


The method finally frees the ATS inter-process message by sending itself an SV_FREE message, with a 
return value containing the result of the checksum calculation. 


TY_ATS_RECORD 

Starts (if pm->u.par is non-zero) or stops (if pm->u.par is FALSE) Keypress recording. 

If attempting to start keypress recording when recording is already in progress, the method simply frees the 
ATS inter-process message by sending itself an sv_FREE message, with a return value of E_GEN_INUSE. 


Otherwise the method sets the keypress recording state (by storing the handle of this instance of arssv in 
DatGate->gate.getkeys) and sends itself an sv_FREE message, with a return value of zero. 


rs er ee 
4-5 


XADD REFERENCE 
a ss SSS 


If stopping keypress recording the keypress recording state is cleared (by clearing 
DatGate->gate.getkeys). If atssv.pm_key is non-zero, indicating that a Ty_ATS_GET_KEY inter-process 
message is outstanding, that message is freed by a call to p_mfree, passing a return value of 
E_FILE_CANCEL and atssv.pm_key is set to NULL. regardless of the initial value of atssv.pm_key, the 
method finally frees the Ty_ars_Recorp inter-process message by sending itself an sv_FREE message, with 
a return value of zero. 


TY_ATS_GET_KEY 


Transmits the next keypress to another process when in the keypress recording state. 


It is a programming error if an inter-process message of this type is received when the application is not in 
the keypress recording state, as set by the earlier receipt of a ry_ars_REcorD inter-process message. 


If atssv.pm_key is not wuLL, indicating that an inter-process message of this type is already waiting to be 
processed, the method frees the ry_ars_RECoRD inter-process message by sending itself an SV_FREE 
message, with a return value of E_GEN_INUSE. 


Otherwise the method simply copies the message pointer pm to atssv.pm_key. The message will be freed 
by the execution of the sv_key method, when the application next receives a keypress. 


TY_ATS_ALLCOUNT 
Checks the application's heap. 


Sends w_ws a WS_GET_ALLOC_INFo message, which walks the application's heap and displays an 
information message showing the number of allocated cells and the total number of bytes of allocated 
memory. The method then frees the ATS inter-process message by sending itself an sv_FREE message, with 
a return value of zero. 


an error 
VOID sv_abrun(ATS_MESS *pm, INT ret) ; 
Provide additional, specific, error processing. 


If atssv. freed is FALSE, indicating that the ATS inter-process message has not yet been freed, the method 
frees the message by calling: 


p_mfree (pm, ret) ; 


VOID sv_free(INT ret); 
Provide the normal means of freeing an ATS inter-process message after its processing. 
Sets atssv. freed tO TRUE, Calls: 


p_mfree (self->atssv.pm, ret) ; 


and then sends w_am->appman.ipcs aN AO_QUEUE message to queue a read for the next ATS inter-process 
message. 


ypress 


VOID sv_key(ATS_KEY *pkey) ; 


Report a keypress to the process that has previously registered an interest by sending an ATS inter-process 
message of type Ty_ATS_RECORD. An sv_kEy message is received from the ao_run method of the 
application's instance of a subclass of wsERv. 


If atssv.pm_key is NULL, the method simply returns. Otherwise, the ATS_KEY struct pointed to by pkey is 
copied to the offset atssv.pm_key->u.offs in the process with process ID atssv.pm_key->mess. pid. 
Following this, the current ATS inter-process message is freed by calling: 


p_mfree (self->atssv.pm_key, 0); 


and atssv.pm_key is set to NULL. 


4-6 


4 AUTOMATIC TEST SYSTEM CLASSES 


ATSTIM 


priority 
isactive 
pcb 

stat 


destroy ae—tadte 


ao_init 
ao_run 


ae init ao_queue 
ao_cancel tm_qabsolute 
ao_abrun 

ao—quere 

ae—sen 


The atstim class is specifically designed for use by arssv to implement its Pause function. It is not 
expected that application code will explicitly create an instance or send messages to any instance. 


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


CLASS atstim timer 


{ 


REPLACE ao_init 
REPLACE ao_run 
PROPERTY 


{ 


VOID *owner; 
} 
} 


Property 
atstim.owner The handle of the owning instance of arssv. 


ATSTIM methods 
AQINT 28 x 


VOID ao_init(VOID *owner) ; 


Initialise the ATS timer. 


Supersends the ao_inrT message to open a channel to the Tm: device and then copies owner, the handle of 
the owning instnce of arssv to atstim.owner. The final action is to add itself to the application manager's 
task list, with priority zero, by sending w_am an AM_ADD_TASK message. 


CORRE ; Pr 


INT ao_run(VOID) ; 


mpletion 


Process completion of the timer interval. 


Frees the ATS inter-process message by sending atstim.ownex an SV_FREE message, with a return value of 
zero. 


CHAPTER 5 


ADDITIONAL ACTIVE OBJECT CLASSES 


This chapter documents the tocona and unLoap active object classes. 


Precursors 


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


e the active class described in the ACTIVE Class and Active Objects chapter of the OLIB Reference 


manual. 


e the p_logona and p_logoffa PLIB routines described in the Error Handling chapter of the PLIB 


Reference manual. 


e the use of dynamic link libraries: see for example the Object Oriented Programming chapter in the 


PLIB Reference manual and the Building a Dynamic Library chapter in the Object Oriented 


Programming Guide. 
Class diagram 
si active” ; 
v tb faye 


7 a 


 logona > ” unload > 


XADD REFERENCE 


LOGONA 


q 
priority 
isactive 
pcb 

stat 


destroy ao_init 
ind ao_cancel 
ao_queue 


ao_run 


The Locona class is used to queue a request for the termination of a process to be reported. The report is 
implemented by sending a specified message to a specified owning object. 


Locona adds value to the PLIB p_1ogona routine by packaging the mechanism into an active object, 
thereby simplifying the detection of the completion of the asynchronous request. 


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


CLASS logona active 
{ 
REPLACE ao_init 
REPLACE ao_queue 
REPLACE ao_cancel 
REPLACE ao_run 
PROPERTY 
{ 
UWORD pid; 
VOID *owner; 
UWORD mess; 
} 
} 


Property 
logona.pid The process ID of the process whose termination is to be reported. 


legona.owner The handle of the object to which a message should be sent on termination of the 
process. 


legona.mess | The method number of the message that is to be sent to logona. owner. 


i ee SS ee Se ee eS ee SS EE Ee 
LOGONA methods 


lnitialise 


VOID ao_init(UWORD pid, VOID *owner,UWORD mess}; 
Initialise the Locona object. 


Initialises property by writing pid to logona. pid, writing owner to logona.owner and writing mess to 
logona.mess. 


Adds se1£ to the task queue by sending an am_app_TAsK message to w_am. 


> eS 
§-2 


5 THE LOGONA AND UNLOADA CLASSES 


Queues a request by sending self an Ao_QUEUE message. 


AO_QUEUE 


VOID ao_queue (VOID) ; 


tuest 


Queue a request for a report of process termination. 


Queues the request by calling the p_logona PLIB routine with as arguments logona.pid and the address of 
active.stat. The call is made under the protection of the f_1eave PLIB routine. 


AQ_CANCEL | 


VOID ao_cancel (VOID) ; 


Cancel a queued request. 
If active .isactive is non-zero indicating that a request is active: 
° cancels the request by calling the p_logoffa PLIB routine with an argument of logona.pid. 


¢ — ensures that the cancel has completed by calling the p_waitstat PLIB routine with, as argument, 
the address of active. stat. : 


e — indicates that no request is now outstanding, by writing FALSE to active. stat. 


Note: this method may safely be called if no requests are outstanding. 


AQ_ 


INT ao_xrun (VOID) ; 


Report process.termination 


Report process termination. 
Reports process termination as follows: 
p_send2 (logona.owner, logona.mess) ; 


Indicates that the event has been consumed by returning RuN_ACTIVE_USED. 


UNLOAD 


UNLOAD 


cathand 


gq 
priority 
isactive 
peb 

stat 


destroy 
ao_init 
ao_run 


ao_cancel 
ao_abrun 


ao_queue 
BO—FR 


The untoap class is used to queue a request to unload a dynamic library. It provides a convenient means of 
ensuring that a dynamic library is not unloaded until completion of the current task - or until the next 
AM_START message is sent to the application manager. 


An UNLOAD object automatically assigns itself a very high priority in order to ensure rapid completion of the 
request. 


SSE 
5-3 


XADD REFERENCE 
eee 


The unzoap class is intended to be used in a DYL that is loaded by a mechanism such as that provided by 
the WSERV ws_launch_dy1 method - that is, where an instance of a single class in the DYL is created and 
initialised immediately after the DYL is loaded. The untoan class should be made a component of the class 
in the DYL that is created and initialised and should receive a pesTRoy message when that class is 
destroyed. Since initialisation failures are handled by the mechanism of the ws_1launch_ay1 method, the 
instance of unLoap should not be created and initialised until all other initialisation is complete. Doing this 
ensures that the instance of untoap will only receive a pesTRoy message in circumstances where unloading 
the DYL is a valid operation. 


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


CLASS unload active 


REPLACE destroy 
REPLACE ao_init 
REPLACE ao_run 
PROPERTY 


HANDLE cathand; 


} 
} 


Property 
unload.cathand The handle of the category to be unloaded. 


UNLOAD methods 


_ Destroy 


VOID destroy (VOID) ; 
Destroy the untoap object. 
If unload. cathand is non-zero, sends self an AO_QUEUE message. 


Otherwise sends self a DESTROY message. 


VOID ao_init (HANDLE cathand) ; 
Initialise the untoap object. 
Writes cathana, the handle of the category to be unloaded, to unload. cathand. 


Assigns itself a high priority by writing pRIORITY_ACTIVE_POSTER tO active.priority and then adds itself 
to the application manager's task queue by sending w_am an AM_ADD_TASK message. 


A 


VOID ao_run(VOID) ; 


Process completion 


Unload the target category. 


Unloads the category specified by unload. cathand by calling the p_unloadiib PLIB routine and then 
sends self a DESTROY message. 


The method returns RUN_ACTIVE_USED. 


INDEX 


AO_CANCEL, 5-3 
AO_INIT, 4-7, 5-2, 5-4 
AO_QUEUE, 5-3 

AO_RUN, 4-7, 5-3, 5-4 

COM _EXIT, 2-23 
COM_INIT, 2-22 
COM_MENU, 2-22 
DESTROY, 2-3, 2-10, 3-4, 5-4 
DL_DYN_INIT, 2-25, 2-27 
DL_KEY, 2-25, 2-27 
LPR_INIT, 2-3 
PVC_PREVIEW EXIT, 2-24 
PVC_PREVIEW_JUMP, 2-23 
PVC_PREVIEW_MARGINS, 2-23 
PVC_PREVIEW_ OPTIONS, 2-23 
PVC_PREVIEW PRINT, 2-23 
PVV_DONE, 2-14 
PVV_INIT, 2-15 
PVV_MARGINS, 2-15 
PVV_NEW_PAGE, 2-15 
PVV_PAGES DONE, 2-15 
SV_ABRUN, 4-6 

SV_FREE, 4-6 

SV_INIT, 4-4 

SV_KEY, 4-6 

SV_RUN, 4-4 
WN_DODRAW, 2-20 
WN_DRAW, 2-12, 2-17, 2-20 
WN_EMPHASISE, 3-9 
WN_INIT,-2-12, 2-17, 2-21, 3-5 
WN_KEY, 2-11, 3-7 
WN_REDRAW, 3-2 
WN_SENSE, 3-9 
WN_SENSE_HELP, 2-10 
WN_SET, 2-12, 2-17 


kab 


| 
ee 

ss cemeel heron 
b « BP Bhs ia, 
‘ EP Te MOT A 
; 2Pe PO |! Wa 
; She Tih wax 

ese Ata a2 


fe fe hear MC fee gn 
7a TE TAL ON eS | 
fet HE NA io 


Get f 

bf, 1 RNS oe © 
tes an WAR V4 

‘T eat AM WarzaaT ov 

re £. Slag we v4 


£1 VEN a re 
Ab AM 
> e Sans 
fe ee 
we 77 * 
ph gilt