SIBO 'C' Software Development Kit HWIM REFERENCE Version 2.11 February 3, 1995 (C) Copyright Psion PLC 1990-95 All rights reserved. This manual and the programs referred to herein are copyrighted works of Psion PLC, London, England. Reproduction in whole or in part, including utilization in machines capable of reproduction or retrieval, without express written permission of Psion PLC, is prohibited. Reverse engineering is also prohibited. The information in this document is subject to change without notice. Psion and the Psion logo are registered trademarks, and Psion, PsionMC, Psion HC, Psion Series 3, Psion Series 3a and Psion Workabout are trademarks of Psion PLC. TopSpeed is a registered trademark of Clarion Software Corporation. Intel 8086 and 80286 are registered trademarks of Intel Corporation. IBM, IBM XT and IBM AT are registered trademarks of International Business Machines Corp. Microsoft and MS-DOS are registered trademarks of Microsoft Corporation. Apple and Macintosh are registered trademarks of Apple Computer Inc. VAX and VMS are registered trademarks of Digital Equipment Corporation. Brief is a registered trademark of Underware Inc. Psion PLC acknowledges that some other names referred to are registered trademarks. CONTENTS DIMtroductiOns ccsccccisesssesnsssccscicaconsectssssasutusnresesnesctesdiainavessisnssibuscecseedl omiotios com ee ces 1-1 Using: WIM classes. ts... % uss tesee. Be citich a eeatennsee haeercee eee ie 1-] INOCALION 335, c tices ceccratsyloreecosctaeecstueaecvasdi casi seueesSeltorss ssa coht ovacacivsss REO RS eR OM 1-2 IN@MICS ore ec arbcaaletict lees rsbaceee cos ethane to el anode sist eat aes ces es R= RE 8 1-2 Method Rimchion prototypes -..-.ccsciosercsesciedacsbccsat2estosisesseovsatcasvoiouieiisieoee wotsiblaas-c2aece 1-2 The: novleave: Symbol 5.2, Ystceeevetssaceeutiacvsclisssesteidees hasteves en eeecod toon oe tie eis 1-2 CLASS CIA SEIS ci stccesnssin! cael oboe gees epacsaieneduacraiaheews a6thataacMecciea Meee leas ae lanes leeeNM ct 1-3 Class:Hierarchy.. 25 <::,.ciscaceeaatvitetersth, cysvatesraseies estes asians ccsstaedthty Sea aM Tide, Chee ee? 1-3 Structured Error: Recovery sch. cztiasccteterii acdsee eee olnece er ses 1-4 Use of. the:p. leave mechanisins..:si:sssssisasnsed cctissssssitaceestaserds cnc en se osc 1-4 PAC MUMNOETS os etic cteatiey nd aie dyce te sae tenleaveliiu rai licss eA MIRE ae ee et eee 1-4 2 The HWIMMAN Application Manager ..........ssssssssssssssresssscssoserossssssssasssosoresscecosecentacesesssssereseees 2-1 PHECUDSOLS <3: 52.5 css SeiscidsVassebsaakieasarctacedscsitestataesescates retecteeraceat oie tvs delets ones aeeteectte sceieee 2-1 Class :diactanimeenrmercteecert ert ee eet ee ee 2-2 CLASS CORI OIG tresses tadieSython eerea lect loeestadocas ocmarnasetten reese Co meet etait 2-2 PROPGIt ites atts, cated eRe A ACA cote hectiinast ale hscce eh tutsessdediec ce ate ihe heaton 2-3 HIWIMMAN methods. .1..3:s0s2isccai ashe ales rees teats uecsitenscoledteesel on SNe ne ee 2-3 PaO AMS Grasses cuca cain sbata tenga snucitevctveassascucodiagaln soa mart AO os ORE cs 2-3 Generate resource: file Mame ...:5s:::ci:ssc.sctiasesacstevedact vides SE osc eee esas 2-5 MW alt fOr ATICCVENE i. scccsieacotaaccu geal vassensvoueecoveshestacacck shea: Meissen ED 2-6 Clean up resources and report aM €rT Or .........cccssssssssesscsesssssesssssessscsseesscsecearececeeseceenenenes 2-6 Recordia new: filename... ..ccessexectsci ons capuvecueets caeadestascanesevicsstevtelaresadsecdeih ataclinadivette 2-7 IREPOteAM errr ec. sevcasceethoca secs etousvnueles eb atadevtveneatuedbucasccdos teSt Mibelassiei bet stéesetavet seus Metiae 2-7 Wait for all activity to Cease..........sessssesssesscsssssecssscseecssscsssessscsccecsearscserersacnencassecacesees 2-7 PEAY aI OIY LRA Eilers. goer careasaansensstousycaacseecctesscerdavisrseesa dre nv ines ioesen at eaicaeee 2-7 Guarantee existence Of IPCS 00... eecescsssssssesssesecssesnenesesersnesssesussvscerseeveessecsesecesscacneess 2-8 3 THE WSERV., Class «5. ssceasctisiscassssinccecsanvasesiendtcesstessossbcons tos ieodedeuvastastetedeaasieacsséssteieosonce hese hia teccse 3-1 PE CUTSOIS oi3sscsisecsassissateescsbbastecveatt fe caucn Stvedadean cisasisedeagectesavicsiievaesedeatd ote ie tes 3-2 Class ia orarm ' cses cake cccsdsevenstseysiys osetesbigantededsaeveiSesaasdasts g Gia ecseeies ea Hee 3-2 Class definition: fais ccssciseuzésscssenacsevaraa vi covetdatastecatteasagvecdsavacasdiaios Sessexics theo bale wenonte 3-2 PROperey, 2s Sccrs ssvssco cate, cssevevccustscesssnsassecss oubwivutskapasdesevadontcusatesdatadhosgtsceidedes ee ea 3-6 WSERV methods acrc0 08 ie: facies ihe cal eceshens es toit te eR Eas ha slvtahnenuebin esac haves erases 3-9 Application imitialisation 0.0.0... ccseesessscesessseseseseessseseessessssesssesssessssenececsecetensscaseesece 3-9 Dra TtrAl AS © 52.22.05 scttcnssccasca os sstevsqpsousstedelactavacd sales caesa sieschaatstesbedteldosaesiec en ol ee 3-9 Queue:a message from the Server: :...::.ssis.ssessececsesersecttsociaracecseacsasscassesieedeabe aati 3-10 Cam ce 5 oo scsca cee Sh Soca sh ozs catieba ousted voaceva aud dnetsdetch cancdecioadecteasSics loos aera 3-10 Cancel any pending window Server read.............cccssssssscssseseecsssessssceresecseseerseeeccetseesnenes 3-10 Process a message from the Server ..........c.ccsccessssssesesesssnsnsesssesseesscsssssssecsssensneneseeceeeece 3-11 Log anew: client Window 3.213.220; -S.ccslesdbsacitevesetvansisicsasddseeesidecudidieciaeuoreie eee oe eses 3-14 Runa dialogns 2st 208 ett) 08 aes vente capa ce tascedssliecie etc tees sstote come een eas 3-15 Add-a'dialogto the: dialog lists... ciseFaetepulsven dei dnadteiskeS decode isweee aces ks 3-15 Remove a dialog from the dialog list ............:.sccesssssssssssssessssesssesesssssssessessececeesseeseseenes 3-16 Paragraph word" wraptsnrk creme ena tect erste eee ee: 3-16 Runehelp:sy Stem eee temcccez cree aeccrs, Sirgere: ne corre ari eth we Oe el aL 3-16 Get'choicedist:resource:text::. 2a ere er ee a eer 3-16 Ruin the free-form dialling Aialog s.o.3scccsasidccssasassnseseassusddasxassssedesdsbsvosuiticereenndiovevnsave 3-17 Process a Switchfiles message ...........scsssscssecssssssesesescscsssvsssesssssecscecsercacscecesssesecvsvscesesess 3-17 ALIER Me OGK COUN ea tistic sos Saausedwsktneateasccebers ines Sewssid dvi nentcavasi scsies dese RES, GM 3-17 Del altermative mene DAT 27, ois. 2.25¢zcesnuythesareccessasasace iS iaeenavaadennasascaveccartrn ian teat 3-17 Reset:the menu’ Dan -ts.ste.sccccictvacccScccastiassettesttotateclitans tus gesdovtessaiss Res cceavetousseoea llouissatheet 3-17 RUM -AsSUDMEMI ses ce ccsvcovsleaccarutselcisieet ect tetl ta wlvanatt sige jo adh eubavaeaedes cniadeantiec te oees 3-18 BRUM FAT AAD aes nsec spats yeu canegh setae den sup rnecdnalves caution scalar neaasuivios abu tbOde sa 3-18 Runnjanterror: dialog ois. ce.ccsistic.covecusadiiev sid siecssehess stacecssviaSadtuloatensavasessuedvestvesenteceynecasteks 3-19 Evaluate an expression scicii.as03sisr.;6cesantecelatactaisseoes estat sibaiaostvseats Sas stSeeusahe oslones dees: 3-19 Set or get evaluator environment Variable..............ccsscssscesesssssssssesscsessscscscscetsseesseeceres 3-19 Set or get dial environment variable .............cscccsessssssssssssssssssssssesssscssssseecerssensseececsesees 3-20 RAI ENE. Set LOrmae Ig OG iced csencceastsaotesceaevesanbstte teditasevetoaveurieritaisioacseMivecpdliaieiause 3-20 BPE TACE tO wy SALE EE se Acceso shac 9 cul aio hnis ston vane drusracenta os sneles caph Sits sana ves aa see sedte hans 3-21 Runicountry selector, dialog -....3:..-:.ssscsscenedsessetatessacivesetsescetusevsvvesdvetesdravdsesinvioese eRe 3-21 Smart dial of a NUM Der sf h. 2. l ea cécceadencensteseasttsddiaesessdasissdeusleaetesvc eae ee 3-21 Ensure print context data exists... cesccsessssssssccsssssssssscsesssssssessscssssscstasssssossareveeees 3-22 Run:iprint:sétup:dialog Serres: ss elas ae canals cstesss tiv tha ovtaosasariiv Siationseenetties See 3-22 Rusmprintencon figuration dialog gat sysiacncredirietcess pla oases eet cco meesceesactansaes 3-22 Sense text for current printer device ........cececssssscssssessssssescecssssessesesssusssseavscsescscensnseceres 3-22 Add a:tilelist-tosthe listens: eActe tc ccetesteacsetacetaiissestsshccscontnes isto oh eee tesnlel 3-22 Removelathilelist:trom the tlists0 cc cisarae cet ssehivids. ena nace ecto eth eees 3-23 Anudator lias ticked Overy ss, oMees wetter teh claccoast oth ys hati eaadeec seen ae Roa nase 3-23 Unrecognised WSERV€Venit ...22:..cs..:c¢estsesiahevencatistassvesovetdenrsint mentee athe wae as 3-23 Ore TOUNG MESSAGE es. ccveasasstcauavistead ustiensvonsasueesed wih wacker te oe athe tos 3-23 Backeround Message... ciz.ce.scccvessscocassesscucsarvsveavaslesesnsradevessvasacesscastMeesvisaviene i aeenes 3-23 Request date change motification.............csscecssessssssesesesssssssssscccssssececssssssacsrsssssesscavecaeers 3-23 Process WM_DATE_CHANGED .000....eceseesesssssssecsssesesesencesetsssensessasssssescasasscacceaneesees 3-24 Launch: aD Vile arvameem. senmrrsrres oie tore tossh tence t res ss sess t isstes ere esate ees 3-24 Set up a status window ‘diamond! list..............cccccsececsscessssessesscessscssscssssssacesscecesectssneneece 3-24 Display dllocator statistics 3x, nse:sonnnssuatadedtysehseceussasodeesoesedenseloivsvaslsueseabecnterss 3-25 Copy print context from @ Process ...........ssesessssssssssesessessssscssseesscevesscssassasssssssssasscersssvees 3-25 Performintermal' data CHECK 5. i.:.ccesccccusdethedecic¥etsactgcesvcisdees lonels anctstsceaeeisteebseupeiee catel 3-26 Hide application from System Screem...........sccssscsssssssesessscsssssscscnsessseesessesessnscsavsossauesere 3-26 Set attachedistate -, c-.....hesirescsiserisesseycsdesndesarensvanevsatintienr visi gssucainhe RA ee 3-26 Display, a file-related message, s,s, r Defined in sub-category file hwimman.cl (generated header file hwimman.g). CLASS hwimman appman Hwim application manager - schedules attached active objects REPLACE REPLACE REPLACE REPLACE am_init am_wait am_rscname am_clean_up REPLACE am_notifyerr REPLACE am_findimg ADD am_new_filename ADD am_yield ADD am_ensure_ipcs CONSTANTS { H_COMMAND_DEFAULT_FILE H_COMMAND_OPEN_FILE H_COMMAND CREATE FILE H_COMMAND_EXIT H_COMMAND_TRANSLATE_FILE H_COMMAND RUN FILE H_COMMAND_LAUNCH_DYL H_COMMAND_BYPASS FLG_APPMAN_FULLSCREEN 0x1000 FLG_APPMAN_ LINKING 0x2000 FLG_APPMAN FROM_HWIF 0x4000 FLG_APPMAN_OWNPRIO 0x8000 FLG APPMAN S3FS 0x0100 Oversee HWIM initialisation Check with window server everything is okay Name depends on language May need to clean wserv temporary resources Use wsAlertW not p_ notifyerr Insist on the SSD being replaced Record a new filename Wait for all active objects to stop processing Ensure that ipe is initialised 'p! ‘Oo! en x! Tv! 'R! UD Al Matches PR_WSERV_FULLSCREEN Not used by HWIM applications Matches PR_WSERV_OWNPRIO Compatibility mode using full screen FLG_APPMAN_WSERV_MASK (PR_WSERV_FROM_HWIF|PR_WSERV_OWNPRIO|PR_WSERV_FULLSCREEN) RUN_ACTIVE_CLEANUP_NONOTIFY } TYPES { typedef struct { UWORD flags; HANDLE wserv_cat; UWORD wserv_class; } IN_HWIMMAN; } PROPERTY { UBYTE contig; UBYTE command; TEXT *defext; TEXT *aliasinfo; PR_AIDLE *yield; } ) -1 Same value as E_GEN_FAIL flags to supersend cat of wserv class of wserv TRUE if filename in same alloc block as command line The default extension for the application The Series 3 uwimman class does not support the am_ensure ipcs method. In addition, it does not define the command characters H_COMMAND_LAUNCH_DYL and H_CoMMAND_Bypass, or the FLG_APPMAN_FULLSCREEN flag. The Workabout introduces the flag FLG_APPMAN_s3FS. 2 HWIMMAN APPLICATION MANAGER Property hwimman.contig TRUE if the application's current file name is in the same allocated heap cell as the process command line. This is, if appropriate, set to TRUE by the am_init method, but will be set rause by the first use of the am new filename method. hwimman .command the command byte, if any, read from the process command line by the am_init method (which converts an H_COMMAND_DEFAULT_FILE value to one Of H_COMMAND_CREATE_FILE Of H_COMMAND_OPEN_FILE, depending on whether the specified file already exists) hwimman .defext a pointer to the application's default file extension, if any, as supplied in the process command line. This item is initialised during the am_init method hwimman.aliasinfo a pointer to the application's alias information, if any, as supplied in the process command line. This item is initialised during the am_init method hwimman.yield either nuuL or the handle of an instance of the OLIB arpze class. The instance is created automatically on first use of the am_yie1a method ESS a ee a ee a a HWIMMAN methods AN_INIT INT am_init (IN_HWIMMAN *init,UBYTE *wserv) ; This method is documented for information only. It should not be replaced in any application-specific subclass of HwIMMAN. Initialise the application, creating an instance of (a subclass of) wseRv together with instances of other classes that may be specified by init->f1ags. These flags may be a combination of the FLc_APPMAN_Xxx flags listed above, together with the following rLc_appman_xxx flags defined for the OLIB appman class: FLG_APPMAN_CLEAN Create a cleanup list component FLG_APPMAN_SYSTEM Create a system configuration component FLG_APPMAN_RSCFILE Create a resource file component FLG_APPMAN_SRSCFILE Create a system resource file component FLG_APPMAN_IPCS Create an 1pcs component FLG_APPMAN_ONLYONE Fail if the process already exists The differences, compared with the allowed flag combinations for the am_init method of the OLIB appman class are as follows: e An HWIM application must have access to the system resource file and so init->f1lags should include FLG_APPMAN_SRSCFILE (and hence also FLG_APPMAN_CLEAN). e An HWIM application must be provided with an application resource file and so init->flags should include rLG_APPMAN_RSCFILE (and hence also FLG_APPMAN_CLEAN). e An HWIM application that wishes to create an instance of the system class, in order to access the link paste (Bring) system services (described in the System Services chapter of the OLIB Reference manual) must set init->£1lags to contain the flag rL¢_APPMAN_LINKING rather than the flag FLG_APPMAN_SYSTEM that is required by the appman superclass. If the application wishes to use an instance of the OLIB recs class to implement the link paste server, init->£1ags may contain the flag FLG_APPMAN_IPCs, as for APpman. Note that, on all machines except on the Series 3, an instance of rpcs will always be created (but at a later stage in the initialisation) so the presence or absence of the FLc_Appman_1pcs flag is less significant on this machine. e If set, the flag FLG_APPMAN_FULLSCREEN Causes applications on the Series 3a and the Workabout to run in native, rather than Series 3 compatibility, mode. HWIM REFERENCE ee SSSSeSFSeSeFeSeeSeeeeeSSSSSSSSSSSSMmMMHheheFeFeFSSFFSSSFSee e The additional flag rLc_appman_s3rs may be set. On the Workabout, this causes a Series 3 application to run in compatibility mode, but using the full 240x100 screen. To take advantage of this, the Series 3 application must be able to adjust the size of its display to the available screen size. ¢ The additional flag, rLc_apeman_ownprio may be included, to be written to wsERV property (where it is identified as pR_wsERV_owNPRIO). See the chapter The WSERV Class for further details of this flag. The following operations are performed: e Writes its own handle to the magic static w_am. e For the Series 3a, loads the general data that can be accessed via the magic static patcate. e Attempts to open a language-specific system resource file, expected to be in the ROM. If this succeeds, the FLG_APPMAN_SRSCFILE bit in init->flags is cleared to prevent any attempt to open the default system resource file by the superclass am_init method. e Supersends the am_inrT message to the appman superclass, passing the flag values in init->flags. If the previous step failed to load a language-specific system resource file, this will include an attempt to open the file (as described in the APPMAN Application Manager Class chapter of the OLIB Reference manual). e Ifinit->£1lags contains the flag rLc_APPMAN_LINKING, creates and initialises an instance of the OLIB system class for communication with the window server process, SYS$WSRV. e On the Series 3a anf Workabout, records the current value of the magic static w_ws for later use. This will only be non-zero in the case where the application is started, and hence owned, by another application (see the description of p_getowner in the Processes and Inter-process Messaging chapter of the PLIB Reference manual). A non-zero value is expected to be the address of a status word in the owning application's data segment. e Creates an instance of the class init->wserv_class from category init->wserv_cat and writes its handle to the magic static w_ws - it is assumed to be (a subclass of) the wserv active object class. e The FLG_APPMAN_ownpRio and (for the Series 3a and Workabout) the FLG_APPMAN_FULLSCREEN flag bits, if present, are extracted from init->flags and written to the w_ws->wserv. flags property field (where they are known as PR_WSERV_OWNPRIO and PR_WSERV_FULLSCREEN respectively). e On the Workabout, if the flag FLc_appman_s3Fs is present, sets the pR_xwsERV_s3Fs flag in DatGate->gate. flags. e The values of the magic statics patprocessNamePtr, DatUsedPathNamePtr and DatStatusNamePtr, together with the hwimman.contig, hwimman.defext, hwimman.command and hwimman.aliasinfo property fields, are set up as appropriate from the data in the process command line, pointed to by patcommandPtr. See the example below and The Series 3 command line in the Communicating with the System Screen chapter of the Series 3 Programming Guide for a description of the components of the command line. Note that this processing of the command line is specifically designed to handle a command line of the form that is passed to an application that is started from the System Screen. The command line data passed to an application started in any other way may not be of this form. In such a case (for example, a custom application running on the Workabout) the application may need to provide its own code to process the command line data. On the Series 3a and the Workabout there is an option to process a reduced command line, signalled by the presence of a command byte with value »_commanp_sypass. In this case, the command byte is assumed to be immediately followed by the alias information (rather than the ususal public name of the application) and, of the items previously listed, only hwimman. command and hwimman.aliasinfo are initialised. The application is expected to perform its own interpretation or processing of any additional command line data, starting at the byte pointed to by hwimman.aliasinfo. e If the application is file-based (DatusedPathNamePtr is not nuLL) and the command byte in hwimman->command iS H_COMMAND_DEFAULT_FILE, the flag PR_WSERV_CONNECT_AT_BACK is ored into 2 HWIMMAN APPLICATION MANAGER w_ws->wserv. flags and the value of hwimman->command is converted to either H_COMMAND_OPEN_FILE OF H_COMMAND_CREATE_FILE, depending on whether the file specified by DatUsedPathNamePtr exists or does not exist. e On the Series 3a and the Workabout, if the application is not file-based and the command byte is H_comMaNnD_Bypass, the flag pR_WSERV_OWNPRIO is ored into w_ws->wserv. flags. e Sends w_ws an ao_INIT message, passing on the wserv parameter (which is a pointer to an IN_WSERV Struct). e On the Series 3a and the Workabout, sends itself an amM_ENSURE_IPCs message to create an instance of rpcs if one does not already exist. e Also, on the Series 3a and the Workabout, creates and initialises an instance of the arssv automatic test system server class. e Enables the future display of a temporary status window by calling wstnableTemp. e On the Series 3a and the Workabout, if the previously stored initial value of w_ws was not zero, it is assumed to be the address of a status word in the data segment of an owning process. A value of zero is written into that status word and the owning process is signalled by means of a call to p_iosignalbypid. This notifies the owner that the owned application has completed its initialisation and is now ready to receive inter-process messages. e Ifall the previous steps are completed without error, Hwrmman sends itself an aM_START message, to start the active object event scheduler. This will not return until the application terminates by sending Hwimman the corresponding am_stop message. On receipt of this message the application is terminated by means of a call to p_exit. If any of the previous steps result in an error, other than RUN_ACTIVE_CLEANUP_NONOTIFY, the error is reported by means of a call to p notifyerr before the application is terminated by a call to p_exit. The method formally returns zero, but the return is never executed since the method always terminates with a call to p_exit. Furthermore, an HWIM application will typically terminate with a direct p_exit (0) call, rather than sending HWwIMMAN an AM_sToP message (see, for example, the comman com_exit method in the Command Manager chapter). Although EPOC will not attempt to run the application unless there is sufficient memory for the application's start-up heap (as specified by the .app file header - see Greater control over the image file created in the Building an Application chapter of the General Programming Manual) the initialisation could still fail. Possible reasons for failure include the heap space of the window server process or the file server process becoming exhausted, the application being passed the name of a file of the wrong type, or running out of memory while loading a large file. Command line example If the heap cell (pointed to by patcommandPtr) containing the command line for a file-based application has, for example, the following content: ROM: : WORD .APP<0><0x29>0Program<0>.OPL OROPO<0>LOC: :M: \WRD\MYPROG.OPL<0> then, at the conclusion of the am_inrr method: hwimman.contig is TRUE hwimman.command is '0' (H_COMMAND_OPEN_FILE) DatProcessNamePtr points to the string "program" hwimman.defext points to the string ".opx" (the original following space is overwritten by zero) hwimman.aliasinfo points to the string "oropo" DatUsedPathnamePtr points to the string "Loc: :M: \WRD\MYPROG.OPL" DatStatusNamePtr points to the string "mypRoG.oPL" For an application that is not file-based, and therefore has nothing following the application file name in its command line, all the items in the above list will be set to nut. AM_RSCNAME VOID am_rscname (TEXT *pname) ; ‘resource file name Write, to the buffer pointed to by pname, (which must be at least p_rwamEsize bytes long) the default full file specification (see the Files chapter of the PLIB Reference manual) of the application resource file. HWIM REFERENCE eee eee eeSSeSSSSSSSSSSSSSSSSSSSFesesesesee The name is generated from the application's start-up full file specification, pointed to by the magic static DatCommandPtr. The name also depends on the current language, as determined by the value returned by a call to p_ getlanguage. If the language is English (p_get1anguage returns a value of 1) the resource file is assumed to be built into the image file, so that the full file specification of the resource file is identical to that of the image file. For all other languages the resource file is assumed to be located in the same directory and have the same name as the application image file, but with a language-dependent file name extension. The extension is assumed to be .~nn, where the characters mn represent the language number, as two decimal digits. Thus, a German language resource file would have a .~03 extension. This method is designed for use by built-in applications, whose resource files are in the ROM:: device (which does not support subdirectories) and whose default language is English. A multi-lingual application that is run from an SSD should subclass this method. The following example, for a myHwman subclass of xwimman, implements the scheme described in the Resource Files chapter of the Additional System Information manual. In this scheme the resource file for the default language is built into the image file. Resource files for other languages are located in a subdirectory of the directory containing the application image file. The subdirectory has the same name as the application and the resource file name is derived from the application name, with the final two characters containing the language number. METHOD VOID myhwman_am_rscname(PR_MYHWMAN *self, TEXT *pname) { TEXT *p; P_FPARSE crk; P_INFO f; TEXT buf [10]; p_fparse (DatCommandPtr, NULL, pname, &crk) ; p=pname+crk.system+crk.device+crk.path; *(p_bepy (&buf [0] ,p,crk.name) ) =0; ‘pete \\'; p=p_sepy (p, &buf[0)); pete! \\'; if (crk.name>6) crk .name=6 ; p=p_bepy (p, &buf [0] ,crk.name) ; p_atos(p,"%02d.rsc",p getlanguage()); if (p_finfo(pname, &£) <0) P_scpy (pname, DatCommandPtr) ; The default resource file, built into the image file, is used if a particular language is not supported by a corresponding resource file. Of course, in a specific application - where the resource file name is known - less gereral code can be used for this method. Wait for an event VOID am_wait (VOID) ; Send w_ws an AO_QUEUE message, to ensure that window server events will be processed (a queued read may have been cancelled) and then call p_iowait. ip resources an ort an error VOID am_clean_up(INT err,UBYTE *htask) ; Call wcleanup to free any window server temporary resources, supersend the AM_CLEAN_UP message to provide the standard error recovery and reporting, then set appman. err to zero. 2 HWIMMAN APPLICATION MANAGER AM_NEW FILENAME Record a new filename VOID am_new_filename (TEXT *newname) ; Record the new file name pointed to by newname. The buffer pointed to by newname must remain in existence until the name is changed again. If the current file name is specified to be in the process command line (hwimman. contig is TRUE) then the allocated heap cell containing the command line is truncated to remove the name, and hwimman. contig is set to FALSE. The magic statics patusedPathNamePtr and DatStatusNamePtr are set up to point to the appropriate positions in the text string. 1 an error VOID am_notifyerr(INT err,INT resid) ; Notify an error for error number err, with text as specified by the resource id resid providing additional information about the context of the error. This text may be up to 80 bytes in length (50 bytes for the Series 3). If no additional text is required, resia may be zero. This method is guaranteed to succeed in displaying an error message. Cancels any busy indicator by calling wcance1BusyMsg and writes zero to the wsERv active object's wserv.£ilter property. On the Series 3a the value of wserv.£ilmethod is also set to zero but, provided the original value of wserv.£ilmethod was negative (ie it is a ‘permanent filter - see the WSERV Class chapter) both values are restored after notification of the error. On the Series 3, any application that needs to restore wserv. filter to its original state on conclusion of the error report may need to subclass the am_notify method. If err has the value RuN_ACTIVE_CLEANUP_NonoriFy the method returns, without displaying any error notification. On the Series 3 the value of wserv.£ilter will have been cleared, but on the Series 3a and the Workabout, both wserv. filter and wserv.filmethod are preserved. Unlike in the superclass am_notifyerr method, the p_notify service is not used. The method calls the hErrorDialog utility function, to attempt to display the error in an error dialog. If this fails due to lack of memory, the error is displayed as an alert, by sending w_ws a wS_ALERT message. This alert cannot fail, but may not display any context information specified by resid if the attempt to load this resource fails. Using one of these two forms of error display means that the error notification is application modal; only that application is suspended and the user may task switch to another application. The superclass method is system modal, preventing interaction with any application until the user has responded to the error report. VOID am_yield (VOID) ; Use an idle active object to suspend the current action until all active objects with priority greater than PRIORITY_ACTIVE_COMPUTE have had the opportunity to service their outstanding events. Automatically creates an instance of the OLIB arnt class, if it does not already exist, storing its handle in hwimman.yield. Sends this object an ao_quEUE message and then sends itself an am_sTART message, which will not return until the idle object has had an opportunity to run. ition image file INT am_findimg (VOID) ; Refuse to continue until the image file has been located. If the image file can not be found, it is assumed that this is because the SSD containing it has been removed. The application is suspended by sending a ws_ALERT message to wsERV, displaying an alert requesting that the SSD be replaced. It is worth noting that, in consequence, the am_load_res_buf method can never fail in an HWIM application. HWIM REFERENCE AN Guarantee existence of IPCS VOID am_ensure_ipcs (VOID) ; This method is not available on Series 3 computers. If it does not already exist, create the application's instance of the rpcs class. The handle of the instance is written to appman.ipcs. This method is called from the am_init method, following the sending of the ao_1nrv message to the applications instance of (a subclass of) the wsErv class. An application is free to call this method at an earlier stage - for example, from the wsERV ws_dyn_init method. CHAPTER 3 THE WSERV CLASS q priority isactive peb stat destroy ws com dial bar cli info oldinfo filter £filmethod flags ao_init ao_cancel ao_queue ao_run ws_do_dial ws_add_ dial ws_remove_dial ws_sense_accel ws_change_cliwin ws_cancel ws_wrap_para ws_error_dialog ws_query dialog ws_do_help ws_do_submenu ws_set_menubar ws_reset_menubar ws_load_chlist_res ws_append_country ws_free dial ws_smart_dial ws_dial_env ws_lock ws_format_dialog ws_evaluate ws_eval_env ws_sense_pdev_text help_index_id help lock subdial sc[10] locmask filelist anim printer ws_edit_pdev_serup ws_edit_print_context ws_ens_print_context ws_add_filelist ws_remove_filelist ws_anim_tick ws_switch_ files ws_alert ws_unknown ws_foreground ws_background ws_dyn_init ws_process_ key ws_date_changed ws_launch_dyl ws_define_fnbar ws_hook_today_ changed ws_get_alloc_info ws_get_print_context ws_self_check ws_hide_app ws_attach_app ws_file_ info print ws_run_memo ws_do_remote_dial ws_user_abandoned An instance of the wsErv active object class is the application's event source for events (keypresses, redraws and so on) generated by the window server process. Every HWIM application must create a WSERV object at an early stage in its initialisation and this instance should remain in existence until the application terminates. The handle of the wserv object is stored in the w_ws magic static and can be accessed by the associated application. HWIM REFERENCE SSS In addition to its main role as the source of window server events, WSERV supplies a number of general services and utilities, including, for example, methods to: e — start up an application-specific dialog e una variety of system-supplied dialogs e evaluate a numeric expression e word wrap a paragraph of text An application is expected to subclass wserv, at least to supply a ws_dyn_init method which should perform all application-specific initialisation. Subclassers may, where appropriate, replace existing methods but, for future compatibility, should avoid adding new methods or property. Precursors Familiarity with the following topics will aid the understanding of this chapter: e the p_enter and p_leave error handling services e the OLIB active active object class. Class diagram eine tale / shutter “> Class definition Defined in sub-category file hwimman.cl (generated header file hwimman.g). CLASS The window server active object { wserv active REPLACE ao_init REPLACE ao_cancel=p_ dummy REPLACE ao_queue REPLACE ao_run ws_do_dial ws_add_ dial ws_remove_dial ws_sense_accel ws_change_cliwin ws_cancel wsS_wrap para ws_error_dialog ws_query dialog ws_do_help ws_do_ submenu ws_set_menubar ws_reset_menubar ws_load_chlist_res ws_append_country ws_free dial ws_smart_dial ws_dial_ env ws_lock Queue a message from the server Process a message from the server Start a dialog going Add a dialog to the list Remove a dialog from the list Lookup an accelerator for a pull down menu Log in a new client window Cancel pending window server read Wrapping service error dialog query dialog Help system Run a submenu Set an alternative menu bar Reset the menu bar Get text of a chlist item direct from resource file country selector dialog, for mark up purposes Invoke the free-form dialling dialog smart dial of a number with reference to home Set or get dial setup environment variable Increment or decrement the lock count 3 THE WSERV CLASS ooo eee AOD ws_format_dialog ws_ evaluate ws_eval_env ws_sense_pdev_text ws_edit_pdev_setup ws_edit_print_context ws_ens_print_context ws_add_filelist ws_remove_filelist ws_anim_tick ws_switch_files ws_alert ws_unknown_wm=p_dummy ws_foreground=p_dummy ws_background=p_dummy ws_dyn_init=p_dummy wS_process_key ws_date_changed ws_launch_dyl ws_define_fnbar ws_hook_today_changed ws_get_alloc_info ws_get_print_context ws_self_check=p_false ws_hide_app ws_attach_app ws_file_info_print ws_run_memo ws_do remote_dial ws_user_abandoned TYPES { typedef struct { HANDLE com_cat; UWORD com_class; } IN_WSERV; typedef struct { UBYTE menu; mnitem; menubar_id; first_com; count; UBYTE accel [1]; } WSERV_INFO; typedef struct { UWORD id; VOID *rbuf; PR_DLGBOX **pdilg; } DL_DATA; typedef struct { TEXT *dupnp; TEXT hidden [6] ; } WS_HIDE_APP_DATA; typedef struct { UWORD margin; UWORD fmargin; WORD font; UWORD style; WORD nlines; UBYTE *ptable; } WRAP_DATA; Launch set format dialog for evaluator or calc Evaluate an expression Set or get evaluator environment variable Sense text describing current printer device Invoke printer device setup dialog Invoke print setup dialog Check context data has been initialised Add a filelist to the list Remove a filelist from the list Animator has ticked over Switch files instruction received Subclassable interface to wsAlert Unknown message received from server Process WM_FOREGROUND Process WM_BACKGROUND Applications usually supply this Process WM_KEY Process WM_DATE_CHANGED Launch DYL in response to wGetCommand('L') Utility layer over wsSetList Request or cancel today changed notification p_allent facility Fetch printer context from other process For access by IPC testing or otherwise Hide or show application Appear to attach to other application Present standard file infoprint Run memo editor Run dialog in attached process Exit application with alert command manager category command manager class Which menu was pulled down Which item was selected in the menu Resource ID of menu bar Method number of first command Number of accelerators Accelerator keys Comes from a resource file dialog resource ID NULL or address of dialog result buffer NULL or location to receive handle of dialog Stores DatUsedPathNamePtr Por "SYSSK" Width in pixels to fill with text Width of margin for first line Font used Style used Max no lines to add to table Table to write line lengths to HWIM REFERENCE > kee typedef struct { UWORD ncells; UWORD nbytes; } WS_ALLOC_INFO; typedef struct { VOID *next; VOID *object; UWORD message; } WS_TODAY_HOOK; typedef struct { UWORD len; VOID *p; } MEMO_DATA PART; typedef struct { MEMO_DATA_PART body; MEMO_DATA_PART styles; MEMO_DATA_PART title; } MEMO_DATA; typedef struct { VOID *owner; UWORD method; } MEMO_CALLBACK; } CONSTANTS { PR_WSERV_CONNECT_AT BACK PR_WSERV_FOREGROUND PR_WSERV_CLIWIN_KEY PR_WSERV_CANCELLING PR_WSERV_BASIC_HELP PR_WSERV_FREEFORM_DIALLING PR_WSERV_INSERT_MODE PR_WSERV_INSERT_PENDING PR_WSERV_OWN_DEFAULT_FONT PR_WSERV_RECEIVED_KEY PR_WSERV_HIDDEN PR_WSERV_ METRIC PR_WSERV_FULLSCREEN PR_WSERV_CANCELLING DIALOG PR_WSERV_FROM_HWIF PR_WSERV_OWNPRIO PR_WSERV_HELP_INDEX WSERV_DTOB_HEX 3 DEGREES_MODE 0x80 DTOB_MAX WIDTH 20 WS_EVAL_ENV_SET 0 WS_EVAL_ENV_GET 1 WS_DIAL_ENV_SET ) WS_DIAL_ENV_GET 1 PDEV_TEXT_MAX_LEN 14 WS_LOCCHG_Low 0x0100 WS_LOCCHG_HIGH 0x4000 WS_EM_STYLES WS_EM_PRINT_CONTEXT WS_EM_REUSE_ BODY BUFFER WS_EM_REUSE STYLES BUFFER WS_EM_ CALLBACK MEMO_NO_CHANGE ) MEMO_NULL_LENGTH 1 MEMO_STANDARD CHANGE 2 } W_CONNECT_AT_ BACK 0x02 0x04 0x08 0x10 0x20 0x40 0x80 0x100 0x200 0x400 0x800 0x21000 0x2000 0x4000 0x8000 0x01 (Bit re-used) continue from P_DTOB type (ie 0x01) -X.xx...x (13 dec places) e-99 0x01 0x02 0x04 0x08 0x40 PROPERTY } { WS_EVENT_X ws; PR_COMMAN *com; PR_DLGCHAIN *dial; PR_MENUBAR *bar; PR_WIN *cli; WSERV_INFO *info; WSERV_INFO *oldinfo; PR_WIN *filter; INT filmethod; UWORD flags; UWORD help_index_id; UWORD help; UBYTE lock; UBYTE subdial; TEXT sc[10); UWORD locmask; PR_ROOT *filelist; PR_ROOT *anim; PR_ROOT *printer; } 3 THE WSERV CLASS —_—<—“— ee SER CLASS to take WSERV event command manager handle of current dialog, or NULL menu bar (if present) client window (if present) menu bar ID, command manager cat and class ete store info when in submenu mode send all keys here if non-NULL possible filter message (if not WN_KEY) foreground state, etc resource ID of application help index count of help screens count of how many times locked index of subdialog to launch, less one array of special characters mask for locchg topmost filelist animator print manager The following methods, structures and defined constants are not available on the Series 3. Methods: ws_process_ key ws_date_ changed ws_launch_dyl ws_define_fnbar ws_hook_today_changed ws_get_alloc_info ws_get_print_context ws_self_ check ws_hide_app ws_attach_app ws_ file info_print ws_run_memo ws_do_remote_dial ws_user_abandoned Structures: WS_HIDE_APP_DATA WS_ALLOC_INFO WS_TODAY_HOOK MEMO_DATA_PART MEMO_DATA MEMO_CALLBACK Constants: WS_EM_STYLES WS_EM_PRINT_CONTEXT WS_EM_REUSE_BODY_BUFFER WS_EM_REUSE_STYLES_BUFFER WS_EM_CALLBACK MEMO_NO_CHANGE MEMO_NULL_LENGTH MEMO_STANDARD_CHANGE The constants PR_WSERV_HIDDEN and PR_WSERV_FULLSCREEN have replaced the Series 3 constants PR_WSERV_SHUTTER and PR_WSERV_MACRO_DIALOG respectively. Neither of these two Series 3 constants were used in any Series 3 application code. HWIM REFERENCE eos eee Property WSERV property is accessible via the w_ws magic static. Although this means that the property may be accessed from any point in the application code, the property should, except where write access is specifically allowed, be considered as read-only. wserv. wserv. wserv. wserv. wserv. wserv wserv. wserv. ws com dial bar cli .info oldinfo filter This, together with the immediately preceding active. stat superclass property, effectively forms a ws_Ev struct, in which is stored the data relating to a window server event. The ws_EventT_x and wS_Ev structs are defined in wilib.h as: typedef struct { UWORD handle; /* Destination handle */ UWORD time; WS_EVENT_UNION u; } WS_EVENT_X; typedef struct { WORD type;/* E_FILE_PENDING, err or (+ve) event */ UWORD handle; UWORD time; WS_EVENT_UNION p; } WS_EV; Note that the ws_kv struct and the ws_rvenr struct (also defined in wiib. h) are alternative descriptions of the same physical structure. The WS_EVENT_UNION struct is a union of the structures used to store the details of each of the possible window server events (keypress, redraw, etc) and is also defined in wiib.h. The handle of the application's command manager, assumed to be an instance of (a subclass of) comman, set by system initialisation code, in the wserv_ao_init method. NULL if the application is not currently displaying a dialog, otherwise the handle of the application's current (foremost) dialog (but see the ws_add_diai method). NULL if the application is not displaying a menu bar, otherwise the handle of the application's menu bar, set by system code in the ws_process key and ws_do_submenu methods. The handle of the application's client window, set by application-specific initialisation code (in ws_dyn_init ) and modified either directly by application code or by the ws_change_cliwin method. A pointer to a WSERV_INFo struct, containing the the current menu bar and accelerator data. This data is initially loaded from the application resource file during wserv initialisation of an HWIM application. The elements wserv.info->menu and wserv. info->mnitem respectively indicate which menu was last pulled down and which item was selected in that menu (if both are zero this indicates the first item in the first menu). An application may read (and, if necessary, write to) either or both of these elements. A pointer to the main menu bar and accelerator data while an alternate menu or submenu is in use. If not nuut, indicates that keyboard input is filtered, by being diverted away from its normal destination. The value of wserv.filter may be either -1 to discard all incoming keypresses, or the handle of a window to which all keypresses are diverted. An application may write this property. 3 THE WSERV CLASS —_—_--_—— Corwen READS wserv. wserv. wserv wserv wserv. wserv. wserv. wserv. wserv. wserv wserv. filmethod flags -help_index_id -help lock subdial sc locmask filelist -anim printer State flags If not zero, the method number of the message to be sent to the object specified by wserv.£ilter on receipt of a keypress. Otherwise a wn_KEY message is sent. On the Series 3a, if the method number is stored in wserv.filmethod as a negative value, the filter is said to be permanent. A permanent filter allows keyboard access to the application's Help and is preserved across error notification by the application manager's am_notifyerr method. Note that the concept of a permanent filter does not exist on the Series 3. An application may write this property. A collection of state flags, described below. Either zero or the resource ID of the application's Help index. An application may write this property. A count of the number of levels of help currently being displayed, incremented and decremented by system code, in the ws_do_help method and the destroy method of the HELppte class. Zero if the application is not locked. Otherwise a count of the current number of times the application is locked. The count is incremented and decremented by the ws_lock method. Set and cleared by system code and used to identify a subdialog to be launched by the current dialog. Application code should not modify this item. A buffer containing special characters, loaded from the system resource file during wserv initialisation of an HWIM application. A bitmask used to ensure that successive items in the wserv. filelist list have distinct bits set, in the range ws_LOcCHG_Low to WS_LOCCHG_HIGH inclusive, for use with calls to p_locchg. Either nut or the handle of the first item in a list of FrILELIST instances. Either wowt or the handle of an instance of the OLIB anrmator class, used when wserv. filelist is not NULL to send WSERV a WS_ANIM_ TICK message every three seconds. The handle of the application's print manager, assumed to be an instance of (a subclass of) the FORM printer class, set by the ws_ens_print_context method. The state flags, stored in wserv. flags, may be any combination of the pr_wseRv_xxx flags specified in the class definition (with the exception of PR_WSERV_CONNECT_AT_BACK). The flags may be divided into several groups. The first group consists of those wserv flags that may be written into wserv. flags by the HWIMMAN am_init method, before it calls the wsERV ao_init method. PR_WSERV_OWNPRIO PR_WSERV_FULLSCREEN TRUE if the application is to connect to the window server with the priority specified in the header of its .app file. Otherwise the process priority is determined by the window server's client process priority management mechanism. This flag may be set explicitly (as FLG_APPMAN_OWNPRIO) in the flags passed to the application's instance of Hwimman from the start-up code in main(). On the Series 3a, rauss if the application is running in compatibility mode. Only applications writtm expressly for the Series 3a set this flag to rruE. This flag may be set explicitly (as FLG_APPMAN_FULLSCREEN) in the flags passed to the application's instance of Hwimman from the start-up code in main(). HWIM REFERENCE cr PR_WSERV_CONNECT_AT_BACK TRUE if the application is to connect to the window server as a background process. This flag is exceptional in that it is used during initialisation, but is not stored permanently in wserv.flags - its value is reused for PR_WSERV_HELP_INDEX. The HWIMMAN am_init method includes this flag automatically if the command line includes the command byte H_comMAND_DEFAULT_FILE. It can not be set explicitly in the flags passed to the application's instance of HWIMMAN from the start-up code in main(). An application that expressly wishes to make a background connection to the window server should replace the wseRV ao_init method to or PR_WSERV_CONNECT_AT_BACK into wserv.flags and then supersend the ao_INIT message. The next group consists of those flags used to record semi-permanent state information. These are read and written by system code, but may also be read by application code: PR_WSERV_FOREGROUND PR_WSERV_METRIC PR_WSERV_RECEIVED KEY PR_WSERV_HIDDEN TRUE if the application is the foreground process. TRUE if metric units are selected. TRUE if the application has received a key since coming to foreground. On the Series 3a, this flag indicates whether the application is hidden, being set or cleared by the ws_hide_app method. On the Series 3 it is used internally, under the name PR_WSERV_SHUTTER, in code that controls the locking of an application against Shutdown or Switchfiles messages from the System Screen. The next group contains flags that are generally of no interest to application code. Most of them indicate states that are more transient than those of the previous group. PR_WSERV_HELP_INDEX PR_WSERV_BASIC_HELP PR_WSERV_FREEFORM_DIALLING PR_WSERV_CANCELLING PR_WSERV_CANCELLING DIALOG PR_WSERV_FROM_HWIF TRUE if a help index dialog is present. Used during the display of Help to indicate that a ‘Help on help’ dialog is present. TRUE if the free-form dialling dialog is present. Used internally by the mechanism that cancels a read request on the window server process. Used internally by the dialog cancel mechanism. Must always be rause for an HWIM application. The final group contains flags that are primarily intended for use by an application. Although system code may set or clear them as a service to an application, the application may also write these flags. PR_WSERV_OWN_DEFAULT_FONT PR_WSERV_CLIWIN_KEY an application, such as Word, that supplies its own specification of printer fonts, rather than using a single default printer font, should set this flag. It is read by the prnmopex dialog and, if set, disables the selection of a default font for printed output cleared by the ac_run method when a keypress is sent to a destination other the client window. Used by the Word application to abort the two-character sequence that enters a style or emphasis shortcode 3 THE WSERV CLASS ——_—_ OE WISER CLASS PR_WSERV_INSERT_PENDING cleared when a keypress event arrives with a keycode of 0x100 or greater, or (but only when using epw1n) when the keypress is either Psion-Delete or Shift-Psion-Delete. Used by the Word application, together with PR_WSERV_INSERT_MODE, to control the creation of, and insertion into, an emphasis region by entering a two-character shortcode sequence and then typing characters PR_WSERV_INSERT_MODE cleared when a keypress event arrives with a keycode of 0x100 or greater, or (but only when using epwzn) when the keypress is either Psion-Delete or Shift-Psion-Delete. See pR_WSERV_INSERT_PENDING i Se i WSERV methods VOID ws_dyn_init (VOID) ; The application's wserv receives a ws_DyN_InrIT message at the end of the processing of the ao_init method. The supplied method does nothing. An application is expected to subclass wserv to supply a replacement ws_dyn_init method that performs application-specific initialisation. The application should create and initialise all objects that are required to display the initial view. This will generally involve at least the creation and initialisation of a client window, whose handle should be written to wserv.cli. An application that has engine components should create and initialise these components either directly from the ws_dyn_init method, or during the initialisation of the client window, depending upon which alternative is more convenient. A file-based application should open or create a file, depending on the data stored in w_am->hwimman.command and the file name pointed to by patusedPathNamePtr. It may also have to take note of the alias information in w_am->hwimman.aliasinfo. VOID ao_init (IN_WSERV *init); This method is documented for information only. It should not, in general, be replaced in any application- specific subclass of wsERV. One exception to this rule is to make a background connection to the window server, as indicated in the earlier description of the PR_WSERV_CONNECT_AT_BACK flag. Initialise the wsERv active object. The following points indicate significant aspects of the initialisation code: © wsERV adds itself to the application manager's active object queue with priority PRIORITY _ACTIVE_WSERV. e Special characters (those with u_sc_xxx #defines in symbols.h) are loaded into the wserv.sc buffer from the system resource file. Every HWIM application must therefore have access to the system resource file. e The method loads resource number | from the application's resource file into wserv. info. This resource is expected to be a WsERV_INFo resource struct (defined in Awim.rh, and duplicating the C WSERV_INFo struct that is declared in the wserv class definition). Every HWIM application must therefore have a resource file. © wserv. flags initially contains data written by the HwIMMAN am_init method and thus may contain any combination of PR_WSERV_OWNPRIO, PR_WSERV_CONNECT_AT_Bacx. and (on the Series 3a) PR_WSERV_FULLSCREEN. The application allocates memory for a WsERV_sPEc struct and connects to the window server, by calling wconnect, passing the address of this struct and the appropriate combination of w_coNNECT_PRIORITY and w_coNNECT_aT Back flags. The call to wconnect writes the address of the wserv_spxc struct to the magic static wserv_channel (application code may ———SeSeSeSSSSeSeeSeSeeSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS 3-9 HWIM REFERENCE eee subsequently read the contents of the comvect_inFo struct accessed by wserv_channel->conn - see the description of wconnect in the General Window Server Functions chapter of the Window Server Reference manual). The PR_WSERV_CONNECT_AT_BACK flag is removed from wserv. flags, for later reuse as the PR_WSERV_HELP_INDEX flag. ¢ On the Series 3a, if wserv. flags contains PR_WSERV_FULLSCREEN, the application is switched out of compatibility mode by means of a call to wcompatibilityMode. On the Workabout, full screen compatibility mode is set if patcate->gate.flags contains PR_XWSERV_S3FS. e On the Series 3a the pseudo-constant data that is accessed via the patcate magic static is set up (including patGate->gate.x and, additionally for the Workabout, patcate->gate .dx - see the chapter: The GATE Class). ¢ An instance of a command manager, whose class and category are specified by the In_WSERV struct pointed to by init, is created and sent a com_rnrT message. All HWIM applications must therefore have a command manager, which will normally be a subclass of comman. e Ifacall to p_getctd indicates that the machine is currently set to use metric units, PR_WSERV_METRIC is ored into wserv. flags. ¢ The final action of the ao_init method is to send a ws_pyn_rnzT message. The application must subclass wsERv to supply this method. INT ao_queue (VOID) ; HWIM applications are not expected to replace or to make explicit use of this method. If there is already an outstanding read (note that the Hwrmman am_wait method always sends wsERv an AO_QUEUE message) flush the client-side buffer by calling wcheckPoint. If this were not done window server calls (for example, wInvalidateRect) could, in some circumstances, remain buffered for an indefinite period of time. Regularly flushing such calls ensures that any consequential wm_REDRAW event is received promptly and the screen's appearance is kept up to date. Otherwise, queue a read to the window server process by calling weetEvent and then setting active. isactive to TRUE. The call sets active.stat to E_FILE_PENDING. On completion of the read, the result will be written to active.stat and the immediately following wserv.ws (these two items of property effectively form a ws_Ev struct, described earlier in this chapter). For historical reasons the method returns zero. Cancel VOID ao_cancel (VOID) ; HWIM applications are not expected to replace this method. Does nothing. The wserv cancel functionality is performed by the ws_cance1 method, described below. The reason for this is that an active object's ao_cancel method is called from the object's destroy method, but the wserv cancel action is not appropriate when wseErv is being destroyed. To some extent this is no longer necessary since the current tendency is that an application never destroys its instance of wsERv, relying on operating system code to recover an application's resources when the application terminates. | any pendint IW Server read VOID ws_cancel (VOID) ; HWIM applications are not expected to replace this method Cancel any pending read queued on the window server process by calling wcancelGetEvent. Since the destruction of a window involves operations on both the client side and the server side of application/window server interaction, it is possible that the window server could send an event, such as a redraw event, destined for a window that is in the process of being destroyed. To prevent this possibility, 3-10 3 THE WSERV CLASS the ws_cance1 method is called at an early stage of any window destruction sequence called from within the run method of an active object (apart from wsznv itself). This is done automatically when required and it is not expected that an application will ever have to make explicit use of this method. Note that there is no need to explicitly requeue a request following a cancel since wsERv is sent an AO_QUEUE message by the HWIMMAN am_wait method. Process a message: e server INT ao_run (VOID) ; HWIM applications are not expected to replace this method. Handle an event that indicates the completion of a window server read - the application has received an inter-process message from the window server process. On entry to the method the event type is in active.stat and any further data relating to the event is in wserv.ws. In particular, if relevant, the handle of the destination window is in wserv.ws. handle. The ao_run method always returns RUN_ACTIVE_USED. If the event is not one of those listed below, wserv sends itself a ws_UNKNowN_wM message. Otherwise the various event types are handled as follows: WM_REDRAW Sends the destination window a wn_REDRAW message, passing the address of wserv.ws.u.rect, specifying the rectangle to be redrawn. WM_FOREGROUND If wserv. flags contains PR_WSERV_HIDDEN, indicating that the application has attached to another process (this mechanism is not available on the Series 3) that process - provided it has not terminated - is brought to the foreground by means of a call to wclient Position. Otherwise, processing is as follows. Clears PR_WSERV_RECEIVED_XEY and set PR_WSERV_FOREGROUND in wserv. flags. If wserv.anim is not NULL, it is sent an Ao_QUEUE message with a time interval of zero, to restart any animated message. wserv then sends itself a ws_FOREGROUND, TRUE Message. WM_BACKGROUND Clears PR_WSERV_FOREGROUND in wserv. flags. If wserv.anim is not NULL, it is sent an AO_CANCEL message to suspend any animated message. wserv then sends itself a ws_BACKGROUND, FALSE Message. WM_COMMAND Processes an Exit or a Switchfiles message from the System Screen. Does nothing if the magic static DatLocked is non-zero. If DatLocked is zero, calls the window server function weet commana. If the content of the first byte of the resulting command buffer is H_commanp_Ex1T, the HWIM utility function hwservcomsend is used to send the command manager a com_ExIT message. Otherwise the command string is assumed to contain a file name and wserv sends itself a ws_swrTCH_FILES message, passing the address of the (temporary) command buffer. WM_CANCELLED There is no action on receipt of this event. WM_KEY If DatGate->gate.getkeys is not NULL, it is the handle of an instance of atssv. This object is notified of the receipt of a keypress by being sent an sv_key message (see the Series 3a Automatic Test System chapter of the Object Oriented Programming Guide, and the description of arssv in the Automatic Test System Classes chapter of the XADD Reference manual). WSERV Sends itself a ws_PROCESS_KEY message, passing the values of wserv.ws.u.key. keycode and wserv.ws.u.key.modifiers. Note that, on the Series 3, the ws_process_key method does not exist. On the Series 3, processing equivalent to that described for the ws_process_key method is performed by code that is called directly from the ac_run method. HWIM REFERENCE WM_DATE_CHANGED WSERV sends itself a ws_DATE_CHANGED message. This event will not occur on the Series 3. Process WM_KEY VOID ws_process_key(INT keycode, INT modifiers) ; This method is not available on the Series 3. On the Series 3, equivalent processing is performed by code that is called directly from the ao_run method. There are minor differences between the code executed in the two cases and, where significant, the differences are noted in the following description. Note that the Series 3 W_KEY_MODE keycode is broadly treated in the same way as described for w_KEY_DIAMOND. Unless otherwise stated, the processing of all types of keypress terminates with the clearing of the PR_WSERV_CLIWIN_KEY flag in wserv. flags. The method first clears the w_caps_MoDIFIER flag in modifiers since the caps lock status is of no significance to HWIM key processing. It sets the PR_WSERV_RECEIVED_KEY in wserv. flags to record that a keypress has been received since the last time the application became the foreground process. There is some further manipulation of the keycode and modifiers values to aid the distinguishing and recognition of command accelerators. If keycode is w_KEY_DIAMOND and modifiers contains W_PSION_MODIFTIER, the value w_spEcraL_KEY is ored into keycode. If modifiers contains W_CTRL_MODIFIER, the w_spEcIaAL_xey flag is removed from keycode, regardless of the value it contains; no keypress will be recognised as an accelerator if the Control key is held down. If the keypress is not consumed by a keyboard filter, as described below, and if keycode is greater than ox££ (cursor movement keys and others - see the Events chapter of the Window Server Reference manual for a full list of the keys concerned) the PR_WSERV_INSERT_MODE and PR_WSERV_INSERT_PENDING bits are cleared in wserv. flags, as a service to the Word application (see the earlier description of these flags). The keypress may be dispatched to one of a number of destination objects, as illustrated in the following diagram, where the clockwise order of the destinations broadly indicates their priorities. The destination depends on both the type of the keypress and the presence or absence of the various destination objects, as described below. ws_do_help wn_key window server process The menu bar is created when the Menu key is pressed wn_key —~, com_statwin com_accl_check com_menu com_mode_change The command manager also has a set of methods that correspond to menu items 3 THE WSERV CLASS —_ SSE WISER CLASS Keyboard filters Keyboard input may be filtered, that is, diverted from its normal destination, by setting a non-zero value for wserv. filter. The filter behaviour may be further modified by the value of wserv. filmethod. If wserv. filter is equal to -1, regardless of the value of wserv.filmethog, the keypress is discarded and processing of the keypress terminates. Any other non-zero value of wserv. filter is assumed to be an object handle and a message is generally sent to that object. The only exception is that a permanent filter (wserv. £ilmethod is negative) does not filter the Help key, nor does it filter any key if Help is being displayed. (Note that this exception does not apply to the Series 3, which does not support the concept of a permanent filter.) If the absolute value of wserv.£ilmethod is not zero it is assumed to be the method function number of the message to send to wserv. filter, otherwise a wi_kEy message is sent. In all cases the message contains the parameters keycode and modifiers. The message may return a value of WN_KEY_CHANGED to indicate that the keypress has been ‘consumed and that no further processing is required. For any other return value, the keypress is further processed as described below, as if wserv. filter were NULL. If wserv. filter is NULL, or if the message sent to wserv. filter returns any value except WN_KEY_CHANGED, the action depends on the current state of the application and on the values of keycode and modifiers, as described in the following sections. Help If keycode is w_xey_HELP, and Help is not currently being displayed, one of the following is done, depending on the value of modifiers: Help The resource ID of the help to be displayed is found by sending a WN_SENSE_HELP message. The message is sent to either the current dialog or the client window, depending on whether a dialog is present (wserv.dial is not woLL) or absent. The resulting ID is sent as a parameter to a Ws_DO_HELP message, to display the appropriate Help, and processing of the keypress then terminates. Control-Help Provided wserv. flags does not contain PR_WSERV_HELP_INDEx, sends a WS_DO_HELP message to display the system Help index and then terminates processing of the keypress. Otherwise the behaviour is as for the Help key. Control-PSION-Help Sends a Ws_FREE_DIAL message to run the free format dialling dialog and (Control-Dial) then terminates processing of the keypress. other Continues with further processing. Dialogs Ifa dialog is present (wserv.diai is not NULL) a wN_KEY message is sent to the dialog, passing keycode and modifiers. The wn_key message is not sent under two circumstances: ¢ ifmodifiers contains the w_specraL_xey flag, processing of the keypress simply terminates. e if the dialog's win. £1ags contains DLGCHAIN_WITH_MENU, processing continues as described in the following section, to allow access to the dialog's command menu. Any keypress that is not consumed by the command and command menu processing will be offered back to the dialog via a WN_KEY message. Note that this option is not available on the Series 3. If the return value from the wi_key message is non-zero, the dialog is sent a DESTROY message. If the return value is wN_KEY_CANCELLED, the value that will be retumed by the ws_po_pzaz method that launched the dialog is set to zero. If, on return from the wn_KEY message, wserv.subdial is non-zero, the dialog is sent a DL_LAUNCH_SUB message, passing the index of the dialog item that is launching the subdialog (one less than the value of wserv.subdial) and wserv.subdial is cleared. Processing of the keypress then terminates. Commands and command menus The value of keycode is then tested for any value that initiates a command by one of the following three means: e A value of w_KEY_DIAMOND (w_KEY_mopE on the Series 3) is interpreted as a COM_MODE_CHANGE command. On machines other than the Series 3, the com_mopE_CHANGE message is sent direct to the 3-13 HWIM REFERENCE a command manager, passing the value of modifiers masked with w_sHtFT_mop1FTER. On the Series 3 the message is sent as described below, with a preceding com_accL_CHECK message (which is expected always to return TRuvE in this case). e If the w_specraL_xey bit is set in keycode (indicating the Psion key was held down) this bit is masked out and keycode is tested against the list of accelerators held in wserv.info->accel. A match determines the method function number of the command to be executed, otherwise processing of the keypress terminates. The match is forced to be independent of case on the Series 3 but is otherwise case-dependent. e Ifamenu bar is displayed, it is sent a ww_kEy message, passing keycode and modifiers. If this returns a zero value, processing of the keypress terminates. Otherwise, the return value specifies the method function number of the command to be executed. Before executing the command (with the exception of com_MoDE_CHANGE, as noted above) a COM_ACCL_CHECK message is sent to the command manager, passing the proposed method function number. Processing of the keypress terminates at this pont if the com_accl_check method returns FALSE. Otherwise, if a menu bar is displayed, it is sent a Destroy message and the underlying window is sent a WN_EMPHASISE, TRUE message. This window is normally the client window but, except on the Series 3, it could be a dialog that allows the use of a command menu. The command is executed by sending the command manager the appropriate message, by means of the HWIM hwservcomSend utility function (again, with the exception of com_MoDE_CHANGE). Processing of the keypress then terminates. If keycode has a value of w_key_menu, one of the following is done, depending on the value of modifiers: Menu Create an instance of mznusar, storing its handle in wserv.bar, load the menu bar resource with resource ID wserv.info->menubar_id and send the menu bar a wy_rnrT message, followed by a wN_VISIBLE, WV_INITVIS message. Finally, send the client window a wN_EMPHASISE, FALSE message and terminate processing of the keypress. Shift-Menu As for the Menu key. Control -Menu Send the command manager a com_sTATwIN message, by means of the HWIM hwservcomsend utility function, and terminate processing of the keypress. other Terminate processing of the keypress. Client window Any unconsumed combination of values of keycode and modifiers is sent to the client window ina wN_KEY message. On return from this message, processing of the keypress terminates, without clearing the PR_WSERV_CLIWIN bit in wserv. £1ags. Thus, this bit is only set if the keypress has been offered for processing to the client window. Any return value from the client window is ignored. Ifa dialog is in existence, any keypress not consumed by the command and command menu processing is offered to the dialog, as described earlier, rather than to the client window. INGE_CLIWIN PR_WIN *ws_change_cliwin(PR_WIN *wh) ; Provided that the window with handle wn is not already the current client window, record this window as the new client window. The previous client window, which must still exist, is de~-emphasised (it is sent a WN_EMPHASISE, FALSE message). The new client window is emphasised (sent a WN_EMPHASISE, TRUE message) and is made the foreground window. Its handle is stored in wserv.cli. Returns the handle of the previous client window as a courtesy to the caller. The method does nothing but return the client window handle if the new window handle is the same as the previous one. 3-14 3 THE WSERV CLASS © WS SENSE INT ws_sense_accel(UINT comid) ; accelerator HWIM applications are not expected to replace this method. Return the lower case accelerator character corresponding to the command manager method number comid. The return value is meaningless if the method number is outside the range for which accelerators are defined. This method is used by the display code for pull-down menus. _ Runa dialog INT ws_do_dial (HANDLE cat, INT class, DL_DATA *pdata) ; Load, initialise and run the dialog specified by category handle cat and class number class. All HWIM dialogs must be started, directly or indirectly, via this method. The method creates an instance of the class specified by cat and class, assumed to be (a subclass of) pLGBox. It then loads the resource specified by pdata->id and uses it to create and initialise the dialog's components. The pi_para struct is defined in the wszrv class definition section of hwimman.g as: typedef struct { UWORD id; dialog resource ID VOID *rbuf; NULL or pointer to dialog result buffer PR_DLGBOX **pdlg; NULL or location to receive dialog handle } DL_DATA; On the Workabout, if the flags in the dialog's resource contain pLGBox_sMALL_Fowt, this flag is cleared in the loaded resource and the dialog's digbox. font property is set to DLGBOX_ROMANS_FONT. The dialog is then sent a pL_1n1T message, followed by pL_pyn_in1T and pL_SET_s1zE messages. The initialisation of the dialog is completed by a call to the HWIM utility function htnitvis and this completion is noted by oring PR_WIN_INITIALISED into the dialog's win. flags. If pdata->pdig is not NULL, the dialog's handle is written to pdata->pdlg. The dialog is then added to the wserv. dial list of dialogs by means of a ws_ADD_DIAL message. If the dialog's digbox. f1ags does not contain pLGBox_no_warr, the application manager is sent an AM_START message. This will not return until the dialog has terminated. Users of this method should note the following significant points: e The dialog receives, in order, pt_InIT, DL_pyN_INIT, and DL_SET_sIzE messages before being made visible. e The creation and initialisation is protected from out of memory failure, by the use of OLIB CLEANUP mechanisms, until the dialog has been made visible. The application does not need to provide any explicit protection against failure unless application initialisation code allocates additional resources. ¢ The dialog handle is not lodged in *pa->pdig until the dialog has been made visible. The return value is zero if the dialog is cancelled by the cancel mechanism provided by system code (that is, without the intervention of application-specific code - see the Dialog Boxes chapter for further details). This value is only of significance for dialogs for which the pLcBox_no_wart flag is not set. The method calls p_leave (which will trigger the automatic cleanup mechanism) on failure. S_ADD_DIAL | VOID ws_add_dial(PR_DLGCHAIN *hand) ; Add the object with handle hana (normally a dialog but, more accurately, an instance of any subclass of DLGCHAIN) to the front of the list whose first element is pointed to by wserv.dial. If a menu bar is visible send it a pestroy message, otherwise send a wN_EMPHASISE, FALSE message to the currently emphasised window, which will be either the first item in the wserv.diat list or, if this list is 3-15 HWIM REFERENCE empty, the client window. Then add hana to the front of the list (wserv.dial now contains the handle hand) and send this object a wN_EMPHASISE, TRUE message. Note that system-supplied subclasses of pLccuatn include help screens, pL¢gox and all system dialog classes. Remove a dialog from the dialog list VOID ws_remove_dial(PR_DLGCHAIN *hand) ; Remove the dialog with handle hand (not necessarily the first in the list) from the list of dialogs whose first element is pointed to by wserv. dial. If, after its removal, there are no dialogs in the list, wserv.dial will now be nuuu. Then send a wN_EMPHASISE, TRUE message to either the first dialog in the list or, if there are no such dialogs, the client window. raph word wrap INT ws_wrap_para(TEXT *buf, INT len, WRAP_DATA *pd) ; Word wrap the first 1en characters in the buffer pointed to by buf, writing the number of characters in each line to successive bytes of the table pointed to by pd->ptabie (assumed to be pd->nlines bytes long). The wrap_pata struct is defined in the wssrv class definition as: typedef struct { UWORD margin; width (pixels) to fill with text UWORD fmargin; width (pixels) of first line WORD font; font used UWORD style; style used WORD nlines; max no lines to add to table UBYTE *ptable; table of bytes to receive line lengths } WRAP_DATA; Returns either the number of lines into which the text has been wrapped, or zero if there is not enough space in the line length table. Ws VOID ws_do_help(INT start_id); Run help system Create, initialise and make visible a help dialog displaying the help information contained in the resource with ID start_ia. Help: Sustem screen Create an instance of the HELPpie class and intialise by sending it a ww_inrT message with an argument of start_id. Make the dialog visible and add to the dialog list by sending a ws_app pra message to self passing as argument the handle of the nELppte instance. Increment wserv.help and or PR_WIN_INITIALISED into the win. flags property of the HeELppte instance: this indicates that the HELPDLG destroy method should decrement wserv. help. WS_ LOAD CHLIS Get choice list resource text TEXT *ws_load_chlist_res(INT rid, INT nsel, TEXT *buf) ; Copy, into the buffer pointed to by bug, the zero terminated string that forms choice list item number nse1 (0 selects the first item) in the choice list resource with ID rid. This method is somewhat analogous to the more general application manager am_load_res_buf method. It is the user's responsibility to ensure that ria refers to a choice list resource and that the buffer is sufficiently long to contain the specified string. The method returns a pointer to the trailing zero that follows the loaded resource. 3-16 3 THE WSERV CLASS _ Run the free-form dialling dialog VOID ws_free_dial (VOID) ; Create, initialise and make visible the free-form dialling dialog: es message VOID ws_switch_files(UBYTE *buf) ; Create an instance of the sHurTER active object class and send it an ao_rnrT message, passing but, which is assumed to point to a buffer containing a command byte followed by a string specifying the new file name. This method is called as a result of the receipt of a Switchfiles message from the System Screen. If necessary, the SHUTTER active object delays the processing of the message (this processing includes sending the command manager a com_swITCH_FILEs message) until the application is in a suitable state to proceed. See the description of the sHurrer class, later in this chapter, for a fuller explanation of Switchfiles processing. Alte : ‘ock count INT ws_lock (INT lock); Add or remove a level of locking, depending on whether 1ock is TRUE Or FALSE. The application is considered to be locked if the magic static DatLocked is non-zero. A locked application does not receive Exit or Switchfiles messages from the System Screen, that is, the wseRV ao_run method ignores events of type wM_COMMAND. Note that the method stores the locked state in both wserv.lock and DatLocked. It is the programmer's responsibility to ensure that adding and removing levels of locking are balanced within an application. WSERV_INFO *ws_set_menubar (INT rid); Use hboadResource to allocate a cell and load into it the resource with ID ria (assumed to be a WSERV_INFO resource that defines the accelerators and the menu bar resource ID) writing the address of the cell to wserv. info. Returns the previous value of wserv. info, pointing to the allocated memory holding the original menu bar resource data. It is the programmer's responsibility to store this value for future restoration of the original menu bar data (normally by use of ws_reset_menubaz). If, exceptionally, this resource is not to be restored, it may be released with a call to p_free. Note that this method does not make the new menu bar visible, but the new menu will appear when the user next presses the Menu key. There is no straightforward automatic means of forcing the new menu bar to be displayed. VOID ws_reset_menubar (WSERV_INFO *info) ; Reset the menu bar Free the heap cell pointed to by wserv. info and set wserv. info equal to info. This is typically used as follows: HWIM REFERENCE p_send3 (w_ws,WS_RESET_MENUBAR, w_ws->wserv.oldinfo) ; to restore the main menu data after, for example, using the ws_set_menubar method. Run a submenu VOID ws_do_submenu(INT rid); Run the submenu specified by the wszrv_1nFo resource with ID ria. Sends a WS_SET_MENUBAR Message, passing rid, storing the returned pointer (to the loaded main menu resource data) in wserv.oldinfo. Then creates, initialises and makes visible an instance of MENUBAR (writing its handle to wserv.bar) to display the specified submenu. Sends a wN_EMPHASISE, FALSE message to the client window. An example of a submenu is the Series 3 Spreadsheet application's Print submenu, displayed by selecting the Print command from the Special menu of the main menu bar: (File Edit View Search Range Note that, as illustrated above, commands in a submenu may have accelerators that duplicate those appearing in the main menu. Submenus therefore provide a means of exceeding an application's normal limit of 30 commands (see The Command Manager). This method would normally be called from within the command manager method associated with the main menu option that gives rise to the submenu. The original menu bar is automatically restored when the submenu menu bar ceases to be visible. INT ws_query_dialog(INT secondrid, INT rid, INT *pargs) ; Run the system query dialog, with up to two lines of text. i’ Delete all files on "[BI"? No Yes as has The first line of text is generated, using hatob, from the format string loaded from the resource with ID ria and the list of arguments pointed to by pargs. The generated text may not exceed 50 characters, including the terminating zero. The value of pargs may be nut if there are no arguments, and rid may be zero, in which case there will be no first line text. The second line of text is loaded from the resource with ID secondrid, which is assumed to be a simple string resource. The value of secondrid may be zero, in which case there will be no second line text. On the Series 3 this method can call p_leave if there is insufficient memory to create and initialise the dialog. On the Series 3a the method will not fail, since it will call wsalertw to present an equivalent alert if there is insufficient memory to display the dialog. The method returns True if the user confirms, otherwise it returns FALSE. See also the hconfirm and h2LineConfirm utility functions. 3 THE WSERV CLASS Run an error dialog INT ws_error_dialog(INT err, INT rid, INT *pargs); Run the system error dialog, with up to two lines of text. The argument is 12 units Invalid arguments Continue Saal The first line of text is generated, using p_errs, from the error number err. The second line of text is generated, using hatob, from the format string loaded from the resource with ID ria and the list of arguments pointed to by pargs. The generated text may not exceed 50 characters, including the terminating zero. The value of pargs may be nut if there are no arguments, and ria may be zero, in which case there will be no second line text. Returns zero, to confirm that the method did not call p_1eave. This method is suitable for calling under the protection of p_ enter. See also the hErrorDialog utility function. INT ws_evaluate (TEXT *pResult, TEXT *pExpr, VOID *oplmod); Evaluate the expression contained in the zero terminated string pointed to by pexpr, writing the result to the buffer pointed to by presult. The result is evaluated according to the format preferences derived from the evaluator environment variable, MSV, accessed via the ws_eval_env method, described below. If the initial value of the byte *presult is zero, the evaluation is performed in so-called ‘calculator’ mode. After evaluation in this mode, the result buffer contains the numerical value, as a DOUBLE, in its first eight bytes. This is followed by the text representation of the value, as a zero terminated string, using the calc preferences from MSV. Any initial non-zero value in *pResuit causes the evaluation to be performed in 'evaluator' mode. After evaluation in this mode, the result buffer contains only the text representation of the value, as a zero terminated string, using the eval preferences from MSV. The expression to be evaluated may be any expression that is acceptable to the OPL programming language. The value of op1mod may be either nut or a pointer to the name of an OPL module containing additional functions (for example, a set of hyperbolic trigonometrical functions) to be used in evaluating the expression. Returns -1 if the evaluation is successful. Otherwise reports an error, using hinfoPrintErr, and then returns the byte offset, within the buffer at pexpr, to the point at which the error was detected. WS_EVAL ENV r get evaluator en VOID ws_eval_env(EXTENDED_MEM_VALUES *pev, INT getit); nt variable Write, from « ev, OF read, to *pev, the M$ V environment variable, which stores evaluator format Pp preferences. The EXTENDED_MEM_VALUEs struct is defined in h_eval.h as: typedef struct { UBYTE evalFormat; /* Dtob format code for all except calc */ UBYTE evalDPlaces; /* Decimal places for all except cale */ UBYTE calcFormat; /* Dtob format code */ UBYTE calcDPlaces; /* Decimal places, if relevant */ DOUBLE values [MAX_MEMORIES] ; } MEM_VALUES; HWIM REFERENCE eee eeeeSeSeSSSSSsSSFFSSSSSSSSSSSSSsSSSSSSSSSSSSSSSSsSSSSSSSSeee typedef struct { UBYTE evalDegrees; UBYTE calcDegrees; MEM_VALUES memVal; } EXTENDED _MEM_VALUES; Note that the Series 3 supports two global sets of evaluator preferences, one specifically for the Calculator application (set by the Calculator's Format command) and one for all other evaluations (set by the System Screen's "Evaluate" format command). If getit is TRUE, read the contents of the M$V environment variable into *pev. If the environment variable does not exist it is created with default values as follows: pev->evalDegrees=DEGREES_MODE; pev->calcDegrees=DEGREES_MODE; pev->memVal.evalFormat=P_DTOB_FIXED; pev->memVal.evalDPlaces=EVAL DEFAULT_PLACES; pev->memVal .calcFormat=P_DTOB_GENERAL; pev~>memVal.calcDPlaces=CALC_DEFAULT_PLACES; p_bfil (&pev->memVal.values [0] ,MAX_MEMORIES*sizeof (DOUBLE) , 0) ; If getit is FALSE, write *pev to the MSV environment variable. Note that this process modifies the contents of «pev. dial environment variable VOID ws_dial_env(DIAL_ENVAR *pev, INT getit); Write, from «pev, or read, to *pev, the D3X environment variable, which stores telephone dialling preferences. The prIaL_ENvaR struct is defined in the sptanpxc smart dialling dialog class definition as: typedef struct { UWORD toneLengthTicks; UWORD delayLengthTicks; UWORD pauseLengthTicks; UBYTE dialOutCode [6] ; to access an external line } DIAL_ENVAR; If getit is TRUE, read the contents of the DSX environment variable into «pev. If the environment variable does not exist it is created with default values as follows: pev->toneLengthTickss8; pev->delayLengthTicks=8 ; pev->pauseLengthTicks=48; p_scpy (&pev->dialoutCode[0],"9,"); /* from the SYS_DIAL_OUT system resource */ If getit is FALSE, write «pev to the DZX environment variable. VOID ws_format_dialog(INT flags) ; Run the set format dialog Run the system dialog to set the evaluation format preferences. Set "Evaluate" format Fixed > Decimal places 2 Trigonometry units Degrees If flags is TRUE, run the dialog to set the general evaluate preferences, as shown in the above diagram, otherwise run it to set the preferences for the calculator. On exiting the dialog, except by pressing Esc, the preferences are written to the MSV environment variable. See the description of the EvALDLGc system dialog class for further details. 3-20 3 THE WSERV CLASS VOID ws_alert (TEXT *t1, TEXT *t2); Ensure the magic static DatLocked is TRUE and then call: wsAlertW(WS_ALERT_CLIENT,t1,t2,0,0,0); On return from this call, patLocked is restored to its original value. This method is called from the HwrMman am_notifyerr method as the final fail-safe stage of the system's error reporting mechanism. WS _ APPEND COUNTR INT ws_append_country (TEXT *outStr) ; lintry Selector dialog Run the dialog used to add the country name to a telephone number (on pressing Control-Shift-PSION-Help) when editing a Data application entry: Append country Gees) + Snited Kingdoms Append Writes, as a zero terminated string, the selected name, enclosed in square brackets and preceded by a single space, to the buffer pointed to by outstx and returns Trus if the dialog is terminated by pressing Enter. Otherwise just returns FALSE. See the description of the cwrrype system dialog class for further details. Smart dial of a number VOID ws_smart_dial(SMART_DIAL_DATA *data) ; Run the smart dialling dialog: 3657339990 Cancel Freeinput Dial Dial out « Haris: to dial any of up to four (on the Series 3) or six (on the Series 3a and Workabout) telephone numbers passed in the sMART_DIAL_DATA Struct pointed to by data. The struct is defined in the spranptc class definition, effectively as: #define SMART DIAL MAX PROMPT 11 /* max prompt length */ typedef struct { TEXT pmt [SMART_DIAL MAX _PROMPT+1] ; TEXT str [WR_MAX_IN_STRING+2] ; } SMART_DIAL ITEM; typedef struct { WORD count; how many separate numbers SMART_DIAL ITEM it [4]; } SMART_DIAL DATA; where wR_MAX_IN_STRING is defined in wr_io.h. See the description of the spraLpie system dialog class for further details. HWIM REFERENCE w VOID ws_ens_print_context (VOID) ; KT Ensure print context data ¢ If it does not already exist, create and initialise an instance of the FORM printer class, writing its handle to wserv.printer. The method does nothing if wserv. printer is not NULL. VOID ws_edit_print_context (VOID) ; Send a Ws_ENS_PRINT_CONTEXT message and then run the print setup dialog as, for example, is used by the Print setup command in the Series 3 Word application's Special menu: "Margins... 1.25, 1.25, 1.25, 1.25 *Header.. “F *Footer.. “P "Paging control. 15 Nos 15253 "Printer model... Canon BJ-1@e This dialog is used to review and/or modify the print context data stored in the application's instance of the PRINTER Class, whose handle is in wserv.printer. See the Print Classes chapter for further details of the Print setup dialog. VOID ws_edit_pdev_setup (VOID) ; Run the dialog to set up the system-wide printer device configuration, as for the Printer setup command in the Series 3's System Screen's Special menu: ¢Parallels Serial characteristics .. Serial handshaking .. File: Name Disk Inches INT ws_sense_pdev_text (TEXT *buf) ; On the Series 3, this is a voip function. Write as a zero terminated string, to the buffer pointed to by bué, the text that describes the current printer device. This text will be one of "Parallel", "Serial" or, if printing to file, the name and extension of the print file. Except on the Series 3, returns the ID of the current printer device. WS_ADD_FILELIST _ VOID ws_add_filelist(PR_FILELIST *f1); Add the instance of rrLeLrst with handle £1 to the front of the list whose first item is pointed to by wserv.filelist. The instance's property, £1->filelist .1locmask is set to a distinct single bit value in the range WS_LOCCHG_LOw tO WS_LOCCHG_ HIGH inclusive If wserv.anim is nuLL, the method creates and initialises an instance of the ANIMATOR class, writing its handle to wserv.anim. The Ao_1NIT message sets up the aNIMaTor instance to send WsERV a WS_ANIM_TICK message every 3 seconds, with an initial delay of 6 seconds. 3-22 3 THE WSERV CLASS © WS_REMOV VOID ws_remove_filelist(PR_FILELIST *f1l); Remove the instance of FrLeLIst with handle £1 from the list whose first item is pointed to by wserv.filelist. If, after the removal, the list is empty and wserv.anim is not NULL, a DESTROY message is sent to the object with this handle and wserv. anim is set to NULL. The method does nothing if £1 does not appear in the list. VOID ws_anim_tick (VOID) ; If it exists, send the object whose handle is stored in wserv.filelist an FL_LOCCHG message. VOID ws_unknown_wm (VOID) ; This message is received when an event of a type not known to the ao_run method is received from the window server process. At the time of writing, possible unrecognised event types are ww_on and WM_TASK_UPDATE (this latter event type will be received only by the System Screen). The supplied method does nothing. An application should subclass this method if it needs to process such messages. VOID ws_foreground(UINT flag) ; The application receives this message, with f1ag set to TRUE, when it becomes the foreground process. The supplied method does nothing. The flag parameter is passed so that a subclasser may map the ws_foreground and ws_background methods to a single method function, the two cases being distinguished by the value of flag. VOID ws_background(UINT flag) ; The application receives this message, with f1ag set to FALSE, when it becomes a background process. The supplied method does nothing. The £1ag parameter is passed so that a subclasser may map the ws_foreground and ws_background methods to a single method function, the two cases being distinguished by the value of flag. VOID ws_hook_today changed(VOID *handle, INT message) ; This method is not available on the Series 3. Register or de-register the interest of the object specified by handie in being notified of the arrival of a WM_DATE_CHANGED inter-process message. If message is non-zero, the interest is registered by storing handle and message at the front of a list of such data items. On receipt of a wM_DATE_CHANGED inter-process message, message number message will be sent to the object specified by handle. If message is zero, the entry for the object indicated by handle is removed from the list. It is normally a programming error to register the same object more than once. An attempt to remove an object that has not been registered is a programming error with unpredictable results. HWIM REFERENCE WS_DATE CHANGED ~—__—s Process WM_DATE CHANGED VOID ws_date_changed (VOID) ; This method is not available on the Series 3. Send a message to each object that has registered, via the ws_hook_today_changed method, interest in the occurrence of date changes. Each object that has such an interest is sent a message of the type specified at the time it registered its interest. The Ws_DATE_CHANGED message is sent from the ws_process_key method, in response to a WM_DATE_CHANGED inter-process message from the Window Server process. Launch a DYL VOID ws_launch_dyl (TEXT *pname) ; This method is not available on the Series 3. Load and link the DYL whose full file specification is pointed to by pname, create an instance of its first class and send this instance a message with message number 1 (by convention, this is an initialisation message). This method is indended for use by an application that is started with a command line that contains the command byte H_CoMMAND_LAUNCH_DYL ('L' - see the HWIMMAN Application Manager chapter). If the loading of the DYL fails because the DYL is has already been loaded by this application, the ws_launch_dy1 method simply returns, without reporting any error. Any other loading error causes p_leave to be called. If the DYL is successfully loaded and linked, an instance of its class number zero is created. This instance is sent, under the protection of p_enter, message number 1, passing the DYL's category handle as the method's sole parameter. The corresponding method is expected to return zero to indicate its successful conclusion. If the method terminates without error, the DYL is considered to be successfully launched and ws_launch_dy1 then returns. If the method returns a non-zero value, or calls p_1eave, the DYL's instance of class number zero is sent a Destroy message and the DYL is unloaded. Any such error is not reported. If successfully launched, it is the DYL's responsibility to ensure that it unloads itself at some later time, when its task is complete. A convenient means of ensuring that the DYL is unloaded correctly is to supply the DYL's class number zero with a component object that is an instance of the XADD untoap class (using PROPERTY n in the class definition so that the component will receive a DESTRoy message when the owning class is destroyed). This component should be created and initialised as the last step of the initialisation of its owning class. See the description of the unioap class in the Additional Active Object Classes chapter of the XADD Reference manual. INT ws_define_fnbar(INT resid, INT pos, UBYTE *pselect) ; mond' list This method is not available on the Series 3. Set up, from a resource file, the text for the list of modes to be displayed in the application's status window. This method provides a utility layer over the Window Server's wsSetList function The text is read from the menu resource with ID resid. The following example shows the resource used by the Series 3a Agenda: 3 THE WSERV CLASS ——— eee WISER RLASS RESOURCE MENU diamond_list { items = { MENU_ITEM { mn_item="Day"; }, MENU_ITEM { mn_item="Week"; }, MENU_ITEM { mn_items"Year"; }, MENU_ITEM { mn_item="To-do"; }, MENU_ITEM { mn_item="Anniv"; }, MENU_ITEM { mn_item="List"; } }i } Note that there is a fairly serious width restriction on the text of each item - if you use more than five characters, you should test the application carefully. As for wsSetList, the value of pos should be either w_staTus_wIN_No_DIamonp or the index, counting from zero, of the item against which the diamond symbol is to be displayed. If pselect is NULL, all the text items from the resource will be shown in the list. Otherwise, pselect should point to a uByTE array where each byte is either Tru or FALSE to include or exclude the corresponding text item. The following example code uses the resource listed earlier. It would set up the Agenda diamond list to show no diamond symbol and contain the two text items "Week" and "Anniv". LOCAL_C VOID SetDiamondItems (VOID) { UBYTE select [6]; p_bfil(sselect [0] ,6, FALSE) ; select [1] =TRUE; select [4] =TRUE; p_sends (w_ws,0_WS_DEFINE_FNBAR, DIAMOND_LIST,W_STATUS_WIN_NO_ DIAMOND, &select [0]); } The method calls p_leave if any error occurs. It returns zero if successful and is,therefore, suitable for being called under the protection of p enter. VOID ws_ (VOID) ; This method is not available on the Series 3. Walk the application's heap to determine the number of allocated cells and the total number of bytes of allocated memory. The method presents an information message showing both these values. An application may send this message to itself or the message may be sent from an external process, as part of an automated test suite for the application. xt from a process INT ws_get_print_context (UWORD pid) ; This method is not available on the Series 3. Copy the print context from the process with ID pia. The method first sends a ws_ENS_PRINT_CONTEXT message to ensure that the application has default print context data. It then performs a series of inter-process copies to overwrite the application's print context data with the corresponding data from the specified process. It is assumed that the process with ID pia exists and has a valid print context. The method calls p_ieave if any error occurs during the copying of the data. If the method completes successfully it returns zero to indicate that p_1eave has not been called. The method is suitable for being called under the protection of p_ enter. HWIM REFERENCE INT ws_self_check (VOID) ; Perform internal data check This method is not available on the Series 3. Perform an internal self-consistency check on the application's data. The supplied method simply returns ransz which, by convention, implies success of the check. This method is intended to be replaced to provide application-specific consistency checks. An application may send this message to itself or the message may be sent from an external process, as part of an automated test suite for the application. The behaviour following the failure of a self-check will be application-specific. VOID ws_hide_app(UWORD pid, WS_HIDE_APP DATA *p); This method is not available on the Series 3. Hide the application from, or reveal it to, the System Screen. This method is intended to be used as part of the mechanism to attach one application to another (see the Series 3a Attached Applications chapter of the Object Oriented Programming Guide). It should be called by the controlling application, after it has successfully launched the attached process. The application is hidden if pia is non-zero. In this case, the value of pid is assumed to be the process ID of the attached process. The application's current patusedPathNamePtr is preserved in p->dupnp and DatUsedPathNamePtr is set to point to the string "SYS$X" (a name that will not be displayed in the System Screen’s file lists). Provided the attached process has not yet terminated, the application is made system modal and sent to the back of the task list by means of a call to wsystemModal. The value PR_WSERV_HIDDEN is ored into wserv. flags. If pid is zero, the application is restored to visibility. The application's original value of DatUsedPathNamePtr is recovered from p->dupnp and, by means of a call to wCancelSystemModal, the application's modal state is cancelled and it is brought to the front of the task list. Finally, the value PR_WSERV_HIDDEN is cleared from wserv. flags. Note that the ws_HIDE_APP_para struct must remain in existence until the application is restored to visibility. VOID ws_attach_app(UWORD pid); This method is not available on the Series 3. Set the application's appearance as being attached to the application with process ID pia (the process that controls the attachment (see the Series 3a Attached Applications chapter of the Object Oriented Programming Guide). It should be called by the attached application itself, during its initialisation. Sets DatLocked to the value of patLocked in the controlling process and then sets patProcessNamePtx to point to a copy of the text pointed to by patprocessNamePtr in the controlling process. Copies over the text pointed to by patusedPathNameptr in the controlling process and sends the application manager an AM_NEW_FILENAME message, passing a pointer to this text. Any error will result in p_leave being called. 3 THE WSERV CLASS VOID ws_file_info_print (TEXT *fname, INT rid); ed message This method is not available on the Series 3. Present a file-related information message. The text of the message is constructed from the file specification pointed to by fname and the text string resource with resource ID rid. The string resource is expected to be a format string containing a single ss that will be replaced by the file name. The passed file specification is parsed to locate the file name and extension. If the extension matches the application's default extension, pointed to by w_am->hwimman.defext, the extension is removed from the file name. The file name is string capitalised and the message is displayed by means of a call to the hInfoPrint HWIM utility function, passing rid and a pointer to the file name (with or without a trailing extension). The method is used extensively by applications built into the Series 3a to report the completion of file- based operations, in conjunction with the resource strings: SRT_FILE_CREATED SRT_FILE_OPENED SRT_FILE_SAVED SRT_FILE_COMPRESSED SRT_FILE_MERGED Thus, for example: GLREF_D VOID *w_ws; TEXT *p; p="LOC: :M: \AGN\AGENDA.AGN"; p_send4 (w_ws,O_WS_FILE_INFO_PRINT,p,-SRT_FILE_SAVED) ; will, in the Agenda application, display the message: "Agenda" saved _ Run Agenda memo editor INT ws_run_memo (INT flags, MEMO_DATA *pd, MEMO CALLBACK *cb) ; This method is not available on the Series 3. This method is supplied with the specific intention of being used by the Agenda application to edit a Memo attached to an Agenda entry. It is not intended to be used by any other application. Run dialog VOID ws_do_remote_dial(PR_ACTIVE **pa, INT mainrid, INT butrid); er process This method is not available on the Series 3. Run a dialog (an instance of arsp1at) in either an attached process or the foreground process. Determines the process ID of an attached process or, if no such process exists, the current foreground process, and checks that this process is suitable for receiving the instruction to run the dialog. The method then loads the main dialog resource, specified by the resource ID mainrid. If butria is not zero, the ‘button’ resource that it specifies is also loaded from the resource file. This resource may be either an ACLIST_ARRAY, defining the buttons for the dialog's single instance of an action list dialog item, or a MENU resource, defining the contents of the dialog's single instance of a choice list dialog item. If the dialog is not being run in an attached process, the value of pa must be nutu. Otherwise it should be a pointer to memory into which a handle can be written. In this case the ws_do_remote_dial method runs the dialog under the protection of an idle object (an instance of the OLIB arptz class) whose handle is stored in *pa as a service to the caller. This idle object will receive an ao_RuN message on successful termination of the dialog. HWIM REFERENCE An inter-process message starts the remote dialog. Providing there has been no error, the method does not terminate until the remote dialog is complete, when it returns the key code that terminated the dialog. On error, the method calls p_leave. Note that, although arspzat allows an option to present an editable text control in the dialog, the ws_do_remote_dial method does not support this mechanism. VOID ws_user_abandoned (VOID) ; This method is not available on the Series 3. Provide a standard means of terminating an application, with user notification. The method first terminates any attached process. It then presents an alert displaying the two messages "User abandoned' and 'Press Esc to exit application’. This method is intended to be used in the event that the user abandons a crucial operation, leaving the application in a state where it is unable to continue. The following example is taken from the Agenda application. It is displayed, for example, when a user removes the SSD containing the current Agenda file, attempts to modify an Agenda entry and refuses to replace the SSD whm prompted to do so. Agenda User abandoned Press Esc to exit application Continue aaa SHUTTER q count priority buf isactive peb stat destroy ao_init : ao_run ao_abrun ao_cancel ae—abren ao_queue S0—Fun An instance of the syurTEr class is used by wseRv to implement a switch to a new file initiated bya Switchfiles message from the System Screen. It is not expected that an HWIM application will ever explicitly create an instance of suurTer, nor is it ever expected to send explicit messages of any kind to any instance. The sHuTTER class is documented as a way of explaining the mechanism of the processing of a Switchfiles message, and under what circumstances that processing may succeed or fail. Processing a Switchfiles message A Switchfiles message may be received by an application at any time that it has not set itself in the locked state (see the WSERV ws_lock method). Even if an application is not locked, it may not be in a state where it can immediately respond to the message. It may be displaying a menu bar, or it may be interacting with the 3-28 3 THE WSERV CLASS user via a dialog. (which is likely to manipulate data that will change when a new file is loaded). The action of the sHuTTER object is to attempt, by removing any displayed menu and trying to cancel any dialogs, to return the application to a state in which it can respond to the Switchfiles message. A Switchfiles message is received by wsErv as an event of type ww_commann to the ao_run method. This, in turn, results in wserv being sent a ws_SwrTCH_FILEs message, whose main task is to create and initialise an instance of SHUTTER. SHUTTER'S first action is to remove any visible menu bar. Then, in successive calls of its ao_run method, it attempts to close down all the items in the wsERv wserv.dial list. These items, most commonly dialogs, are subclasses of DLGCHAIN and are expected to conform with the guidelines for this class. In some cases an item may not fully conform (for example, where a dialog responds to the Escape key by presenting an "are you sure?" query dialog) and suurTer may fail to close such an item. On such a failure sHuTTerR destroys itself, the net result being that the Switchfiles message is not processed. Otherwise, when all the wserv. dial items have been closed down, suurter's final action, before destroying itself, is to process the Switchfiles message by sending the command manager a COM_SWITCH_FILES message. Class definition Defined in sub-category file hactive.cl (generated header file hactive.g). CLASS shutter active { REPLACE ao_init REPLACE ao_run REPLACE ao_abrun CONSTANTS { SHUTTER_BUFFER_LEN 128 SHUTTER_COUNT_MAX 32 } PROPERTY { WORD count; UBYTE buf [128] ; } } Property shutter. count a count of the number of ‘hits' of the sHuTTER ao_run method, used to terminate sHuTTER if it has not been able to initiate the file switch in 32 cycles shutter. buf holds the Switchfiles command byte followed by a zero terminated string containing the name of the new file SE SO ae ne 8 i Ee Le ETE eT SHUTTER methods AO VOID ao_init (UBYTE *buf); in itialise Copy SHUTTER_BUFFER_LEN bytes from the buffer pointed to by buf into shutter .buf. This data consists of a Switchfiles command byte followed by a zero terminated file name. If a menu bar is displayed (w_ws->wserv.bar is not NULL) destroy the menu bar and send the client window (with handle w_ws->wserv.cli) a WN_EMPHASISE, TRUE message. Then add itself to the application manager's active object queue with priority PRIORITY_ACTIVE_WSERV-1 and send itself an ao_QUEUE message. HWIM REFERENCE AO_RUN — ~~—~—=—:CS So, or prepare for, the file switch ( INT ao_run (VOID) ; If shutter.count is equal to sHurrER_CouNT_MAX, send itself a DEsTRoy message and return, otherwise increment shutter .count. If a ‘dialog’ is visible (w_ws->wserv.dial is not NuLL) send itself an ao_QUEUE message to ensure the later receipt of a further ao_run message. Then send w_ws->wserv.dial a WN_KEY message with a keycode of w_key_EscapE. If this message returns a non-zero value, indicating that the dialog has not destroyed itself, send the dialog a pestroy message. This process will be repeated in successive ao_run methods until all items in the w_ws->wserv.dial list have been cancelled and destroyed unless the number of attempts exceeds SHUTTER_COUNT_MAX. Otherwise, if w_ws->wserv.dial is NuLL, the command manager (w_ws->wserv.com) is sent, under the protection of p_enter, a COM_FILE_CHANGE message, passing the command byte and a pointer to the file name, both of which are stored in shutter. buf. On an error-free return from this message, indicating that the file switch has been successfully completed, the method sends itself a pEstRoy message and returns. Any error results in p_leave being called. Returns RUN_ACTIVE_USED. VOID ao_abrun (VOID) ; Supersend the ao_aBRuN message to perform standard error reporting and then send itself a pEsTROY message. CHAPTER 4 THE COMMAND MANAGER The command manager is a component of the application's instance of (a subclass of) wserv. Every HWIM application must create and initialise a command manager, which must remain in existence for the lifetime of the application. The command manager may be accessed via its handle which is stored in w_ws->wserv.com. The category and class of the application's command manager are passed in an IN_WSERV Struct to the application manager's am_init method from the application's main, as described in the Introduction chapter. There is no need to send a DesTRoy message to a command manager since its resources will be released, along with all other application resources, on termination of the application. Any HWIM application that supports commands that are initiated by a selection from a menu bar and pull- down menu (or a corresponding accelerator) must subclass comman to app a method for each such command (with the exception of the Exit command command that is assumed to be handled by the (possibly replaced) com_exit method. These methods must be apped in a single uninterrupted group, following immediately after the superclass com_exit method, in the command manager's class definition. It is not, however, always necessary to supply a separate method function for each method. All invocations of command manager methods that may be selected from a menu bar (that is, com_exit and the following methods added by a subclass) are via the hwservcomSend utility function, which sends messages to the command manager, passing the command method number as an additional parameter. The command manager's class definition may, if it is convenient, assign two or more methods to share a common method function. This function can distinguish between the different cases by the method number in this parameter. Every command must have an associated accelerator. These accelerators must be listed in the first item of the application resource file, in the same order as the corresponding command manager methods in the class definition. However, this is not necessarily the order in which they appear in the application's command menus; note that the Exit command, corresponding to the com_exit method (which is necessarily the first method in the sequence) conventionally appears as the last item in the last menu of all Series 3 applications. See also the Commands and Command Menus and HWIM Resource Files chapters of the Object Oriented Programming Guide. All Series 3 keyboards, irrespective of language differences, support 30 distinguishable accelerator keypresses (the 26 non-accented alphabetic keys are common to all machines, but the remaining four depend on the keyboard layout, which varies from language to language). As a result, a Series 3 HWIM application is nominally restricted to a maximum of 30 commands, including Exit. This limit may, however, be exceeded if the application supports alternative menus and/or sub-menus. Series 3a machines distinguish between upper and lower case accelerators and therefore may use up to 56 separate commands in a single menu bar. Each alternative menu or submenu requires a further contiguous block of anped command manager methods and a further resource file item to provide an accelerator for each command. Precursors Familiarity with the following topics would be helpful: e the p enter and p leave error handling services e the wserv class, especially the ao_init, ao_run and ws_switch_files methods, all of which send messages to the command manager HWIM REFERENCE Ss SSSFSFSSSFSFSSFFSSSSSSSSSSSSSsSFSFsFsFeFeFeFsFFMSSSSssSSsees Class diagram (0 Oa mee a pt eet / wser / comman 7 ES ae ee a en a rere COMMAN com_init com_statwin com_acel_check com_menu com_mode_change com_file_change com_exit The comman class provides the basic skeleton for a command manager, supplying minimal functionality for the methods that an HWIM command manager must support. Although it is possible to build an application that uses an instance of comman as its command manager (for example, an application that consists of nothing but a chained sequence of dialogs) any non-trivial application will subclass comman, replacing one or more of the supplied methods and adding further application-specific methods. All file-based applications must replace the com_file_change method and, if they can modify the contents of their current file, the com_exit method. Class definition Defined in sub-category file comman.cl (generated header file comman.g). CLASS comman root Superclass of all command managers { ADD com_init=p_dummy Users own initialisation ADD com_statwin=p_ dummy Toggle permanent status window ADD com_accl_check=p_true Called whenever an accelerator is matched ADD com_menu=p_dummy Called whenever a menu is pulled down ADD com_mode_change=p_dummy W_KEY_MODE received ADD com_file_change=p_dummy The core code for open or new ADD com_exit Message sent here on exit accelerator CONSTANTS { O_COM_SYS_LAST O_COM_EXIT BREAK_LINE_FOLLOWS 0x80 item is underlined PURE_COM_ID Ox7£ Mask to exclude underline flag } } The Series 3 version does not contain the defined constants BREAK_LINE_FOLLOwSs and PURE_COM_ID. Property There is no property associated with the comman class. 4 COMMAND MANAGER COMMAN methods COM_INIT | a Initialise VOID com_init (VOID) ; Perform application-specific initialisation. The supplied method does nothing. A subclass may use this method to create and initialise one or more command manager component objects, such as a link paste server to implement the supply of data for the Bring command executed in another process. The method is called from the wszrv ao_init method, immediately before wserv receives a ws_DYN_INIT message. Any failure should result in p_leave being called: this will cause the start-up of the application to be aborted. In general, this method would not be expected to fail since the application's start-up heap should be calibrated to provide sufficient memory. COM_STATV VOID com_statwin (VOID) ; This method is called when the application receives a Control-Menu keypress in circumstances explained in the description of the wseRv ao_run method. The supplied method does nothing. A subclass may, if appropriate, keep a record of the status window visibility in its property and use this method to toggle the visibility of a permanent status window by appropriate calls to either wsEnable or wsDisable - and adjust the size of its display accordingly. An application that can not reasonably alter its display size may choose not to subclass this method. co INT com_accl_check (INT comid) ; When an application command is selected, by either by pressing an accelerator key combination or by selecting a pull-down menu item, the command manager is sent the appropriate message, with message number comid. Before this message is sent, the command manager receives a com_ACCL_CHECK message from the application's instance of WSERV (on the Series 3, this message is sent from the ao_run method and on the Series 3a, it is from the ws_process_key method, called from the ao_run method). If the com_accl_check method returns rausz, the message with message number comid is not sent. This method may therefore be used to check if the application is in a state to respond to the comid command. The Word application, for example, uses this method to ignore the PSION-+ accelerator if the Spell check software has not been installed. The supplied method simply returns true, allowing all command messages to be received at all times. Il-down m out to appear VOID com_menu(INT menu_num, PR_VAROOT *array) ; This method is called when pull-down menu number menu_num (the leftmost menu is menu number zero) is about to appear. The supplied method does nothing. At the time this method is called, the text of the menu has been loaded from a resource file, with the items held in successive elements of the variable array with handle array, but the menu window has not yet been made visible. The data of the array is held in allocated memory. Each array element consists of a length byte followed by a MENU_ITEM Struct, defined in pulldown.g as: typedef struct UBYTE com_id; /* command manager method number */ TEXT mn_txt[i]; /* zero terminated text string starts here */ } MENU_ITEM; HWIM REFERENCE and containing the command manager method function number, followed by the text, stored as a zero terminated string. As for the menus themselves, the first menu item is item zero, the second is item one, and so on. A subclass may use the com_menu method to modify the menu contents according to the current state of the application, either to replace the text of one or more items - for example, to replace the text of the second item in the third menu: TEXT *p; if (menu_num==2) { p=(TEXT *)p_send3 (array,O_VA_PREC,1); /* locate second item */ hLoadResBuf (REPLACEMENT _TEXT_RID,p+2); /* skip byte count and method number */ } or to completely remove one or more items - for example, to remove the third item in the fourth menu: if (menu_numss3) p_send3 (array,O_VA_DELETE,2); /* delete third item */ These operations must be performed each time the menu bar is about to appear, since it is always reloaded from the resource file. When replacing text note that, since the data is held in an allocated heap cell, any replacement text must not be longer than the original text for that item. The leading byte count allows system code to determine the amount of memory occupied by a menu item, even if the text has been replaced by text of a different length. COM_MODE_CHA! VOID com_mode_change (INT shifted) ; When wserv receives an event of type wm_key with a keycode of w_key_mopk, in circumstances explained in the description of the wseRV ao_run method, it sends the command manager a coM_MODE_CHANGE message. On receipt of this message the application should either do nothing or make some appropriate alteration to its state. On the Series 3 the Word application, for example, toggles in or out of Outline mode, the Data application switches in and out of data entry mode, while the Agenda application cycles around its views. On the Series 3a the standard action is to cycle around the application's ‘diamond list’. If shifted is TRUE, in an application that cycles between three or more states, the direction of cycling should be reversed. Note that the shifted parameter should be ignored by code running on the Series 3. The supplied method does nothing. COMEFIKE CHANGE ~~ ney _— INT com_file_ change (INT command,TEXT *pname) ; ate a file On receipt of this message the command manager of a file-based application should close its current file, saving it if necessary and, depending on whether command is H_COMMAND_OPEN_FILE or H_COMMAND_CREATE_FILE, open or create the file whose file specification is pointed to by pname. Note that pname points to a transient cell and thus should not be passed as an argument to the am_new_filename method. This message is sent to the command manager by wssrv as a result of the application receiving a Switchfiles message from the System Screen. The application itself may also send the command manager this message, for example, during start-up initialisation (normally in its ws_dyn_init method) and/or to implement the appropriate parts of its New file or Open file commands. An application that is not file-based will not receive this message from wsERv. The method should return zero to indicate that p_1eave has not been called. The supplied method does nothing other than to return zero. 4 COMMAND MANAGER —_ EM MAND MANAGER See the description of the sHurTEr class in the chapter The WSERV Class for an explanation of the full processing of a Switchfiles message. COM EXIT : : Exit the application VOID com_exit (VOID) ; This message may be received either as the result of the application receiving a Shutdown message from the System Screen or as the result of the user having selected the application's Exit command. A file-based application must, if its file has changed, save the changes before exiting. If this fails it must come to the foreground and inform the user of the error, offering the user another chance to save the file. The supplied method simply calls p_exit (0). This is the recommended way to terminate the application, leaving the operating system to recover its resources. CHAPTER 5 WINDOWS A window is a rectangle in screen coordinates that provides a coordinate system for clipped drawing. Everything that is displayed by an HWIM application is drawn within one or more windows. All HWIM windows subclass the wxn class, which is thus the ultimate superclass of all windows. The window classes supplied by HWIM are abstract classes and will normally need to be subclassed in order to create useful window objects. The supplied classes, listed below, are described in the following sections of this chapter. WIN the ultimate window superclass. BWIN a subclass of wrn that draws a standard border around the window. LODGER a pseudo-window that subclasses win. Such a window is assumed to occupy a rectangular region within another window. The enclosing window (referred to as the /andlord) will normally delegate all processing for that rectangle to the lodger. Precursors Familiarity with the following topics will aid the understanding of this chapter: ¢ — the window concepts described in the Introduction and Windows chapters of the Window Server Reference manual e the wserv class, especially the ao_run method, which may send messages to a window ¢ — graphics contexts and drawing, described in the Graphics Output chapter of the Window Server Reference manual Class diagram In addition to the methods and property in the application's code and data segments, a window has an associated data structure in the window server's resources, created by a call to wcreateWindow when an instance of win is itself created. The window server provides a set of functions that operate on such data structures, each data structure being uniquely identified by a window ID returned by wcreatewindow. Since a uniquely identifiable data structure with a set of functions that operate on it is effectively an object, the window server resources associated with a window can be considered as a component object. The existence of the window server resources is thus indicated in the above class diagram by the ‘using’ relationship between win and a notional wswin (Window Server WINdow) class. HWIM REFERENCE The WIN class destroy wn_redraw wn_dodraw wn_connect wn_key wn_visible wn_emphasise wn_position wn_calc_position wn_sense_help wn_set wn_sense wn_draw wn_init The wrn abstract class subclasses roor to form the superclass for all windows in HWIM applications. As described earlier, a window effectively has a component window server object. However, as can be seen from the pRopERTy section of the following class definition, the wxn class does not store an object handle for this ‘component’. Instead, it is referenced by means of a unique ID that is initialised in a call to a window's wn_connect method. In effect, the wn_connect method performs the function of creating and initialising the window server ‘component’, in the same way that a normal component object is created and initialised in an object's initialisation method. It is therefore clear that the sending of a w_connecT message is an essential part of the initialisation of any window (with the exception of ‘lodger' windows, which are described later in this chapter). Class definition Defined in sub-category file win.c/ (generated header file win.g). CLASS win root The window object superclass { REPLACE destroy Close server window then supersend destroy ADD wn_redraw Called in reponse to WM_REDRAW ADD wn_dodraw Same effect as redraw but called by application ADD wn_connect Connect the window to window server data (wswin) ADD wn_position Calculate position and re-position ADD wn_calec_position Calculate position ADD wn_key=p_false For processing WM_KEY from server ADD wn_visible Alters visibility state of window ADD wn_emphasise Window is highlighted in some way ADD wn_sense_help Give start ID for help DEFER wn_set Set some window object property fields DEFER wn_sense Sense some window object property fields DEFER wn_draw Draw to existing graphics context - usually subclassed DEFER wn_init Specific initialisation for a type of window 5 WINDOWS CONSTANTS { CURSOR_WIDTH 2 CURSOR_COLWID 2 SYSTEM_FONT_COLWID 2 W_KEY_SPACE 32 PR_BWIN_CUSHION oxi matches W_BORD CUSHION PR_BWIN_CORNER_4 0x2 matches W_BORD_CORNER_4 PR_BWIN_SHADOW 2 0x4 matches W_BORD SHADOW_S PR_BWIN_SHADOW 2 0x8 matches W_BORD SHADOW _D PR_WIN_EMPHASISED 0x10 matches W_BORD_ SHADOW ON PR_BWIN_OPEN 0x20 matches W_BORD OPEN PR_BWIN_CORNER_1 0x40 matches W_BORD CORNER_1 ! Gap of four bits, reserved for the arrow bits, for subclasses of BWIN only ! A dialog control is always a LODGER subclass, so can use 1 of the 4 bits PR_WIN_IS_DLCTRL 0x80 set by LODGER subclass whose landlord is a DLG PR_WIN_INITIALISED 0x800 Window completely initialised PR_WIN_FORCE_RIGHT 0x1000 PR_WIN_FORCE_LEFT 0x2000 PR_WIN_FORCE BOTTOM 0x4000 PR_WIN_FORCE_TOP 0x8000 PR_WIN_FORCE_FLAGS Oxf000 WIN_3dBORDER PR_WIN_FORCE_RIGHT Alternative use, for S3a border style WIN_FROM_ATS PR_WIN_FORCE_LEFT Alternative use, for auto test system IN_WIN_EMPHASISED (PR_WIN_EMPHASISED) WV_INVISIBLE ) WV_VISIBLE 2 WvV_INITINVIS 2 WV_INITVIS 3 WN_KEY_NO_CHANGE 0 WN_KEY_CHANGED 3 WN_KEY _CHANGED_DEFER 7 ( ( WN_KEY_ CANCELLED -1) WN_KEY_ABSORB_ON -2) ERROR_RID_OFFSET 512 } PROPERTY { UWORD id; window server window ID UWORD flags; PR_WIN EMPHASISED etc. } } The Series 3 and Series 3a versions of the class definition do not contain the defined constant PR_WIN_IS_DLCTRL. The Series 3 version of the class definition does not contain the defined constants wIn_34BoRDER and WIN_FROM_ATS. It does, however, contain the following additional defined constants: SCREEN_WIDTH 240 SCREEN_HEIGHT 80 CURSOR_HEIGHT 10 SYSTEM_FONT_HEIGHT 8 SYSTEM_FONT_ASCENT 7 SYSTEM_FONT_NUM_WIDTH 6 CONTROL_HEIGHT (SYSTEM_FONT_HEIGHT+2) SYSTEM_FONT_ID WS_FONT_BASE BOLD_FONT_ID WS_FONT_BASE+1 DIGITS_FONT_ID WS_FONT_BASE+2 SYSTEM_MONO_WIDTH 6 BOLD_MONO_WIDTH 8 DEFAULT_ICON_ID WS_BITMAP_BASE+2 On the Series 3a the corresponding values are read or derived from the globally accessible data that is described in the Introduction chapter of this manual. HWIM REFERENCE Property win.id the window ID, returned from a call to wcreatewindow, and used to identify the window server data structures associated with the window win.flags a collection of flags recording the state of the window, as described below Window flags The content of win.£1ags may be any legal combination of the following flags: PR_WIN_EMPHASISED TRUE if the window is to be drawn in a highlighted state, the flag is set or cleared by the wn_emphasise method PR_WIN_INITIALISED TRUE if some significant aspect of the window initialisation is successfully completed, normally implying some change in action during subsequent destruction of the window. This is currently used by only the pu¢zox subclass PR_WIN_IS_DLCTRL set TRUE , by pLcBox methods, for a LopcErR subclass if its landlord window is an instance of (a subclass of) p.cBox. Introduced for the Workabout to enable dialog controls to determine if they need to draw themselves in a small font. Additional flag bits are used by the pwrn subclass. The following flag values are used by system code, for example by the mm_calc_position method, during the initialisation of a number of types of window, but they are never set in win. flags: PR_WIN_FORCE_RIGHT the window is to be positioned at the right hand edge of the screen. This flag is mutually exclusive with pR_WIN_FORCE_LEFT PR_WIN_FORCE_LEFT the window is to be positioned at the left hand edge of the screen. This flag is mutually exclusive with pR_wIN_FORCE_RIGHT PR_WIN_FORCE_BOTTOM the window is to be positioned at the bottom edge of the screen. This flag is mutually exclusive with pR_WIN_FORCE_TOP PR_WIN_FORCE_TOP the window is to be positioned at the top edge of the screen. This flag is mutually exclusive with PR_WIN_FORCE_BOTTOM SSS EE a ae ee a WIN methods Destroy VOID destroy (VOID) ; Destroy the window, including its window server data structure, provided this has previously been successfully created. An application will not normally send this message to its client window (or to any permanent component of the client window). The method ensures that no window server event can be directed to the window after its destruction sequence is initiated, and calls wcloseWindowTree, passing win. id, to free the window's window server data. Finally, the method supersends the pEsTRoy message, to destroy the window's client-side resources (including automated destruction of any component objects). 5 WINDOWS S window server data VOID wn_connect (PR_WIN *par, UINT fields, W_WINDATA *windata) ; Create the window server data structure for the window by calling the window server function wCreateWindow, writing the returned ID to win. id, as indicated by the following code: METHOD VOID win_wn_connect (PR_WIN *self,PR_WIN *par,UINT fields,W_WINDATA *wdata) { self->win.id=wCreateWindow( (par ?par->win.id:0) ,fields,wdata, (UWORD) self) ; } The parameters windata and fields are as described for wcreateWindow in the Windows chapter of the Window Server Reference manual. The value of par should be nuxu if the window is to be a top-level window, otherwise it should be the handle of the parent window in the window tree. The value of sez is passed to wCreateWindow for use by the window server as a handle to identify the window, for example, when the window must be sent a wN_REDRAW message. The window server uses self in much the same way that window method functions use win. id. In general, HWIM windows are created with the w_w1n_BacK_BITMAp bit in windata->flags cleared, so that they will be redrawn by the window server wm_REDRAW mechanism, which causes the window to be sent a WN_REDRAW message. Assuming that the window server function woisableLeaves has not been called, any failure will result in p_leave being called. This method must be executed during the initialisation of any window (other than ‘lodger' windows - see later). Application code will frequently replace this method to customise the window's features and/or to create child windows. VOID wn_redraw(P_RECT *prect) ; This method is intended to be called by system code to redraw the window, following receipt by wserv of a window server event of type ww_REDRAW. An application will not normally replace this method, nor will it explicitly send a ww_REDRAW message to any of its windows. The operation of the method is as illustrated in the following code: VOID win_wn_redraw(PR_WIN *self, P_RECT *prect) { wBeginRedrawWinGCo (self->win.id) ; p_send2 (self,O_WN_DRAW) ; wEndRedraw () ; } Note that the whole window is redrawn, the rectangle coordinates pointed to by prect being ignored. A window that selectively redraws only the area specified by prect should replace this method. WN_DODRA VOID wn_dodraw(VOID) ; Application-initiated redraw This method is intended to be called by the application itself, for example, following a change in the data being displayed. An application will not normally subclass this method. The operation is illustrated in the following code: VOID win_wn_dodraw(PR_WIN *self) { wValidateWin (self->win.id); gCreateTempGC0 (self->win.id) ; p_send2 (self,O_WN_DRAW) ; gFreeTempGC() ; wFlush(); } HWIM REFERENCE The use of this method is equivalent to making a call to the window server function winvalidatewin, except that the redrawing is performed immediately, without having to wait for a redraw event to arrive from the window server. INT wn_visible(UINT flag) ; Set the visibility of the window, and any descendant windows, according to the value of flag. An application will not normally subclass this method. During initialisation of a window, possible values of flag are: Wv_INITVIS which calls winitialiseWindowTree (win. id) Wv_INITINVIS which calls wMakeInvisible(win.id) and then wInitialiseWindowTree (win.id). For an existing initialised window, this method may be called with flag set to either w_visrBLE or WV_INVISIBLE which respectively call wMakeVisible(win.id) OF wMakeInvisible (win.id). This method will normally be called during the initialisation of a window. See also the HWIM utility function htnitvis. The method returns zero and is thus suitable for being called under the protection of p_enter. dow highlight VOID wn_emphasise(UINT flag) ; Set or clear the PR_WIN_EMPHASISED bit in win. flags, depending on whether flag is TRUE or FALSE. Then call winvalidateWin (win. id) so that the window will eventually receive a wn_REDRAW message. Windows generally draw themselves differently in some way, according to whether or not they are emphasised. This method is not suitable for use in quality applications. It is expected that a subclass will always replace this method to provide specific and more effective redraw logic (see, for example the swzn subclass). rtiD for help INT wn_sense_help (VOID) ; Sense the resource ID for the application's current Help index. Returns the value of w_ws->wserv.help_index_id or, if this value is zero, the (negative) system resource ID -syS_HELP_ON_HELP. This method can be subclassed to facilitate context-sensitive Help. — Calcula VOID wn_calc_position(INT flags, P_EXTENT *pext); iw position Calculate, and write to pext->t1.x and pext->t1.y, the required screen coordinates of the top left corner of the window of width pext->width and height pext->height to place it on the screen in the position specified by flags. The calculation assumes that the window includes a surrounding blank ‘cushion’, one pixel wide. The value of flags may contain any ored combination of: e either PR_WIN_FORCE_RIGHT Or PR_WIN_FORCE_LEFT, with obvious meanings. In either case the window is positioned so that the single pixel cushion at the side of the window that touches the edge of the screen is not visible. If neither flag is present the window is centred horizontally ¢ — either PR_WIN_FORCE_TOP OF PR_WIN_FORCE_BOTTOM, again with obvious meanings. In either case the window is positioned so that the single pixel cushion at the side of the window that touches the edge of the screen is not visible. If neither flag is present the window is centred vertically 5 WINDOWS An application will not normally need to either replace or make explicit calls to this method. WN_POSITION _ _ Set window position VOID wn_position(INT flags) ; Position the window according to the value of flags, which may contain any ored combination of: e either PR_WIN_FORCE_RIGHT OF PR_WIN_FORCE_LEFT, with obvious meanings. In either case the window is positioned so that the single pixel cushion at the side of the window that touches the edge of the screen is not visible. If neither flag is present the window is centred horizontally ¢ — either PR_WIN_FORCE_TOP Or PR_WIN_FORCE_BOTTOM, again with obvious meanings. In either case the window is positioned so that the single pixel cushion at the side of the window that touches the edge of the screen is not visible. If neither flag is present the window is centred vertically The method sends a wn_caLC_PosITIon message to determine the required position before moving the window by means of a call to wset window. If used, this method will normally be called during the initialisation of a window, but must not be called before the window has processed a wN_CONNECT message. An application will not normally need to replace this method cess a keypress INT wn_key (INT keycode, INT modifiers) ; Process a keypress, where keycode is the code of the key pressed and modifiers contains a set of flags indicatinf which modifier keys (SHIFT, CTRL etc.) were held down when the key was pressed. The possible values of keycode and modifiers are described in the Events chapter of the Window Server Reference manual. Depending on the type of keypress and the current state of the application, the ww_key message may be sent to a window (normally the client window or a dialog) by system code - notably the ws process key method of the application's instance of (a subclass of) wsERv. The supplied method does nothing other than return zero (wN_KEY_NO_CHANGE). A subclass will, in general, replace this method. In many cases the wn_key method of a window may delegate the processing by sending wn_kEy messages to one or more other windows. Note that the return value generally only has significance for subclasses of win. A dialog, for instance, will return a non-zero value to indicate that the keypress should terminate the dialog and a menu bar may return the ID of a command menu option to be executed. See the description of the wsERV ws process key method for the way in which system code interprets wn_key return values from various types of window. The possible return values given by the various wn_KEY_xxx constants specified in the wrn class definition are of particular significance for the wn_key methods of the pieBox class and the dialog component classes. See the Dialog Boxes chapter and the following dialog box component chapters for further details. Deferred WIN methods A window will generally replace one or more of the methods described below. Note that there is no requirement for any particular subclass to replace all these methods. WNUINIF . Initialise VOID wn_init(...); Provide class-specific initialisation. For most windows this will include a call of the form: p_sends (self,O_WN_CONNECT, parent,ws flags,&ws data); The number and types of parameters to the wn_init method depend on the class. However, once specified for a particular class, further subclasses will normally follow the same parameter structure. HWIM REFERENCE Note that a simple window may not need to supply this method, since all essential initialisation may be performed by the wn_connect and wn_visible methods. VOID wn_set(...); Set property Set one or more property fields. The number and types of parameters to the wn_set method depend on the class. However, once specified for a particular class, further subclasses will normally follow the same parameter structure. VOID wn_sense(...); Sense one or more property fields. The number and types of parameters to the wn_sense method depend on the class. However, once specified for a particular class, further subclasses will normally follow the same parameter structure. VOID wn_draw(VOID) ; Supply class-specific drawing for the whole area of the window, called from the wn_redraw and wn_dodraw methods. Most application subclasses will need to supply this method. The method assumes that an appropriate graphics context exists, so the caller is responsible for supplying a graphics context. Note, however that this method is called from the wn_redraw and wn_dodraw methods, both of which create a basic graphics context around the sending of a wx_DRAW message. 5 WINDOWS The BWIN bordered window class destroy wn_draw wn_calc_position wn_emphasise wn_connect wn_dodraw wn_emphasise wn_key wn_position wn_redraw wn_sense_help wn_visible wn_set wn_sense wh-draw wn_init The Bwrn abstract class is the superclass for all bordered windows. Class definition Defined in sub-category file bwin.cl (generated header file bwin.g). CLASS bwin win All windows that have a border use this { REPLACE wn_draw Redraw border REPLACE wn_emphasise Update border CONSTANTS { IN_BWIN_CORNER_4 PR_BWIN_CORNER_4 IN_BWIN_SHADOW_1 PR_BWIN_SHADOW_12 IN_BWIN_SHADOW_2 PR_BWIN_SHADOW 2 IN_BWIN_CUSHION PR_BWIN_CUSHION IN_BWIN_OPEN PR_BWIN_OPEN BWIN_CUSHION_X BWIN_CUSHION_Y BWIN_SHADOW_1_ HEIGHT BWIN_SHADOW_1_ WIDTH BWIN_SHADOW_2_ HEIGHT BWIN_SHADOW 2 WIDTH NNPRRP PB Draw border VOID wn_draw(VOID) ; Draw the window's border by calling gBorder (self->win. flags) ; HWIM REFERENCE See The significant flag bits are PR_BWIN_CUSHION to PR_BWIN_CORNER_1 inclusive, together with the following four bits (0x80 to 0x400 inclusive) used to indicate the corner arrows. These bits are equivalent to the window server flags W_BoRD_CUSHION to W_BORD_CORNER_1 and W_BORD_TOP_oN to W_BORD_BOT_oFF, whose effects are explained in the description of gBorder and gBorderrect in the Graphics Output chapter of the Window Server Reference manual. An application-specific subclass will normally replace this method to provide drawing of the window's content, including the line: p_supersend2 (self,O_WN_DRAW) ; to draw the border. e border VOID wn_emphasise(UINT flag) ; If f1ag is FALSE, Clear the PR_WIN_EMPHASISED flag (equivalent to the window server W_BORD_SHADOW_ON flag) in win. flags, otherwise set it. Then redraw the border as indicated in the following code: gCreateTempGCo (self->win.id) ; gBorder (self->win.flags) ; gFreeTempGC; The shadow of a shadowed bordered window is only visible when the window is emphasised. The LODGER class LODGER landlord offset width destroy wn_calc_ position wn_connect wn_dodraw wnh_emphasise wn_key wn_position wn_redraw wn_sense_heip wn_visible wn_set wn_sense wn_draw wn_init destroy wn_init wn_visible 1g_draw ig_self_check ig_set_id_pos ig_sense_width lg_update The Loner class defines a window that does not have its own independent window server data structure, and therefore does not have an independent window server ID. A lodger window is defined to be any window that subclasses LopGER. A lodger window occupies a rectangular region within another window, referred to as the lodger window's landlord, and shares the window ID of the landlord window. In other respects a lodger window has broadly similar behaviour to a normal window, supporting a similar set of drawing and key processing messages. A lodger window can be considered to take over the responsibility for drawing the content of a rectangular region of the landlord window. 5 WINDOWS A significant difference between the two types of window is that drawing in a lodger window is not clipped by the boundaries of the lodger window itself. Drawing will only be clipped by the landlord window rectangle. In consequence, a lodger window has a duty never to draw outside its bounding rectangle. The most common single use for a lodger window is as a component control within a dialog box. Since a lodger window does not have an independent window server data structure, it is more efficient in terms of memory usage. This can be significant in the case of a complex compound window (a dialog box, for example, can easily need ten or more component sub-windows). An additional advantage is that such a compound window will scroll more smoothly - the scroll mechanism operates on only the single 'real' window and does not require messages to be sent to any of the component lodger windows (except for those that have freshly exposed regions to draw). Subclasses of Lopcer (and, indeed, any windows that do not subclass swrn) are free to reuse the flag bits PR_BWIN_CUSHION tO PR_BWIN_CORNER_1 inclusive, together with the four flag bits 0x80 to 0x400 inclusive that are used to indicate corner arrows. Class definition Defined in sub-category file /odger.cl (generated header file lodger.g). CLASS lodger win Lodger window { REPLACE destroy=root_destroy REPLACE wn_init Set up landlord REPLACE wn_visible ADD lg_set_id_pos Set window ID after dynamic initialisation ADD lg_draw Temp GC and call wn_draw ADD 1lg_self_check=p_true Returns TRUE if contents are legal DEFER lg_sense_width For dialogs to set their sizes DEFER lg update For fnselwn and fnedit CONSTANTS { LG_CHECK_OK Zz Lodger self checked o.k., no change LG_CHECK_FAILED 0 Lodger failed self check, no change LG_CHECK_FAILED_CHANGED (-1) Lodger failed self check, changed LG_CHECK_OK_CHANGED (-2) Lodger self checked ok., changed ) PROPERTY { P_POINT offset; offset into landlord window UWORD width; width available to control PR_WIN *landlord; owner window } } Property lodger .offset the pixel coordinates of the top left corner of the lodger window with respect to the top left corner of the landlord window lodger.width the width, in pixels, of the area available to the lodger window lodger. landlord the handle of the window's landlord window, assumed to be (a subclass of) win. The lodger window has access to the window server ID of the 'real' window (the landlord) via lodger .landlord->win.id A lodger window's property does not record the height of the lodger window. This is suitable when a lodger window is a component of a dialog box since, in this case, it always has a fixed height of CONTROL_HEIGHT pixels. HWIM REFERENCE LODGER methods WNINT me Initialise VOID wn_init(UINT *par, PR_WIN *landlord) ; Initialise the lodger window by copying the value of landlord, which should be the handle of the owning landlord window, into Lodger .landlord. The method ignores the value of par, which is specified for use by subclassers. _ Destroy VOID destroy (VOID) ; Destroy only the client-side resources of the lodger window, together with automatic destruction of any components. Calls the Roor destroy method directly, to avoid calling the destroy method at the wxn level, which might free the landlord's window server data structure. VOID wn_visible(UINT flag) ; Make the lodger window invisible if f1ag is rausz, otherwise make the lodger window visible. (Note that, in contrast to the wrn superclass, only two flag values are supported.) If the lodger window is being made visible, the method copies the landlord window's window server ID into win.id and sends an LG_DRAW message to draw the lodger window's contents. If the lodger window is being made invisible, win. id is set to zero and the method creates a temporary graphics context, calls gclrrect to clear the area in the landlord window that is occupied by the lodger window and then frees the temporary graphics context. A non-zero value of win.id thus indicates that the window is visible and this test is used, for example, by the 1g_draw method. Setting win. ia to be a copy of the value in lodger. landlord->win.id is an implementation decision that simplifies access to the window server ID of the 'real' window. Set | VOID 1g_set_id_pos(INT id, P_POINT *pos, UINT width) ; Set win.id to the value of id, copy «pos into lodger.offset and set lodger.width to width. A typical call to this method will be from a dialog box after all the items have been loaded and the dialog box has been set to the required width to display all its items. VOID 1g_draw(VOID) ; If win.id is non-zero, indicating that the window is in the visible state, draw the window content: gCreateTempGCO (self->win.id) ; p_send2 (self,O_WN_DRAW) ; gFreeTempGC () ; Otherwise do nothing. This method is intended to be called following a change in the data displayed in the lodger window (for example, at the conclusion of a lodger window's wn_set method). Since it creates its own temporary graphics context, it must never be called when a temporary graphics context exists, for example, as a result of the landlord window receiving a wn_REDRAW message. 5 WINDOWS sELF_CHECK a Check content is valid INT lg_self _check(INT item, INT can_defer) ; Perform a check that any property contains valid data. A numeric editor may, for example, check that its current value is within its allowed upper and lower bounds. Possible return values are as follows: LG_CHECK_OK the data has not changed and the check succeeded LG_CHECK_FAILED the data has not changed and the check failed LG_CHECK_FAILED_CHANGED the data has changed and the check failed LG_CHECK_OK_CHANGED the data has changed and the check succeeded The supplied method just returns 1G_CHECK_oK. Deferred LODGER methods These methods are intended to be replaced by classes that are used as components of a dialog box. red width INT lg_sense_width (VOID) ; This method is expected to return the width, in pixels, required to draw the lodger window contents. An object will only receive this message when it is a component of a dialog box (see the pLGBox dl_set_size method, described in the Dialog Boxes chapter). Some system-supplied subclasses assume that this method is called only once in the lifetime of an instance. LG{UPDATE: Up VOID lg_update (TEXT *pack, INT derr); 3 file name This method is defined for the ryseLwn and rneprt dialog box component classes. See the descriptions of these classes for an explanation of the method. jL CHAPTER 6 List BOXES AND MENUS All HWIM applications are expected to use commands and will normally require a menu bar and its associated pull-down menu(s). A menu bar is implemented with the aid of the LtsTBox class, which forms a basic component of a number of other HWIM window objects. Precursors Familiarity with the following topics will aid the understanding of this chapter: e the descriptions of the win and Bwrn classes in the Windows chapter e the creation of a menu bar and the sending of wn_kEy messages to a menu bar from the wsERv ao_run method, as described in the chapter The WSERV class Class diagram f Py % ; FA a ¢ ne \ : . 7 1 Fa ae forts Ne (rte. See ne a Ves i ta ares j win / win / listbox “¢ goehe \ oe yet ses \ verte Pa ee iC Sone vmatcher ‘ é t va ’ (ee ie oe ‘ TPN a ote F, Bee g / menutab * / menubar > / pulldown > f : , f 2 Bc ————— On o————— H = 1 ws 4 / Xpulldwn ~> ¢ ra HWIM REFERENCE List boxes wn_calc_position wn_connect wn_dodraw wn_position wn_redraw wn_sense_help wn_visible wn_set wn_sense match va flags width matchlen curofft offset current top first last vastart matchstart destroy wn_init wn_key wn_draw wn_emphasise 1b_draw_item 1b_draw_emphasis 1b_size_ window ib_item_width lb_take_focus lb_inquire_focus 1b_inquire_item lb_inquire_last A list box is a bordered window that displays a list of items, one per line. One of the items is normally the current item and is highlighted with an inverse obloid (a rectangle without its four corner pixels). List boxes - that is, instances of (a subclass of) L1sTBox - are used, for example, to display the expanded contents of a choice list, for listing items in help screens and for pull-down menus. The following diagram shows an example of selecting, by means of an expanded choice list, the use of a template file - within the dialog used by the Word application's Create new file command. Create new file else tenplate Template: Name Disk List boxes are also used to display file /ists, as shown in the following diagram. This illustrates that a list box may have a title consisting of one or more lines, separated from the main list by a horizontal line. The main list may contain more items than can be shown on the screen. The presence of further items before or after those that are visible can be indicated by up and down arrows in a right hand scroll gutter. ¢ Disk Internal, 62K free + NURDN* NURDN ey Opl.urd 689 63:24pm _ 11702793 pred 1HAVS Llitsan Sa-o1-92 Vord.urd 7O9? = 1:81pm 24716792 VJorkwrd 89¢ 6:24pm 11/82/93 4 The current item may be changed by means of the page up, page down and cursor keys. If there are more items than can be displayed in the list box window, the contents will be scrolled so that the current item remains visible. 6 LIST BOXES AND MENUS OES TE BUAES AND MENUS The t1stBox class provides support for incremental matching, whereby successive keypresses select the first item in the list box that starts with the sequence of matching characters that has so far been typed in. (This behaviour is exhibited, for example, by the file selector, displayed by selecting the file name item in the dialog for any file-based command and pressing the Tab key.) The items displayed in a list box are assumed to be stored in a variable array (an instance of a subclass of the OLIB varoor class). The data in each individual element of this array is assumed to be stored contiguously rather than, say, crossing the boundary between two or more allocated memory cells. Each element is assumed to contain a zero terminated string (which may, however, be preceded by a constant number of bytes of other data). There is no requirement for adjacent records to be contiguous with each other. Class definition Defined in sub-category file /istbox.c! (generated header file listbox. g). CLASS listbox bwin List box { REPLACE destroy REPLACE wn_init REPLACE wn_key REPLACE wn_draw REPLACE wn_emphasise ADD 1b_draw_item Draw an item by index number ADD lb draw_emphasis Draw/undraw emphasis on an item ADD lb_size_window Resize the window to the correct size ADD 1b_item_width Returns the required width of the item ADD lb _take_focus Move focus item specified by index ADD lb inquire focus Returns index of item with focus ADD 1lb_inquire_item Get pointer to item text ADD 1b_inquire_last Get index of last item CONSTANTS { IN_LISTBOX_MATCHER 0x0001 IN_LISTBOX_KEEP_ARRAY 0x0002 IN_LISTBOX_TEXT_OFFSET 0x0004 IN_LISTBOX_CUR_SET 0x0008 IN_LISTBOX_FIRST_SET 0x0010 IN_LISTBOX_LAST_SET 0x0020 IN_LISTBOX_POS_ALIGN_X 0x0040 IN_LISTBOX_POS_ALIGN_Y 0x0080 IN_LISTBOX_MIN_WIDTH 0x0100 IN_LISTBOX_AUTO_SIZE 0x0200 IN_LISTBOX_FORCE_WIDE 0x0400 IN_LISTBOX_WRAP_ROUND ox0800 IN_LISTBOX_FIXED WIDTH 0x8000 PR_LISTBOX_KEEP_ARRAY PR_LISTBOX_FORCE_WIDE PR_LISTBOX_WRAP_ROUND IN_LISTBOX_KEEP_ARRAY IN_LISTBOX_FORCE_WIDE IN_LISTBOX_WRAP_ROUND PR_LISTBOX_UNSTABLE 0x1000 PR_LISTBOX_BOLD_CURSOR 0x2000 PR_LISTBOX_PLAQUE 0x4000 PR_LISTBOX_FIXED_WIDTH PR_LISTBOX_SMALL FONT LISTBOX_TOP_EDGE LISTBOX_BOTTOM_EDGE LISTBOX_LEFT_EDGE LISTBOX_RIGHT_EDGE XLISTBOX_TOP_EDGE XLISTBOX_BOTTOM_EDGE XLISTBOX_LEFT_EDGE XLISTBOX_RIGHT EDGE LISTBOX_OBLOID_INDENT LISTBOX_TITLELINE_HEIGHT 3 LISTBOX_SCROLL_GUTTER LISTBOX_SCROLL_OFFSET } IN_LISTBOX_FIXED_WIDTH PR_WIN_FORCE_RIGHT set into win.flags property (BWIN_CUSHION_Y¥+2) (LISTBOX_TOP_EDGE+BWIN_SHADOW_1_ HEIGHT) (BWIN_CUSHION_X+2) (LISTBOX_LEFT_EDGE+BWIN_SHADOW_1_ WIDTH) (LISTBOX_TOP_EDGE+6) (LISTBOX_BOTTOM_EDGE+S) (LISTBOX_LEFT_EDGE+6) (LISTBOX_RIGHT_EDGE+5) 2 extra width on each side for highlight obloid additional height for line below a title 7 horizontal space for a scroll indicator 1 HWIM REFERENCE _— eee TYPES { typedef struct { UWORD flags; PR_VAROOT *array; UWORD offset; WORD current; UWORD top; UWORD first; UWORD last; P_POINT pos; UWORD minwid; } IN_LISTBOX; } PROPERTY 1 } { PR_VMATCHER *match; PR_VAROOT *va; UWORD flags; WORD width; UWORD matchlen; UWORD curoff; UWORD offset; WORD current; WORD top; WORD first; WORD last; WORD vastart; WORD matchstart; matcher object if any item list holds PR_LISTBOX flags Width of the list box in pixels for matcher offset of text for matcher cursor offset of text in VA item current selection top visible item in scrolling section first item in scrolling section last item in scrolling section index in listbox where va starts index in listbox where matching starts The Series 3 version does not contain the definitions of In_LISTBOx_FIXED_WIDTH, PR_LISTBOX_PLAQUE, PR_LISTBOX_FIXED_WIDTH, XLISTBOX_TOP_EDGE, XLISTBOX_BOTTOM_EDGE, XLISTBOX_LEFT_EDGE and XLISTBOX_RIGHT_EDGE. It does, however, contain an additional constant definition: LISTBOX_ITEM_HEIGHT (SYSTEM_FONT_HEIGHT+2) On the Series 3a, this value is derived from the data described in the Globally accessible data section of the Introduction chapter. The constant pR_LISTBOx_SMALL_FonT is introduced in the class definition for the Workabout. Property listbox. listbox. listbox. listbox. listbox. listbox. match va flags width matchlen curoff Either wont or the handle of an instance of vmarcuer. Incremental matching is enabled if this element is not nouu. The handle of an instance of a subclass of varoot containing the items that are displayed in the list box. By default each item is assumed to contain zero terminated text, whose first character is at a byte offset of listbox.offset within the item. A combination of the state flags listed below. The width, in pixels, of the region within the list box that is used to display items (not counting the window borders and any scroll gutter). Provided incremental matching is enabled, the number of characters that have currently been incrementally matched. The address of this item is passed to any VMATCHER component, which automatically updates its value. Provided incremental matching is enabled, the current horizontal offset to the incremental matching cursor. 6 LIST BOXES AND MENUS —_— I BU AES AND MENUS listbox.offset The byte offset within each element of the 1istbox.va array to the first character of the text to be displayed. listbox.current The index number of the currently highlighted item. listbox. top The index of the first visible item in the main list; its value is always greater than or equal to listbox. first. listbox.first The index of the first item that forms part of the main list of items in the list box. If non-zero, items with indexes in the range 0 to listbox. first- 1 are drawn as the list box title, separated from the main list by a horizontal line. listbox.last If not zero, the index of the last item from the 1istbox.va array to be displayed in the main list. Setting 1istbox.1ast allows trailing array items to be excluded from the list. listbox.vastart The index of the first item whose content is stored in the 1istbox.va array, allowing subclasses (see, for example, the rrLeLrst class) to derive items, such as their title, from other sources. Such subclasses must replace the lb_inquire_item method. listbox.matchstart The index of the item at which incremental matching is to start - intended for use by the rrLeLrst subclass. No incremental matching cursor is ever drawn in an item whose index number is less than 1istbox.matchstart. List box flags The content of 1istbox. flags may be any combination of the following flags: PR_LISTBOX_KEEP_ARRAY If set, the 1istbox.va array is not sent a DESTRoy message on destruction of the list box. PR_LISTBOX_FORCE_WIDE If set, the list box is drawn to include a scroll gutter, even if all the list items can be displayed within the list box window. PR_LISTBOX_WRAP_ROUND If set, pressing the up cursor key when positioned on the first item in the list, or the down cursor key when positioned on the last item in the list will wrap between the first and last items. PR_LISTBOX_UNSTABLE This flag should be set by a L1sTBox subclass to indicate that the contents of the listbox.va array are in an inconsistent state. It is used in this way by the FILELISst class. PR_LISTBOX_BOLD_cursoR Should be set if all selectable list box items are displayed in bold text. PR_LISTBOX_PLAQUE If set, the listbox is drawn with a 3-dimensional style grey and black border, otherwise a simple black border is used, as on the Series 3. This flag is not supported on Series 3 machines. PR_LISTBOX_FIXED_WIpTH This flag should only be set on initialisation by including IN_LISTBOX_FIXED_WIDTH in the flags field of the 1n_LisTBox inintialisation struct. If set, the width of the listbox is exactly as specified by the minwid element of the 1n_ursTsox struct. Otherwise, the width of the listbox is adjusted if necessary to accommodate the widest item. This flag is not supported on Series 3 machines. The contents of the remaining bit fields of listbox. flags are undefined. On the Workabdout, an additional flag may be set in win. flags: PR_LISTBOX_SMALL FONT On the Workabout, this flag may be set in the win. £1ags property of the list box, to indicate that the list box contents should be displayed in the small font. This flag is currently only set on initialisation of the Workabout rILeutst class HWIM REFERENCE LISTBOX methods Destroy VOID destroy (VOID) ; Destroy the list box and, optionally, its variable array component. If listbox. flags does not contain PR_LISTBOX_KEEP_ARRAY, listbox.va (if not nuLL) is sent a DESTROY message. The method then supersends the pEstroy message. _ {Initialise VOID wn_init (IN_LISTBOX *init) ; Initialise the list box. The horizontal cursor offset, 1istbox.curoff, is set to a suitable initial value of LISTBOX_LEFT_EDGE + LISTBOX_OBLOID_INDENT. The list box data array handle, 1istbox.va, is set from init->array. This handle is assumed to be of an instance of a subclass of varoor and must always be supplied. The value of init->£lags is copied to listbox. f1ags. The significant flags for general behaviour of the list box are: IN_LISTBOX_KEEP_ARRAY Referred to in listbox. flags aS PR_LISTBOX_KEEP_ARRAY. If set, prevents the destroy method from sending a pEsTRoy message to listbox.va. IN_LISTBOX_FORCE_WIDE Referred to in 1istbox. flags aS PR_LISTBOX_FORCE_WIDE. If set, forces the list box width to include space for the scroll symbols that would otherwise only be shown if the list box contained more enties than could be displayed on the screen. IN_LISTBOX_WRAP_ROUND Referred to in listbox. flags aS PR_LISTBOX_WRAP_ROUND. If set, pressing the up and down cursor keys will cause wrapping between the first and last entries in the list box. PR_LISTBOX_PLAQUE If set, the list box is displayed with a 3D border (not available on the Series 3). This is used, for example, for Help lists. Further initialisation processing depends on other flags specified in init->f1ags. If set, these have the following meanings, explained in the order in which they are processed: IN_LISTBOX_MATCHER Create an instance of the vmatcuer class, storing its handle in listbox.match, and initialise it, effectively as follows: p_sends (listbox.match,O IM_INIT, &listbox.matchlen,128, init->array) ; IN_LISTBOX_TEXT_OFFSET Set listbox.offset from init->offset, otherwise listbox. offset is zero IN_LISTBOX_FIRST_SET Set listbox. first from init->first, otherwise listbox. first is zero IN_LISTBOX_LAST_SET Set listbox.last from init->1last, otherwise listbox. last is zero IN_LISTBOX_CUR_SET Set listbox.current from init->current, otherwise listbox. current is set equal to listbox. first IN_LISTBOX_MIN_WIDTH Set the initial value of listbox. width from init->minwid, otherwise or listbox.width is zero. The width of the list box will not be less than any IN_LISTBOX_FIXED_WIDTH initial value of Listbox.width. If the flag 1n_LISTBOX_FIXED_WIDTH is set (not on the Series 3) the width will not be further adjusted. 6 LIST BOXES AND MENUS ————_———_—. Ss OEE BO KAES AND MENUS IN_LISTBOX_AUTO_SIZE Send an LB_SIZE_WINDOW Message, passing init->flags and the address of init->pos. This sets the height and (provided the width of the list box is not specified to be fixed) width of the list box to be sufficient to display the contents. Note that if the 1n_t1sT_Box_auro_sizz flag is not set, the creator of an instance of prsTBox must send an explicit LB_SIZE_wInDow message before attempting to make the list box visible. The remaining initialisation flags, 1n_L1sTBox_Pos_aLIGN_x and IN_LISTBOX_POS_ALIGN_Y, are of significance to the 1b_size_window method. é key input INT wn_key(INT keycode, INT modifiers) ; Sends an LB_INQUIRE_LAST message to find the index number of the last item in the list box. Further processing depends on the value of keycode as follows: W_KEY_RETURN Retums listbox. current+1. W_KEY_ESCAPE Retums wN_KEY_CANCELLED. W_KEY_ LEFT, If modifiers contains W_CTRL_MODIFIER, positions to the top item in the main list W_KEY_UP (with index number listbox. first). Otherwise, moves up one item in the list unless the current item is already the first. If already on the first item and listbox. flags contains PR_LISTBOX_WRAP_ROUND, positions to the last item in the list. Sets 1istbox.matchlen to zero, sets the new item by sending an LB_TAKE_FOCUS message and returns WN_KEY_NO_CHANGE. W_KEY_ RIGHT, If modifiers contains W_CTRL_MODIFIER, positions to the last item in the main W_KEY_DOWN list. Otherwise, moves down one item in the list unless the current item is already the last. If already on the last item and 1istbox. flags contains PR_LISTBOX_WRAP_ROUND, positions to the first item in the list. Sets listbox.matchlen to zero, sets the new item by sending an LB TAKE Focus message and retumms WN_KEY NO_CHANGE. W_KEY_PAGE_UP If modifiers contains W_CTRL_ MODIFIER, or if all the items are visible in the list box, positions to the first item in the main list. Sets 1istbox.matchlen to zero, sets the new item by sending an LB_TAKE Focus message and returns WN_KEY_NO_CHANGE. Otherwise, scrolls up by one less than the number of visible items in the main list (or to the top of the list, if less) writing a new value to 1istbox. current, moving the emphasis to this item and, if 1istbox.match is not NULL, sending it an IM_SET_VAL message and resetting the match cursor to the first character of the item. The method then terminates by returning wN_KEY_NO_CHANGE. W_KEY_PAGE_DOWN If modifiers contains w_CTRL_MODIFIER, Or if all the items are visible in the list box, positions to the last item in the main list. Sets 1istbox.matchlen to zero, sets the new item by sending an LB_TAKE_Focus message and returns WN_KEY_NO_CHANGE. Otherwise, scrolls down by one less than the number of visible items in the main list (or to the end of the list, if less) writing a new value to listbox. current, moving the emphasis to this item and, if 1istbox.match is not NULL, sending it an IM_SET_VAL message and resetting the match cursor to the first character of the item. The method then terminates by returning w_KEY_NO_CHANGE. HWIM REFERENCE Ss eSSSSSSSSSSSSSSSSSSFFee any other key If 1istbox.match is NULL, keycode represents a printable character and listbox .va is not NULL, a cyclic search is made, forward from the current item, for a case-insensitive match between keycode and the first letter of an item. Ifa match is found, the matching item is made the current item by means of an LB_TAKE_FOCUS message. If 1istbox.match is not wuLL, incremental matching is attempted by sending listbox.match an IM_KEY message (which will adjust listbox.matchlen as appropriate) passing keycode and modifiers. e if this returns IM_NEW_DISPLAy, the new current item is found by adding listbox.vastart to the return value from an 1M_SENSE_VAL message sent to Listbox.match. This item is made the current item by means of an LB_TAKE_FOCUS message e if itreturns Im_nwew_En the incremental matching cursor is redrawn in its new position, according to the value of listbox.matchlen In all of these cases the method returns wN_KEY_NO_CHANGE. Draw VOID wn_draw(VOID) ; If listbox. flags contains PR_LISTBOX_UNSTABLE the method simply clears this flag and calls winvalidateWin so that the list box will receive a ww_REDRAW message at a later time. Otherwise the method draws the list box border and sends an LB_INQUIRE_LAST message to find the index number of the last item to be drawn. It then draws its content as follows: e if listbox. first is not zero the items with index numbers from 0 to listbox. first-1 are drawn at the top of the list box, followed by a horizontal line across the full width of the list box. e if 1listbox.top is greater than listbox. first, indicating that more items are available above the first visible item in the main list, an up arrow is drawn at the top of the scroll gutter e starting with the item with index number 1istbox.top, successive items are drawn until the items are exhausted or the list box is full. If the item that has just been drawn is the selected item (with index number equal to listbox.current) and win. flags contains PR_WIN_EMPHASISED, the item is emphasised by sending an LB_DRAW_EMPHASIS message e if more items are available following the last item drawn, a down arrow is drawn at the bottom of the scroll gutter The text for each item is found by sending an LB_INQUIRE_ITEM message and is drawn by sending an LB_DRAW_ITEM message. VOID wn_emphasise(INT flag); Set the list box window's emphasis if f1ag is TRUE, otherwise clear the emphasis. The method first sets or clears the pR_wIN_EMPHASISED flag in win. flags, creates a temporary graphics context and draws the border in the appropriate emphasised state. Provided listbox. current is greater than or equal to listbox. first, the method calculates, in a P_RECT struct, the rectangular region within its window corresponding to the 1istbox. current item. It then sends an LB_DRAW_EMPHASIS message, passing listbox.current, a pointer to the p_REct struct and the value of flag. The temporary graphics context is then freed. If incremental matching is being used the incremental text cursor is drawn in its current position if £1ag is TRUE, otherwise it is erased. 6 LIST BOXES AND MENUS Set the window size and position VOID lb_size_window(INT flags, P_POINT *pos) ; Set the size of the window to that required to display the contents. The position of the window's top left comer is set, guided by the flags passed in f1ags and the coordinates in the p_poznr struct pointed to by pos. Note that this method includes the code that creates the window and so must be called before attempting to make the list box visible. It will normally be called from the wn_init method, provided the parameters to this method include the In_LIsTBox_AUTO_szzkE flag. On entry, 1istbox.width contains a previously specified minimum allowable width for the list box. Provided 1istbox. flags does not include pr_LIsTBox_FIXED_wipTH, the required width to display all the list box items is calculated as the larger of: e the value of listbox.width less the left and right borders e the widest of all the items, found by sending an LB_ITEM_wIpTH message for each item This value overwrites the original value of 1istbox.width, but the original value is also held for later use. The total width of the window is calculated by adding 1istbox.width, LISTBOX_LEFT EDGE, LISTBOX_LEFT_EDGE and (if either listbox. flags contains PR_LISTBOX_FORCE_WIDE, or there are more than seven items to be displayed) Ltstaox_scroLL_curTerR. Except in the case of the Workabout, if the calculated width exceeds the screen width, the method calls p_1eave (E_GEN_TOOWIDE). The height of the list box is calculated to display a the number of items in the list, provided this does not exceed the number of items that can be shown on the screen. If listbox. first is not zero, the height is increased by the additional amount required for the line dividing the title from the main list. Once the dimensions of the list box have been determined, the position on the screen is calculated. Three options are allowed: ¢ if £1ags contains In_LIsTBox_Pos_aLren_x the list box is centred horizontally on the region starting as pos->x and of width equal to the value that 1istbox.width had on first entry to the method. If this results in the window extending beyond either the left or right edge of the screen, the window is positioned at the corresponding edge. The y-coordinate of the top left corner of the list box window is set to be equal to pos- >y. This option is used, for example, to display a pull- down menu, centred as closely as possible on its menu bar item. ¢ if £1ags contains IN_LISTBox_Pos_aLIcn_y the list box is positioned so that, as far as possible, the currently highlighted item (the item with index 1istbox. current) is aligned with the position indicated by pos->y. The x-coordinate of the top left corner of the list box window is set so that the text of the items starts at the position indicated by pos->x, unless this results in the window exrending beyond the right edge of the window, in which case it is positioned as far to the right as possible. This option is used, for example, to display the list used to display an expanded set of choices for a dialog box choice list control. e if £1ags contains neither In_LISTBOX_POS_ALIGN_X Nor IN_LISTBOX_Pos_ALTGN_x, the list box is centred on the screen by sending a wN_CALC_POSITION message. The list box's win. flags is set to PR_BWIN_CUSHION| PR_WIN_EMPHASISED ored with either IN_BWIN_SHADOW_1 OT, if listbox. flags contains PR_LISTBOX_PLAQUE, IN_BWIN_SHADOW_2. The window is created with the required position and size as a root window (that is, with a nuL value of the parameter par) by sending a wN_CONNECT message. If incremental matching is enabled, the incremental matching cursor is drawn at the first character of the currently selected item. 5B DRAW_ITEM : Draw an item VOID 1lb_draw_item(TEXT *buf, INT index, P_RECT *prect); Draw, in the rectangle specified by prect, the content for the list box item with index number index, using the zero terminated text pointed to by bug. The text is drawn to the current graphics context by a call to the window server function gprintBoxText: It is the caller's responsibility to ensure that a suitable graphics context exists. HWIM REFERENCE This method does not use index, which is provided for subclasses that replace this method (punipown, HELPLIST and FILELIST). MPHASIS =+=— Toggle emphasis for an item VOID 1lb_draw_emphasis(INT index, P_RECT *prect, INT on); Toggle the presence of a highlighting obloid, in the rectangle specified by prect, for the item with index number index. The value of on is Truz if emphasis is being set, and ranse if emphasis is being cleared. The action is as indicated in the following code: METHOD VOID listbox_lb_draw_emphasis(PR_LISTBOX *self, INT index,P RECT *prect, INT on) { P_EXTENT ob; ob.tl=prect.tl; ob.width=p_send3(self,O LB ITEM_WIDTH, index) ; ob. height=DatGate->gate.x.cht; giInvObloid(&ob) ; } The supplied method does not use on, which is provided for use by the HELPLIsT subclass. ‘Sense required width for an item INT 1b_item_width(INT index) ; Return the pixel width required to display the text of the item with index number index, including a gap of width LIsTBOx_OBLOID_INDENT at either side of the text, to allow the item to be highlighted. s to an item VOID 1lb_take_focus(INT focus) ; Select the item with index number focus. If focus is the index number of the item that is currently selected the method does nothing other than ensure that, provided 1istbox.match is not nuLL and the window is emphasised (win. flags contains PR_WIN_EMPHASISED) the incremental matching cursor is drawn in its current position. Otherwise, listbox. current is set to focus. Provided the window is emphasised, the previously selected item has its highlighting removed and the highlight is set on the item with index number focus. If necessary, the list box contents are scrolled until this item is visible. If incremental matching is enabled, 1istbox.match is sent an IM_SET_VAL message, passing the value of focus-listbox.vastart and, provided the window is emphasised, the incremental matching cursor is drawn in its newly set position. QUIRE FOCUS | INT lb_inquire_focus (VOID) ; Return the index number of the currently selected item. This method simply returns the value of 1istbox. current. RE_ITEM Get po TEXT *lb inquire _item(INT index) ; Return a pointer to the first character of the text of the item with index number index. The pointer is calculated by adding 1istbox.offset to the pointer returned by sending the message: p_send3 (self->listbox.va,O VA_PBUF, index) ; There is an implicit assumption that the entire content of the item is stored contiguously. 6-10 6 LIST BOXES AND MENUS Get index of last item INT lb_inquire_last (VOID) ; Return the index number of the last item in the list box. If listbox.1last is not zero, return this value. Otherwise return one less than the number returned bya VA_COUNT message Sent to listbox.va. The Menu Bar destrey wnedraw wn_calc_ position wn_emphasise wn_connect wn_dodraw destroy wn_init wn_key wn_draw wn_visible mb_add_menu wn_position wn_redraw wn_sense_help An HWIM menu bar provides a means of browsing through an application's commands and their associated command accelerators. In addition, it may be used to select and execute a command, as an alternative to the direct use of an accelerator. A menu bar uses component instances of the menuras and puLLDown classes. Note that one or other of a menu bar's pull-down menus is always displayed while a menu bar is visible, and one item, the current item, is highlighted. The command corresponding to the current item may be executed by pressing Enter. A typical menu bar (from the Series 3 System Screen) is shown below, together with a menuras anda PULLDOWN Component. Menu tab Menu bar —~( File Disk Info Special ) Install application ¥° Install standard LJ Remove application YY ,e=—=Pull-down Quit speplication =n Kill application 2 Assign button 2 In an HWIM application the menu bar and its components do not exist unless the menu bar is visible. They are created each time the menu bar becomes visible (generally from the wszRv ao_run method in response to the user pressing the Menu key) and destroyed when it disappears (when the user either presses Esc or executes a command). HWIM REFERENCE When the menu bar is displayed, one menu is pulled down (the Apps menu in the above example) and an item in that menu (for example, Quit application) is selected. The initial visible menu and selected item are determined by the wserv property items accessed by w_ws->wserv.info->menu and w_ws->wserv.info->mnitem respectively. An HWIM application will normally rely on system code to manage the presentation of the menu bar. Applications are not expected to subclass Menusar or to send explicit messages to any instance. The following description is included for completeness, and for interest. Class definition Defined in sub-category file menubar.cl (generated header file menubar.g). CLASS menubar bwin The menu bar { REPLACE destroy Free any memory used REPLACE wn_init Set up the menu bar text and menus to pull down REPLACE wn_emphasise For 3d border effects REPLACE wn_draw Draw the menu bar text REPLACE wn_key Toggle through the menus or pass on to menus REPLACE wn_visible When made visible show menu as well ADD mb_add_menu Add a menu to the menu bar TYPES { typedef struct { UWORD menu_id; resource ID of associated pull-down menu TEXT mb_txt{1]; menu header text (2TS) } MENUBAR_ITEM; typedef struct { UBYTE count; number of items } MENUBAR; (followed by count MENUBAR_ITEMs) } CONSTANTS { MENUBAR_LEFT_ SHOULD 4 horizontal space occupied by the menu bar left shoulder MENUBAR_RIGHT_SHOULD 4 horizontal space occupied by the menu bar right shoulder MENUBAR_MAX MENU 15 MENUBAR_MIN_GAP 3 half the minimum separation between successive text items MENUBAR_MAX_GAP 10 half the maximum separation between successive text items MENUBAR_3b TAIL WIDTH 18 } PROPERTY 2 { PR_MENUTAB *tab; Tab top for current pull down menu PR_PULLDOWN *menu; Current pull down menu MENUBAR *mb; Pointer to menu bar information UBYTE num; Number of currently pulled down menu UBYTE xoff; X offset of start of menu bar on screen UBYTE toff; Offset of start of text from tab position UBYTE asc; Ascent where text should be drawn UWORD pos [MENUBAR_MAX_MENU+1]; Leading tab positions, including terminal entry } On the Series 3, the menubar. asc property is not defined and menubar .pos is a UBYTE alTay. The Series 3 version of the class definition includes the following additional constr definitions: MENUBAR_MAX WIDTH (SCREEN_WIDTH-MENUBAR_LEFT_SHOULD-MENUBAR_RIGHT SHOULD) MENUBAR_HEIGHT (SYSTEM_FONT_HEIGHT+ (BWIN_CUSHION_Y+2)*2+BWIN SHADOW 1 HEIGHT) On the Series 3a the corresponding values are read or derived from the globally accessible data that is described in the /ntroduction chapter of this manual. 6 LIST BOXES AND MENUS Property menubar .tab The handle of the menu tab (an instance of menuras)for the currently displayed pull-down menu. menubar .menu The handle of the currently displayed pull-down menu. menubar .mb A pointer to a MENugaR struct, containing an array of MENUBAR_ITEM structs, one for each of the menu bar's pull-down menus. menubar .num The index number of the currently visible pull-down menu. menubar .xoff The screen x-offset, in pixels, to the left hand edge of the menu bar. This is stored for convenience, rather than repeatedly reading it from the window server. menubar. toff The pixel offset from the left edge of any menu tab to the start of the corresponding text. menubar.asc The ascent, in pixels, to the position where the menubar text is drawn. This differs for different machine types. This property is not defined on Series 3 machines. menubar .pos An array of the positions of the menu tabs for the tops of all the pull- down menus. Each entry contains the pixel position, relative to the left edge of the menu bar, of the left edge of the menu tab of the corresponding pull-down menu.The array contains a terminating entry that indicates the rightmost extent of the last menu tab. On the Series 3, menubar .pos iS an alray of UBYTES. i SSS ee ee a ia MENUBAR methods Displaying a pull-down menu A pull-down menu is displayed by creating and initialising component instances of the menutaz and of PULLDOWN Or (if a 3D border is used on the Series 3a) xpuLtown classes. An initial pull-down menu is set up by the wn_visible method, and the wn_key method may subsequently switch to another menu. The pull-down menu to be displayed is identified by the value of menubar .num, which is used to locate the corresponding MENUBAR_ITEM struct in the buffer pointed to by menubar .mb. If there are existing MENuTAB and PULLDOwN components they are destroyed before new instances are created, with their handles stored in menubar .tab and menubar .menu. The PuLLpown instance is initialised from an 1n_LIsTBox list box initialisation struct. This struct is defined in the ttsrsox class definition as: typedef struct { UWORD flags; PR_VAROOT *array; UWORD offset; WORD current; UWORD top; UWORD first; UWORD last; P_POINT pos; UWORD minwid; } IN_LISTBOX; where: ® flags is set to IN_LISTBOX_TEXT_OFFSET | IN_LISTBOX_MIN_WIDTH | IN_LISTBOX_WRAP_ROUND | IN_LISTBOX_POS_ALIGN_X | IN_LISTBOX_AUTO_SIZE | IN_LISTBOX_CUR_SET ¢ array contains the handle of an instance of varEs, containing the items loaded from the pull-down menu resource specified by the value of menu_id in the relevant MENUBAR_ITEM struct HWIM REFERENCE — ee SSS * offset is set to 1 to skip the first byte (containing the command id) of each element of the array * current is set to either the value of w_ws->wserv. info->mnitem (on creation of the menu bar) or zero (when switching to another menu) ® top, first and last are not used ¢ pos.x is set to the value of menubar. pos [menubar .num) less the value MENUBAR_LEFT_SHOULD and pos.y is set to be four pixels less than the height of the menubar © minwid is set to the width of the menu tab plus an allowance for the left and right shoulders of the pull-down menu The command manager is sent a com_meNnu message (to inform it of the imminent display of the pull-down menu) passing menubar .num and the array handle. The pull-down menu is then sent a WN_INIT message, passing the address of the 1n_L1stsox struct described above. The menu tab is also sent a WN_INIT message, passing the address of the p_exrent struct described earlier, the value of menubar.tofé anda pointer to the menu bar text for that item. Finally both the pull-down menu and the menu tab are sent a wN_VISIBLE, WV_INITVIS message. The code to implement the display of a pull-down menu is executed under the protection of p enter and returns either zero on successful completion or a negative error number on failure. VOID destroy (VOID) ; Record the current pull-down menu item selection by writing menubar .num to w_ws->wserv. info->menu and menubar .menu->listbox.current to w_ws->wserv. info->mniten. If w_ws->wserv.oldinfo is not NULL (normally meaning that the current menu is a submenu) w_ws is sent a WS_RESET_MENUBAR message, passing W_ws->wserv.oldinfo, and then w_ws->wserv.oldinfo is set to NULL. The menu bar is destroyed by freeing the allocated cell pointed to by menbar .mb and then supersending the DESTROY message. Finally, w_ws->wserv.bar is set to NULL. INT wn_init (MENUBAR *pmenbar) ; Initialise the menu bar to display the menu items in the menupar struct pointed to by pmenbar (this struct will normally have been loaded from a resource file). The method scans the text of the items in the mznupar struct, calculating the cumulative pixel position of each item and storing the results in successive elements of the menbar.pos array. The text of successive items is separated by 2*MENUBAR_MIN_Gap pixels. Except in the case of the Workabout, if the total width of the menu bar exceeds the width of the screen (less the sum of MENUBAR_LEFT_SHOULD, MENUBAR_RIGHT_SHOULD and TaB_EDGES) the method calls p_leave (E_GEN_TOOWIDE). The value of win. flags is set to PR_BWIN_SHADOW| PR_BWIN_CUSHTION| PR_WIN_EMPHASISED and the window is created as a top-level window by sending a wn_connecT message. The method does not set the position or dimensions of the window. This must be done by the later sending of a WN_VISIBLE message. The method returns zero to indicate that p_1eave has not been called, and is thus suitable for being called under the protection of p_enter. vite sility INT wn_visible(UINT state) ; Set the position and size of the menu bar and make it (and one of its pull-down menus) visible. The implementation of the method assumes that a menu bar will receive only one WN_VISIBLE message in its lifetime, and that the value of state will be wv_inrtvis. To recover any previous selection of a pull-down menu, menubar .num is set to w_ws->wserv.info->menu. This pull-down menu will be drawn with a highlight set to the item indicated by w_ws->wserv.info->mnitem. Both of these values are protected against overrun, should the number of 6-14 6 LIST BOXES AND MENUS pull-down menus or the number of items within a pull-down menu be decreased since the last time the menu bar was visible. The gaps between the menu bar items are expanded as much as possible, up to a maximum of 2*MENUBAR_MAX_GAP. This determines the width of the menu bar, which is then centred horizontally and the pixel position of the left edge of the menu bar is stored in menubar .xof£. The menu bar is positioned at the top edge of the screen, with a fixed height equal to the height of the menu bar. The position and dimensions of the menu bar are set by a call to wset window. The value of menubar .tof¢ is set so that the text of each menu bar item will appear centrally within its menu tab. The method supersends the wv_vis1BLe message before displaying the pull-down menu with index number menubar .num, highlighting the item with index number w_ws->wserv.info->mnitem. The method returns either zero on successful completion or a negative error number. Errors will be related to a failure to create and display the pull-down menu. VOID wn_draw (VOID) ; Draw the menu bar border and the text of each item. Each item of text is drawn by means of a call to gprint Text. The horizontal position of each text item is determined by adding menubar .tof¢ to the value of corresponding entry in the menubar .pos array. INT wn_key(UINT keycode,UINT modifiers) ; Process the keypress with key code keycode and the modifiers indicated by modifiers. The following table describes the response to specific keys. W_KEY_ LEFT Cycle left by one item and display the new pull-down menu. The return value is either wN_KEY_NO_CHANGE (0) or a negative error caused by a failure to create and display the pull-down menu. W_KEY_RIGHT Cycle right by one item and display the new pull-down menu. The return value is either wN_KEY_NO_CHANGE (0) or a negative error caused by a failure to create and display the pull-down menu. W_KEY_MENU If modifiers contains w_sHIFT_MODIFIER perform the same action as for W_KEY_LEFT, otherwise perform the same action as for W_KEY RIGHT. W_KEY_HOME Display the first pull-down menu. The return value is either ww_xEY_No_CHANGE (0) or a negative error caused by a failure to create and display the pull-down menu. W_KEY_END Display the last pull-down menu. The return value is either wn_KEY_NO_CHANGE (0) or a negative error caused by a failure to create and display the pull-down menu. numeric, i to 9 Display the corresponding pull-down menu; numbers greater than the number of items in the menu bar all display the last pull-down menu. The return value is either wN_KEY_No_CHANGE (0) or a negative error caused by a failure to create and display the pull-down menu. All other key codes for which p_isprint retums FALSE are sent, via a WN_KEY message, to the currently displayed pull-down menu, whose handle is in menubar .menu. Significant key codes are W_KEY_ ESCAPE, W_KEY_RETURN, W_KEY_UP, W_KEY_DOWN, W_KEY_PAGE_UP and W_KEY_PAGE_Down. The return value is the value returned by the wv_xey message to the pull-down menu. All remaining key codes are tested for a case-independent match with the accelerator keys, stored in w_ws->wserv.info.accel. If there is a match, and the corresponding command is in the currently displayed pull-down menu, the pull-down menu is sent an LB_TAKE_Focus message to highlight the appropriate item. If the match is with a command in another pull-down menu, the new pull-down menu is displayed, with the appropriate item highlighted. The return value is either ww_KEY_NO_CHANGE (0) or a negative error caused by a failure to create and display a pull-down menu. HWIM REFERENCE eee MB_ADD_MENU INT mb_add_menu(TEXT *title, INT menu_id) ; _ Add amenu Append a pull-down menu to the end of the menu bar. The additional item will be displayed with the text in the zero terminated string pointed to by title and uses the pull-down menu indicated by the resource ID menu_id. If used, this method may only be called between the calls to the wn_init and wm_visible methods. Uses p_realloc to reallocate the buffer pointed to by menubar ..mb so that it is large enough to contain the additional item. The text string and menu_id are copied into menubar .mb to form its final MENUBAR_ITEM struct, an additional entry is added to the menubar. pos array (as with the wn_init method, the inter-item gap is set to 2*MENUBAR_MIN_GaP) and menubar.mb->count is incremented. The method returns zero if it completed successfully, or one of the errors: E_GEN_NOMEMORY if there was insufficient memory to reallocate the buffer E_GEN_TOOWIDE if the new width is too wide for the screen (this error is not returned on the Workabout) E_GEN_TOOMANY if the number of menus exceeds MENUBAR_MAX_MENU (this error is not returned on the Workabout) PULLDOWN pull-down menu match va flags width matchlen curofft offset current top first last vastart matchstart destroy wn_calc_position 3 wn_init wn_connect wa-key wn_dodraw wn_draw wn_key lb_draw_item 1b_draw_emphasis 1lb_item_width wn_emphasise wn_position wn_redraw wn_sense_help wn_visible wn_set wn_sense 1b_size_window ib-tem—width lb_take_focus 1lb_inquire_focus 1b_inquire_item 1lb_inquire_last The puLpown class subclasses L1sTBox to provide the display of pull-down menus. In an HWIM application a pull-down menu does not exist unless it is visible. 6-16 6 LIST BOXES AND MENUS —_—_—_— eee BU AES AND MENUS An HWIM application will normally rely on system code to manage the presentation of pull-down menus. Applications are not normally expected to subclass puLLpown or to send explicit messages to any instance. The following description is included for completeness, and for interest. Class definition Defined in sub-category file pu//down.cl (generated header file pulldown.g). CLASS pulldown listbox pull down menu from menu bar { REPLACE wn_key Check for accelerator matching REPLACE lb draw_item Draw accelerator at right edge REPLACE 1b draw_emphasis Emphasise whole area REPLACE lb item_width Returns the required width of the item TYPES { typedef struct { UBYTE com_id; TEXT mn_txt [1]; } MENU_ITEM; } Property There is no property associated with the puLLDown class. SSS See eee ee EE, ee) PULLDOWN methods WNUKEY” ext, are adjusted to the slightly larger dimensions of the Series 3a pull- down menus, and the result adjusted if necessary to ensure that the window does not exceed the boundaries of the screen. The flags w_wIN_BACK_CLR and w_WIN_BACK_GREY_CLR are ored into pwd->background, and W_WIN_BACKGROUND is ored into flags. The method then supersends the wn_connecT message. VOID wn_draw(VOID) ; Draw the pull-down menu border and the text of each item. Each item of text is drawn by means of a call to gprint Text. The currently selected item is highlighted by dending an LB_DRAW_EMPHASIS message. VOID 1b _draw_emphasis (INT index,P RECT *prect,INT on); Toggle the presence of a highlighting obloid, in the rectangle specified by prect, for the item with index number index. The value of on is TRuE if emphasis is being set, and raLsE if emphasis is being cleared. Increment the x-coordinates in the p_recr struct pointed to by prect and supersend the LB_DRAW_ EMPHASIS message. As for the superclass method, the value of on is ignored. HWIM REFERENCE MENUTAB destroy wn_sense_help | wa-draw wn_calc_ position wn_visible wn_emphasise wn_connect wn_dodraw wn_set wh-emphasise wn_sense wn_key wn_position wn_redraw The menutas class subclasses swrn to provide the display of the tab above a currenly visible pull-down menu. In an HWIM application the tab does not exist unless it, and its associated pull-down menu, is visible. An HWIM application will normally rely on system code to manage the presentation of a menu tab. Applications are not normally expected to subclass menuras or to send explicit messages to any instance. The following description is included for completeness, and for interest. Class definition Defined in sub-category file menubar.cl (generated header file menubar.g). CLASS menutab bwin { REPLACE wn_init REPLACE wn_draw PROPERTY { TEXT *txt; Pointer to the text to display UWORD xoff; Offset at which to display the text } } Property menutab. txt A pointer to the menu tab text, assumed to be a zero terminated string. menutab.xoff The pixel x-offset in the menu tab window to the position at which the text is to be drawn. Sa eee a a a en ee ray MENUTAB methods WNONID alge VOID wn_init (P_EXTENT *pext,UINT xoff,TEXT *txt) ; Sets win. flags to PR_WIN_EMPHASISED|PR_BWIN_CUSHION|PR_BWIN_SHADOW_1|PR_BWIN_OPEN, menutab.off to xoff and menutab.txt to txt. Then sends a wN_CoNNECT message to create the window with position and size as specified by pext. Draw VOID wn_draw(VOID) ; Draw the menu tab. Supersends the ww_praw message to draw the border and then draws the text of the menu tab with a call to gPrintText. 6-20 CHAPTER 7 DIALOG BOXES This chapter describes the classes provided in HWIM for the creation and operation of dialogs. A dialog box shows the user the current values of one or more data items and, in general, allows the user to modify one or more of these values. In an HWIM application the most common use of a dialog is as a result of the user selecting a command from a command menu. In response to an Open file command, for example, a dialog would be presented to allow the user to specify the name (and possibly the type) of the file to be opened. All HWIM dialogs are modal, that is, while the dialog is visible the user can interact with the application only via that dialog; the application enters a 'mode' such that all attempts to interact with, say the menu bar are disallowed. This mode terminates when the user satisfactorily completes the dialog. A number of pre-defined system dialogs exist and are described in later chapters of this manual. The system dialogs may be run by specific wserv methods, such as ws_error_dialog, ws_query dialog and ws_format_dialog, that are described in the chapter The WSERV Class. See also the dialog utility functions described in the Dialog box utilities section of the HWIM Utility Functions chapter. Precursors Familiarity with the following topics will aid the understanding of this chapter: e the window concepts described in the Introduction and Windows chapters of the Window Server Reference manual e the wssrv class, especially the ws_do_dial method, which starts up a dialog box, and the ao_run method, which may send messages to a dialog box window ¢ graphics contexts and drawing, described in the Graphics Output chapter of the Window Server Reference manual e — the basic principles of resource files as described in the Resource Files chapter of the Additional System Information manual. (Further information is available in the HWIM Resource Files chapter of the Object Oriented Programming Guide.) Class diagram rote ee orm ee Ps f ee 7 ae ‘ area / digchain ~ / digbox > / atsdiat ~ 4 a i : HWIM REFERENCE DLGCHAIN destroy wn_sense_help wn_draw wn_cale position wn_visible wn_emphasise wn_connect wn_dodraw wn_set we-enpheacies wn_sense wn_key whedraw wn_position wn_init wn_redraw The piccuarn abstract class subclasses swrn, but adds or modifies no methods. It adds property that makes all instances of its subclasses suitable for including in a chained list of objects. Such a list is maintained by the application's instance of wserv (with the foremost dialog's handle stored in wserv.diai) to implement stacked dialog boxes. Other subclasses of pLGcuarn may also be included in this list. For example, Help 'dialogs' (which do not subclass pLGBox) may appear in the list, intermixed with true dialogs. Class definition Defined in sub-category file digbox.cl (generated header file digbox.g). CLASS dligchain bwin Dialog box next and previous chaining { CONSTANTS { ! All four bits re-used from original meanings PR_WIN_NO_DDP PR_WIN_FORCE_TOP DatDialogPtr should never point to this dialog HELPDLG_BASIC_HELP PR_WIN_FORCE_RIGHT HELPDLG_HELP_INDEX PR_WIN_FORCE_LEFT DLGCHAIN_WITH_MENU PR_WIN_FORCE BOTTOM } PROPERTY { PR_BWIN *next; Next dialog, if present } } On the Series 3 the constants section of the class definition does not contain the definitions: HELPDLG_BASIC_HELP HELPDLG_HELP_INDEX DLGCHAIN_WITH_MENU Property dlgchain.next The handle of the next item in a list of pLccHarn instances, mainly used for the list headed by the item whose handle is stored in the wsERv property wserv.dial. DLGCHAIN flags The following flags may be set in win. flags: PR_WIN_NO_DDP If a subclass of piGcHarn sets the PR_WIN_NO_Dpp flag in win. flags during its initialisation, it will never have the handle of an instance written to the magic static DatDialogPtr. HELP_DLG BASIC_HELP Not defined for Series 3 code. HELPDLG_HELP_ INDEX Not defined for Series 3 code. 7 DIALOG BOXES oon nr DLGCHAIN WITH_MENU Not defined for Series 3 code. If set, indicates that the dialog has an associated menu bar whose commands are accessible by the Menu and cursor keys, or by hot-key combinations. If, as is the case for most dialogs, the flag is clear, then all such keypresses are directed to the dialog box itself. If a subclass does not set PR_WIN_NO_pDppP in win. flags, it is signalling that it is prepared to have DatDialogptr set to the handle of any instance that appears in the wserv.diai list. An advantage of doing so is that the handle does not need to be passed as a parameter to any utility functions - see, for example, the dialog box utility functions described later in this chapter. The subclass should write its handle to DatDialogPtr when it adds itself at the front of the wserv.diai list, during initialisation. Note that this handle may be overwritten by a different value when another subclass of puccHatn adds itself to the list. Any such subclass must cooperate with other items in the wserv.dial list. On destruction, provided DatDialogPtr contains its handle, it must scan all the remaining items in the list and write to DatDialogptr the handle of the first item for which win. flags does not contain PR_WIN_NO_DDP. Note that this means that any such instance is liable to have its handle written to DatDialogPtr, and thus must perform the operation described above, even if it does not write its own handle to patpialogptr. This situation will never arise for a subclass that sets PR_WIN_No_Dpp. DLGBOX flags next id destrey wheodraw wn_position wn_redraw wn_sense_heip wn_visible current font” absorb changed dl_item_replace dl_item_append qa@l_init di_dimmed_message dl_item_add dl_set_size dl_ing_minsize dl_item_lock dl_dyn_init dl_item_dim dl_key dl_set_item_flags dl_set_prompt dl_changed dl_take_focus dl_focus di_handle_to_index dl_launch_sub dl_index_to_handle dl_item_new The piesox class provides a flexible set of mechanisms for displaying and controlling a wide variety of dialog boxes. Although formally an abstract class (since some methods are pererred) an instance of pLcox may be created and used to display simple notification dialogs. The majority of normal dialogs may be created and used with a subclass that replaces at most two methods: very few dialogs require all the beFErred methods to be defined. This is discussed at greater length in the Using dialog boxes section of the Object Oriented Programming Guide. HWIM REFERENCE An HWIM dialog box consists of a bordered window containing between one or more lines, or items. The maximum bumber of items that may be displayed varies from machine to machine as follows: Series 3 seven items Series 3a nine items Workabout six items in the system font, or eight items in a small font Each item may be plain text, a control, or a combination of a plain text prompt and a control. Each control may be an instance of one of many different classes, including: e aplain text window © achoice list ¢ an action list of buttons (may only be the last item in the dialog box) e atext edit box © anumeric editor e a floating point editor e atime editor e a date editor e a scrolling or non-scrolling text editor e asecret data input box e a filename selector e a filename editor ® an application-specific control All these controls are subclasses of the Lopcgr class. Any item in the dialog box may be separated from the following items by a horizontal line, referred to as an underline. In the case of the Series 3a and Workabout, any number of items may be underlined, but for the Series 3, only one underline may appear in a dialog box. In the majority of dialogs an underline is used to separate the first item, designated to be the dialog title, from those that follow. The title is normally, but not necessarily, plain text. Many dialogs can be created and run using the piczox class directly, together with wsERv's ws_do_dial method. Class definition Defined in sub-category file digbox.cl (generated header file digbox.g). CLASS dlgbox dlgchain Dialog box class { REPLACE destroy REPLACE wn_key REPLACE wn_emphasise Pass on to item with focus REPLACE wn_sense_help Give start ID for help REPLACE wn_set Set item by index REPLACE wn_sense Sense item by index REPLACE wn_draw 7 DIALOG BOXES ee dl_item_lock dl_item_dim di_set_item_flags dl_set_prompt @l_take_focus di_handle_to_index dl_index_to_handle dl_item_replace dl_item_append dl_init dl_dimmed_message dl_item_add dl_set_size dl_ing_minsize=p_dummy dl_dyn_init=p_dummy dl_key DEFER dl_changed DEFER di_focus DEFER dl_launch_sub DEFER dl_item_new CONSTANTS { DLGBOX_NOTIFY_ENTER DLGBOX_NOTIFY_ESCAPE DLGBOX_RBUF_FILLED DLGBOX_ACTION_LIST DLGBOX_FROM_HWIF DLGBOX_SMALL_ FONT DLGBOX_NO_WAIT DLGBOX_NOTIFY_ALL ACT DLGBOX_REPORT_ACT HORIZ DLGBOX_APPEND_UNITS TITLE 0x0100 DLGBOX_SMALL_ACTION_LIST DLGBOX_NO_SHADOW DLGBOX_NO_DDP Lock an item by index Dim an item by index Set some dlgbox_item flags Change the prompt for an item Move focus item specified by index Return index for given handle Return handle for given index Replace an existing item with another Add an item (by rid) to end of list Initialise dialog from a resource file Present reason for item being dimmed Add an item to the end of the list Sets size of dialog after dynamic initialisation Allows default minimum sizes to be changed For subclass dynamic initialisation Primarily for C call processing For users that request item changed messages For users that request change focus messages launch sub dialog if required Create instance of non-system dialog item 0x0001 Notify when dialog terminated with enter 0x0002 Notify when dialog terminated with escape 0x0004 Set if subclasser fills rbuf 0x0008 Dialog contains an action list 0x0010 Reserved for system use DLGBOX_FROM_HWIF Dialog box uses the small font 0x0020 No am_start 0x0040 Report ALL keys to dl_key 0x0080 Report matching action key as horiz Append units(cm/in) used to title 0x0200 Dialog contains a small action list 0x0400 Create dialog with no shadow 0x0800 Do not overwrite DatDialogPtr ! Four bits 0x1000 to 0x8000 reserved for PR_WIN_FORCE_XXX DLGBOX_ITEM_NOTIFY_CHANGED 0x0001 Report item changes to item DLGBOX_ITEM_DIMMED DLGBOX_ITEM_UNDERLINED DLGBOX_ITEM_APPL_CAT DLGBOX_ITEM_CENTRE DLGBOX_ITEM_DEAD DLGBOX_ITEM_NOTIFY_FOCUS DLGBOX_ITEM_NEEDS PACK DLGBOX_ITEM_LOCKED DLGBOX_ITEM_CAN_DEFER_X DLGBOX_ITEM_X_PENDING DLGBOX_ITEM_ACLIST DLGBOX_LEFT GAP DLGBOX_BULLET_GAP DLGBOX_VERT_GAP UNDERLINE_DEPTH EXTRA_GUTTER_WIDTH DLGBOX_MAX_ITEM DLGBOX_ROMAN8_FONT } 0x0002 Item dimmed 0x0004 0x0008 Application specific item 0x0010 Item centred in dialog 0x0020 Can't ever select item 0x0080 Report item focus changes to dialog 0x0100 Add a pack selector immediately after 0x0200 Visible & can take focus: values locked 0x0400 Can defer self-check 0x0800 Item must be checked before exit 0x1000 This is the aclist in the dialog (BWIN_CUSHION_X+7) 3 (BWIN_CUSHION Y+2) 3 4 9 5 Add (WS_FONT_BASE-1) to get small font ID HWIM REFERENCE eee eS TYPES { typedef struct { UWORD flags; TEXT title[1]; 2ZTS string, ! followed by a byte count of the following items, ! each of which has a leading length byte } HD_DLGBOX_RSC; typedef struct { WORD flags; initialisable DB_ITEM flags UBYTE class; class of item TEXT prompt [1] ; ZTS string ! followed by IN_ structure } AD_DLGBOX; header for each item in resource information typedef struct { PR_LODGER *hand; handle of item object PR_TEXTWIN *prompt; handle of prompt for item WORD flags; property DB_ITEM flags } DLGBOX_ITEM; internal representation of items typedef union { DLGBOX_ITEM item(7] ; Array of items in dialog DLGBOX_ITEM *pitm; ptr to an array of more than 7 items } DLGBOX_ITEM_UNION; } PROPERTY { DLGBOX_ITEM_UNION u; either array of items or ptr to array of items VOID *rbuf; address of result buffer WORD dimrid; rid for dimmed item status message WORD helprid; rid to start help UWORD flags; holds DLGBOX_XXX flags UBYTE focus; TRUE when an item has focus UBYTE count; number of items (ine title) in dialog UBYTE current; number of current control (0-6) UBYTE font; LSB+1 of WS_FONT_BASE font ID UBYTE absorb; direct all keypresses to the current control UBYTE changed; TRUE if the current item needs self check } On the Series 3 the constants section of the class definition does not contain the definitions of: DLGBOX_ITEM_ACLIST EXTRA_GUTTER_WIDTH DLGBOX_MAX ITEM but does contain two alternative definitions: GUTTER_WIDTH 10 ACLIST_EXTRA_HEIGHT 20 In the property section of the Series 3 class definition, the element: DLGBOX_ITEM_UNION u; either array of items or ptr to array of items is replaced by the simpler: DLGBOX_ITEM item[7] ; array of items in dialog These differences are associated with internal code changes and, apart from the additional number of items that a Series 3a dialog box may contain, have no significant consequences for the application programmer. The Workabout class definition introduces the defined constants pLGBox_sMALL_FONT and DLGBOX_ROMAN8_FONT. In the PRopERTy section of the Workabout class definition, the line: UBYTE font; LSB+1 of WS_FONT_BASE font ID a SSSSSSSSSSSSSSSSSSeSSeeSSSSeSeeeeSSSSeESee 7-6 7 DIALOG BOXES has replaced the Series 3/3a line: UBYTE underline; Property dlgbox. dligbox. dlgbox. digbox. digbox. dlgbox. dlgbox. digbox. dlgbox. dlgbox. dlgbox. digbox. digbox. u.item u.pitm rbuf dimrid helprid flags focus count current font underline absorb changed y offset of S3 underline (not used in S3a code) used to provide access to an array of pLGBox_rTEM structs for the component items. If the dialog box contains seven or fewer items, the array is stored directly in digbox.u.item. For more than seven items, the array is held in allocated memory, pointed to by dlgbox.u.pitm. Jn consequence, subclassers should not access the data in the array other than through the supplied methods, such as d1_index_to_handle. the address of a user-supplied ‘result’ buffer, from which initialisation data may be read and to which result data may be written. The buffer's address may optionally be passed to the window server object's ws_do_dial method (or the equivalent nuaunchpial utility function). either zero or the resource ID of a text message that is to be displayed if a user attempts to modify a ‘dimmed' control either zero or the resource ID of a context-specific Help resource a collection of state flags, described below TRUE if keyboard focus is held by one of the dialog box controls. Only system code may write to this item. a count of the number of items in the dialog box, including any dialog title. Only system code may write to this item. the index of the dialog's component control that currently has focus. Only system code may write to this item. introduced in the Workabout, to replace dlgbox .underline. If not zero, its value determines the ID of the small font used in dialogs and, optionally, in list boxes. The font ID is given by digbox. font+wS_FONT_BASE-1. Although the value could, in principle, specify any font ID, it is restricted to be either zero or DLGBox_RomaNs_FoNrT. This is because the pseudo-static data held in patGate->gate. dx, used to determine the size and position of dialog controls using the small font, is calculated for this font. not used in Series 3a code, and replaced by digbox. font in the Workabout. On the Series 3 only, if not zero, it is the pixel offset from the top of the dialog box to a horizontal line drawn across the dialog box. On the Series 3, a dialog box may contain only one such line, normally used to separate the dialog title from the remainder of the dialog content. TRUE if all keypresses are to be directed to the control that currently has the focus. Otherwise the dialog box intercepts keypresses that can be interpreted by any dialog action list, and those with keycodes W_KEY_RETURN, W_KEY_ESCAPE, W_KEY_UP, W_KEY_DOWN, W_KEY PAGE up and W_KEY_PAGE_DOWN. set TRUE if the 1g self_check method of any of the dialog's component controls reports that its value has changed. Cleared when focus is transferred to another control. HWIM REFERENCE DLGBOX flags The content of dlgbox. flags may be any combination of the following flags: DLGBOX_NOTIFY_ENTER DLGBOX_NOTIFY_ESCAPE DLGBOX_RBUF_FILLED DLGBOX_ACTION_LIST DLGBOX_SMALL_ACTION_LIST DLGBOX_NOTIFY_ALL ACT DLGBOX_REPORT_ACT_HORIZ DLGBOX_SMALL_FONT DLGBOX_NO_WAIT DLGBOX_APPEND_UNITS_TITLE DLGBOX_NO_ SHADOW DLGBOX_NO_DDP PR_WIN_FORCE_RIGHT PR_WIN_FORCE_LEFT if this flag is set the dialog box will be sent a pL_KEY message when the dialog receives an Enter keypress if this flag is set the dialog box will be sent a pL_kEy message when the dialog receives an Esc keypress if this is not set and algbox.rbuf is not NULL, system code will write to *dlgbox.rbuf on exiting the dialog. A subclass that uses dlgbox.rbuf for its own purposes should set this flag this flag must only be set if the dialog contains an action list (class ACLIST) as its last item. It is set automatically during the initialisation of an AcLIsT component control. When set (provided dlgbox. absorb is FALSE) all received keys are first offered to the action list by sending it a wn_key message, which returns a value indicating whether or not the keypress matched one of the buttons this flag must only be set if the dialog contains a 'small' action list (class smacLIST) as its last item. It is set automatically during the initialisation of an sMAcLIST component control. When set (provided dlgbox.absorb IS FALSE) all received keys are first offered to the action list by sending it a ww_KEy message, which returns a value indicating whether or not the keypress matched one of the buttons if this flag is clear, report only those keys that match an action button by sending the dialog box a pL_KEy message, otherwise send a DL_key message for all keypresses that have been offered to the action list, irrespective of whether they matched an action button if a keypress to an action button causes the dialog to terminate, a value may be written to *dlgbox.xbuf (See DLGBOX_RBUF_FILLED). If DLGBOX_REPORT_ACT_HoRIz is set, the value written to *dlgbox.rbuf is the index number of the button that matched the keypress (or -! if it did not match). Otherwise the value is the uppercased key code of the keypress. this flag is not defined for the Series 3 or 3a. If it is set in a dialog's resource, the dialog is initialised to use the small (8 point Roman) font, rather than the system font. This flag is not stored permanently in a dialog's property (see the wsERV ws_do_dial method) if this flag is clear, the dialog is run between am_start and aM_sToP messages to the application manager set this flag to append the current preferred units (cm or in) to any dialog title if this flag is set the dialog box is created without a shadow border if this flag is clear, the dialog box's handle is written to DatDialogPtr during initialisation and, on destruction, either nu. or the handle of the foremost of any remaining items in the wserv.dial list for which this flag is clear is written back to DatDialogptr. Normally this flag is clear to improve the efficiency of dialog-related utility functions, which then do not need to pass the dialog box handle as a parameter if set, the dialog will be positioned at the extreme right of the screen (see the wrn class) if set, the dialog will be positioned at the extreme left of the screen (see the wrw class) 7 DIALOG BOXES —_—.:s Se IALUG BOAES PR_WIN_FORCE_BOTTOM if set, the dialog will be positioned at the bottom of the screen (see the wzn class) PR_WIN_FORCE_TOP if set, the dialog will be positioned at the top of the screen (see the WIN Class) These flags are set, during creation of the dialog, from the initialisation data for the dialog box, which is normally loaded from a resource file. Small font dialogs for the Workabout Workabout dialogs may be set to use the small (8 point Roman) font by including the flag DLGBOX_SMALL_FonrT in the flags field of the pranoc resource that defines the dialog. On initialisation of the dialog, this causes the value of digbox. font to be set to DLGBOx_ROMAN8_FonT and the value pR_WIN_IS_DLCTRL to be set in the win. flags property of each subclass of LopcEr that is used as a component of the dialog. All the supplied Lopcer subclasses that may be used as dialog controls will draw themselves using the small font, but only if: e they are components of a dialog i.e. if win. flags contains PR_WIN_IS_DLCTRL e they are set to use the small font i-e. if ((PR_DLGBOXx *) lodger->1andlord) ->dlgbox. font is non-zero Outside a dialog box, or if the dialog is not set to use the small font, these subclasses of LopcER will draw themselves using the normal, system font. When positioning controls within a dialog box, and when calculating the dimensions of controls and the dialog itself, the pre-calculated pseudo-static data is read from either patcate->gate.x or DatGate->gate.dx, depending on whether the dialog is set to use the normal or the small font. DLGBOX_ITEM flags The picBox_rrem flags can be set individually for each dialog box item and are stored in the flags field of the corresponding pLGBox_1T= struct in the array that is either held in the digbox.u. item property, or pointed to by dlgbox.u.pitm. The content of the f1ags field may be any combination of the following flags: DLGBOX_ITEM_NOTIFY_CHANGED if this flag is set, changes to the item result in the dialog box receiving a DL_CHANGED message. This flag is normally only set in the item's initialisation data DLGBOX_ITEM_NOTIFY_Focus if this flag is set, each loss or gain of focus by the item results in the dialog box being sent a pL_rocus message. This flag is normally only be set in the item's initialisation data DLGBOX_ITEM_UNDERLINED if this flag is set, the corresponding item will be drawn with an underline extending across the full width of the dialog box. This flag is normally only set in the item's inintialisation data. For a Series 3 application it must not be set for more than one item in the dialog box DLGBOX_ITEM_APPL_CAT this flag should be set for any dialog item whose class definition is not in the HWIM category file. This flag may only be set in the item's initialisation data DLGBOX_ITEM_CENTRE this flag indicates that the corresponding item is to be centred in the dialog box. This flag is normally only set in the item's initialisation data DLGBOX_ITEM_NEEDS PACK this flag indicates that, on initialisation of the dialog box, a pack selector control is to be added as the item immediately following this one. This flag may only be set in the item's initialisation data, and must be set for FNSELWIN or FNEDIT component controls DLGBOX_ITEM_LOCKED an item for which this flag is set is visible and can take focus, but its value may not be changed. This flag may be set or cleared by the dl_item_lock method HWIM REFERENCE a SSFSSFSSSSSSSSSFSSSSeeeSSeeSeeSSSSSFSMSSSSSSFFFFFeeeee DLGBOX_ITEM_DIMMED if this flag is set, the item is 'dimmed, that is, its control is made invisible. This flag may be set or cleared by the d1_item_dim method DLGBOX_ITEM_DEAD an item for which this flag is set may never take focus and may never be modified. This flag may only be set in the item's initialisation data DLGBOX_ITEM_CAN_DEFER_X an item for which this flag is set can, on losing focus, defer its self- check. A deferred check is automatically registered by the setting of the DLGBOx_ITEM_x_PENDING flag, described below. Applications will normally only set the pucBox_ITEM_CAN_DEFER_X flag in an item's initialisation data, but the flag is set automatically during initialisation of FNSELWN Or FNEDIT component controls DLGBOX_ITEM_X_PENDING an item for which this flag is set must be checked before exiting the dialog. This flag is set and cleared by the system and should not be modified by application code DLGBOX_ITEM_ACLIST this flag indicates that the corresponding item has a control that is an instance of either acLIst or smacListT. This flag is set by the system and should not be present in any dialog resource, nor should it be modified by application code DLGBOX methods In addition to optionally providing replacements for the pererred methods: di_changed dl_focus di_launch_sub dal_item_new applications are, in general, not expected to subclass methods other than: dal_dyn_init dl_key dil_ing minsize dl_set_size Occasionally a dialog box may additionally need to subclass one or more of: dl_item_add dl_dimmed_message wn_sense_help Consistency checks A dialog box control may need to perform a consistency check on its content, a typical case being a numeric control whose value must remain within prescribed limits. In simple cases a dialog may check the consistency of its data in its d1_key method. However, in many cases it is either not feasible or inappropriate to check the value at each keypress that modifies the value. For example, a numeric edit box whose value is constrained to lie between 10 and 50 may transiently contain the ‘illegal’ text "1" while the number "18" is being typed in. The piesox class provides a mechanism for checking the validity of the content of its controls, triggered either when focus is transferred to one of its controls, or when the dialog is being terminated by any means other than by pressing Esc. Since a control's validity may, for example, depend on the values of one or more of the other controls, the check on change of focus may be deferred until the dialog termination, when the final values of all controls are known. Such items are indicated by setting the DLGBOX_ITEM_CAN_DEFER_X flag in the flags field of the corresponding puGBox_ITEM struct. The check on an item is always deemed to succeed if the item is locked or dimmed, or if the check is deferred. Otherwise the control is sent an L¢_sELF_CHECK message (see the description of this method for the LopcEr class, described in the Windows chapter). This message returns a value that indicates whether or not the content has changed as well as whether the check failed or succeeded. 7-10 7 DIALOG BOXES ——_— SS IAL OG BOXES Regardless of the success or failure reported by the 1g_self_check method, if the return value indicates that the value has changed, digbox . changed is set to TRUE and, provided the flags field of the relevant DLGBOX_ITEM struct contains DLGBOX_ITEM_NOTIFY_CHANGED, the dialog box is sent a DL_ CHANGED message. On any failure the checking stops and focus is set to the item that failed its check. This may prevent the user from moving to another item in the dialog or from exiting the dialog (except by pressing Esc to cancel the dialog) until the item is modified so that it passes the check. DLINT — eee Initialise INT dl_init (HD_DLGBOX_RSC *head, VOID *rbuf) ; Initialise a dialog box from an item in a resource file. This method is called from the wsERV ws_do_dial method to create and initialise the component controls (before calls to the dl_dyn_init, and dl_set_size methods). The method performs the following actions: ¢ copies the value of rbuf, which points to a user-supplied 'result' buffer, into algbox.rbuf, and copies head->flags into digbox. flags ¢ sets win. flags tO PR_BWIN_CUSHION oRred with PR_BWIN_CORNER_4 and, if dlgbox. flags does not contain DLGBOX_NO_SHADOW, ORS PR_BWIN_SHADOW_2 into win. flags e if head->£1lags contains DLGBOx_NO_DDP, ORS PR_WIN_NO_ppp into win. flags, otherwise sets the magic static DatDialogptr to the handle of the dialog box ¢ — sends itself a wi_connecT message, with a parent pointer of nuuz to create a top-level window, and with a zero flags field parameter so that the window is initially of indeterminate size and position e ifhead->title does not contain a null string, creates and initialises an instance of TEXTWIN containing this text, with centred alignment. This is made the first, unprompted, item in the dialog box: its handle is written to the hand element of the dialog's first pL¢Box_1TEM struct the £1ags element of this struct is set to DLGBOx_ITEM_DEAD|DLGBOX_ITEM_CENTRE the prompt element of this struct is left nu the title is set be underlined Algbox.count Is set to 1 On the Workabout, the initialisation of this instance of textwin is preceded by setting the PR_WIN_IS_DLCTRL flag in the instance's win. flags. This allows the text window to determine whether it needs to draw itself using the smaller font. e the byte following the zero terminator of any string in head->title is read to determine the number of items in any following list of items to be included in the dialog (this byte is generated by the resource compiler). The specified items are added to the dialog box, in order, with a sequence of pL_ITEM_ADD messages Any failure to add an item results in p_ leave being called. The method returns zero to indicate that no failure has occurred. It is suitable for calling under the protection of p_enter. This method is not intended to be replaced. DESTROY __ _ | Destroy VOID destroy (VOID) ; Destroy the dialog box and its component items. The method first sends pEstroy messages to each of the prompts and controls whose handles are stored in the dialog box's array of pLGBox_ITEM structs. Further action depends on how the dialog box was started up: e if the start-up of the dialog by the wseRv ws_do_dial method completed without error (this is indicated by the dialogs win. f1ags containing PR_WIN_INITIALISED) the dialog box will have 7-11 HWIM REFERENCE ee been added to the wserv. dial list. In such a case w_ws is sent a WS_REMOVE_DIAL message, passing the dialog's handle e the DatDialogptr magic static may contain the dialog's handle. If this is so, the wserv. dial list is searched for the foremost item that does not have pR_wIN_No_ppp set in its win. flags and DatDialogPtr is set to contain this item's handle, or nuxz if no such item is found ¢ if the dialog was successfully started by ws_do_dial and does not have pLGBox_No_WArT set in digbox . flags, aN AM_START message was sent to w_am, so the destroy method sends w_am an AM_STOP message In all cases, before the optional sending of the am_stop message, the method supersends the pEsTRoy message. This method is not intended to be replaced. Add an item INT di_item_add(AD_DLGBOX *par) ; Append, as the current last line of the dialog box, the control specified by the ap_pLGxox struct pointed to by par. This struct is defined in d/gbox.g as: typedef struct { WORD flags; /* initialisable DB_ITEM flags */ UBYTE class; /* class of item */ TEXT prompt [1] ; /* ZTS string */ /* followed by an IN_XXX component-specific initialisation structure */ } AD_DLGBOX; /* header for each item in resource information */ It is a programming error, with unpredictable results, to add an item if the dialog box currently contains the maximum number of items. The method first creates an instance of the class par->class, writing its handle to the hana element of the corresponding DLGBox_ITEM struct. If par->f1ags does not contain pLGBox_ITEM_aPPL_car the class is assumed to be a standard control in the HWIM category. Otherwise the method sends a pL_ITEM_NEW message to create the instance. The par->f1ags value is copied into the flags element of the corresponding DLGBOx_ITEM struct. If the string at the start of the par->prompt buffer is not a null string, an instance of rextwrn is created, writing its handle to the prompt element of the corresponding pLGBox_zTeM struct. This instance is sent a WN_INIT message, passing the address of an 1n_TExtwrn struct and the dialog box handle. The 1n_TExTwIN struct contains the prompt string and.a state value of 0 if par->£1ags contains any of DLGBOX_ITEM_DIMMED, DLGBOX_ITEM_LOCKED OF DLGBOX_ITEM_DEap, otherwise state is set to IN_TEXTWIN_BULLET. The method then sends a wn_1n1T message to the item's control, passing a pointer to any data (assumed to be a suitable initialisation structure) that follows the terminating zero of the string in the par->prompt buffer. Further parameters are the dialog box handle and the handle of the control in the previous line! (see also the Special note below). On the Workabout, the sending of the wy_1n1T message to both the control and any prompt is preceded by setting the PR_wIN_IS_picTRu flag in the corresponding object's win. f1ags. This allows the control or prompt to determine whether it needs to draw itself using the smaller font. If par->f1ags contains DLGBOX_ITEM_UNDERLINED, the item will be drawn with an underline (only one underline is allowed on the Series 3). Finally, the value of digbox.count is incremented by one. The method returns zero to indicate that no failure has occurred. It is thus suitable for calling under the protection of p_enter. !This will contain an indeterminate value when adding the first item, but the wn_init methods of most controls ignore this value. Those that make use of this parameter are never used as the first item in the dialog box. 7-12 7 DIALOG BOXES _-———————-———————— SS TALLOG BOXES This method may be either used or replaced by application writers. It is called by system code, once for each component control, from the wsERv ws_do_dial method after the dialog resource has been loaded from the resource file. An application may call this method to add one or more items, depending on run-time circumstances, although the ai_item_append method - which also loads the item's resource - will usually be more appropriate. All such uses must be before the pL_seT_s1zE message is processed at the picsox level. Application code will typically send a pi_1T=m_app message from the a1_dyn_init method. Since the method is called by system code once for each item that appears in the dialog resource, it may be replaced to omit one or more items, or to add items at positions other than the end of the dialog, depending on run-time circumstances. The following example is a replacement of the a1_item_add method that optionally omits the third item (with index number 2) from a dialog. It assumes that the mvpze subclass of pucpox adds two items of property: mydlg.needed, which is True if the item is to be included, and mydig.omittea which is initially FALSE and is set to True if the item is not included in the dialog (an alternative would be to store this information in a result buffer, pointed to by digbox. rbuf). METHOD VOID mydlg_dl_item_add(PR_MYDLG *self, AD _DLGBOX *par) Lf ((sel£->dlgbox.count==2) &&(!self->mydlg.needed) &&(!self->mydlg.omitted) ) self->mydlg.omitted=TRUE; else p_supersend3 (self,O_DL_ITEM_ADD, par) ; Special note If par->flags contains DLGBOX_ITEM_NEEDS_PACK (normally only if adding a control of either the rneprtT or the rNsELwn class) then this method will result in the addition of two controls, thus occupying two lines in the dialog box. After the creation of the first control, but before its initialisation, the method sends a further, recursive, pL_ITEM_ADD message to create a PACKSEL control with an associated "Disk" prompt string (this prompt is read from the sys_pacx resource in the system resource file). In this case the final parameter passed in the wn_rnzT message to the first control is the handle of the following control (that is, the instance of pacxset). If par->flags contains DLGBOX_ITEM_UNDERLINED, the underline is transferred to be below the pacxsex control, so that an item and its corresponding pack selector will never be separated by an underline. em by resource ID VOID dl_item_append (INT rid) ; Append the item specified by the resource item with resource ID ria. The resource item is loaded into a temporarily allocated buffer, the loaded data being assumed to be an AD_DLGBOx struct. The control and any associated prompt are appended to the dialog box, as described for the dl_item_add method. The temporarily allocated buffer is freed before the method returns. The method must not be used to add an item following any action list item. An application may call this method to add one or more items at the bottom of a dialog, depending on run- time circumstances, for example, to generate two different, but similar, dialogs from a common dialog box resource. All such uses must be before the pn_seT_szzE message is processed at the pLGpox level. A call from application code to the a1_item_append method will typically be from the dl_dyn_init method. This method is not intended to be replaced. DL_ITEM_REPLACE VOID dl_item_replace (INT index, INT rid); place an existing item Replace existing item number index by the item specified by the resource item with resource ID ria. The existing control and any corresponding prompt are sent pesTRoy messages. The resource item is then loaded into a temporarily allocated buffer, the loaded data being assumed to be an AD_pLGBox struct. The replacement item and any corresponding prompt are created and initialised as described for the HWIM REFERENCE ee SSSSSSSSeSSSSSSSSeFeFeSSSSSSSSSSSSSSSSSSSSSSSSSSSSFSEeee dl_item_add method, their handles overwriting those that they replace. The method does not increment digbox.count. The temporarily allocated buffer is freed before the method returns. This method must not be used with a resource which has the pL¢Box_ITEM_NEEDS_Pack flag set in its flags data. An application may call this method to replace one or more items, depending on run-time circumstances, for example, to generate two different, but similar, dialogs from a common dialog box resource. All such uses must be before the pu_szT_s1zE message is processed at the picxox level. A call from application code to the dl_item_replace method will typically be from the a1_dyn_init method. This method is not intended to be replaced. "Set item by index VOID wn_set (INT index, VOID *par); Set one or more data elements in the property of the control associated with the dialog box item with index number index, by sending a wn_sET message to the control. The parameter par is assumed to be a pointer to a struct that specifies the data to be set. The type of struct that is expected depends on the class of the control that is being set; the various structs are described in the following Dialog Controls chapter. This method will normally be used (rather than replaced) by application writers. See also the various hD1gSet Xxx utility functions. VOID dl_set_prompt (INT index, SE_TEXTWIN *par) ; Send a wn_sET message to the prompt associated with item number index, passing the parameter par, assumed to be a pointer to an SE_TEXTWIN struct. This method replaces an existing prompt; it can not be used to add a prompt to an item that does not already possess a prompt. Thus the method may not be used on an item for which no prompt was defined in the item's resource. It is perfectly permissible for a replacement prompt to be longer than the prompt text that was supplied in the dialog's resource. However, such a replacement may alter the width needed to display the dialog. If this is the case, the replacement should not be made after the wsERV ws_do_dial method has sent the dialog a DL_SET_SIZE message. This method is not intended to be replaced. by index VOID wn_sense (INT index, VOID *par); Sense the property of the control associated with the dialog box item with index number index, by sending a WN_SENSE message to the control. The parameter par is assumed to be a pointer to a struct that matches the data to be sensed. The type of struct that is expected depends on the class of the control that is being sensed; the various structs are described in the following Dialog Controls chapter. This method will normally be used (rather than replaced) by application writers. See also the various hD1lgSensexxx utility functions. 7 DIALOG BOXES Handle a keypress INT wn_key (INT keycode, INT modifiers) ; The description of this method is included for interest only. Applications should neither replace this method nor call it explicitly. Handle a keypress, directing it, if necessary, to a component control. This message is sent by the application's instance of wserv. Any non-zero return value from the wn_key method will terminate the dialog, causing the dialog box to receive a DESTROY message. If digbox.absorb is TRUE, all keys are directed to the current control, as described later. Otherwise keys are processed as follows. If the dialog contains an action list (which must always be the last item) the action list is sent a wn_KEY message, passing a key code of p_toupper (keycode). This message returns either a negative value if the keypress does not match any of the action buttons, or the index number of the button that matched the keypress (the leftmost button has index number zero). If there was no match and digbox. f1ags does not contain DLGBOX_NOTIFY_ALL ACT , processing continues with the testing for specific keys, as described later. Otherwise (that is, either the keypress matches an action button, or dlgbox. flags contains DLGBOX_NOTIFY_ALL_AcT) a forced consistency check is applied to all controls. If any control fails its check the method terminates, returning wN_KEy_No_CHANGE (0) so that the dialog box is not exited. If the consistency check succeeeds, the method sends a pL_KeY message, passing dlgbox. current, p_toupper (keycode) and the key-matching value returned by the wn_xey message that was sent to the action list. The method terminates, returning the value returned by the pL_Key message. Before returning, and provided that: e the return value is non-zero (that is, the dialog is terminating) @ dlgbox.rbuf is not NULL ® dalgbox. flags does not contain pLGBOX_RBUF_FILLED a worn of data is written to *dlgbox.rbuf. If digbox. flags contains DLGBOX_REPORT_ACT_HoRrz this data is the index number of the action button that was selected. Otherwise the value written to *dlgbox. rbuf is the uppercased key code. Provided the keypress has not been processed by an action list, the following specific keypress codes are tested: W_KEY_ RETURN this key is ignored if the dialog contains an action list (a1gbox. flags contains DLGBOX_ACTION_LIST OF DLGBOX_SMALL_ACTION_ LIST) in which case the method terminates immediately, returning wn_KEY_No_CHANGE. Otherwise a forced consistency check is applied to all controls. If any control fails its check the method terminates, returning wN_KEY_NO_CHANGE. If dlgbox. flags does not contain DLGBOx_NOTIFY_ENTER the method just retums WN_KEY_CHANGED, otherwise it returns the result from sending a pL_KEY message. In either case, provided: e — the return value is non-zero (that is, the dialog is terminating) e § dlgbox.rbuf is not NULL @ dlgbox. flags does not contain DLGBOX_RBUF_FILLED the value of dlgbox. current is written to the worp pointed to by digbox. rbuf. W_KEY_ESCAPE provided dlgbox. rbuf is not NULL and dlgbox. flags does not contain DLGBOX_RBUF_FILLED write, to the worD pointed to by digbox. rbuf, either W_KEY_EScAPE or, if dlgbox.flags contains DLGBOX_REPORT_ACT HORIZ, a value of -1 HWIM REFERENCE Ss SSS W_KEY_UP move up 'one' item in the dialog. The current item becomes the first earlier item whose flags do not contain pLcBox_ITEM_DEAD. A DL_TAKE_FOcUS message is sent, passing the new current item's index number. Moving up from the first item in the dialog positions to the last item W_KEY_DOWN move down ‘one’ item in the dialog. The current item becomes the first following item whose flags do not contain pLGBox_ITEM_DEAD. A DL_TAKE_FOCUS message is sent, passing the new current item's index number. Moving down from the last item in the dialog positions to the first item W_KEY_PAGE_UP move to the 'first’ item in the dialog. The current item becomes the first item whose flags do not contain pLGBox_ITEM_DEAD. A DL_TAKE FOCUS message is sent, passing the new current item's index number. W_KEY_PAGE_DOWN move to the ‘last’ item in the dialog. The current item becomes the last item whose flags do not contain pL¢Box_ITEM_DEAD. A DL_TAKE_FOcUS message is sent, passing the new current item's index number. If dlgbox. focus is FALSE, any other keypress is ignored and the method returns wN_KEY_NO_CHANGE. Otherwise the keypress is directed to the dialog's current component control, as explained in the following paragraphs. All incoming keys are processed in this way if dlgbox. absorb is TRUE. If the flags field of the current item contains pLGBOx_ITEM_DIMMED Or DLGBOX_ITEM_LOCKED, a DL_DIMMED message is sent, to inform the user that the item can not be modified, and the method then returns WN_KEY_NO_CHANGE. Otherwise the current control is sent a wn_KEy message, and further processing depends on the return value: e if the return value is wN_KEY_ABSORB_ON, dlgbox. absorb is set TRUE, so that all subsequent keys will be directed to the current control e if the return value is anything other than wi_key_No_CHANGE and digbox. absorb is TRUE, digbox. absorb is set FALSE, so that subsequent keys may be processed by the dialog box as described above e if the return value is ww_kEyY_CHANGED and the current item's flags contain DLGBOX_ITEM_NOTIFY_CHANGED, the dialog box is sent a DL_ CHANGED message In all these cases the dialog wn_key method returns wn_KEY_NO_CHANGE. die key input INT dl_key(INT index, INT keycode, INT actbut); Process a keypress that may potentially exit the dialog. This method is supplied so that it may be replaced to perform application-specific processing of such keypresses. This message is sent by the dialog box wn_key method in the following circumstances: e when dlgbox. flags contains DLGBOx_NOTIFY_ENTER and the dialog is about to terminate after receiving a W_KEY_RETURN. The value of keycode is W_KEY RETURN and actbut is -] e when dlgbox. flags contains DLGBOxX_NOTIFY_ESCAPE and the dialog is about to terminate after receiving a w_KEY_ESCAPE. The value of keycode is W_KEY_ ESCAPE and actbut is -] e the dialog is about to terminate after receiving a key that matches a button in an action list. The value of keycode is the uppercased key code that was passed to the action list's wn_key method and actbut is the index (0 for the leftmost button) of the matching button e following any non-matching keypress received by an action list, provided algbox. flags contains DLGBOX_NOTIFY_ALL_act. The value of keycode is the uppercased key code that was passed to the action list's wn_key method and actbut is -1 In all cases index contains the current value of dlgbox.current. The method should return w_xEy_No_CHANGE to prevent termination of the dialog, or wN_KEY_CHANGED to confirm termination (which causes the dialog box to be sent a DesTRoy message). Before returning 7-16 7 DIALOG BOXES WN_KEY_CHANGED the method is responsible for ensuring that any relevant dialog box state is either saved or returned to the initiator of the dialog box. Data may conveniently be returned to the initiator via a user- supplied buffer pointed to by digbox. rbuf. The supplied method simply returns wn_KEY_CHANGED. DL_TAKE FOCUS _ Move focus to specified item INT di_take_focus (INT index) ; Attempt to change the focus to item number index. A deferred consistency check is applied to the current item. If the check fails the focus change is not made. Otherwise, provided the specified item is not already the one with focus, the focus is switched to the specified item: ¢ any prompt of the item that is losing focus is sent a wN_EMPHASISE, FALSE message © provided its flags do not contain pLGBOx_ITEM_DIMMED Or DLGBOX_ITEM_LOCKED, the control of the item that is losing focus is also sent a wN_EMPHASISE, FALSE Message e if the flags of the item that is losing focus contain pLGBox_ITEM_NoTIFY_Focus, the dialog box is sent a DL_Focus message to inform it that the item is losing focus © a TRUE value is written to dlgbox. focus and dlgbox.current is set to index, so that it now refers to the item that is gaining focus ¢ any prompt of the item that is gaining focus is sent a WN_EMPHASISE, TRUE message © provided the item that is gaining does not have the either of the flags pLGBox_ITEM_DIMMED or DLGBOX_ITEM_LOCKED set, the control of this item is also sent a WN_EMPHASISE, TRUE Message e if the item that is gaining focus has the flag pLcBox_IT=M_NoT1FY_Focus set, the dialog box is sent a DL_Focus message to inform it that the new item is gaining focus The method returns rause if a failed consistency check prevents a change of focus being made. In all other circumstances (including the case where the specified item is already the one with focus) the method returms TRUE. This method is not intended to be replaced. It is not suitable for being called from the a1_ayn_init method. If an application wishes to set the focus on initialisation, it should do so from a replaced dl_set_size method. It may be called from any other method (such as 41_key) once the dialog has been made visible. dialog VOID wn_draw (VOID) ; Draw the dialog box and its contents. The method first draws the dialog box border. It then sends a wn_pRaw message to every prompt, and to every control that does not have pLGBox_1ITEM_DIMMED set in the flags field of the corresponding DLGBOx_ITEM struct. If the flags field of a control also has pLGBOXx_ITEM_UNDERLINED bit set, a horizontal line is drawn below the item, extending across the full width of the area inside the window's border. On the Series 3, only one underline can be present in a dialog box and its vertical position is specified by dilgbox underline. If this value is non-zero, a horizontal line is drawn at the specified position, extending across the full width of the area inside the window's border. On the Workabour, all text is drawn in the small (8 point Roman) font and line heights are calculated accordingly. HWIM REFERENCE Set size of dialog INT dl_set_size(VOID) ; Set the height and width of the dialog to the values required to display all the component items, and set the position all components within the dialog box. An Lc_sENsE_wIDTH message is sent to each component to determine the width needed to display it. A DL_SET_SIZE message is sent from the WSERV ws_do_diai method, after that method has sent the dialog box DL_INIT and DL_DyN_INIT messages. If digbox. flags contains DLGBOX_APPEND_UNITS_TITLE the SYS_CENTIMETRES OF SYS_INCHES resource (depending on whether w_ws->wserv. flags contains PR_WSERV_METRIC) is loaded from the system resource file and appended to the dialog title. This will call p_panic if the dialog has no title. Some dialog items (such as an instance of Textwrn used as a title) are composed of a single control component, whereas others are formed from two components - a prompt and a control. The width of each component is found by sending it an Lc_sENSE_wIDTH message. The dialog box width is set to contain the widest item from each of these two groups, subject to any explicit minimum widths set by sending each control a DL_INQ_MINSIZE message. The width for single-component items is the larger of the width written to *poverallwidth by dl_ing_minsize (zero by default) and the single-component item of greatest width. The width for two-component items is the width of the widest prompt plus the width of the widest control (respectively not less than any values written to ppromptwWidth and *pcontrolwidth by dl_ing minsize) plus a minimum gutter width separation between them. Provided at least one item is not marked with the DLGBOX_ITEM_DEAD flag, the prompt width allows space for the prompt to include a leading bullet to show that an item can be modified. The width of the dialog box is the greater of these two widths plus an allowance for the dialog box borders and a small gap at either side. If this is wider than the screen, an attempt is made to clip the right hand side of the control components. On all machines except the Workabout, if such clipping means that one or more controls will be entirely invisible the method calls p_leave (E_GEN_TOOWIDE). The height of the dialog box is just the sum of the heights of the controls, plus the top and bottom borders and a small additional amount for each item that is underlined. On all machines except the Workabout, if the total exceeds the screen height the method calls p_leave (E_GEN_ToomaNy) . In most cases there will always be room for the maximum number of items, but some items (for example, instances of ACLIST) take up additional height. The method then positions each prompt and control by sending it an Lc_seT_1D_Pos message. Unless marked as centred, prompts are positioned at the left side, aligned at their left edges, and controls occupy a right hand region, again aligned at their left edges. The prompt and control regions are aligned with the edges of the widest centred control, subject to their being separated by a small gap. Finally, provided that not all items are marked with the p.cBox_1TEM_pEap flag, the method sets the focus to the first such unmarked item - algbox. focus is set TRUE, dlgbox. current is set to the item and a WN_EMPHASISE, TRUE message is sent to the item's prompt, if it exists. The control itself is not sent a WN_EMPHASISE message as it will receive one later, when the dialog box itself receives a wN_EMPHASISE message. The method returns zero to indicate that p_1eave has not been called. It is suitable for calling under the protection of p_enter. This method may be replaced, but should not be called explicitly from application code. It offers the last opportunity to modify the dialog box content before it becomes visible. A common use is to modify the content after the size of the dialog box has been calculated. Any replacement method should only add further processing, before and/or after supersending the DL_SET_SIZE message. 7 DIALOG BOXES _ Dim an item VOID dl_item_dim(INT index, UINT flag) ; Undim item number index if flag is FALSE, otherwise dim it. When an item is dimmed its control is not displayed and its prompt does not display a bullet point. It is harmless to send a dimmed item a DL_ITEM_DIM, TRUE Message, or an undimmed item a DL_ITEM_DIM, FALSE message. Dimming the item clears the pLGBox_ITEM_DIMmep flag in item number index and sends any prompt (an instance of TEXTWIN) a WN_SET message to Clear its PR_TEXTWIN_BULLET flag. The control is sent a WN_VISIBLE, FALSE message. Undimming the item reverses these flag changes and sends the control a wN_vIsIBLE, TRUE message. In either case the ww_v1sIBLE message is sent only if the dialog box win. flags contains PR_WIN_INITIALISED. This prevents any control from drawing itself during the initialisation of the dialog box, before the whole dialog box can be made visible. If item number index has the pLGBox_ITEM_NEEDS_PAcK flag set, the dimming/undimming operation is also performed on the following pacxseE item. This method is not intended to be replaced. Lock an ite VOID di_item_lock(INT index, UINT flag); Unlock item number index if £1ag is FaLse, otherwise lock it. When an item is locked its prompt does not display a bullet point but, unlike a dimmed item, its control remains visible. It is harmless to send a locked item a DL_ITEM_LOCK, TRUE message, or an unlocked item a DL_ITEM_LOCK, FALSE message. Locking the item clears the pL¢Box_ITEM_LocKEp flag in the item's flags field and sends any prompt (an instance of TEXTWIN) a WN_SET message to clear its PR_TEXTWIN_BULLET flag. Unlocking the item reverses these flag changes. If item number index has the pLeBox_ITEM_NEEDS_Pacx flag set, the locking/unlocking operation is also performed on the following packse item. This method is not intended to be replaced. ed’ message _ Display ‘d VOID dl_dimmed_message (VOID) ; Display a status message, using hInfoPrint, indicating that a locked or dimmed item can not be modified. This method will be called by system code when the uset attempts to modify an item that is either dimmed or locked. The resource ID passed to hinfoprint is digbox.dimrid or, if this is zero, either of the system resource ID's SYS_DIMMED_MSG OF SYS_LOCKED_mSG depending on whether or not the item's flags contain DLGBOX_ITEM_DIMMED (if this flag is not present the item is assumed to be locked, without testing for the presence of DLGBOX_ITEM_LOCKED). This method can be replaced, for example, to display a context-sensitive message. DL_HANDLE ~ INT dl_handle_to_index(PR_LODGER *handle) ; Sense item index Return the index number for the item whose control handle is handle. Returns -1 if handle does not match any dialog item. This method is not intended to be replaced. HWIM REFERENCE Sense item handle PR_LODGER *dl_index_to_handle (INT index) ; Return the handle of the control in item number index. It is a programming error to call this method with a value of index that does not correspond to an existing dialog box item. This method is not intended to be replaced. ee ee VOID dl_set_item_flags(PR_LODGER *lodger, UINT flags); or the passed f1ags into the flags field of the dialog box item corresponding to the control with handle lodger. This method is intended for use by a component control to set some aspect of the dialog's state. It is used, for example, by the rnsELwn and acuist dialog control classes. The DLGBOX_ITEM_LOCKED and DLGBOX_ITEM_DIMMED flags should be set (or cleared) by use of the appropriate specific method. Note that, apart from these two flags, no means is provided for clearing any of an item's flags. This method is not intended to be replaced. INT wn_sense_help(PR_DLGBOX *self) ; The action depends on the value of digbox.heipria as follows: ¢ return digbox.helprid, if it is greater than zero. ¢ if dlgbox.helprid is zero, return the result of supersending the w_SENSE_HELP message. This is handled by the win superclass and returns either w_ws->wserv.help_index_id or, if this is zero, the (negative) system resource ID -sys_HELP_ON_HELP. © if dlgbox.helprid is -1, call p_leave (RUN_ACTIVE_USED). This is used by the ERRORDLG class, to disable the display of help information when an error is being reported (so that, for example, multiple nested out of memory errors can not be generated by requesting Help while an out of memory error report is visible). ox emphasis VOID wn_emphasise(UINT flag) ; Emphasise the dialog box if flag is True, otherwise de-emphasise it. First supersends the wN_EMPHASISE message to set the border emphasis. If an item has the keyboard focus (dlgbox. focus is TRUE) and if the current item is not dimmed or locked, send a WN_EMPHASISE message to the control of this item. VOID di_ing minsize (INT *pOverallWidth, INT *pPromptWidth, INT *pControlwidth) ; Inform the caller of the minimum widths for whole line items (*poverallwidth) and for the prompt (*pPromptwidth) and control (*pcontrolwidth) segments of two-part items. The method is called from the dl_set_size method and, on entry, all three parameters point to locations containing zero. The supplied method does nothing. A subclass may replace this method to write application-specific minimum values to any or all of *pOverallWidth, *pPromptWidth Or *pControlwidth. On all machines except the Workabout, writing 7-20 7 DIALOG BOXES values that force a dialog to exceed the width of the screen will cause d1_set_size to call p_leave (E_GEN_TOOWIDE) . DL_DYN_INIT VoID dl_dyn_init (VOID) ; alisation A DL_DYN_INIT message is sent from the WsERV ws_do_dial method, after that method has sent the dialog box a pL_InitT message, but before the sending of apL_sET_s1z= message. The supplied method does nothing. It is supplied so that it may be replaced to perform application-specific initialisation of the dialog box after all its items have been added, but before its size is calculated and it is made visible. The most common use for this method is to set the initial value of one or more controls, depending on the current state of the application, but other actions may include dimming, locking, adding or replacing one or more dialog items. Initialisation data may conveniently be passed by means of a buffer pointed to by digbox. rbuf. Deferred DLGBOX methods There is no general requirement to subclass pLGBox to provide any of these pzrsrred methods. Each method need be supplied only if the conditions are satisfied for the corresponding message to be received. HANGED VOID dl_changed (INT index) ; éd message Notify the dialog box that the item with index number index has changed in some way. This message will only be received for values of index for which the flags field of the corresponding item contains DLGBOX_ITEM_NOTIFY_CHANGED. The method need not be supplied for any dialog in which no items are so marked. A typical use would be to modify an item - say the allowed range of a numeric edit box - as a result of changes made by the user to some other item. ged message VOID dl_focus (WORD index, WORD flag) ; Notify the dialog box that the item with index number index has gained or lost focus. The value of flag is TRUE if the item has gained focus, or rause if the item has lost focus. This message will only be received for values of index for which the flags field of the corresponding item contains DLGBOX_ITEM_NOTIFy_Focus. The method need not be supplied for any dialog in which no items are so marked. A common use is to detect when an edit box loses focus. This may be an appropriate time to sense the value and make any necessary modifications to other dialog box items. alog if required VOID dl_launch_sub(INT index) ; This message is sent by the window server object if, on return from a wn_key message sent to the dialog, the value of w_ws->wserv.subdial is non-zero. The value of index is the item number of the item that is launching the subdialog. The method need not be supplied for any dialog that does not write a non-zero value to w_ws->wserv.subdial. For further information, see the description of the use of subdialogs in the Dialogs chapter of the Object Oriented Programming Guide. HWIM REFERENCE Create non-system dialog item VOID *dl_item_new(AD DLGBOX *par) ; Create an instance of the application-specific dialog item with class number par->class. Assuming that the application category file is myapp.cat, the code of a d1_item_new method for a dialog box that has application-specific items defined only in this category would be: £_new(CAT_MYAPP_MYAPP, par->class) ; If, exceptionally, a dialog box contains two or more application-specific items, with classes defined in different categories, the method will need additional logic to create the item from the appropriate category. This message will only be received if the flags field associated with one or more of the items in a dialog box contains pLGBox_ITEM_APPL_car, indicating that the item does not have its class definition in the HWIM category. The method need not be supplied for any dialog whose items are not so marked. ATSDIAL flags next item count id rbuf current dimrid underline helprid absorb changed destrey wh—draw di_item_replace wn_key dl_item_append wn_emphasise dl_init wn_sense_help d1_dimmed_message wn_set di—itemadd wn_sense dl_set_size wn_draw di_ing_minsize di_item_lock di—dyn—inie dl_item_dim di—key dl_set_item_flags dl_set_prompt dl_changed di_take_focus di_focus dl_handle_to_index dl_launch_sub dl_index_to_handle dl_item_new wn_calc_position |wn—emphasise wn_position wn_redraw wn-senserheip wn_visible The atsp1au class is not present on the Series 3. The arspzax class implements ATS dialogs, that is, dialogs that are presented in response to an inter- process message from another, controlling, process. The ATS dialog mechanism is intended to be used only via the mechanisms supplied within the HWIM library (see, for example, the description of the ws_do_remote_dial method in the WSERV Class chapter. An application should not subclass arsDIAL. An ATS dialog may be dependent on two items of data that are copied from the controlling process. The first of these must be the resource for the dialog itself (considered to be an Hp_DLGBox_rsc struct). The second may be one of: e achoice list resource ® an action list resource e editable text for an edit box. 7 DIALOG BOXES The ATS dialog may therefore contain, in addition to controls of other types, not more than one control selected from these three types. None of the other controls may be of any type that requires additional data (for example, from another resource file item). See the Series 3a Automatic Test System chapter of the Object Oriented Programming Guide for a description of the use of ATS. Class definition Defined in sub-category file xd/gbox.cl (generated header file xdlgbox.g). CLASS atsdial dlgbox { REPLACE destroy REPLACE dl_item_add REPLACE dl_dyn_init REPLACE dl_key PROPERTY { VOID *owner; VOID *main; VOID *buts; PR_WIN *filter; WORD filmethod; WORD chlist; WORD pid; WORD ret; UWORD locked; } Property atsdial.owner If not nout, the handle of an instance of the arssv class (see the XADD Reference manual). atsdial.main A pointer to an allocated memory cell containing the main resource data for the dialog. atsdial buts If not NULL, a pointer to an allocated memory cell containing resource data for the dialog's one control that needs such data. The control may be a choice list, an action list or an edit box. atsdial.filter A preserved copy of the application's w_ws->wserv. filter property. atsdial.filmethod A preserved copy of the application's w_ws->wserv. £ilmethod property. atsdial.chlist Either zero or one plus the index of the control that makes use of the second item of data copied over from the controlling process. If positive, the control is a choice list, if negative the control is an edit box. atsdial.pid The process ID of the process that launched the ATS dialog. atsdial.ret A terminating value that can be sent in an sv_FREE message to atsdial.owner. atsdial.locked Normally revs, indicating that the ATS dialog code has incremented the application's patLocked magic static. HWIM REFERENCE [SEE Sa eae \ ATSDIAL methods DESTROY : _._ : Destroy VOID destroy (VOID) ; Destroy the ATS dialog and its resources. The action is as follows: e Frees the allocated memory cell pointed to by atsdial.main and, if it exists, the allocated memory pointed to by atsdial .buts. e Restores the values of w_ws->wserv. filter and w_ws->wserv. filmethod from the preserved values in atsdial.filter and atsdial.£ilmethod. e Ifatsdial.owner is not NULL, sends it an sv_FREE message, passing the value of atsdial. ret. e Ifatsdial.locked is non-zero, decrements patLocked. e Supersends the pEstroy message. VOID dl_item_add(AD_DLGBOX *p); Mark the dialog as being started by the ATS mechanism by oring the flag wIn_FROM_ATs into win. flags (for use by any AcLIST or cHLIST component) and then supersend the DL_TTEM_ADD message. INT dl_dyn_init(ATS_MESS *pm, VOID *owner) ; Copies the value of owner into atsdial.owner, and also copies w_ws->wserv. filter and w_ws->wserv.filmethod into atsdial.filter and atsdial.filmethod. If there is a keyboard filter that is non-permanent (atsdial . £ilmethod is not negative), the method then calls p_leave(E_GEN_IN_usE). An application with a temporary keyboard filter is deemed not to be ina suitable state to handle an ATS dialog. The process ID of the controlling process is copied from pm- >mess.pid into atsdial .pia, and the application's filter is cleared (w_ws->wserv. filter and w_ws->wserv.£ilmethod are cleared). The value of atsdial.ret is set to -1, the default value that will indicate termination of the dialog by pressing Esc. If pm->u.d.butslen is negative, this is taken to mean that pm->u.buts contains a pointer to initial text for an edit box. The value of pm->u.d.butslen is copied into atsdial.chlist, for later use, and pm->u.butsien is set to 2 (the length of a pointer). Memory is allocated to contain the resources specified by pm->u.d.main (the main dialog resource) and pm-u.d.buts (optional data for one of the dialog's controls) The data is copied from the controlling process and pointers to the two allocated cells are written to atsdial.main and atsdial.buts. The flags pLGBox_No_wart and DLGBox_No_ppp are ored into the dialog box flags in the main dialog resource and the dialog box sends itself a pL_1n1T message. If atsdial.chlist is negative, the dialog's edit box is seeded with up to ars_MAX_EDITOR_LEN bytes of text read over from the controlling process, at an offset that is specified by the two-byte cell pointed to by atsdial.buts. The dialog then sends itself a p._seT_s1z= message and calls hinitvis. The flag PR_WIN_INITIALISED is ored into win. flags, the dialog sends w_ws a wS_ADD DIAL message, DatLocked is incremented and atsdial.locked is set TRUE. The method returns zero to indicate that p_1eave has not been called. The method is thus suitable for being called under the protection of p_enter. 7 DIALOG BOXES SSE ITALOG BOKES Handle key input INT dl_key (VOID) ; Handle the Enter key input that exits the dialog. If atsdial .chlist is positive (the dialog is presenting a choice list) write the index of the currently selected choice list item to atsdial.ret and retum WN_KEY_CHANGED. If atsdial.chlist is negative (the dialog is presenting an edit box) copy the text back to the controlling process, overwriting the string used to intialise the edit box, write zero to atsdial. ret and return WN_KEY_CHANGED. If atsdial.chlist is zero, just return WN_KEY_CHANGED. CHAPTER 8 LABELS, BUTTONS AND CHOICE LISTS This chapter describes three of the basic components of a dialog box. The TExtwrn class, as its name suggests, is used to display static text, including any dialog box title and optional prompt messages for other controls. Dialog box buttons, used to exit the dialog box or to initiate other actions, are implemented by either the acList or smacuztsvt ‘action list' classes. The cuurst class provides the means of selecting one option from a number of alternatives. It is unlikely that an application will need to subclass any of the classes described in this chapter and it is expected that the vast majority of applications will simply use them as standard dialog components. In consequence applications will generally not send explicit messages to instances of these classes and it is therefore not necessary to understand the class methods in any great depth. Precursors Familiarity with the following topics will aid the understanding of this chapter: e the wr and Lopcer classes, described in the Windows chapter ¢ — the description of the piczox class in the Dialog Boxes chapter, particularly the wn_key method which may sent wn_KEy messages to a dialog box component and respond to the return value e for the cuurst class, the description of its LtstBox component in the List Boxes and Menus chapter Class diagram [tra ee [oT eee ce a tata! ¢ “ epflat > 7 wid ; ra nf ¢ x‘. ‘ % NS E ‘AL 5 x \ . : . er \ ee ‘ a ot me tes Pade ae Pe ee pom et ‘ 4 ie: as ? * aK. ‘i rs -s. / textwin ~ / lodger > / chlist 7s “~~ fAachlist “> é if ‘ Zz 4 i“ / ‘4 NS c SSS <+—_———_ ¥ i re \ hs ' ee ‘ ‘ woes 7 i) ort meee’ rte eee” Rae ee ‘ oo eee Nee” ea Dabs i No” a are he / smaclist > Zc ‘ ‘ pete , - a ae pore ede > vanumber > HWIM REFERENCE The TEXTWIN class flags landlord i offset width destroy ig_draw 1lg_self_check ig_set_id_pos fe wn_visible lg_sense_width wn_draw wn_emphasise wn_init wn_key wn_cale_ position wn_connect wn_dodraw wn_sense wn_set wn_position wn_redraw wn_sense_help ig_update An instance of rextw1n is used within a dialog box to display static text. In addition to displaying simple informational messages, it may be used as a prompt (or label) to a control, or as the dialog box title. Text may be specified in a dialog resource in a number of ways. For example, the system error dialog, whose resource is listed below, simply declares two rexTwin components: RESOURCE DIALOG sys_error_dialog { £lags=DLGBOX_RBUF_FILLED|DLGBOX_NO_DDP; controls= { CONTROL { class=C_TEXTWIN; £lags=DLGBOX_ITEM_CENTRE|DLGBOX_ITEM_DEAD|DLGBOX_ITEM UNDERLINED; info=TXTMESS { flags=IN_TEXTWIN_AL CENTRE; }; } ’ CONTROL { class=C_TEXTWIN; £lags=DLGBOX_ITEM_CENTRE|DLGBOX_ITEM_DEAD; info=TXTMESS { flags=IN_TEXTWIN_AL CENTRE; }; }, CONTROL { class=C_ACLIST; info=ACLIST { rid=sys_ac_continue; ); ); } where the TxrmEss resource struct and its default values are defined in Awim.h as: STRUCT TXTMESS { WORD flags=0; TEXT .str=""; } 8 LABELS, BUTTONS AND CHOICE LISTS The first of the rexrwin components sets the flag DLGBOx_ITEM_UNDERLINED so that it appears as a dialog box title. The text of both components is determined by the type of the run-time error that causes the dialog to be displayed and is supplied dynamically. A Textwin dialog title may be specified more simply by providing text for the title element, as in the following example. This example also shows how to specify a TExTwrN prompt to a control, by providing text for the prompt item of a conrrot resource. In both of these cases the Textwrn flag values are set as appropriate by system code. RESOURCE DIALOG sys_printer_model { title="Set printer"; flags=DLGBOX_NOTIFY_ENTER|DLGBOX_RBUF_FILLED; controls= } { CONTROL { prompt="Select printer"; flags=DLGBOX_ITEM_NOTIFY_CHANGED; class=C_CHLIST; info=CHLIST{}; } t CONTROL { class=C_TEXTWIN; prompt="Default font"; info=TXTMESS { flags=IN_TEXTWIN_POPOUT; by }; Class definition Defined in sub-category file textwin.cl (generated header file textwin.g). CLASS textwin lodger Text window { REPLACE wn_draw REPLACE wn_init REPLACE wn_set REPLACE wn_sense REPLACE wn_key REPLACE 1g_sense_width REPLACE wn_emphasise CONSTANTS { PR_TEXTWIN_AL LEFT PR_TEXTWIN_AL RIGHT PR_TEXTWIN_AL CENTRE PR_TEXTWIN_BOLD PR_TEXTWIN_BULLET PR_TEXTWIN_POPOUT PR_TEXTWIN_FLASHING IN_TEXTWIN_AL LEFT IN_TEXTWIN_AL_RIGHT IN_TEXTWIN_AL_CENTRE IN_TEXTWIN_BOLD IN_TEXTWIN_BULLET IN_TEXTWIN_POPOUT 0x00 0x01 0x02 0x04 0x20 0x40 0x80 PR_TEXTWIN_AL LEFT PR_TEXTWIN_AL RIGHT PR_TEXTWIN_AL_CENTRE PR_TEXTWIN_BOLD PR_TEXTWIN_BULLET PR_TEXTWIN_POPOUT HWIM REFERENCE a SE_TEXTWIN_ALIGN SE_TEXTWIN_BOLD (PR_TEXTWIN_AL_RIGHT|PR_TEXTWIN_AL CENTRE) PR_TEXTWIN_BOLD SE_TEXTWIN_TEXT 0x08 SE_TEXTWIN_BULLET } TYPES { typedef struct { PR_TEXTWIN_BULLET UWORD state; TEXT label {1} ; } IN_TEXTWIN; typedef struct { INT flags; UWORD state; Alignment, underline TEXT *buf; UWORD len; }SE_TEXTWIN; } PROPERTY 1 { PR_EPFLAT *label; UWORD state; } } label text object Alignment, underline The flag PR_TEXTWIN_FLASHING is not defined on the Series 3. Property textwin.label textwin.state TEXTWIN flags PR_TEXTWIN_AL LEFT PR_TEXTWIN_AL RIGHT PR_TEXTWIN_AL CENTRE PR_TEXTWIN_ BOLD PR_TEXTWIN BULLET PR_TEXTWIN_POPOUT PR_TEXTWIN_FLASHING either nuLL or the handle of the instance of epriat that contains the text any sensible combination of the flags listed below if set, the text is aligned left. No other pR_TEXTWIN_AL_ xxx flag should be set if set, the text is aligned right. No other pr_tExTWwINn_aL_xxx flag should be set if set, the text is centred. No other pR_TexTwIn_aL xxx flag should be set if set, the text is to be drawn in a bold font if set, the text is to be preceded by a rectangular bullet if set, the text window is to trigger a 'pop-out' subdialog on receiving a Tab keypress If set, use a flashing text cursor, otherwise any cursor is a highlighted obloid. This flag is not available on the Series 3, which is restricted to a non-flashing cursor. 8 LABELS, BUTTONS AND CHOICE LISTS TEXTWIN methods WAUISU Sei VOID wn_init (IN_TEXTWIN *par, PR_WIN *landlord) ; Initialise the text window to contain any text specified by the 1n_TExtTwrn struct pointed to by par. Sets Lodger . landlord to the value of landlord and textwin.state tO par->state. If the par->labe1 buffer does not contain a null string, an instance of EprLar is created and initialised to contain the specified text, as indicated by the following code: p_send3 (epflat,O_EP_INIT,WS_MAX_PRINT_BOX_TEXT_LEN) ; p_send4 (epflat,O_EP_SET_ TEXT, &par->label [0] ,p_slen(&par->label [0] )); If this is successful, the handle of the instance of EPFLat is stored in textwin. label. On failure p leave is called. This message is sent from the DLGBox dl_item_add method. Draw text VOID wn_draw(PR_TEXTWIN *self); Draw the text of the text window, assuming the existence of an appropriate graphics context. If textwin.state contains PR_TEXTWIN_BOLD, the graphics context is set to use a bold font. On the Workabout, if the control is being used as a dialog component (win. flags contains PR_WIN_IS_DLCTRL) and the dialog is set to use the small font (the owning dialog box, whose handle is stored in lodger.1andlord, has a non-zero value of digbox . font) the graphics context is set to use the small font. The text is sensed by sending textwin. label aN EF_SENSE_BUF message and is then drawn, with a call to gPrintBoxText, at a position within the text window determined by the pR_TExtwin_aL xxx flag in textwin.state. The bullet rectangle is drawn or cleared, depending on the presence or absence of the PR_TEXTWIN_BULLET flag in textwin.state. If win. flags contains PR_WIN_EMPHAStIsED, the text (and any bullet) is highlighted. If textwin.state contains PR_TEXTWIN_FLASHING, the highlight takes the form of a flashing cursor. If the first character in the string is oxo1 then the second character is interpreted as an offset in pixels for the remaining characters. This technique is used to align the pack selector prompt as illustrated in the following picture: Open file | ¢ gelacuti+ ng Disk _ Internal The "Disk" text has been offset so as to align it with the "Name" text. If textwin.state contains PR_TEXTWIN_BOLD, the graphics context is reset to use a normal font. This message is sent from the DLGBox wn_draw method. WEST ) Set property VOID wn_set(SE_TEXTWIN *txtset); Set the text and/or the textwin. state flags according to the data in the sz_Texrwrn struct pointed to by txtset. The items that are to be modified are specified by txtset->flags, which should be a combination of se_TEXTwIN_xxx flags. The value of txtset->state should be a combination of pr_TExtwINn_xxx flags. HWIM REFERENCE ee SSSeSFSSeeFFeeeSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSOOee If txtset->flags contains sE_TEXTWIN_TEXT, the method sets the text (by sending textwin.1label an EP_SET_TEXT message) to the first txtset->1en bytes in the buffer pointed to by txtset->buf. If textwin. label is NULL, an instance of EPFLAT is created and initialised (as described in the wn_init method) before the Ep_seT_TExT message is sent. Each of the remaining flags in txtset->flags causes the corresponding PR_TEXTWIN_xxx bit in txtset->state to be written (either set or cleared) to textwin. state. An LG_DRAW message is sent, causing the text window to be redrawn, if txtset->£1ags contains any of the flags SE_TEXTWIN_TEXT, SE_TEXTWIN_ALIGN, SE_TEXTWIN_BOLD OF SE_TEXTWIN_BULLET. The following example sets the text to the string pointed to by str. It also clears any PR_TEXTWIN_BOLD flag and sets PR_TEXTWIN_AL_RIGHT (clearing PR_TEXTWIN_AL_LEFT and PR_TEXTWIN_AL_CENTRE in the process). No other flags in textwin.state are affected. LOCAL_C VOID SetTextWin(PR_TEXTWIN *textwin,TEXT *str) { SE_TEXTWIN set; set .flags=SE_TEXTWIN_TEXT|SE_TEXTWIN_ALIGN|SE_TEXTWIN_BOLD; set.state=PR_TEXTWIN_AL_RIGHT; /* PR_TEXTWIN_BOLD not set, so will be cleared */ set .buf=str; set.len=p_slen(str) ; P_send3 (textwin,O_WN_SET, &set) ; } It is rare for application code to set more than the text of an instance of rextwrn used as a dialog box component. The flags in textwin. state are generally either set on initialisation (usually from IN_TEXTWIN_Xxx values set in a resource item) or are set or cleared by system code (see, for example, the DLGBOX dl1_item_lock and dl_item_dim methods). This message is sent from the pLczox wn_set method, normally invoked from application code by means of the hpigset and npigset Text utility functions. VOID wn_sense(SE_TEXTWIN *txtset) ; Write a pointer to the text in txtset->buf and the length of the text to txtset->1en, according to the code: txtset->len=p_send3 (self->textwin.label,O_EF_SENSE_BUF, &txtset->buf) ; On the Series 3, this method must not be called if the text window contains no text. On other machines the method simply writes zero to txtset->len if the text window contains no text. This message is sent from the pLGBox wn_sense method, normally invoked from application code by means of the hDigSense utility function. sirwia ae y input INT wn_key (INT keycode, INT modifiers) ; Simply returns wN_KEY_No_CHANGE (0) unless textwin. state contains PR_TEXTWIN_POPOUT. If textwin.state contains pR_TEXTWIN_POPOUT, the text window can trigger a subdialog (see the discussion of subdialogs in the Dialog Boxes chapter) on receipt of a wn_kEy message with keycode set to w_key_TAB. It does this by writing to wserv.subdial a value of one plus the text window's index within the dialog (the index is found by sending the dialog box a DL_HANDLE_TO_INDEX message). For any other value of keycode, the method uses the hinfoprint utility function to display the information message with system resource ID sys_popout_HELP (in English, this is the message "Press Tab to change this item"). In all cases the method returns wn_KEY_No_CHANGE (0). This message is sent from the pLGBox wn_key method. 8 LABELS, BUTTONS AND CHOICE LISTS LG_SENSE WIDTH oS Return required contro! width INT lg_sense_width(VOID) ; If textwin. label is NULL, returns zero. Otherwise, senses the text window's text by sending textwin. label an EF_SENSE_BUF message and returns the width required to draw the string, plus an allowance for a preceding bullet (regardless of whether a bullet is actually present). This message is sent from the pu¢Box dl_set_size method. _. Emphasise VOID wn_emphasise(UINT flag) ; Emphasise the window if £1ag is TRUE, or remove the emphasis if f1ag is FALSE. Does nothing if attempting to set the emphasis to its current state, or if textwin. label is NULL. Sets the PR_WIN_EMPHASISED bit in win. flags if f1ag is TRUE, otherwise clears this bit and erases any text cursor. This message is sent from the DLGBox dl_take_focus method. The SMACLIST class landlord offset width totalwidth destroy 1lg_sense_width 1g_set_id_pos wn_draw destroy wn_calc_position lg_draw wn_connect 1lg_self_check wn_dodraw wn_init wn_key wn_sense wn_emphasise wnrkey wn_position wn_redraw wn_sense_ help ig_update SMACLIST is the 'small' form of an action list. It is used to implement a set of buttons in cases where there is a requirement for the dialog to occupy as small a region of the screen as possible. In consequence, a dialog containing an instance of smacuist usually does not contain any other controls. The following diagram shows an example of the use of smacutst in the Replace command of the Word application, to control how text replacements are made. In this case the dialog must be small since there is a requirement to display as much as possible of the text in which replacements are being made. (BEnd Replace (S)Skip x is the x- offset of the button's leading left bracket character and smaclist .pos->width is the width of the single character that represents the button's key code smaclist.totalwidth the basic width of the control's buttons, including the smallest allowed button spacing. The actual width of the control, contained in lodger .width, may be greater than smaclist.totalwidth smaclist .num a count of the number of buttons in the action list smaclist.lwidth the width of a left bracket ae eS ES SS ers SMACLIST methods _ Destroy VOID destroy (VOID) ; Free the heap cell pointed to by smaclist .pos and supersend the pEsTRoy message. This message is sent from the pLGBox destroy method. Initialise VOID wn_init (IN_SMACLIST *init, PR_DLGBOX *landlord) ; Sets lodger. landlord to the passed value of landlord, which is assumed to be the handle of an instance of (a subclass of) pLcBox and ors DLGBOX_SMALL_ACTION_LIST into landlord->digbox. flags. Creates an instance of vares, then (provided init->rid is not zero) loads the resource specified by the resource ID init->ria and uses it to initialise the instance of vares (by means of a va_1nrT message). If this succeeds the handle of the instance of vargs is written to smaclist.data. The resource, when loaded, is regarded as a sequence of pusH_sur structs, this struct being defined in the acurst class definition as: typedef struct { WORD keycode; /* keycode to match text of inside button */ TEXT str{1]}; /* text above the button */ } PUSH_BUT; /* correspond to push_but in hwim.rh */ It corresponds to the pusH_BuT resource struct used to construct an ACLIST_ARRAY resource (both of these resource structs are defined in Awim.rh). On the Series 3a, if 1andlord->win.flags contains wIN_FRoM_aTs (which implies that the landlord is an instance of arsprat or a subclass) the data in the varzs instance pointed to by smaclist .data is loaded with button data from the arspraz instance. The number of buttons is found by sending smaclist .data a VA_counT message and is written to smaclist .num. A heap cell is allocated to contain the width an offset of each button and its address is written to smaclist.pos. The dialog box flags for this item are set to contain DLGBOx_ITEM_CENTRE, DLGBOX_ITEM_DEAD and (but not on the Series 3) pLeBox_ITEM_ACLIsT by sending lodger.1landlord a DL_SET_ITEM_FLAGS message. The method calls p_leave on failure to create or initialise the smaclist .data component or to allocate the smaclist.pos heap cell. This message is sent from the pLGBox dl_item_add method. 8 LABELS, BUTTONS AND CHOICE LISTS INT wn_key(INT keycode, INT modifiers) ; Scan the items in the smaclist .data array for a match between the stored key code and the passed keycode value. If the stored key code is negative it is considered to match with either the correponding (positive) value of keycode or the keycode value w_KEY_ ESCAPE. If there is a match, the corresponding button is animated to give a visual response to the keypress and the method then returns the index (the leftmost button has an index of zero) of the matching button. If there is no match the method returns -1. This method is not subclassed by acutrsr. It supplies the button animation for both the smaciist and ACLIST Classes, distinguishing the two cases by testing lodger . landlord->dlgbox. flags for the presence of pLGBOXx_ACTIoN_LIsT. In the smacutst case the button's key code character is animated by highlighting the button text for a period of two tenths of a second. For acurst the animation consists of a call to wDrawBut ton to draw the button in a depressed state, followed two tenths of a second later by another call to redraw the button in its undepressed state. In all cases a temporary graphics context is created for the animation and freed again afterwards. This message is sent from the pLGBox wn_key method. VOID wn_draw(VOID) ; Draw the row of buttons, assuming the existence of an appropriate graphics context. The method constructs a text string containing the buttons and displays it with a call to gprintBoxText. The data for each button is read from the smaclist .data array. The text of each button consists of the bracketed character corresponding to the button's key code, followed by the button text. Consecutive buttons are separated by two numeric spaces. This message is sent from the pLGBox wn_draw method. VOID wn_sense(SE_CHLIST *se) ; An instance of smacutst has no data that can usefully be sensed, so the supplied method does nothing. This method is supplied since it is called by system code. LG SET ID POS VOID lg_set_id pos(INT id, P_POINT *pos, UINT width) ; Supersend the Lc_seT_1p_Pos message and then, provided that smaclist .totalwidth (the width occupied by the buttons themselves) is less than lodger. width, adjust the button positions to centre them in the lodger window. This method is not subclassed by acutsv. It supplies the button positioning logic for both the smacuist and AcLIsT Classes, distinguishing the two cases by testing lodger . landlord->dlgbox. flags for the presence of DLGBox_AcTIon_utst. In the smacuist case the button separation is kept fixed but the buttons are centred by adjusting the value of lodger.offset.x. For acurst the button spacing is increased (by adjusting the x position of each button in the smaclist .pos array) as well as centering the buttons by changing lodger.offset .x. This message is sent from the pLGBOx dl_set_size method. HWIM REFERENCE LG SENSE INT lg_sense_width (VOID) ; Calculate the minimum width required to draw the contents. The content of the smaclist .pos element for each button is set so that smaclist .pos->x contains the x-offset to the leading left bracket of the button and smaclist .pos->width contains the pixel width of the uppercased character representing the button's key code. The display width of each button is calculated as the width of the uppercased key code character, including its enclosing brackets, plus the width of the following string. The button widths are accumulated into smaclist .totalwidth, together with a fixed separation between the buttons. The method assumes that smaclist .totalwidth initially contains zero, that is, it assumes that the method is called only once in the lifetime of an instance. The method returns the width of the control (which is also the final value stored in smaclist .totalwidth). This message is sent from the pLGBox d1_set_size method. The ACLIST class landlord offset width destrey wn_calc_ position lg_draw wn_connect 1g_self_check wn_dodraw 3 wn_emphasise — wa-key wn_visible wn_key wn_position wn_sense wn_redraw tg—ense—width wn_sense_help lig_update The acutist class is used to add an action list of one or more buttons to a dialog, in cases where screen space is not at a premium. Each button has two associated items of text; one drawn inside the button, representing the key press that activates it, and one drawn above the button, intended to inform the user of the action that the button initiates. ¢BT = Body text > Stop Delete Delete all 8 LABELS, BUTTONS AND CHOICE LISTS ini paren As for sMacLIst, an AcLIsT control requires the buttons to be described in an ACLIST_ARRAY resource: RESOURCE ACLIST_ARRAY delete_ac { button = { PUSH_BUT { keycode=W_KEY_ESCAPE; str="Stop"; } ’ PUSH_BUT { keycode=W_KEY DELETE LEFT; str="Delete"; be PUSH_BUT ote Wee str="Delete all"; } }; } Again, the keycode of one element may be negative to allow it to be activated by pressing Esc as well as the specified key. The above example does not use this option since it explicitly uses a keycode of w_KEY_EscapE for one of its buttons. The dialog resource for the dialog illustrated above is as follows: RESOURCE DIALOG delete di { title="Delete"; flags=DLGBOX_NOTIFY_ESCAPE|DLGBOX_RBUF_FILLED; controls= { CONTROL { class=C_CHLIST; prompt="Style"; info=CHLIST{}; /* choice list content supplied dynamically */ }, CONTROL { class=C_ACLIST; info=ACLIST { rid=delete_ac; }; }; } As with sMACLIST, an ACLIST control must be the last component of the dialog. HWIM REFERENCE eee Class definition ( Defined in sub-category file aclist.cl (generated header file aclist.g). CLASS aclist smaclist action list lodges within dialog.It is equivalent to a list of push_buttons { REPLACE wn_init load action list given rid & set dead & centre REPLACE wn_draw REPLACE lg _sense_width returns min width of control TYPES { typedef struct { WORD keycode; keycode to match text of inside button TEXT str{1]); text above the button } PUSH_BUT; corresponds to push_but in hwim.rh } PROPERTY 1 { PR_VARES *text; array holding the keycode & text for above each button WORD width width of each button ( UWORD yl; offset to top of upper text boxes . UWORD y2; offset to top of buttons themselves } } The Series 3 version contains the following defined constants: ACLIST_BUTTON_MIN_GAP 5 min gap between 2 buttons ACLIST_BUTTON_WIDTH 38 For French 'Entrer' ACLIST_BUTTON_HEIGHT 12 ACLIST_BUTTON_SHADOW 2 ACLIST_TOP_GUTTER 4 from self->lodger.offset.y On the Series 3a the corresponding values are read or derived from the globally accessible data that is described in the Introduction chapter of this manual. The property items: WORD width width of each button UWORD yl; offset to top of upper text boxes UWORD y2; offset to top of buttons themselves do not exist in the Series 3 acu1st class definition. Property aclist.text The handle of an instance of a vanes array, containing the key code and associated text that is to be displayed above each button. aclist.width Used internally on the Series 3a to store the (fixed) width of all buttons. On the Series 3 this width is represented by the constant value ACLIST_BUTTON_WIDTH. aclist.yl Used internally on the Series 3a to store the (fixed) y-offset within the control's window to the top of the rectangle containing the text that is displayed above a button. On the Series 3 this is calculated from the sum of lodger offset .y and ACLIST_TOP_GUTTER. aclist.y2 Used internally on the Series 3a to store the (fixed) y-offset within the control's window to the top of the rectangle containing a button. On the Series 3 this is calculated from the sum of lodger.offset.y, ACLIST_TOP_GUTTER and ACLIST_BUTTON_HEIGHT. 8-14 8 LABELS, BUTTONS AND CHOICE LISTS The superclass property smaclist .data is set to the handle of an instance of vares that contains an array of key codes and text (to appear inside the button) for standard buttons. These are loaded from the SYS_BUTTON_TEXT system resource, which contains the following standard buttons: Keycode Button text (English version) W_KEY_RETURN Enter W_KEY_ESCAPE Esc W_KEY DELETE LEFT Del W_KEY_SPACE Space W_KEY_UP t W_KEY_DOWN + W_KEY_RIGHT > W_KEY_LEFT W_KEY_TAB Tab W_KEY_MENU Menu ACLIST methods _ Initialise VOID wn_init (IN_ACLIST *init, PR_DLGBOX *landlord) ; Sets DLGBOX_ACTION_LIST in landlord->dlgbox. flags, creates an instance of vars and loads into it the standard button data from the sys_BuTTon_TEXxT system resource. If this is successful, the vars handle is written to aclist.text. On the Workabout lodger.landlord is set to the passed value of 1andiord (as is done on all machines in the sMACLIST wn_init method) so that the control can determine if it should draw itself using the small font. Finally, the method supersends the wy_In1T message and, on the Series 3a, clears the flag DLGBOX_SMALL_ACTION_LIsT that is set in landlord->dlgbox. flags by the superclass wn_init method. Note that this means that a Series 3 acurst sets both the pLcBox_ACTION_LIsT and DLGBOX_SMALL_ACTION_LIST flags in 1andlord->dlgbox.flags (system code that must distinguish between the two classes always tests for the presence of pLGBOX_ACTION_LIST). This message is sent from the pLGBox d1_item_add method. Draw VOID wn_draw(VOID) ; Draw the row of buttons, assuming the existence of an appropriate graphics context. For each button, the method uses gprintBoxText to draw centred text above the button, the text (and the key code) being read - via a va_pBur message - from the corresponding element of the vares array whose handle is stored in smaclist .data. Each button is drawn with a call to worawButton, the text for the button being read from the element of the aclist .text array whose key code matches the one read earlier from the button's smaclist .data array element. If the button's key code does not match with any of the standard buttons, its text is taken to be the uppercased key code. This message is sent from the pLGBox wn_draw method. required width INT 1g_sense_width(VOID) ; Calculate the minimum width required to draw the contents. The method calculates the width of each button, sufficient to contain its text, subject to each button having a minimum width that is dependent on the machine type. These widths are stored in successive elements of the array pointed to by smaclist .pos. The button separations are calculated so that they are evenly spaced, with a minimum separation that is dependent on the machine type. The corresponding button positions are 8-15 HWIM REFERENCE also stored in the smaclist .pos array. Note that the button positioning logic pays no attention to the widths of the labels that appear above the buttons. It is the responsibility of the application programmer to select the text for these items so that they do not overlap. The method writes the sum of the widths of the buttons and the inter-button gaps to smaclist .totalwidth and returns this value. The width of the control may subsequently be increased, on receipt of an LG_sET_ID_Pos message, with the control's actual width then being stored in lodger.width. This message is sent from the pLGBox d1_sense_size method. The CHLIST class flags landlord i offset width data flags matcher matchlen nsel pop destroy 1g_sense_width wn_draw wn_calc_ position wn_connect wn_dodraw eestzeay 1lg_draw lg_self_check ig_set_id_pos ins wn_visible wn_emphasise wn_init wn_key wn_sense wn_set wn_position wn_redraw te-sensewidth lg_update wn_sense_help The cuurst class provides a choice list control that can be used to select one of a range of options. A choice list appears as shown by the ‘Page size' control in the following illustration, taken from the page size system dialog. ¢A49 Width 8.27 Height 11.69 ‘Orientation Portrait A particular option may be selected by means of the Home and End keys, the left and right cursor keys, or by first letter match. A choice list may additionally be configured to perform incremental matching with a sequence of key presses. A choice list responds to the Tab key by displaying a pop-out expanded view, as shown below. “Orientation The simplest form of choice list has its items specified by menu resource structs. The dialog illustrated above contains two choice list controls, with their resources defined in the system resource file as follows: 8-16 § LABELS, BUTTONS AND CHOICE LISTS rar ee RESOURCE MENU sys_page_size { items= { CHOICE_ITEM {str="A4";}, CHOICE_ITEM {str="Custom";}, CHOICE_ITEM {str="Executive";}, CHOICE_ITEM {str="Legal";}, CHOICE_ITEM {str="Letter";}, CHOICE_ITEM {str="Monarch";}, CHOICE_ITEM {str="DL"; } la } RESOURCE MENU sys_orient { items= { CHOICE_ITEM {str="Portrait";}, CHOICE _ITEM {str="Landscape"; } }; } where the cHorce_ITEM resource struct is defined in Awim.rh as: STRUCT CHOICE_ITEM /* choice list item */ BYTE { TEXT str=""; /* identification text */ } The corresponding system pra.oc resource is as follows where, for clarity, only the choice list control elements are shown: RESOURCE DIALOG sys_pagesize_dl { title="Page size"; £lags=DLGBOX_NOTIFY_ENTER |DLGBOX_RBUF_FILLED|DLGBOX_APPEND_UNITS TITLE; controls= { CONTROL { class=C_CHLIST; flags=DLGBOX_ITEM_NOTIFY_CHANGED; prompt="Page size"; info=CHLIST{rid=sys_page_size;}; }, CONTROL { class=C_CHLIST; prompt="Orientation"; info=CHLIST{rid=sys_orient;}; } he } where the cuurst resource struct and its default values are defined in hwim.h as: STRUCT CHLIST { LINK rid=0; BYTE nsel=0; BYTE flags=0; } The content of a choice list may be set dynamically, using the wn_set method. This will typically be performed in the dialog's d1_dyn_init method. Changing the content of a choice list after the dialog box has become visible is not recommended, particularly if there is any risk that the new content may need a wider display. HWIM REFERENCE Ss SSS Class definition Defined in sub-category file chlist.cl (generated header file chlist.g). CLASS chlist lodger choice list self->win.offset.x is tl.x of text (excluding left arrow) { REPLACE destroy REPLACE wn_key REPLACE wn_draw REPLACE wn_set REPLACE wn_sense process key press print text of current selection set data,nsel or retain property sense nsel value REPLACE wn_emphasise draws arrow if highlighted REPLACE wn_init create menu given rid REPLACE lg _sense_width returns (min text width + right arrow). CONSTANTS { SE_CHLIST_NSEL 0x01 SE_CHLIST_DATA 0x02 SE_CHLIST_RETAIN 0x04 IN_CHLIST_INCREMENTAL 0x01 PR_CHLIST_RETAIN 0x04 PR_CHLIST_SUSPENDED 0x08 To suspend display of cursor PR_CHLIST_FIXED WIDTH 0x10 } TYPES { typedef struct { WORD rid; resource ID of lbc text-array UBYTE nsel; initial value of nsel UBYTE flags; IN_CHLIST INCREMENTAL } IN_CHLIST; typedef struct { UWORD set_flags; which fields significant PR_VAROOT *data; possible new data value UWORD nsel; possible new nsel value } SE_CHLIST; } PROPERTY 2 { PR_LISTBOX *pop; handle of pop-out menu (NULL if un-squirted mode) PR_VMATCHER *matcher; set if incremental matching required PR_VARES *data; pointer to lbc text-array struct UWORD nsel; selected item in list (zero for first) UWORD flags; holds PR_CHLIST_ flags UWORD matchlen; length of match string } } The Series 3 version does not define pR_CHLIST_FIXED_WIDTH. Property chlist.pop chlist.matcher chlist.data chlist.nsel chlist.flags either wut or the handle of an instance of LrsTzox, used to display a pop- out expanded view either nuut or the handle of an instance of vmarcuer, used to perform incremental matching the handle of an instance of vargs, containing the text for the choice list items the index number of the currently selected item a combination of the pr_cuList_xxx flags described below 8 LABELS, BUTTONS AND CHOICE LISTS chlist.matchlen if chlist.matcher is not NULL, the character offset to the incremental matching cursor, otherwise not used CHLIST flags PR_CHLIST_RETAIN if set, the instance of vanes whose handle is stored in chiist .data will not be destroyed when replaced by another instance of vanes or when the choice list is destroyed PR_CHLIST_SUSPENDED when set, disables the drawing of any incremental matching cursor CHLIST methods Destroy VOID destroy (VOID) ; If chlist . flags does not contain pR_CHLIST_RETAIN and chlist.data is not uLL, send chlist.dataa DESTROY message. Then supersend the pEstroy. This message is sent from the pLGBox destroy method. oo Initialise VOID wn_init (IN_CHLIST *init, PR_WIN *landlord) ; Set lodger. landlord to the passed value of landlord. Create an instance of vares and (provided init->rid is not zero) load into it the resource with ID init->ria. If the creation and initialisation is successful, write the handle of the instance to chiist .data. On the Series 3a, if landlord->win. flags contains win_FRom_ats (which implies that the landlord is an instance of aTspIat or a subclass) the data in the varzs instance pointed to by smaclist .data is loaded with data from the arsp1at instance, rather than from the resource. If init->flags contains IN_CHLIST_INCREMENTAL, create and initialise an instance of vmarcuer, according to the following code: p_send5 (self->chlist.matcher,O_IM_INIT, &chlist .matchlen, 80,chlist.data) ; and store its handle in chlist .matcher. If init->nsel is not zero, sets chlist .nsel tO init->nsel, provided this is within the range of choice list items, otherwise sets to the last item. If this changes chlist .nsel and chlist.matcher is not NULL, sends chlist.matcher an IM_SET_VAL message, passing chlist .nsel, and Sets chlist.matchlen to zero. This message is sent from the pLGBox a1_item_add method. WN KEY sc ccc cc _ Handie key Input INT wn_key (INT keycode, INT modifiers) ; If the choice list contains no items, the method simply returns ww_KEY_No_CHANGE (0). Ifa pop-out expanded view is currently displayed, chlist .pop is sent the wn_kEy message. Subsequent processing depends on the return value from this message as follows: WN_KEY_NO_CHANGE the method simply returns wN_KEY_NO_CHANGE any positive value this indicates the selection of a new item in the choice list, and chlist .nsel is set appropriately. The method then returns WN_KEY_CHANGED any other (-ve) value chlist .pop is sent a DESTROY message, chlist.pop is set to NULL, and the method returns the message return value Otherwise, processing is dependent on the value of keycode, as follows: HWIM REFERENCE W_KEY_LEFT W_KEY_RIGHT W_KEY_HOME W_KEY_END W_KEY TAB any other non- printable key, except W_KEY_ DELETE_LEFT any other key chlist .nsel is decremented by one or, if already zero, set to the last item in the choice list. The method sends an Lc_pRaw message and returns WN_KEY_CHANGED chlist .nse1 is incremented by one or, if already at the last item in the choice list, set to zero. The method sends an L¢_praw message and returns WN_KEY_ CHANGED chlist.nsel is set to zero. The method sends an Lc_praw message and returns WN_KEY CHANGED chlist.nsel is set to the last item in the choice list. The method sends an LG_DRAW Message and returns WN_KEY_ CHANGED an instance of ursTsox is created, initialised and made visible (using the utility function hinitvis. The initialisation uses an In_LIsTBox struct that is set up as indicated in the following code fragment: IN_LISTBOX lst; ist .flags=IN_LISTBOX_KEEP_ARRAY|IN_LISTBOX_CUR_SET| IN_LISTBOX_POS_ALIGN_Y|IN_LISTBOX_AUTO_SIZE; if (self->chlist.matcher) lst .flags|=IN_LISTBOX_MATCHER; if (self->chlist.flags&PR_CHLIST_FIXED WIDTH) { /* fixed width code not present for Series 3 */ ist .minwid=p_send2(self,0_LG SENSE_WIDTH) ; lst. flags |=IN_LISTBOX_FIXED_WIDTH; winquireWindowOffset (0, self->win.id, &lst.pos) ; lst.pos.x+=self->lodger.offset.x; lst .pos.y+=self->lodger.offset.y; lst.current=self->chlist.nsel; If successfully created and initialised, the prsTsox handle is written to chlist.pop. The method returns wn_KEY_ABSORB_oN to instruct the dialog box to direct all future key presses to the wn_key method of this control. the method sends an L¢_praw message and returns WN_KEY_NO_CHANGE. if chlist .matcher is not nuL, this object is sent an 1m_KEY message, passing keycode and modifiers. If the return value is IM_NEW_DISPLAY, chlist .nse1 is set to the value returned by sending chlist .matcher an IM_SENSE_VAL message. The method then sends an Lc_pRaw message and returms WN_KEY_CHANGED. Otherwise the method attempts to make a first letter match between the choice list items and the value of keycode. This matching is performed by cycling forwards from the current item (so that repeated pressing of an alphabetic key will select, in turn, each item whose text starts with that letter). The method then sends an Lc_pRaw message and returns either WN_KEY_NO_CHANGE, OF WN_KEY_CHANGED if the first letter match changed the current item This message is sent from the pLGBOx wn_key method. VOID wn_draw(VOID) ; Draw Draw the choice list control, assuming the existence of an appropriate graphics context. If the choice list contains no items, the method simply clears the rectangular area occupied by the control. Otherwise, draw (using gprintBoxText) the text of the current item and, if win. flags contains PR_WIN_EMPHASISED, enclosing left and right arrow characters. If the choice list supports incremental 8 LABELS, BUTTONS AND CHOICE LISTS matching the incremental matching cursor is drawn, provided the choice list is emphasised, chlist. flags does not include pr_cHLIST_sUsPENDED and a pop-out expanded view is not currently displayed. This message is sent from the pLGBox wn_draw method. WN_SET VOID wn_set (SE_CHLIST *set) ; titem and/or data Set the data array that contains the choice list items and/or the currently selected item from the SE_CHLIST struct pointed to by set. If set->set_flags contains se_cuListT_pata, the choice list is set to use the data array whose handle is stored in set->data. Provided chiist . flags does not contain PR_CHLIST_RETAIN, any existing chlist.data is sent a Destroy message before the handle in set->data is copied to chlist.data. If chlist .matcher is not nuLL, the value of set->data is also written to chlist -matcher->vmatcher. va. If set->set_flags contains SE_CHLIST_NSEL, the choice list is set to the item with index number set->nsel or, if this number is too large, the last item in the choice list. If chlist .matcher is not NULL, chlist.matcher is sent an IM_SET_VAL message, passing the value of chlist .nsel, and chlist.matchlen is set to zero. If set->set_flags contains sE_CHLIST_RETAIN, the flag PR_CHLIST_RETAIN is ored into Chlist. flags, SO that the instance of vares whose handle is in chlist .data will not subsequently be destroyed. Note that a means of clearing this flag, once set, is not supplied. On conclusion, the method sends an L¢_pRaw message. This message is sent from the pLGBox wn_set method, normally invoked from application code by means of the hDlgSet, hDlgSetChlist and hDlgsetch1istOn utility functions. Sense data and selected item VOID wn_sense(SE_CHLIST *set); Writes chlist .nsel and chlist.data to set->nsel and set->data respectively. This message is sent from the pLGBox wn_sense method, normally invoked from application code by means of the hplgSense and hDlgSenseChlist utility functions. INT 1lg_sense_width (VOID) ; Returns the width required to display the widest item in the choice list. If there are no items, the method returns the width required to display text of zero length. This message is sent from the DLGBox d1_set_size method. VOID wn_emphasise (INT flags) ; If chlist .pop is not NULL, simply send the wn_EMPHASISE message to chlist .pop. Otherwise, set or clear PR_WIN_EMPHASISED in win. flags, depending on whether the passed flags value is TRUE OF FALSE and, if FALSE, erase any incremental matching cursor. Then send an Lc_pRaw message. This message is sent from the DLGBox di_take_focus method. HWIM REFERENCE The NCHLIST numeric choice list class aestesy wn_calc_position wn_connect landlord offset width destrey ig_draw lg_self_check matcher matchlen nsel pop destroy 1g_sense_width wn_draw wn_dodraw 1g_set_id_pos wn_emphasise wWR-ERLE wn_visible wn_position wn_redraw wn_sense_help The ncuutst class is not present on the Series 3. The neuiist class provides a choice list control that allows the selection of a positive integer value in the contiguous range from 1 to a specified maximum value. Class definition Defined in sub-category file nchlist.cl (generated header file nchlist.g). CLASS nchlist chlist Numeric choice list class { REPLACE wn_init REPLACE wn_set REPLACE wn_sense } Property There is no property associated with ncxuisr. Ee aaa ae ee ae ey NCHLIST methods WNLINIT VOID wn_init (IN_CHLIST *init, PR_WIN *landlord) ; Initialise Initialise the numeric choice list. The method sets 1odger. landlord to the passed value of landlora. amd creates an instance of the VANUMBER Class, storing its handle in chlist.data. The list of numeric choices is not set up during initialisation, the init parameter being ignored. In consequence, there must be a following call to the wn_set method. 8 LABELS, BUTTONS AND CHOICE LISTS WN_SET =————SsSSett current itei# VOID wn_set (SE_NCEDIT *pset) ; sr maximum value Set the currently selected item and/or the maximum selectable value from the se_ncEDrT struct pointed to by set. The sz_nceprT struct is defined in ncedit.g as: typedef struct { UWORD value; UWORD low; UWORD high; UWORD flags; } SE_NCEDIT; For further explanation, see the description of the nceprr class, in the Numeric Editors chapter. If pset->£1ags contains s—E_NCEDIT_HIGH, the maximum selectable value is set by sending the component instance Of VANUMBER a VAN_SET_MAX message, passing the value of pset->high. It is essential that an instance of NCHLIST receives at least one wN_SET message to set the maximum value after processing a WN_INIT message. If pset->£1ags contains sE_NcEDIT_vaLuE, the current selection (as specified by chlist -nse1) is set to the item with index number pset->value - 1 and Ncuuist sends itself an Lc_pRaw message. It is the programmer's responsibility to ensure that a wn_seT message does not attempt to set a current selection that exceeds the current maximum value. VOID wn_sense(UWORD *psense) ; Writes the value of chlist.nsel + 110 «psense. The VARES resource array class destroy va_replace va_copy va_count va_reclen va_delete va_init va_sort va_deletem va_key va_insertm va_findisq ind va_prec va_insertisq va_pbuf va_append i va_compress va_insert va_search va_compare va_capacity va_reset va_compress va_test The vares class subclasses varoot to provide an array suitable for storing a sequence of leading byte counted text elements, the array being preceded by a byte count of the number of elements in the array. It is primarily intended for storing data such data that has been loaded from a resource file (for example, a Menu resource that contains the set of text items to be displayed in a choice list). It is used as a component by the CHLIST, ACLIST and smacttst classes. HWIM REFERENCE eee Class definition Defined in sub-category file vares.cl (generated header file vares.g). CLASS vares varoot { REPLACE va_copy REPLACE va_reclen REPLACE va_init REPLACE va_deletem REPLACE va_insertm REPLACE va_prec REPLACE va_pbuf REPLACE va_compress PROPERTY UBYTE *data; } } Property vares.data Either nuuz or a pointer to an allocated cell that contains a byte count of the number of elements, followed by the elements, each consisting of leading byte counted text. a i a es VARES methods UWORD va_copy(UWORD num, UBYTE *prec) ; Copy the data of record number nun, not including its leading count byte, to the buffer pointed to by prec and return the length of the copied data. UWORD va_reclen(UWORD num) ; Return the length of record number nun. The record is located by sending a va_PREc message. VAUIN VOID va_init(UBYTE *data) ; Initialise the array to contain the elements pointed to by data. It is assumed that data points to a leading byte that contains a count of the following items, each of which is leading byte counted text. Copies the pointer data to vares .data and, if the pointer is not NULL, sets varoot .nrec to the value in the first byte pointed to by data. Finally, varoot .key.ofs is set to one - i.e. sizeof (UBYTE). Delete sequence of récords VOID va_deletem(UWORD num, UWORD nrec); Delete nrec records, starting with record number num. The method does nothing if vares.data is nuLL. Otherwise the specified items are removed and the alloc cell adjusted in size by means of a call to p_adjust. The value of varoot .nrec and the item count in the first byte of the data are adjusted accordingly. 8 LABELS, BUTTONS AND CHOICE LISTS VOID va_insertm(UWORD num, UBYTE *prec, UWORD nrec); Insert nrec records from the buffer pointed to by prec, immediately before record number num. The data pointed to by prec is assumed to be one or more leading byte counted text items, with no leading item count. If vares .data is NuLL, the method creates an alloc cell to contain the data, otherwise a gap is opened in the existing cell by means of a call to p_adjust. If this succeeds, the data is copied into the alloc cell. The value of varoot .nrec and the item count in the first byte of the data are adjusted accordingly. The method does nothing to the data and calls p_1eave if there is insufficient memory to create or expand the alloc cell. UBYTE *va_prec({UWORD num) ; Return a pointer to record number num, including its leading count byte. UBYTE *va_pbuf (UWORD num) ; Return a pointer to the data of record number nun, that is, excluding its leading count byte. VOID va_compress (VOID) ; Free unused allocated memory. The method does nothing unless varoot .nrec is zero (inserting or deleting records always adjusts the size of the cell accordingly). If varoot .nrec is zero, the method frees the alloc cell pointed to by vares. data and sets vares.data to be NULL. HWIM REFERENCE The VANUMBER numeric array class va_count va_delete va_sort va_key va_findisq va_insertisq va_append va_insert va_search va_compare va_reset va_replace destroy va_pbuf va_copy van_set_max va_reclen va_swap va_init va_deletem va_insertm va_prec va—pbut va_capacity va_compress va_test The VANUMBER Class is not present on the Series 3. The vanumBer class subclasses varoor to provide a pseudo-array that behaves as though it contains records that consist of string representations of consecutive positive integers, starting with "1". It is used as a component by the ncuurst class. Class definition Defined in sub-category file nchlist.cl (generated header file nchlist.g). CLASS vanumber varoot { REPLACE destroy=root_destroy REPLACE va_pbuf ADD van_set_max PROPERTY { TEXT data [8]; } } Property vanumber.data A buffer containing the string representation of the array 'record' last referenced in a vA_PBUF message. LS a a VANUMBER methods Destroy VOID destroy (VOID) ; This method calls root_destroy since, exceptionally, a vanumBEr array has no allocated memory to contain its ‘records’. 8 LABELS, BUTTONS AND CHOICE LISTS VA_PBUF =—sese Point to record data TEXT *va_pbuf (INT num) ; Return a pointer to 'record' number num. The method uses a call to p_itob to generate, in vanumber .data, a zero-terminated string representing the number num and returns a pointer to this string. VAN_SET.MAX == Set maximum value VOID van_set_max(INT max) ; Set the maximum displayable value. The method simply sets varoot .nrec to the value max. CHAPTER 9 NUMERIC EDITORS This chapter describes the numeric editor dialog components provided by the HWIM library. There are currently seven variants as follows: e the multi-field numeric editor that provides the base class for the remaining six variants: it is not intended to be used as a stand-alone class e the long numeric editor that allows the user to edit a signed long value e the integer numeric editor that allows the user to edit an unsigned integer value e the word numeric editor that allows the user to edit a word value e the date/time numeric editor that allows the user to edit either a date, a time or a duration e — the latitude/longitude editor that allows the user to edit either a latitude or a longitude e — the range numeric editor that allows the user to edit two unsigned words specifying the upper and lower values of a range. Precursors Familiarity with the following topics will aid the understanding of this chapter: ¢ — the win and Lopcer classes described in the Windows chapter of the HWIM Reference manual. e the description of the piggox class in the Dialog Boxes chapter, particularly the wn_key method which may send wn_key messages to a dialog box component. Class diagram af ie oe i Fai baesti H ci _/ ledger a a ( Tame ors ‘ oom 3 rs wncedit ? i / tgedit > AL ' R ‘ ~, ‘ As, ' : Lees < oo eee te eee * atte ae ~ Incedit i a mfne wae fase ~~ ~ x \ ~ 4 . HA ncedit > é lledit rorad HWIM REFERENCE landlord offset width selected cField nField totWidth cPos changed eStr dStr trail £ destrey destroy wn_key wn_calc_position wn_init wn_connect wn_visible wn_dodraw ig_draw wn_draw wn_set wn_emphasise ig_sense_width lg_self_check mf£_range_beep ig_set_id_pos wn_position wn_redraw tg—sense—width wn_sense_help ig_update The mrwe multi-field numeric editor class is intended to be subclassed to create a numeric editor control. In addition to the subclasses supplied in the HWIM library, two example subclasses are described later in this chapter. MFNE supports the display of a series of fields, each of which may be edited, as shown in the following picture: Set time and date (37:14 pm ‘Date 67/12/1993 In this illustration, the Time control allows the user to edit the hours, minutes and seconds fields, and to type a P or an A to toggle the am/pm indicator. The Date control allows the user to edit the day, the month and the year. Class definition Defined in sub-category file mfne.c/ (generated header file mfne.g). CLASS mine lodger Multi field numeric editor { REPLACE wn_key process key press REPLACE wn_draw display current number REPLACE wn_set set data REPLACE wn_emphasise set initial highlight, validate number REPLACE lg_sense_ width return width of max number plus cursor REPLACE lg_self_check check the current number is valid ADD mf_range_beep beep and give range info message 9 NUMERIC EDITORS KK SE SNUMERNG EDITORS CONSTANTS { MFNE_MAX FIELDS 4 MFNE_MAX WIDTH 10 MFNE_MAX TRAILER 3 MENE_LOWER 0 MFNE_UPPER 1 MFNE_CURSOR_WIDTH 3 MFNE_SIGNED 0x01 MFNE_LEFT ALIGN 0x02 MFNE_SUPPRESS LEADING 0x04 MFNE_SUPPRESS_ SEPARATOR 0x08 MFNE_TRAILER 0x10 MFNE_SETS NEXT 0x20 MFNE_SETS PREV 0x40 MFNE_AUTO_ SIZE 0x80 } TYPES { typedef struct } { WORD flags; LONG value; UBYTE width; UBYTE hWidth; UBYTE hPos; UBYTE separator; LONG limits [2]; } MFNE_FIELD; PROPERTY { WORD selected; Current state WORD cField; The current field WORD nField; The number of fields WORD totWidth; The total field width (chars) WORD cPos; The cursor position (chars) WORD changed; The field has changed TEXT eStr (MFNE_MAX_WIDTH+2] ; The current edit context TEXT dStr([MFNE_MAX_FIELDS* (MFNE_MAX_WIDTH+1)+MFNE_MAX TRAILER+2] ; TEXT trail[2] [MFNE_MAX TRAILER+1] ; The trailer text MFNE_FIELD f [MFNE_MAX_FIELDS] ; The fields } } Property mfne.selected TRUE if the current field is selected/highlighted mfne.cField the index of the current field: the first field has index zero mfne .nField the number of fields: less than or equal to MFNE_MAX_FIELDS méne.totWidth the width of the lodger window: a subclasser need not set this mfne.cPos the cursor position within the current field - units of characters: a subclasser need not set this mfne . changed TRUE if one or more fields have been changed. This property is set by the 1g_self_check and wn_key methods. mfne.eStr the editable text of the current field: a subclasser need not set this mfne.dStr the formatted string representing the entire content of the editor: a subclasser need not set this mfne.trail the two zero terminated strings that define the trailer text HWIM REFERENCE ae mfne.f an array of MFNE_FIELD structs. The MFNE_FIELD struct is defined as follows: typedef struct { WORD flags; LONG value; UBYTE width; UBYTE hWidth; UBYTE hPos; UBYTE separator; LONG limits [2]; } MFNE_FIELD; The significance of the members of the mrwe_FIELD struct is as follows: flags may contain an ored combination of the following flags: MFNE_TRAILER which specifies that one of the zero terminated strings specified in mfne.trail is to be drawn: the string to be drawn is specified by the current value. MFNE_SUPPRESS_SEPARATOR which specifies that the separator character is to be ignored. MFNE_SIGNED which specifies that the editable value can assume negative values. MFNE_SETS_NEXT which specifies that the value member provides a lower bound for the next field. MFNE_SETS_PREV which specifies that the value member provides an upper bound for the previous field. MEFNE_AUTO_SIZE which specifies that automatic sizing is allowed. MFNE_LEFT_ALIGN which specifies that the field is to be drawn as left aligned text. Note that mrwe_LEFT_aLIGn takes precedence over MFNE_SUPPRESS LEADING. MFNE_SUPPRESS_LEADING which specifies that the field is to be drawn without leading. value either the numeric editable value or the index of the trailer text width the character width of the field ignoring the separator hWidth the pixel width of the field in pixels ignoring the separator: a subclasser need not set this hPos the horizontal distance in pixels of the field from the left edge of the lodger window: a subclasser need not set this separator the optional separator character that appears to the right of the editable value/trailer text: the separator is ignored if MFNE_SUPPRESS_SEPARATOR is set in flags limits the upper and lower limits for the value member: the elements should be accessed using the mrnE_UPPER and MFNE_LOWER symbolic constants. For a trailer field these should be set to one and zero respectively. 9 NUMERIC EDITORS 77 eS a eee ery MFNE methods WN KEY Handle key press INT wn_key(INT code, INT modifiers) ; Handle a keypress. The return value will be ww_KEY_No_cHance whenever: the editable value is selected and the keypress is either a left arrow, a right arrow, a tab ora space. When there is more than one field the effect of any of these keys is move the current field, and hence the highlight, to the left, or to the right, by one field. the MFNE_stcNeD flag is not set for the first field, the editable value is not selected (mfne selected is FALSE), the cursor is not in the leftmost position, and the keypress is a plus or a minus key. The keypress has no effect. the MFNE_SIGNED flag is not set for the first field, the editable value is selected, the MFNE_SIGNED field £1ag is not set in the current field and the keypress is a plus or a minus key. The keypress has no effect. The return value will be w_KEY_CHANGED whenever: there is only one field, the editable value is not selected and the keypress is a right arrow, a left arrow, a tab or a space. The effect of any of these keypresses is to select the editable value thus highlighting the field. there is only one field and the keypress is a full stop or a comma. If the editable value is selected the effect of the full stop (comma) keypress is to increment (decrement) the current value of the current field. Otherwise the effect of either keypress is to select the editable value thus highlighting the current field. the current field is a trailer field and the keypress corresponds to the first character of one of the two alternative trailer text strings. The effect of the keypress is to toggle the trailer text. The return value will be ww_KEY_CHANGED_DEFER whenever: there is more than one field, the editable value is selected, and the keypress is a right arrow, a left arrow, a tab or a space. The effect of the key is to move the current field by one field to the right (or to the left in the case of the left arrow). there is more than one field and the keypress is a full stop or a comma. The effect of the key is to increment or decrement respectively the current value: if the result is out of range then it is reset to the nearest limit. the current field is not selected, the cursor is currently in the leftmost position (cpos is zero) and the keypress is the plus key or the minus key. Sets the sign of the value member of the current field according to the keypress. the current field is selected, does not have the MrnE_sIGNeED flag set in its flags member, the keypress is a plus or minus key, and the mrwe_siGNep flag is set in the flag member of the first field. The effect of the keypresses is to set the sign of the value member of the first field according to the keypress. the current field is not selected, the cursor is not in the leftmost position (cPos is not zero), the key press is a plus or a minus, and the Mrne_stenep flag is set in the flag member of the first field. The effect of the keypresses is to set the sign of the value member of the first field according to the keypress. the current field is not selected and the keypress is either delete left (w_kKEY_DELETE_LEFT) or delete right (w_KEY_DELETE_RIGHT). Unless the cursor position is zero, the character at the current position will be replaced with a numeric space, and the cursor positon decremented by one. Note that for a trailer field the cursor position is always zero. the current field is selected and the keypress is either delete left (w_KEY DELETE LEFT) or delete right (W_KEY_DELETE_R1GHT). The effect of either keypress is to reset the current field index to the preceding field (mfne.cFie1d is decremented), or, if the current field index is zero, reset the 9-5 HWIM REFERENCE current field index to the rightmost field. If the cursor position is not zero, the character at the current cursor position is replaced by a numeric space and the cursor positon is decremented. Note that the wN_KEY_CHANGED_DEFER flag includes the wn_KEY_CHANGED flag: thus WN_KEY_CHANGED_DEFER&WN_KEY_CHANGED would give wN_KEY_CHANGED. Note also that the while the control key is held down the full stop and comma keys increment/decrement by ten units rather than one. In all cases the mfne . changed property is set to TRUE if the keypress modified the content or the appearance of the editable value. VOID wn_draw (VOID) ; Draw the current editable value. If the PR_WIN_EMPHASISED flag is set in win. flags, and mfne. selected is TRUE, draws the current field as white text on a black background. If the pR_wIN_EMPHASISED flag is set in win. flags, and mfne. selected is not TRUE, draws a cursor in the current field. Otherwise draws the editable value with no cursor and no highlight. Note that the text string pointed to by mine .dstr is not updated before it is drawn. To update and draw the text string the 1g_self_check method should be called instead. VOID wn_set (VOID) ; Set mfe.selected to TRUE, make a direct call to the 1g_se1f_check method with an argument of rRuE and evaluate mnfe.totWidth. The method calls p_leave with an argument of &_cEN_arc if the lower limit of any field exceeds its upper limit. VOID wn_emphasise(UINT flag); If £1ag is TRUE emphasize the control, otherwise de-emphasise the control. If £1ag is TRUE, emphasises the control by oRing PR_WIN_EMPHASISED into win. flags and setting the current field index to zero. Otherwise, clears pR_WIN_EMPHASISED in win. flags, and erases the cursor. In both cases an LG_DRaw message is sent before the method returns. LG_SENSE_ WIDTH INT lg_sense_width(VOID) ; Return the width in pixels required to draw the lodger window. The code is effectively: return (mnfe.totWidth*SYSTEM_FONT_NUM_WIDTH) ; Validate the current number INT lg_self_ check (INT can_defer) ; Validate each field and then update and draw the text string representing the editable value. 9-6 9 NUMERIC EDITORS —_————————S SSS NU MENE EDITORS The following conditions must be satisfied: e the vaiue member of each field must lie within the specified limits. A value member that is out of range is reset to the nearest limit. e the value member of each field must be greater than or equal to the value member of the previous field whenever that field has the mrne_seTs next flag set in its £1ags member. A value member that fails this condition is reset to the value member of the previous field. e the value member of each field must be less than or equal to the value member of the next field whenever that field has the mrwe_seTs_prev flag set in its £1ags member. A value member that fails this condition is reset to the value member of the next field. If the above conditions are satisfied and méne. changed is FALSE, the method returns LG_CHECK_OK. If the above conditions are satisfied and mfne.. changed is TRUE, the method returns LG_CHECK_OK_CHANGED. If one or more of the above conditions is not satisfied, and can_defer is TRUE, the method returns LG_CHECK_OK_CHANGED. Otherwise if one or more of the above conditions is not satisfied, the method makes a direct call to the mf_xange_beep method and then returns LG_CHECK_FAILED_CHANGED. In all cases the method updates and draws the text string representing the editable value. MF_RANGE BEEP = Showrrange iri VOID mf_range_beep (VOID) ; Give a warning beep and present the following message - "Out of range - reset to limit". HWIM REFERENCE MFNE subclass examples A basic subclass The peo class is provided as a simple illustration of the subclassing of the mrwe class. It is typical of the numeric editor classes described later in this chapter. The pemo control presents an offset followed by three characters that indicate whether the offset is relative or absolute. An example of a pemo control used as a dialog component is shown in the following pictures: Write to file { Write to file - Name Dump.dmp ¢ Internal+ : Disk Internal 'Fromoffset 1688 ‘Fromoffset 1880 ‘To offset 1286 Abs 'To offset 206 Rel The peno class is defined in a category file as follows: CLASS demo mfne ? { \ ADD wn_init REPLACE wn_set REPLACE wn_sense } The initial appearance of the control is specified in the resource file by the following control resource: RESOURCE CONTROL demo_control_res /* demo control resource */ { flags=DLGBOX_ITEM_APPL_CAT; class=C_DUMO; prompt="To offset"; info=LNCEDIT { low=0; high=65535; current=10; }; (The tnceprr struct is used for convenience.) The fields are initialised and property set in the wn_init method as follows (the wn_init method is called from within the pucBox class, before the dialog a1_dyn_init method ): METHOD VOID demo_wn_init(PR_DEMO *self,IN_LNCEDIT *pin_Incedit, PR_LWIN *landlord) { /* general settings */ self->lodger.landlord=landlord; self->mfine.selected=FALSE; self->mfne.cField=1; self->mfne.nField=2; /* in a 'real' application, trailing text would be read from a resource file */ p_scepy (&self->mfne.trail [0] [0], "Abs"); Pp_scpy (&self~->mfne.trail [1] [0],"Rel"); /* settings for first field */ self->mfne.f[0] .flags=MFNE_LEFT ALIGN; self->mfne.f [0] .value=pin_ncedit->value; self->mfne.f [0] .limits [MFNE_LOWER] =pin_ncedit->low; self->mfne.f[0] .limits [MFNE_UPPER] =pin_ncedit->high; self->mfne.f [0] .width=5; self->mfne.f£[0].separator=' '; 9 NUMERIC EDITORS NUMERIC EDITORS /* settings for second field */ self->mfne.f [1] . flags=MFNE_TRAILER|MFNE_SUPPRESS_SEPARATOR|MFNE_SUPPRESS LEADING; self->mfne.f[1] .value=0; self->mfne.£ [1] .limits [MFNE_LOWER] =0; self->mfne.f [1] .limits (MFNE_UPPER] =1; self->mfne.f [1] .width=3; p_supersend2 (self,O_ WN_SET); } The contents of the control are set and sensed as follows: METHOD VOID demo_wn_set (PR_DEMO *self,SE DEMO *pset) { if (pset->flags&SE_DEMO_VALUE_LONG) mfne.f [0] .value=pset->value_long; if (pset->flags&SE_DEMO_VALUE_TRAILER) mfine.£ [1] .value=pset->value_trailer; p_supersend2 (self,0_WN_SET) ; METHOD VOID demo_wn_sense(PR_DEMO *self,SE DEMO *psense) { psense->value_long=mfne.f [0] .value; psense->value_trailer=mfne.f [1] .value; } where the sE_pEno struct is defined as follows: typedef struct { LONG value_long; LONG value_trailer; } Extended range date editor control The pate class is provided as an illustration of the subclassing of the mene class and is somewhat more complex than the pEmo class described above. The patE control presents an editable date consisting of the day, the month and the year and improves on the preprr control by providing a wider range of allowed dates. Whereas preprr is restricted to an earliest displayable date of 01/01/1980, the pars class can display dates in the range 01/01/1900 to 31/12/2154 inclusive. An example of a pare control used as a dialog component is shown in the following picture: ( Current date pay 6271988 Note that an application which wishes to use the pars class must declare the class number by including the following line in its .re file: _C_DATE As the use of the pare class is non-trivial, the C SDK disks include an example application, installable into a \sibosdk\hwimdemo\ directory, which uses the pate class. The example dialog shown above may be defined using the following resource: RESOURCE DIALOG date_dl_res { title="Current date"; flags=DLGBOX_NOTIFY_ENTER; controls= { CONTROL { class=C_DATE; flags=DLGBOX_ITEM_CENTRE|DLGBOX_ITEM_APPL_CAT; } }; HWIM REFERENCE The piGsox_1TEm_appi_cart flag indicates that the pare class is supplied by the application. The parte class is defined as follows: CLASS date mfne { REPLACE wn_init REPLACE wn_set REPLACE wn_sense REPLACE lg_self_check PROPERTY { WORD dType; UINT day; UINT month; UINT year; ULONG max; } } The significance of the above property is as follows: aType may contain one of the following values: E_DATE_EUROPE - specifies that the date is displayed as day, month and year. E_DATE_USA - specifies that the date is displayed as month, day and year. E_DATE_JAPAN - specifies that the date is displayed as year, month and day. This property is set by the wn_init method. day specifies the index of the field which displays the current day. month specifies the index of the field which displays the current month. year specifies the index of the field which displays the current year. max specifies the maximum allowed date in days elapsed since 1/1/1900. This property is set by the wn_init method. The fields are initialised and property set in the wn_init method, as follows (the wn_init method is called from within the picBox class, before the dialog 41_dayn_init method ): LOCAL _C VOID InitField(PR_DATE *self,UINT i,LONG val,LONG min,LONG max, UBYTE width) { self->mfne.f [i] .value=val; self->mfne.f [i] .limits [MFNE_LOWER] =min; self->mfne.f[i] .limits [MFNE_UPPER) =max; self->mfne.f [i] .width=width; } LOCAL_C VOID DayMonthYear(PR_DATE *self,INT i,INT j,INT k) { self->date.day=i; self->date.monthsj; self->date.year=k; } 9 NUMERIC EDITORS SO NUMERIC EDITORS #pragma METHOD_CALL METHOD VOID date_wn_init (PR_DATE *self,VOID *par,PR_WIN *landlord) { P_DAYSEC ds; P_DATE dt; E_CONFIG cfg; p_getctd(&cfg) ; self->lodger.landlord=landlord; self->mfne.selected=FALSE; self->mfne.changed=FALSE; self->mfne.cField=0; self->mfne.nField=3; self->mfne.f£[0] .separator=cfg.dateSeparator; self->mfne.f [1] .separators=cfg.dateSeparator; self~>mfne.f [2] .flags=MFNE_SUPPRESS_ SEPARATOR; self->date.dType=cfg.dateType; if (self->date.dType==E_DATE EUROPE) DayMonthYear(self,0,1,2); else if (self->date.dType==E_DATE_USA) DayMonthYear (self,1,0,2); else if (self->date.dType==E_DATE_JAPAN) DayMonthYear (self,2,1,0); InitField (self, self->date.day,1,1,31,2); InitField(self,self->date.month,1,1,12,2); InitField (self, self->date.year,1,1900,2154,4); dt.year=254; dt .month=11; dt .day=30; dt. hour=dt .minute=dt.second=dt .yrday=0; p_dttods (&dt, &ds) ; self->date.max=ds.day; } The contents of the control are set and sensed as follows: METHOD VOID date_wn_set (PR_DATE *self,ULONG *par) { P_DAYSEC ds; P_DATE dt; ds.day=*par; ds.sec=0; if (ds.day>self->date.max) ds .day=self->date.max; p_dstodt (&ds, &dt) ; self->mfne.f[self->date.day].value=dt-day+1; self->mfne.f[self->date.month] .value=dt.month+1; self->mfne.f[self->date.year] .value=dt.year+1900; p_supersend2 (self,O_WN_SET) ; METHOD VOID date_wn_sense(PR_DATE *self,ULONG *par) { P_DATE at; P_DAYSEC ds; dt .second=0; dt.minute=0; dt .hour=0; dt .day=self->mfne.f ({self->date.day] .value-1; dt .month=self->mfne.£ [self->date.month] .value-1; dt .year=self->mfne.f [self->date.year] .value-1900; p_dttods (&dt, &ds) ; *parsds.day; } HWIM REFERENCE The validity of the current date is checked as follows: METHOD INT date_lg_self_check(PR_DATE *self,INT can_defer) { INT ret; INT days; xet=p_supersend3 (self,O LG SELF CHECK, can_defer) ; if ((can_defer==FALSE) && (ret==LG_CHECK_OK_CHANGED) ) { days=p_dayinm( (INT) self->mfne.f {self->date.year] .value-1900, (INT) self->mfne.f [self->date.month]) .value-1) ; if (self->mfne.f[self->date.day] .value> (LONG) days) { hBeep () ; self->mfne.cField=self->date.day; self->mfne.f[self->date.day] . value= (LONG) days; p_supersend3 (self,O_ LG SELF_CHECK, TRUE) ; hinfoPrint (MONTH_DAY_RESET) ; ret=LG_CHECK_FAILED CHANGED; } } return (ret) ; } The MONTH_DAY_RESET resource used by the 1g_self_check method is defined as follows: RESOURCE STRING month_day_reset { str="Day exceeds days in month: reset"; } The dialog resource shown above may be used with the following parepLc example dialog class: CLASS datedlg dlgbox { REPLACE dl_item_new REPLACE dl_dyn_init REPLACE dl_key } An instance of the pate class is created by the d1_item_new method as follows: METHOD VOID *datedlg_dl_item_new(PR_DATEDLG *self,AD_DLGBOX *par) { return (f_new(CAT_DAT_DAT,par->class)); } The dialog is dynamically initialised and its contents sensed before closing using the d1_ayn_init and dl_key methods as follows: METHOD VOID datedlg_dl_dyn_init(PR_DATEDLG *self) { P_DAYSEC ds; p_send4(((PR_DATWIN *)w_ws->wserv.cli) - >datwin.time,O TO SENSE, SENSE_TIME_DAYSEC, &ds) ; p_send4 (self,O_WN_SET,1,&ds.day) ; } METHOD INT datedlg_dl_key(PR_DATEDLG *self,INT index,INT keycode) { P_DAYSEC ds; PR_DATWIN *cli; p_send4 (self,O_WN_SENSE,1, &ds.day) ; ds.sec=0; cli=(PR_DATWIN *)w_ws->wserv.cli; £_leave (p_send4 (cli->datwin.time,O_TO_SET,SET_TIME_DAYSEC, &ds) ); return (WN_KEY CHANGED) ; 9 NUMERIC EDITORS Se ee eee eee LNCEDIT a flags landlord i offset width selected cField nField totWidth cPos changed eStr dstr trail £ dese} wn_calc_ position wn_connect wn_dodraw destroy —ind wn_visible 1g_draw wn_key wn_draw VECSGE wn_emphasise 1lg_sense_width lg_self_check mf_range_beep lg_set_id_ pos wn_position wn_redraw wn_sense_help te-sense—width ig_update A long numeric editor control can be included in a dialog via the appropriate control resource. The following example would be suitable for the dialog illustrated in the above picture: RESOURCE DIALOG demonstration { title="Demonstration"; flags=DLGBOX_NOTIFY_ENTER; controls= { title="Demonstration"; flags=DLGBOX_NOTIFY_ENTER; CONTROL { class=C_LNCEDIT; prompt="LONG" ; info=LNCEDIT { low=1; high=700000; current=500000; ); HWIM REFERENCE The tncenrt struct is defined in Awim.rh as: STRUCT LNCEDIT { LONG current=0; LONG low=0; LONG high=10000000; } Thus the example long numeric editor contro] has replaced the values assigned to the current, low and high members. Class definition Defined in sub-category file ncedit.cl (generated header file ncedit.g). CLASS lncedit mfne Single field long numeric editor { REPLACE wn_set set data REPLACE wn_sense sense value REPLACE wn_init initialise editor CONSTANTS { SE_LNCEDIT_VALUE 0x02 SE_LNCEDIT_LOW 0x02 SE_LNCEDIT_HIGH 0x04 } TYPES { typedef struct { LONG value; LONG low; LONG high; } IN_LNCEDIT; typedef struct { LONG value; LONG low; LONG high; UWORD flags; } SE_LNCEDIT; } Property There is no property associated with the tyceprrt class. LNCEDIT methods VOID wn_init (IN_LNCEDIT *init,PR_WIN *landlord) ; Initialise the long numeric editor from the In_LNcEDIT struct pointed to by init, and write landlora, the handle of the owning landlord window, to ledger. landlord. The In_LNCEDIT struct is defined as follows: typedef struct { LONG value; LONG high; LONG low; } IN_LNCEDIT; 9 NUMERIC EDITORS The members of the 1In_tnceprt struct have the following significance: value the initial value for the editable Lonc. high the upper limit for the editable ton. low the lower limit for the editable Lonc. SET ee oe | . Set data = alle VOID wn_set (SE_LNCEDIT *set) ; Set the long numeric editor according to the content of the sz_LNcEDIT struct pointed to by set. The se_incep1T struct is defined as follows: typedef struct { LONG value; LONG high; LONG low; UWORD flags; } SE_LNCEDIT; The setting is controlled by oring one or more of the following flags into the £1ags member of the SE_LNCEDIT struct SE_LNCEDIT_VALUE indicates that the editable value is to be set SE_LNCEDIT_HIGH indicates that the upper limit is to be set SE_LNCEDIT_LOW indicates that the lower limit is to be set VOID wn_sense (LONG *sense) ; Write the current value of the long numeric editor to the Lone pointed to by sense. HWIM REFERENCE NCEDIT flags landlord selected i offset cPield width nField totWidth cPos changed eStr dStr trail £ wn_calc_position wn_connect wn_dodraw destroy —tnd wn_visible lg_draw wn_key wn_draw wh—set wn_emphasise lg_sense_width 1g_self_check mf£_range_beep lg_set_id_pos wn_position wn_redraw wn_sense_help igsesse dekh lg_update The unsigned word numeric editor presents an editable value of type uworp as illustrated in the following picture: Position to-do entry | An unsigned word numeric editor control can be included in a dialog via the appropriate control resource. The following example would be suitable for the dialog illustrated in the above picture: RESOURCE DIALOG demonstration { title="Position to-do entry"; flags=DLGBOX_NOTIFY_ENTER; controls= { CONTROL { class=C_NCEDIT; prompt="Position within list"; info=NCEDIT { low=1; high=100; current=1; }; 9 NUMERIC EDITORS —_. EF NUMERIC EDITORS: The ncep1r struct is defined in Awim.rh as: STRUCT NCEDIT { UWORD current=0; UWORD low=0; UWORD high=65535; } Thus the example unsigned word numeric editor control (see above) has replaced the values assigned to the current, low and high members. Class definition Defined in sub-category file ncedit.cl (generated header file ncedit.g). CLASS needit Incedit Single field unsigned word numeric editor { REPLACE wn_set REPLACE wn_sense REPLACE wn_init CONSTANTS { SE_NCEDIT_VALUE 0x01 SE_NCEDIT_LOW 0x02 SE_NCEDIT_HIGH 0x04 } TYPES { typedef struct { UWORD value; UWORD low; UWORD high; } IN_NCEDIT; typedef struct { UWORD value; UWORD low; UWORD high; UWORD flags; } SE_NCEDIT; } Property There is no property associated with the nceprr class. ht a er a ares NCEDIT methods Initialise VOID wn_init(IN_NCEDIT *init,PR_WIN *landlord) ; Initialise the unsigned word numeric editor from the 1n_nceprT struct pointed to by init, and write landlord, the handle of the owning landlord window, to 1odger. landlord. The IN_NcEDIT struct is defined as follows: typedef struct { UWORD value; UWORD low; UWORD high; } IN_NCEDIT; HWIM REFERENCE The members of the 1n_NcEprT struct have the following significance: value the initial value for the editable uworp high the upper limit for the editable uworp low the lower limit for the editable uworp =F — : | Set new values VOID wn_set(SE_NCEDIT *set) ; Set the unsigned word numeric editor according to the content of the s=_nceprT struct pointed to by set. The se_NceEn1T struct is defined as follows: typedef struct { UWORD value; UWORD high; UWORD low; UWORD flags; } SE_NCEDIT; The setting is controlled by oring one or more of the following flags into the £1ags member of the SE_NCEDIT struct: SE_NCEDIT_VALUE indicates that the editable unsigned word is to be set SE_NCEDIT_HIGH indicates that the upper limit of the editable unsigned word is to be set SE_NCEDIT_LOW indicates that the lower limit for the editable unsigned word is to be set VOID wn_sense(UWORD *sense) ; Write the current value of the editable unsigned word to the uworp pointed to by sense. 9 NUMERIC EDITORS WNCEDIT landlord selected offset cField width nField totWidth cPos changed eStr dsStr trail £ destrey destroy wn_key wn_cale_ position wh-init wn_draw wn_connect wn_visible wn—set wn_dodraw lg_draw wn_emphasise tg—selfi—cheek lg_sense_width lg_set_id_pos lg_self_check wn_position mf_range_beep wn_redraw wn_sense_help lg_update A word numeric editor control can be included in a dialog via the appropriate control resource. The following example would be suitable for the dialog illustrated in the above picture: RESOURCE DIALOG demonstration { title="Montreal"; flags=DLGBOX_NOTIFY_ENTER; controls= { CONTROL { class=C_WNCEDIT; prompt="Temperature"; info=WNCEDIT { current=-100; 3 }; } The wnceptT struct is defined in hwim.rh as: STRUCT WNCEDIT { WORD current=0; WORD low=-32768; WORD high=32767; } HWIM REFERENCE ee Thus the example word numeric editor control (see above) has replaced the value assigned to the current member. Class definition Defined in sub-category file ncedit.cl (generated header file ncedit.g). CLASS wnecedit Incedit Single field word numeric editor { REPLACE wn_set REPLACE wn_sense REPLACE wn_init CONSTANTS { SE_WNCEDIT_VALUE 0x01 SE_WNCEDIT_LOW 0x02 SE_WNCEDIT_ HIGH 0x04 } TYPES { typedef struct { WORD value; WORD low; WORD high; } IN_WNCEDIT; typedef struct { WORD value; WORD low; WORD high; WORD flags; } SE_WNCEDIT; } Property There is no property associated with the wnceprr class. Sa a ee ee ee ee a ee) WNCEDIT methods Initialise VOID wn_init(IN_WNCEDIT *init,PR_WIN *landlord) ; Initialise the signed word numeric editor from the 1n_wnceD1T struct pointed to by init, and write landlord, the handle of the owning landlord window, to 1odger . landlord. The In_wnczpzT struct is defined as follows: typedef struct { WORD value; WORD low; WORD high; } IN_WNCEDIT; The members of the 1n_wncen1T struct have the following significance: value the initial value for the editable worp high the upper limit for the editable worp low the lower limit for the editable worp 9 NUMERIC EDITORS —_——oe moe ENG EDITORS Set new values VOID wn_set(SE_WNCEDIT *set) ; Set the signed word numeric editor according to the content of the se_wnceprr struct pointed to by set. The sE_wNceptr struct is defined as follows: typedef struct { WORD value; WORD high; WORD low; WORD flags; } SE_WNCEDIT; The setting is controlled by oring one or more of the following flags into the £1ags member of the SE_WNCEDIT struct: SE_WNCEDIT_VALUE indicates that the editable value is to be set SE_WNCEDIT_HIGH indicates that the upper limit is to be set SE_WNCEDIT_LOW indicates that the lower limit is to be set WNSENSE —— Sunes Kawwalie VOID wn_sense(WORD *sense) ; Write the current value of the editable signed word to the worn pointed to by sense. HWIM REFERENCE DTEDIT flags landlord selected cal i offset cField dType width nField changed totWidth inSelfCheck cPos in changed eStr dstr trail £ destrey destroy wn_key wn_set wn_calc_position wh-init wn_draw wn_sense wn_connect wn_visible wh-set wn_init wn_dodraw lg_draw wn_emphasise wn_emphasise ig—self—eheek lg_sense_width wn_key ig_set_id_pos lg_self_check wn_position wn_redraw wn_sense_help mf£_range_beep ig-sense—vidés ig_update (Set time and date [4:28:03 pm tDate 1171871993 A date/time numeric editor control can be included in a dialog via the appropriate control resource. The following example would be suitable for the dialog illustrated in the above picture: 9 NUMERIC EDITORS __ OO NUMERIC EDITORS RESOURCE DIALOG demonstration { title="Set time and date"; flags =DLGBOX_NOTI FY_ENTER; controls= { CONTROL { class=C_DTEDIT; prompt="Time" ; info=DTEDIT { flags=IN_DTEDIT_HHMMSS; }i } ‘ CONTROL { class=C_DTEDIT; prompt="Date"; info=DTEDIT { flags=IN_DTEDIT_DDMMYyyy; }i }; } The preprr resource struct is defined in hwim.rh as: STRUCT DTEDIT { WORD flags; LONG current; LONG low; LONG high; } The example date/time numeric editor controls do not set initial values for the current, low and high members, but merely set appropriate values for f1ags. Note that any supplied values of current, low and high will only be used to initialise the control if the value rv_preprt_tntT is set in f1ags. If this value is not present, any values specified in the initialisation resource are ignored and the control is initialised with a set of standard values based on the current time and date. The format of the display is controlled on initialisation by setting one of the following flags into the flags member of the preprr struct: IN_DTEDIT_DDMMYYyy initialise as a date editor to display a date in day, month and year format: the current date is specified as days elapsed since 1/1/1900. IN_DTEDIT_HHMMSS initialise as a time editor to display a time as hours, minutes and seconds. The current time is specified in seconds elapsed since midnight. IN_DTEDIT_HHMM initialise as a time editor to display a time as hours and minutes. The current time is specified as seconds elapsed since midnight. IN_DTEDIT_HHMMSS_D initialise as a time editor to display a duration as hours, minutes and seconds. The current duration is specified in seconds. IN_DTEDIT_HHMM_D initialise as a time editor to display a duration as hours and minutes. The current duration is specified in seconds. IN_DTEDIT_HHMMSS_ND initialise as a time editor to display a negative duration as hours, minutes and seconds. The current duration is specified in seconds. IN_DTEDIT_HHMM_ND initialise as a time editor to display a negative duration as hours and minutes. The current duration is specified in seconds. Note: on the Series 3a version of the preprt class the user may select the required date by pressing the Tab key to obtain a calendar view. (The calendar view is implemented by the canwrn class.) This is especially convenient for selecting, for example, the first Monday in a given month. HWIM REFERENCE eee Class definition Defined in sub-category file dtedit.cl (generated header file dtedit.g). On the Series 3a the class definition is as follows: CLASS dtedit mfne Date, Time and Duration editor based on the MFNE. { REPLACE wn_set REPLACE wn_sense REPLACE wn_init REPLACE wn_emphasise REPLACE 1g_self_check REPLACE wn_key CONSTANTS { SE_DTEDIT_VALUE 0x01 SE_DTEDIT_LOw 0x02 SE_DTEDIT_HIGH 0x04 PR_DTEDIT_DATE 0x0000 PR_DTEDIT_TIME 0x0100 PR_DTEDIT_DURATION 0x0200 PR_DTEDIT_SECONDS ox1000 PR_DTEDIT_ NEGATIVE 0x2000 PR_DTEDIT_AMPM 0x4000 PR_DTEDIT_NEG_DURATION (PR_DTEDIT_DURATION|PR_DTEDIT NEGATIVE) IN_DTEDIT_INIT (SE_DTEDIT_VALUE | SE_DTEDIT_LOW|SE_DTEDIT_HIGH) IN_DTEDIT_DDMMYYYY (PR_DTEDIT_DATE) IN_DTEDIT_HHMMSS (PR_DTEDIT_TIME|PR_DTEDIT_SECONDS) IN_DTEDIT_HHMM (PR_DTEDIT_TIME) IN_DTEDIT_HHMMSS_D (PR_DTEDIT_TIME|PR_DTEDIT_DURATION|PR_DTEDIT_ SECONDS) IN_DTEDIT_HHMM_D (PR_DTEDIT_TIME|PR_DTEDIT_DURATION) IN_DTEDIT_HHMMSS_ND (PR_DTEDIT_TIME|PR_DTEDIT_NEG_DURATION|PR_DTEDIT_SECONDS) IN_DTEDIT_HHMM_ND (PR_DTEDIT_TIME|PR_DTEDIT_NEG DURATION) } TYPES { typedef struct { UWORD flags; type of edit box LONG value; LONG low; LONG high; } IN_DTEDIT; typedef struct { UWORD flags; LONG value; LONG low; LONG high; } SE_DTEDIT; } PROPERTY 1 { VOID *cal; WORD dType; UBYTE changed; UBYTE inSelfCheck; IN_DTEDIT in; } } On the Series 3 the class definition differs in that: e the wn_emphasise and wn_key methods are not replaced. 9 NUMERIC EDITORS e the dtedit.cai property is absent. Property dtedit.cal this is either the handle of an instance of the canwrn class or NuLL. The caLwIn object provides a graphical calendar view. Note:on the Series 3 this item of property is absent. dtedit.dType specifies the system date format: may be one of either = pare _evRopE for day/month/year, &_paTe_usa for month/day/year or E_DATE_JAPAN for year/month/day. dtedit.changed see the description of the w_sense and 1g_self_check methods. dtedit.inSelfCheck not used. dtedit.in an IN_DTEDIT struct that contains the current editable value, the upper and lower limits and the initialisation flag he a ee SS — ee ey eee DTEDIT methods WN oe eee ees “Waiianee VOID wn_init(IN_DTEDIT *init,PR_WIN *landlord) ; Initialise the date/time numeric editor from the 1n_prep1T struct pointed to by init, and write landlord, the handle of the owning landlord window, to 1odger. landlord. Set dtedit .dType according to the current system setting. The In_DtTep1T struct is defined as follows: TYPEDEF STRUCT { WORD flags; LONG current; LONG low; LONG high; } IN_DTEDIT; The members of the rn_preprr struct have the following significance: flags a combination of initialisation flags, as described below current the initial value for the editable date/time high the initial upper limit for the editable date/time low the initial lower limit for the editable date/time The appearance and behaviour of the date/time editor is specified by assigning one of the following flags into the flags member (note that the system will automatically display the time in am/pm or 24 hour format according to the current system settings): IN_DTEDIT_DDMMYYYY initialise as a date editor to display a date in day, month and year format: the current, low and high dates are specified as days elapsed since 01/01/1900. Note that the control can not display dates before 01/01/1980. IN_DTEDIT_HHMMSS initialise as a time editor to display a time as hours, minutes and seconds. The current, low and high times are specified in seconds elapsed since midnight. Whole days are ignored, so these values could also be supplied in system time format. IN_DTEDIT_HHMM initialise as a time editor to display a time as hours and minutes. The current, low and high times are specified in seconds elapsed since midnight. Whole days are ignored, so these values could also be supplied in system time format. HWIM REFERENCE See eSeeeeSeeeEeeeSeeSeSeSSSSSSSSSSSsFsFeFsFsSFSSsSSSSsSSees IN_DTEDIT_HHMMSS D initialise as a time editor to display a duration as hours, minutes and seconds. The current, low and high durations are specified in seconds. Whole days are ignored, so these values could also be supplied in system time format. IN_DTEDIT_HHMM_D initialise as a time editor to display a duration as hours and minutes. The current, low and high durations are specified in seconds. Whole days are ignored, so these values could also be supplied in system time format. IN_DTEDIT_HHMMSS_ND _initialise as a time editor to display a negative duration as hours, minutes and seconds. The current, low and high durations are specified in seconds. Whole days are ignored, so these values could also be supplied in system time format. IN_DTEDIT_HHMM_ND initialise as a time editor to display a negative duration as hours and minutes. The current, low and high durations are specified in seconds. Whole days are ignored, so these values could also be supplied in system time format. Any supplied values of current, low and high will only be used to initialise the control if the value IN_DTEDIT_INiT is ored into f1ags (in which case all three values must be supplied). If this value is not present, any values specified in the initialisation resource are ignored and the control is initialised with a set of standard values, dependent on the value of flags, as follows: IN_DTEDIT_DDMMYYYY The upper and lower limits are set to the dates 01/01/1980 and 31/12/2049 respectively, and the current value is set to today's date. IN_DTEDIT_HHMMSS The upper and lower limits are set to the times 00h00m(00s) and IN_DTEDIT_HHMM 23h59m(59s) respectively, and the current value is set to the time of day. IN_DTEDIT_HHMMSS_D IN _DTEDIT_HHMM_D IN_DTEDIT_HHMMSsS_ND The upper and lower limits are set to the times -23h59m(59s) and IN_DTEDIT_HHMM_ND 23h59m(59s) respectively, and the current value is set to the time of day. VOID wn_set (SE_DTEDIT *set) ; _ Set new values Set the date/time editor according to the content of the sz_pTEprT struct pointed to by set. The se_preEpzT struct is defined as follows: typedef struct { UWORD flags; LONG value; LONG low; LONG high; } SE_DTEDIT; The property to be set is indicated by oring one or more of the following flags into the £1ags field of the above struct. SE_DTEDIT_VALUE indicates that the current value is to be set. SE_DTEDIT_LOW indicates that the lower limit is to be set. SE_DTEDIT_HIGH indicates that the upper limit is to be set. The interpretation of the values of value, low and high in the sz_preprr struct depends on the type of data that the control has been initialised to display. See the explanation of the IN_DTEDIT_xxx flags in the description of the wm_init method. Sense value VOID wn_sense(SE_DTEDIT *sense) ; Write the current value of the editable date/time to the value member of the s—_preprr struct pointed to by sense. Note that the method does not write to sense->flags, sense->low OF sense->high. 9-26 9 NUMERIC EDITORS The interpretation of value depends on the type of data that the control has been initialised to display. See the explanation of the 1n_pTep1T_xxx flags in the description of the m_init method. If the editable value is a date, and the day is outside the allowed range, resets the day to the last of the month and sets dtedit . changed to FALSE, otherwise sets dtedit . changed to TRUE. VOID wn_key (INT keycode, INT modifiers) ; le a keypress Handle a keypress. If dtedit.cal is non-zero: e — sends the keypress to the calendar view by sending a wn_kEy message with arguments of keycode and modifiers. e if the keypress cancels the calendar view, i.e. the return value is ww_KEY_CANCELLED, removes the calendar view by sending a pestroy message to dtedit .cal and then writes zero to dtedit .cal. e — if the keypress selects the current date, i.e the return value is ww_KEY_CHANGED, senses the current date in the calendar view, sets this as the current date in the preprr control, removes the calendar view by sending a DESTRoy message to dtedit .cal and then writes zero to dtedit.cal. Otherwise if keycode is w_KEY_TAB and the control is not a time editor - i.e. dtedit . flags does not contain PR_DTEDIT_TIME - and w_ws->wserv. flags contains PR_WSERV_FULLSCREEN: e validates the current date in the prepzT control by sending self an LG_SELF_CHECK message and, if the return value is neither L¢_CHECK_OK nor LG_CHECK_OK_CHANGED, returns. ® creates an instance of the canwin class and writes the handle to dtedit.cal. © initialises the calendar view by sending a wn_1nrT message to dtedit .cal. The calendar view is centred. The current date is set to the current date in the prEp1T control. The number of months displayed is equal to twelve if modifiers contains w_CTRL_MODIFIER, three if modifiers contains W_SHIFT_MODIFIER, or one otherwise, Otherwise supersends a wN_KEY message with arguments of keycode and modifiers and returns the return value. Note: on the Series 3 this method is not replaced. ws VOID wn_emphasise (INT flag); Emphasise the control or calendar view if £1ag is rrug, otherwise de-emphasise the control or calendar view. If dtedit .cal is non-zero, sends a wN_EMPHASISE message to dtedit .cal with an argument of flag. Otherwise supersends a wN_EMPHASISE message with an argument of flag. Note: on the Series 3 this method is not replaced Validate values and fields INT 1lg_self_ check (VOID) ; Validate the current date/time and the fields. Supersends an LG_SELF_CHECK message and return either its return value, or alternatively -1 if either of the following are true: e the editable value is outside of the allowed limits in which case reset to its nearest limit and sends an MF_RANGE_BEEP message. © dtedit.changed is TRUE in which case sends an MF_RANGE_BEEP message. HWIM REFERENCE ae ee EE SS ee eee LLEDIT landlord selected offset cField width nField totWidth cPos changed eStr dstr trail £ destrey destroy wn_key wn_calc_position whoinit wn_draw wn_connect wn_visible wnaset wn_dodraw 1lg_draw wn_emphasise wh-emphasise te—seit—eheek ig_sense_width wa-key lg_set_id_pos 1g_self_check wn_position mf£_range_beep wn_redraw ig—sense—width wn_sense_help ig_update Denmark "Longitude 618°16E ‘Latitude 656°H8 N 4 ‘Area code ‘GMT offset 1:80 i :Zone European A latitude/longitude editor control can be included in a dialog via the appropriate control resource. The following example would be suitable for a dialog with a title and two latitude/longitude controls: oa 9 NUMERIC EDITORS a, RESOURCE DIALOG demonstration { title="Set latitude and longitude"; flags=DLGBOX_NOTIFY_ENTER; controls= } { CONTROL { class=C_LLEDIT; prompt="Latitude"; info=LLEDIT { flags=IN_LLEDIT_LATITUDE; current=3368; }; }, CONTROL { class=C_LLEDIT; prompt="Longitude" ; info=LLEDIT { flags=IN_DTEDIT_LONGITUDE; current=33968; }; }i The nueprrT struct is defined in hwim.rh as: STRUCT LLEDIT { WORD flags; WORD value=0; } The latitude/longitude value is specified in minutes of arc: a positive sign indicating a latitude/longitude in the northern /western hemisphere, and a negative sign indicating a latitude/longitude in the southern /eastern hemisphere. Thus -604 corresponds to a latitude of 10° 4 S or a longitude of 10° 4 E. The behaviour of a latitude/longitude editor is specified by assigning one of the following flags to the flags member. IN_LLEDIT_LATITUDE IN_LLEDIT_ LONGITUDE Class definition Defined in sub-category file //edit.cl (generated header file /edit.g). CLASS Latitude,Longitude editor based on the MFNE. lledit mfne REPLACE wn_set REPLACE wn_sense REPLACE wn_init CONSTANTS { IN_LLEDIT_LATITUDE i) IN_LLEDIT LONGITUDE 1 } display value as a latitude. display value as a longitude. 9-29 HWIM REFERENCE en eee TYPES { typedef struct { WORD flags; WORD value; } IN_LLEDIT; typedef struct { WORD value; } SE_LLEDIT; } Property There is no property associated with the LuzprrT class. SS nS eee LLEDIT methods Initialise VOID wn_init(IN_LLEDIT *init,PR_WIN *landlord) ; Initialise the latitude/longitude editor from the 1n_LLEDIT struct pointed to by init, and write landlord, the handle of the owning landlord window, to 1odger. landlord. The 1n_LLEprT struct is defined as follows: typedef struct { WORD flags; WORD value; } IN_LLEDIT; The behaviour of a latitude/longitude editor is specified by assigning one of the following flags to the flags member: IN_LLEDIT_LATITUDE value is to be displayed as a latitude IN_LLEDIT_LONGITUDE value is to be displayed as a longitude Note that the behaviour of a latitude/longitude editor can not be changed once it has been initialised, The value member of the 1n_LLEDrT struct specifies the angle in units of arc minutes. A positive sign indicates that the angle is either a northern latitude, or a western longitude depending on the editors initialisation flag. Otherwise the angle is either a southern latitude or an eastern longitude. _ Set new values VOID wn_set (SE_WNCEDIT *set) ; Set the current angle of the latitude/longitude editor to the value member of the SE_LLEDIT struct which is pointed to by set. The sz_LuEDIT struct is defined as follows: typedef struct { WORD value; } SE_LLEDIT; See above for a description of the value member. 9 NUMERIC EDITORS eee NUMERIC EDITORS Sense current value VOID wn_sense(SE_LLEDIT *sense) ; Write the current value of the latitude/longitude editor to the value member of the SE_LLEDIT struct pointed to by sense. The sE_LLEDIT struct is defined as follows: typedef struct { WORD value; } SE_LLEDIT; See above for a description of the value member. RGEDIT landlord offset width selected cField nField totWidth cPos changed eStr dstr trail £ wn_calc_position wn_connect wn_dodraw wn_position wn_redraw wn_sense_help destroy —ins wn_visible lg_draw itg—seit—eheeck 1g_set_id_pos lg_update wn_key wn_draw wh—set wn_emphasise ig_sense_width 1g_self_check mf£_range_beep A range numeric editor control can be included in a dialog via the appropriate control resource. The following example would be suitable for the dialog shown in the above picture: HWIM REFERENCE eC oS RESOURCE DIALOG demonstration { title="Define"; £lags=DLGBOX_NOTIFY_ENTER; controls= { CONTROL { class=C_RGEDIT; prompt="Age range"; info=RGEDIT { value_1=30; value_2=60; }; }; } The rcpt struct is defined in hwim.rh as: STRUCT RGEDIT { WORD low=1; WORD value_1l=1; WORD value_2=9999; WORD high=9999; } where value_1 must be not greater than value_2 and both values must be not less than low, and not greater than high. Class definition Defined in sub-category file rgedit.cl (generated header file rgedit.g). CLASS rgedit mfne Range editor based on the MFNE. { REPLACE wn_set REPLACE wn_sense REPLACE wn_init CONSTANTS { SE_RGEDIT_LOW 0x01 SE_RGEDIT _VALUE_1 0x02 SE_RGEDIT VALUE 2 0x04 SE_RGEDIT_HIGH 0x08 IX_RGEDIT_LOw ft) /* Indices into value */ IX_RGEDIT_VALUE_1 1 IX_RGEDIT_VALUE_2 2 IX_RGEDIT_HIGH 3 } TYPES { typedef struct { UWORD value [4] ; } IN_RGEDIT; typedef struct { UWORD value [4] ; UWORD flags; } SE_RGEDIT; } PROPERTY { IN_RGEDIT in; 9 NUMERIC EDITORS Property rgedit.in not used. mS ae Eee Se SS See RGEDIT methods Ogee 7 Initialise VOID wn_init (IN_RGEDIT *init, PR_WIN *landlord) ; Initialise the range numeric editor from the 1n_RcEDIT struct pointed to by init, and write landlord, the handle of the owning landlord window, to 1odger landlord. The in_RGEp1T struct is defined as follows: typedef struct { UWORD value [4]; } IN_RGEDIT; The value array is indexed as follows: IX_RGEDIT_LOW index of lower limit in value array. IX_RGEDIT_VALUE_1 index of lower current value in value array. IX_RGEDIT_VALUE_2 index of upper current value in value array. IX_RGEDIT_HIGH index of upper limit in value array. VOID wn_set (SE_RGEDIT *set) ; Set the current values in the range editor to those specified by the sz_RGEDIT struct pointed to by set. The sE_RGEpDIT struct is defined as follows: typedef struct { UWORD value [4] ; UWORD flags; } SE_RGEDIT; The value array is indexed as explained above. The property to be set is indicated by oring one or more of the following flags into the flags field of the above struct. SE_RGEDIT_LOW indicates that the lower limit is to be set. SE_RGEDIT_VALUE_1 indicates that the current lower value is to be set. SE_RGEDIT_VALUE_2 indicates that the current upper value is to be set. SE_RGEDIT_HIGH indicates that the upper limit is to be set. Sense new value VOID wn_sense(SE_RGEDIT *sense) ; Write the current values and the limits of the range editor to the sE_RGEDIT struct pointed to by sense. The sE_RGeprT struct is defined above. CHAPTER 10 TEXT EDITORS This chapter documents the text editor classes. These classes are: EDWIN The superclass for the majority of text editor windows. It is a lodger window that provides a wide range of facilities for the formatted display of editable text. FLTEDIT A dialog control that allows the user to edit a floating point number. PUNCTUED A dialog contro] that allows the user to select a punctuation character. XEDIT A dialog control allowing secret text entry - a password, for example. Precursors Familiarity with the following topics will aid the understanding of this chapter: e the wrn and Lopcer classes described in the Windows chapter, e the Eppoc and Eprpoc classes described in the FORM Reference manual, e the scriay and scric classes described in the FORM Reference manual, e use of the Series 3 Word application. Class diagram ‘ win ; a f Lae as 1 iaenancat ow i re 7 Am or ~ f iB ~~ a pA I is oA ‘ é ‘a 4 pone SN. t % ie ~~ 1 od ; ons ae eee j ON 1 ? ie / gerlay ~} af i SAL 1 > : Paeics ane poker ae Fy . a / xedit > 2 edwin > poe len PS 1 os Ope ot 7 do Cc x ' ~ v2 ’ + es s ‘ t Mee feet x > : = Mabe : Pao ee A gas” on ’ i> . / punctued * / fitedit > vA if if if 4 A ‘ . l ~ . The document class doc may be (a subclass of) either of the FORM classes Eprpoc or EPDOC, or it may be an application-specific class that is compatible with these classes. See the Formatted Document Classes chapter of the FORM Reference manual for further details. 10-1 HWIM REFERENCE wn_calc_position wn_connect wn_dodraw wn_position wn_redraw landlord offset width destrey wn_visible 1lg_draw 1g_self_check lg_update scrimg scrlay doc cpos clen clip destroy wn_init wn_key wn_draw wn_sense_help wn_set wn_sense wn_emphasise lg_set_id_pos 1g_sense_width ew_sense_size ew_set_size ew_set ew_sense ew_insert select change flags margins font ew_snuggle_insert ew_set_font ew_leave ew_find ew_replace ew_evaluate ew_replace_ clip ew_paste_clip ew_bring_ in ew_ep_insert ew_return_key ew_tab_key ew_init_style ew_readonly The Epwrn class provides the functionality of a window containing a formatted display of editable text. It is highly flexible since, in addition to being suitable for use as a simple one-line edit box ina dialog, it also supplies most of the basic functionality of a word processor. A subclass of epwrn is, for example, used by the Word application. Note that a tutorial introduction to the epwrn class may be found in the Edit Windows chapter of the Object Oriented Programming Guide. The edit window In general, the text in an edit window is arranged as a sequence of paragraphs. The text of each paragraph is automatically word wrapped within the window, as illustrated schematically in the following diagram: 10-2 This is an example paragraph in an edit window. The text is automatically wrapped and the first line is indented. Margins are present either side of the text region. This is the next paragraph containing one line only. This example edit window can display a maximum of six lines of text. Many more are not visible as they are out text region The margins can be altered by setting the edwin. margins property, and the size and position of the window can be altered by means of the ew_set_size method. Text lines The text lines in an edit window consist of text spaced out with top and bottom leading as illustrated in the following picture: 10 TEXT EDITORS top leading bottom leading (Note: leading derives from the metal used by typesetters.) The font ascent, font descent and font height are characteristics of the font and the font style: see the Window Server manual for details of fonts. The font and style are by default global to the document: defining local styles and fonts is described in the Object Oriented Programming manual. The top leading is the space at the top of the line whilst the bottom leading is the space at the bottom of the line. The space between two lines is thus the sum of the topa and bottom leading - i.e. the total leading. The leading is global . The font, the style, and the leading can be altered using the ew_set_font method. Cursor position The position of the text cursor is simply the index of the preceding character - thus a cursor placed at the start of the document has a position of zero whilst a cursor placed immediately after the one hundredth character in the document has a cursor position of one hundred. Line cursor The scrimc document imaging class divides the drawing area into three columns consisting of a labels margin, a line cursor margin and a text region: by default the width of the first two columns is set to zero in the wn_init method. However a line cursor, which indicates the current line, may be specified on initialisation. The effect is illustrated by, for example, the Word application's main edit window. Link paste An edit window can act as a link-paste client using the bring in method. It must however be subclassed to allow it to act as a link-paste server. For details of the link-paste mechanism see the Link Paste chapter of the Object Oriented Programming manual. Class definition Defined in sub-category file edwin.cl (generated header file edwin.g). CLASS edwin lodger Editable text window { REPLACE destroy REPLACE wn_init REPLACE wn_key REPLACE wn_draw REPLACE wn_sense_help REPLACE wn_set REPLACE wn_sense REPLACE wn_emphasise REPLACE lg_set_id pos REPLACE lg_sense_width 10-3 HWIM REFERENCE 10-4 ew_sense_size ew_set_size ew_set ew_sense ew_insert ew_snuggle_insert ew_set_font ew_leave ew_find ew_replace ew_evaluate ew_replace_clip ew_paste_clip ew_bring_in ew_ep_ insert ew_return_key=p false ew_tab_key=p_ false ew_init_style=p_dummy ew_readonly=p_true CONSTANTS { PR_EDWIN_DIALLABLE PR_EDWIN_ACCEPT_TABS PR_EDWIN_ACCEPT_SOFT_HYPHENS PR_EDWIN_AUTO_CUR_END PR_EDWIN_AUTO_SELECT PR_EDWIN_DOC_SUPPLIED PR_EDWIN CLIPBOARD PR_EDWIN_NOTIFY_OVERFLOW PR_EDWIN_READONLY IN_EDWIN_DIALLABLE IN_EDWIN_ACCEPT_TABS IN_EDWIN_ACCEPT_SOFT_HYPHENS IN_EDWIN_AUTO_CUR_END IN_EDWIN_NO_AUTOSELECT IN_EDWIN_DOC_SUPPLIED IN_EDWIN_CLIPBOARD IN_EDWIN_VULEN IN_EDWIN_VULEN_NOSCALE IN_EDWIN_VULEN_CHARACTERS IN_EDWIN_VULEN_PIXELS IN_EDWIN LEFT CURSOR IN_EDWIN_TEXT_ SEGMENTED IN_EDWIN POSITION SUPPLIED IN_EDWIN_FONT_SUPPLIED IN_EDWIN LEADING SUPPLIED IN_EDWIN_VISLINES SUPPLIED IN_EDWIN_PAGINATABLE SET_EDWIN_TXT SET_EDWIN_EMPTY SET_EDWIN_CUR_END SET_EDWIN SEL ALL SET_EDWIN_CURSOR SET_EDWIN_ANCHOR EWF_BACKWARDS 0x0001 EWF_CASESENS 0x0002 EW_CHANGE_SINCE_SAVED EW_CHANGE_SINCE_PAGINATE EW_CHANGE EW_BRING SINGLE_SHOT } 0x0001 0x0002 0x0004 0x0008 0x0010 0x0020 0x0040 0x0080 0x8000 Same as IN_EDWIN_VULEN PR_EDWIN_DIALLABLE PR_EDWIN_ACCEPT_TABS PR_EDWIN_ACCEPT_SOFT_HYPHENS (PR_EDWIN_AUTO_CUR_END|PR_EDWIN_AUTO_SELECT) PR_EDWIN_AUTO_SELECT PR_EDWIN_DOC_SUPPLIED PR_EDWIN_CLIPBOARD 0x0080 0x0100 IN_EDWIN_VULEN (IN_EDWIN_VULEN|IN_EDWIN_VULEN_NOSCALE) 0x0200 0x0400 0x0800 0x1000 0x2000 0x4000 0x8000 0x01 0x02 0x04 0x08 0x10 0x20 direction to scan (0=forwards, 1=back) TRUE iff case-sensitive search 0x01 0x02 Oxffft oxfo000 10 TEXT EDITORS AAT EDITORS TYPES { typedef struct { UWORD vulen; UWORD flags; UWORD maxlen; TEXT contents [1]; } IN_EDWIN; typedef struct { WORD total; WORD top; } EDWIN_LEADING; viewing length or width autoselect etc maximum number of characters allowed rest of initial contents follows in line typedef struct { UWORD vislines; number of lines visible in window P_POINT pos; top left offset relative to landlord WORD font; font ID UWORD style; font style EDWIN LEADING leading; total and top-only vertical leadings VOID *doc; document object to use VOID *clip; possible clipboard to use } IN_EDWIN_x; never used in edwins in dialogs typedef struct { TEXT *buf; UWORD len; } SE_EDWIN; typedef struct { UWORD flags; SE_EDWIN txt; UWORD cursor; UWORD anchor; } SET_EDWIN; cursor (moving point of select) anchor point (fixed end of select) typedef struct { UWORD cursor; UWORD anchor; } SENSE_EDWIN; cursor (moving point of select) anchor point (may equal cursor) } PROPERTY 2 { VOID *serimg; VOID *scrlay; VOID *doc; UWORD cpos; UWORD clen; VOID *clip; UWORD select; UWORD change; UWORD flags; screen imager screen layout document content current position total content clipboard TRUE if there is a select region holds EW_CHANGE_ flags holds PR_EDWIN_ flags SCRLAY_MARGINS margins; SCRLAY_FONT font; } } Property edwin.scrimg edwin.scrlay edwin.doc the handle of an instance of scrime: responsible for the screen display. See the Document Layout Classes chapter of the FORM Reference manual for details. the handle of an instance of scriay: responsible for document layout. See the Document Layout Classes chapter of the FORM Reference manual for details. the handle of an instance of eppoc or EPFDoc: contains the document text. See the Editable Documents chapter of the FORM Reference manual for details. _ OC COO SSS 10-5 HWIM REFERENCE edwin.cpos the current cursor position edwin.clen total length of the document ignoring the terminating zero edwin.clip the handle of an instance of EprLaT or EPSEG: contains the clipboard text edwin.select TRUE if a region of text is selected, raLsE otherwise edwin. change set to indicate that the document has been edited: it is the responsibility of the application to reset this to FaLsE once the changes have been recorded. edwin. flags an ored combination of flags which determines the behaviour and content of the text window: the flags are described in the description of the methods edwin.margins the global settings for the margins edwin.font the global font information (Note that doc and clip are not on the auto-destroy list of epwrn - unlike scrimg and scrlay - as they can be created and looked after by the owner of the epwrn instance and may thus survive the destruction of the EDWIN instance.) AE a a a aS EDWIN methods DEST! VOID destroy (VOID) ; If PR_EDWIN_DOC_SUPPLIED is not set in edwin. flags, and edwin. doc is non-zero, sends a DESTROY message to edwin.doc. If PR_EDWIN_CLIPBOARD is set in edwin. flags, and edwin.clip is non-zero, sends a DEsTRoY message to edwin.doc. Supersends a DESTRoy message. Create components an VOID wn_init (IN_EDWIN *init, PR_WIN *landlord, IN EDWIN X *initx) ; Initialise the edit window: landlord should specify the window ID of the 1andlora window. The initial content and behaviour of the edit window are specified by means of an IN_EDWIN struct and an IN_EDWIN_X struct. The 1n_EpwIn struct is defined as follows: typedef struct { UWORD vulen; UWORD flags; UWORD maxlen; TEXT contents [1]; } IN_EDWIN; The members of the In_Epwrn struct have the following significance: vulen the width of the view in characters or pixels. flags an ored combination of flags: see below. maxlen the maximum number of characters in the document: excludes the final zero terminator. contents the initial content of the document. 10-6 10 TEXT EDITORS EAT EDITORS The In_Epwin_x struct is defined as follows: typedef struct { UWORD vislines; P_POINT pos; WORD font; UWORD style; EDWIN_LEADING leading; VOID *doc; VOID *clip; } IN_EDWIN_X; The members of the 1In_Epw1n_x struct have the following significance: vislines the maximum number of lines of text visible in the edit window. pos the top left offset of the edit window relative to the landlord window. font the global font ID style the global font style. leading the vertical line spacing. doc NULL or the handle of an instance of either Eppoc or EPpoc: contains the document text. clip NULL or the handle of an instance of =priar: contains the clipboard text. The initialisation is controlled by oring a suitable combination of the following flags into the f1ags member of the In_EDwrIN struct: IN_EDWIN_NO_AUTOSELECT IN_EDWIN_FONT_SUPPLIED IN_EDWIN_VULEN_CHARACTERS IN_EDWIN_VULEN_PIXELS IN_EDWIN_PAGINATABLE IN_EDWIN_TEXT_SEGMENTED IN_EDWIN_DOC_SUPPLIED IN_EDWIN_CLIPBOARD IN_EDWIN_POSITION_SUPPLIED Do not create a selected region: by default the entire document is selected. Use the font and style specified in initx->font and initx->style respectively: the default values are ws_ronT_sysTEem and G_STY_NORMAL respectively. Set the width of the edit window as specified in init->vulen: units of characters. Set the width of the edit window as specified by init->vulen: units of pixels. For advanced use only. If this flag is set, any document object created during initialisation will be an instance of eppoc, which uses segmented storage. In the absence of this flag (and assuming that the flag IN_EDWIN_DOC_SUPPLIED is also not set) an instance of EPFDoc.is created. Note that this flag must be set if the document object uses segmented storage (which is expected to be an instance of Eppoc or of a subclass of Eppoc) regardless of whether this instance is or is not created by the wn_init method. Use the document object specified in initx->doc. The default, in the absence of this flag, is to create the document object. Use the clipboard object specified in initx->clip , or, if initx- >clip Is Zero create a clipboard object with maximum length as specified in init->maxlen. The default is not to use a clipboard. Use the top left offset of the edit window specified by initx->pos. If this flag is not set the offset must be set by a subsequent call to ig_set_id_pos. 10-7 HWIM REFERENCE SS — — SSSFSFSSSSSSSSSSSSSSSSSSSSSSMmMhFhFsFeFeFese IN_EDWIN_VISLINES_SUPPLIED Use the number of text lines visible specified in initx->vislines. The default is to show only one text line - i.e. a single text line editor. IN_EDWIN_ LEADING SUPPLIED Use the leading specified in initx->leading.top and initx- >leading.total. The default is to use top and total leading of one and two pixels respectively. IN_EDWIN_ACCEPT_TABS Accept Tab key presses. The default is to ignore Tab key presses. IN_EDWIN_ACCEPT_SOFT_HYPHENS Allow soft hyphens. The default is to ignore soft hyphens. IN_EDWIN_LEFT_CURSOR Draw a line cursor in the left margin. The above information is quite sufficient for simple use of the wn_init method. The following detailed explanation of the operation of the method is included for more advanced use. Sets the landlord window ID into property by writing Landlord to lodger . landlord. Writes init->flags to edwin. flags: e allows read and write access to the document by clearing pR_EDWIN_READONLY in edwin. flags. e if IN_EDWIN_NO_AUTOSELECT is set (clear) in init->flags clears (sets) PR_EDWIN_AUTOSELECT in edwin. flags. Sets the font and font style: e if init->flags contains IN_EDWIN_FONT_SUPPLIED, writes initx->font to edwin. font.fid and writes initx->style to edwin. font .style: defines user specified font and font style. e otherwise uses the system font, by writing w_ront_sysTem to edwin. font. fid. In the case of the Workabout, if the edit window is being used as a control in a small font dialog, edwin. font .£id is set to the font indicated by the value of digbox. font in the owning dialog box. Sets the width of the lodger window: ¢ if init->£lags contains neither IN_EDWIN_VULEN_PIXELS nor IN_VULEN_CHARACTERS, writes init->maxlen multiplied by the maximum width of a character in the current font to lodger.width. e if init->flags contains IN_EDWIN_VULEN_PIXELS writes init->vulen tO lodger.width. ¢ if init->flags contains IN_EDWIN_VULEN_CHARACTERS Writes init->vulen multiplied by the nominal maximum width of a character in the current font to lodger .width. If init->flags contains IN_EDWIN_DOC_SUPPLIED: © writes initx->doc to edwin.doc. This is assumed to be the handle of (a subclass of) either Eppoc or EPFDOC, depending on the presence or absence of the IN_EDWIN_TEXT_SEGMENTED flag. Otherwise creates and initialises a document object: e if init->£1ags contains IN_EDWIN_TEXT_SEGMENTED creates an instance of Eppoc and writes the handle to edwin. doc. e otherwise creates an instance of EPFDoc and writes the handle to edwin. doc. e sends an EP_INIT message to edwin. doc specifying a maximum length of init->maxlen characters plus a zero terminator. © copies the text specified by init->content into the document by sending an EP_SET_TEXT messsage to edwin. doc. Senses the document length by sending an Ep_sENSE_LEN message to edwin. doc and writes the result to edwin.clen. Builds a scray_poc struct containing document information and methods required by the scrLay component. If init->£1lags contains IN_EDWIN_TEXT_SEGMENTED (on the assumption that the document content object is, or is a subclass of, EpDoc): 10-8 10 TEXT EDITORS —_— SS SEAT EDITORS e writes 0_EPDOC_SENSE_cuHars to the sensechars member. © writes o_EPDOC_PARA_sTART to the toparst member. e if init->flags contains IN_EDWIN_PAGINATABLE, writes O_EPDOC_ENQ_PAGE to the enqpage member. Otherwise (on the assumption that the document content object is, or is a subclass of, EPFDOC) sets the above members as follows: © writes 0_EPFDOC_SENSE_cuaRs to the sensechars member. e writes o_EPFpoc_PaRA_ start to the toparst member. Sets the remaining members as follows: © writes zero to the sensepdata and senseplabel members: these are thus undefined. © writes edwin.doc to the content member: defines the document object. * sends an EP_SENSE_LEN message to edwin. doc and writes the return value plus one to the 1en member: defines the document length. Builds a scRLAY_STYLE struct containing style information required by the scriay component as follows: © writes SCRLAY_SHOW_TABS to the options member: defines tabs as visible. e writes raLsE to the printer member: defines the layout mode as screen. © writes a pointer to edwin.margins to the pd.margins member: defines the margins. ¢ writes the address of edwin. font to the font and sfont members: defines the global printer and screen fonts. e writes the address of edwin. font .height to the pd. tabs member: defines zero tabs. © writes nuLL to the fwtab member. the global printer font width table is undefined. ¢ writes zero to the scrpwidth member: the printer tab positions information is undefined. Allows subclassers to change the default style settings in the scrLAY_sTYLE struct by sending se1f an EW_INIT_STYLE message. (The default method does nothing.). Creates an instance of scriay and writes the handle to edwin. scriay. Initialises by sending an su_inrT message to edwin. scrlay with pointers to the above scrLay_poc and ScRLAY_STYLE structs. If init->£1ags contains IN_EDWIN_CLIPBOARD and initx->clip is zero, creates an instance of EPFLAT and writes the handle to edwin.clip. Initialises with maximum length init->maxlen characters excluding the zero terminator by sending an EP_INIT message to edwin. clip. If init->£1lags contains IN_EDWIN_CLIPBOARD, and initx->clip is non-zero, writes initx->clip to edwin.clip and clears In_EDWIN_CLIPBOARD from edwin. flags as the clipboard is now initialised. Builds an scrrmc_wrn struct containing window information. If init->£1ags contains IN_EDWIN_LEFT_CURSOR: ¢ writes W_FONT_SYSTEM to win.1cfont: defines the line cursor font. e ifG_stTy_pouBLs is set in edwin. font .style, sets G_STY_DOUBLE in win.1cstyle: defines the line cursor style - zero for the default style. © writes WS_SYMBOL_MARGIN_CURSOR to win. 1ccode: defines the line cursor symbol. If init->flags contains IN_EDWIN_LEADING_SUPPLIED: ¢ writes the sum of the font height in pixels and initx->1eading.total to win. lheight: defines the line height. ¢ writes the sum of the font ascent in pixels and initx->leading.top to win. lascent: defines the line ascent. Otherwise sets the above members as follows: 10-9 HWIM REFERENCE e writes the font height in pixels plus two to win. Lheight: defines the line height. e writes the font ascent in pixels plus one to win. 1lascent: defines the line ascent. If init->flags contains IN_EDWIN_VISLINES: e writes initx->vislines to win.nlines: defines the maximum number of lines visible. e writes win.width divided by four to win. hscrim: defines the horizontal scroll behaviour. Otherwise: e writes one to win.nlines: defines the maximum number of lines visible. e writes zero to win. hscri1x and writes two to win. hscrim: defines the horizontal scroll behaviour. Sets the remaining members as follows: e writes landlord->win.id to win.wid: defines the landlord window ID. e® writes initx->pos to win.t1: defines the top left offset of the window. e writes lodger.width to win.width: defines the width of the edit window. © writes zero to win.margin: defines the default width of the label and line cursor margins. e writes two to win.cwidth: defines the width of the text cursor. Creates an instance of scrimc and write the handle to edwin. scrimg. Sets the window information by sending an s1_sET message to edwin. scrimg with as arguments a pointer to the above scriImG_WwIN stmict and edwin.scrlay. Subtracts the font maximum character width from the pixel width of the text area of the edit window (this is the return value from the last s1_seT message) and writes the result to edwin.margins. right. If win.nlines is one in which case only one line is visible: e disables the word wrap by writing 4096 to edwin. margins. right. If init->flags contains IN_EDWIN_POSITION_SUPPLIED: e sets the offset of the lodger window by writing win.t1 to lodger. offset. e sets the lodger window ID by writing win.wid to win.id. e sends an sI_INIT message to edwin. scrimg with as arguments zero and zero. (Otherwise does nothing and expects the caller to send an LG_sET_rp_ Pos message later.) If edwin. flags contains IN_EDWIN_POSITION_SUPPLIED and either IN_EDWIN_AUTO_CUR_END or IN_EDWIN_AUTO_SELECT: e moves the cursor to the end of the document and scrolls the view until the cursor is visible by sending an SI_MOVE_CURSOR message to edwin.scrimg. e writes the length of the document excluding the terminating zero to edwin. cpos. e if edwin.flags contains IN_EDWIN_AUTO_SELECcT selects the region defined by the old and new cursor positions. ; "Handle key input INT wn_key(UINT keycode, UINT modifiers) ; Handle a keypress. If the keypress is w_KEY_ESCAPE: © cancels any selection, write FALSE to edwin.select and returns WN_KEY_NO_CHANGE. 10-10 10 TEXT EDITORS _—_—_—_—__ EET EDITORS If the keypress is w_kKEY_DELETE_RIGHT: © if edwin. flags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message - is TRUE, calls hBeep then p_leave with RUN_ACTIVE_USED as argument. e ifaselected region exists, moves the cursor to the start of the selection, delete the selection, and scrolls the view until the cursor is visible. Writes the cursor position to edwin. cpos. Writes FALSE to edwin.select. Writes the document length to eawin.clen. Rebuilds the layout and the view - the method sends an s1_FwD_CHANGED message to edwin. scrimg. Writes EW_CHANGE to edwin.change. Returns WN_KEY_CHANGED. ¢ ifthe end of the document has been reached, returns wx_KEY_NO_CHANGE. ¢ — otherwise deletes the character to the right of the cursor - the method reformats and redraws the edited document responsively by sending an st_PARA_CHANGED message to edwin.doc. Writes the document length to edwin.clen. Writes Ew_CHANGE to edwin. change. Return WN_KEY_ CHANGED. If the keypress is w_KEY_DELETE_LEFT: e if edwin. flags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message iS TRUE, Calls hBeep then p_leave with RUN_ACTIVE_USED as argument. ¢ ifmodifiers contains w_PSTON_MODIFIER, Clear PR_WSERV_INSERT_MODE and PR_WSERV_INSERT_PENDING iN w_ws->wserv. flags. Selects the region to the left of the cursor and moves the cursor to the start of the line by sending se1f a wy_KEY message with arguments of W_KEY_HOME and W_SHIFT_MODIFIER. e if aregion is selected, moves the cursor to the start of the selection, deletes the selection, and scrolls the view until the cursor is visible. The selection is copied to the clipboard object if one exists. Writes the cursor position to edwin. cpos. Writes FALSE to edwin. select. Writes the document length to edwin.clen. Rebuilds the layout and the view - the method sends an SI_FWD_CHANGED message tO edwin.scrimg. Writes EW_CHANGE to edwin. changed and returns WN_KEY CHANGED. ¢ if the cursor is at the start of the document returns wi_KEY_NO_CHANGE. e otherwise deletes the character to the left of the cursor, moves the cursor to the left by one character and scrolls the view until the cursor is visible: the method sends an SI_DELPREP message to edwin. scrimg, a EP_DELETE message to edwin.doc and an SI_PARA_CHANGED changed message to edwin. scrimg. Writes the length of the document to edwin.clen. Writes the cursor Position to edwin.cpos. Writes EW_CHANGE to edwin. changed and returns WN_KEY_CHANGED. If the keypress is W_KEY_LEFT: ¢ — if'a selected region exists and modifiers does not contain w_SHIFT MODIFIER, moves the cursor to the start of the selected region, cancels the selection and scrolls the view until the cursor is visible. Writes FALSE to edwin. select. Returns WN_KEY_NO_CHANGE. ¢ if the cursor is at the start of the document returns wN_KEY_NO_CHANGE. e ifmodifiers contains W_CTRL MODIFIER, moves the cursor backwards to the start of a word - the method sends an EP_SCAN_WORD message to edwin. doc - and scrolls the view until the cursor is visible. Writes the cursor position to edwin. cpos. If modifiers contains W_SHIFT_MODIFIER selects the text skipped and writes TRUE to edwin. select. Returms wN_KEY_NO_CHANGE. e otherwise moves the cursor backwards one character and scrolls the view until the line containing the cursor is visible. Writes the cursor position to edwin. cpos. If modifiers contains W_SHIFT_MODIFIER Selects the character skipped and writes TRUE to edwin. select. Returns WN_KEY_NO_CHANGE. If the keypress is W_KEY_ RIGHT: e if selected region exists and modifiers does not contain w_sHIFT_MODIFIER, moves the cursor to the end of the selected region, cancels the selection and scrolls the view until the cursor is visible. Writes FALSE to edwin.select. Returns wN_KEY_NO_CHANGE. ¢ — if the cursor is at the end of the document, returns wx_KEY_NO_ CHANGE. ¢ if modifiers contains w_cTRL_MODIFIER, moves the cursor forwards to the start of a word - the method sends an EP_SCAN_WORD message to edwin. doc and an SI_MOVE_CURSOR message to Sn 10-11 HWIM REFERENCE ee edwin .scrimg - and scrolls the view until the cursor is visible. Writes the cursor position to edwin. cpos. If modifiers contains W_SHIFT_MODIFIER selects the text skipped and writes truE to edwin. select. Otherwise writes FALSE to edwin. select. Returms wN_KEY_NO_CHANGE. otherwise moves the cursor forwards by one character and scrolls the view until the cursor is visible. Writes the cursor position to edwin.cpos. If modifiers contains W_SHIFT_MODIFIER selects the character skipped and writes TRUE to edwin. select. Otherwise writes FALSE to edwin.select. Returns wN_KEY_NO CHANGE. If the keypress is w_KEY_HOME: if modifiers contains both w_crRL_MODIFIER and W_SHIFT_MODIFIER, moves the cursor backwards until a word delimiter is located and then selects the word after the delimiter - i.e. selects the current word. The method sends an EP_sCcAN_woRD message to edwin. doc and an SI_MOVE_CURSOR message to edwin.scrimg. otherwise moves the cursor to the beginning of the current line. If modifiers contains W_SHIFT_MODIFIER Selects the text skipped and writes TRUE to edwin. select. Otherwise cancels any selected region and writes FALSE to edwin. select. If the keypress is W_KEY_END: if modifiers contains both w_crRL_MODIFIER and W_SHIFT_MODIFIER, moves the cursor forwards until a paragraph delimiter is located then selects the paragraph preceding the cursor - i.e. selects the current paragraph. The method sends an EP_scaN_PARA message to edwin. doc and an SI_MOVE_CURSOR message to edwin.scrimg. otherwise moves the cursor to the end of the current line. If modifiers contains W_SHIFT_MODIFIER Selects the text skipped and writes TRUE to edwin. select. Otherwise cancels any selection and writes FALSE to edwin. select. If the keypress is w_KEY_UP: if a region is selected and modifiers does not contain w_SHIFT_MODIFTIER, cancels the selection and writes FALSE to edwin.select. Moves the cursor to the start of the once selected region and scrolls the view until the cursor is visible. Returns wN_KEY_NO_CHANGE. if modifiers contains W_CTRL_MODIFIER, moves the cursor to the start of the current paragraph and scrolls the view until the cursor is visible. If modifiers also contains w_SHIFT_MODIFIER selects the characters skipped and writes TRUE to edwin.select. Otherwise cancels any selected region and writes FALSE to edwin. select. Returns wN_KEY_NO_CHANGE. otherwise moves the cursor up one line and scrolls the view until the cursor is visible. If modifiers Contains W_SHIFT_MODIFIER, anda region is not selected, selects the text skipped and writes TRUE to edwin. select. If modifiers contains W_SHIFT_MODIFIER, and a region is selected, moves the cursor point of the selected region to the new cursor position. Otherwise writes FALSE to edwin.select. Returns wN_KEY_NO_CHANGE. If the keypress is w_KEY_DOWN: if a region is selected and modifiers does not contain W_SHIFT MODIFIER, moves the cursor to the end of the selected region, cancels the selection, and scrolls the view until the cursor is visible. Writes FALSE to edwin.select. Returns WN_KEY_NO_CHANGE. if modifiers contains W_CTRL_MODIFIER, moves the cursor to the start of the first line of the next paragraph and scrolls the view until the cursor is visible. If modifiers also contains W_SHIFT_MODIFIER selects the characters skipped and writes TRUE to edwin. select. Returns WN_KEY_NO_CHANGE. otherwise moves the cursor down one line and scrolls the view until the cursor is visible. If modifiers Contains W_SHIFT_MODIFIER, anda region is not selected, selects the text skipped and writes TRUE to edwin. select. If modifiers contains W_SHIFT_MODIFTER, and a region is selected, moves the cursor point of the selected region to the new cursor position. Otherwise cancels any selection and writes FALSE to edwin. select. Retums WN_KEY NO CHANGE. If the keypress is W_KEY_PAGE_UP: if modifiers contains W_CTRL_MODIFIER, moves the cursor to the start of the document and writes the cursor position to edwin.cpos. If modifiers also contains w_SHIFT_MODIFIER selects the text ng et 10-12 10 TEXT EDITORS —_ HH EAT EDITORS skipped and writes TRUE to edwin. select. Otherwise cancels any selection and writes FALSE to edwin.select. Retumms wN_KEY_NO_CHANGE. e otherwise moves the cursor up by one ‘page’ (that is, by one fewer lines than the number of lines that can be displayed on the screen) and writes the cursor position to edwin.cpos. If modifiers also contains W_SHIFT_MODIFTIER selects the text skipped and writes TRUE to edwin. select. Otherwise cancels any selection and writes FALSE to edwin. select. Returns WN_KEY_NO_CHANGE. If the keypress is w_KEY_PAGE_DOWN: ¢ ifmodifiers contains w_cTRL_MODIFIER, moves the cursor to the end of the document and scrolls the view until the cursor is visible. Writes the cursor position to edwin. cpos. If modifiers contains W_SHIFT_MODIFIER, Selects the text skipped and writes TRUE to edwin. select. Otherwise cancels any selection and writes FALSE to edwin. select. Returns WN_KEY_NO_CHANGE. e otherwise moves the cursor down by one 'page' (that is, by one fewer lines than the number of lines that can be displayed on the screen) and scrolls the view until the cursor is visible. Writes the cursor position to edwin. cpos. If modifiers contains w_SHIFT_MODIFTER, selects the text skipped and writes TRUE to edwin. select. Otherwise cancels any selection and write FALSE to edwin.select. If the keypress is w_KEY_ RETURN: e checks that the document accepts w_kEy_RETURN by sending self an EW_RETURN_KEY message. If the return value is non-zero the method terminates, returning this value. e ifedwin. flags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message is TRUE, Calls hBeep then p_leave with RUN_ACTIVE_USED as argument. ¢ ifmodifiers contains w_SHIFT_MODIFIER, Sets keycode to a carriage return - ie. ‘\n’, e otherwise sets keycode to zero - i.e. ox00. ¢ — inserts keycode into the document at the current cursor position and moves the cursor forwards one character. Writes the document length to edwin.clen. Cancels any selection and writes FALSE to edwin.select. Sends an sI_PARA_CHANGED message to edwin. scrimg. Writes EW_CHANGE to edwin.change. Returns WN_KEY_NO_CHANGE. If the keypress is w_KEY_ TAB: checks that the document accepts w_key_Tas by sending self an EW_TAB_KEY message. If the return value is non-zero returns the return value. ° if edwin. £1ags does not contain pR_EDWIN_ACCEPT_TABS, returms WN_KEY_NO_CHANGE. ° ifedwin. flags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message iS TRUE, Calls hBeep then p_leave with RUN_ACTIVE_USED as argument. * — inserts a tab character at the current cursor position, moves the cursor to the right by one character and scrolls the view until the cursor is visible. Writes the document length to edwin. clen. Cancels any selection and writes FALSE to edwin.select. Sends an st_PARA_CHANGED message to edwin.scrimg. Returns wN_KEY_NO_CHANGE. If the keypress is W_KEY_HELP: ° ifmodifiers does not contain both w_pstoN_MODIFIER and W_SHIFT_MODIFIER, and edwin. flags does not contain PR_EDWIN_DIALLABLE, returns WN_KEY_NO_CHANGE. * ifedwin.£f1ags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message is TRUE, Calls hBeep then p_leave with RUN_ACTIVE_USED as argument. ¢ if modifiers does not contain w_CTRL_MODIFIER, cancels then deletes any selected region - the selected region is copied to the clipboard. Inserts a ws_PHONE_SYMBOL character at the current cursor position, moves the cursor forwards one character and scrolls the view until the cursor is visible. Writes the document length to edwin.clen. Writes the cursor position to edwin. cpos. Writes FALSE to edwin.select. Writes EW_CHANGE to edwin. change and sends an SI_FWD_CHANGE message to edwin.scrimg. Returns wN_KEY_ CHANGED. 10-13 HWIM REFERENCE Se eEeeeSSSSSSSSSSSSSSSSSSMSESE otherwise runs a country selector dialog by sending a ws_APPEND_COUNTRY message to w_ws and inserts the selected country name into the document by sending se1f an EW_INSERT message. Returns ww_KEY_NO_CHANGE. If the keypress is ' ': if edwin. flags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message is TRUE, Calls hBeep then p_leave with RUN_ACTIVE_USED as argument. if a selected region exists, copies the selected region to the clipboard and then cancels and deletes the selected region. Writes the document length to edwin.clen. Writes FALSE to edwin. select. if modifiers contains W_CTRL_MODIFIER, replaces the value of keycode by WS_SYMBOL_HARD_ SPACE. inserts keycode. moves the cursor forwards one character and, if necessary, scrolls the view until the cursor is visible. Writes the document length to edwin. clen. Writes the cursor position to edwin. cpos. if a select region has been deleted, sends an st_poc_CHANGED message to edwin. scrimg, otherwise sends edwin.scrimg an SI_PARA_CHANGED message. Writes EW_CHANGE to edwin. change. Returns WN_KEY_CHANGED. If the keypress is '-': if edwin. flags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message is TRUE, calls hBeep then p_leave with RUN_ACTIVE_USED as argument. if a selected region exists copies the selected region to the clipboard and then cancels and deletes the selected region. Writes the document length to eawin.clen. Writes raLsE to edwin.select. if modifiers contains W_SHIFT_MODIFIER and w_CTRL_mopzFrer, the value of keycode is replaced by WS_SYMBOL_HARD HYPHEN. otherwise, if modifiers contains W_CTRL MODIFIER and edwin. flags contains PR_EDWIN_ACCEPT_SOFT_HYPHENS, the value of keycode is replaced by ws_SYMBOL_SOFT_HYPHEN. inserts keycode. moves the cursor forwards one character and, if necessary, scrolls the view until the cursor is visible. Writes the document length to edwin. clen and the cursor position to edwin. cpos. if a select region has been deleted, sends an st_poc_CHANGED message to edwin. scrimg, otherwise sends edwin.scrimg an SI_PARA_CHANGED message. Writes EW_CHANGE to edwin. change. Returns WN_KEY_CHANGED. For any other keypress: 10-14 if keycode does not specify a printable character or keycode is greater than or equal to oxi00, retums WN_KEY_NO_CHANGE. if edwin. flags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message is TRUE, calls hBeep then p_leave with RUN_ACTIVE_USED as argument. if a selected region exists, copies the selected region to the clipboard and moves to the start of the selected region scrolling the view until the cursor is visible. Cancels and deletes the selected region. Writes the document length to edwin.clen. Writes FALSE to edwin. select. inserts keycode at the current cursor position and moves the cursor forwards one character. Writes the document length to edwin.clen. Writes FALSE to edwin.select. if a selected region existed, rebuilds and redraws by sending an st_Doc_CHANGED message to edwin.scrimg. otherwise rebuilds and redraws responsively by sending an s1_PARA_CHANGED message to edwin. scrimg. writes EW_CHANGE to edwin. change. Returns WN_KEY_CHANGED. 10 TEXT EDITORS Draw view VOID wn_draw (VOID) ; Draw the whole view. Sends an sI_REDRAW message to edwin. scrimg with an argument of NULL. Sense help ID INT wn_sense_help (VOID) ; Sense the ID for epwrn help resource. Returns -syS_HELP_EDIT. N_S Set text VOID wn_set(SE_EDWIN *pset) ; Set the content of the edit window according to the content of the sz_EpwrN struct pointed to by pset. The se_zpwrn struct is defined as follows: typedef struct te *buf; UWORD len; } SE_EDWIN; The members of the se_epw:n struct have the following significance: buf a pointer to the text to be set in the edit window len the total length of the text excluding the terminating zero Sets the text in the edit window by sending an Ep_sET_TExT message to edwin. doc. Writes the length of the document including the terminating zero to edwin.clen. Cancels any selected region, moves the cursor to the start of the document and scrolls the view until the cursor is visible by sending an st_poc_RESET message to edwin. scrimg. Writes the cursor position to edwin.cpos. If PR_EDWIN_AUTO_CUR_END is set in edwin. flags, moves the cursor to the end of the document and scrols the view until the cursor is visible by sending an s1_MovE_cuRSoR message to edwin. scrimg . Writes the cursor position to edwin. cpos. Writes FALSE to edwin. select. If PR_EDWIN_AUTO_SELECT is set in edwin. flags, moves the cursor position to the end of the document, scrolls the view until the cursor is visible and selects the whole document by sending an SI_MOVE_CURSOR message to edwin. scrimg. Writes the cursor position to edwin.cpos. Writes TRUE to edwin. select. WN_SENSE | _ Sense text VOID wn_sense(SE_EDWIN *psense) ; Sense the text in the edit window and write the results to the s=_EDwIN struct pointed to by psense. Senses the text by sending an Er_sENSE_BUF message to edwin.doc. Writes a pointer to the text to psense- >buf and writes the length of the text minus the zero terminator to psense->1en. This method is not supported if the text is not stored contiguously. 10-15 HWIM REFERENCE WN_EMPHASISE = = =e - Set emphasis VOID wn_emphasise (INT flag) ; Emphasise the edit window. Sends an sI_EMPHASIZE Message to edwin.scrimg with an argument of flag. Les VOID 1lg_set_id_ pos(INT id, P_POINT *ppos, UINT width) ; Set the offset of the lodger window as specified by ppos, the width of the lodger window as specified by width, and the ID of the lodger window as specified by ia. Sets the offset width, and ID of the lodger window by supersending an L¢_sET_ID_Pos message. Obtains a copy of the scrimc window information data structure by sending an s1_SENSE message to edwin.scrimg with as argument a pointer to a scRIMG_win struct. Writes the struct pointed to by ppos to the t1 member of the scrimc_wrn struct. Writes width to the width member of the scrrmc_WIN struct. Initialises the scriMe instance and sets the content of the above scrimc_wn struct into property by sending an SI_INIT messsage to €dwin.scrimg. If PR_EDWIN_AUTO_CUR_END is set in edwin.flags, moves the cursor to the end of the document by sending an SI_MOVE_CURSOR Message to edwin. scrimg. Writes the cursor position to edwin.cpos. Writes FALSE to edwin.select. If PR_EDWIN_AUTO_SELECT is set in edwin. flags, moves the cursor to the end of the document and selects the whole document by sending an s1_MovE_cuRSOR message to edwin. scrimg. Writes the cursor position to edwin. cpos. Writes TRUE to edwin.select. Le {WOT oo eee eee INT lg_sense_width(VOID) ; Sense the width of the lodger window. Returns lodger. width. VOID ew_sense_size(P_EXTENT *pext) ; Sense the top left offset of the lodger window, the width of the lodger window and the maximum number of text lines visible and write the results to the p_ExTENr struct specified by pext. Senses the window data for the scrime instance by sending an st_sENSE message to edwin. scrimg. Writes the pixel coordinates of the top left corner of the lodger window to pext->t1. Writes the pixel width of the lodger window to pext->width. Writes the number of text lines visible to pext->height. VOID ew_set_size(P_EXTENT *pext, VOID *hand, INT method); Set the top left offset of the edit window as specified by pext->t1, the width of the lodger window as specified by pext->width and the maximum number of text lines visible as specified by pext->height. Senses the current window data for the scrimc component by sending an s1_SENSE message to edwin.scrimg with as argument a pointer to an SCRIMG_WIN struct. Writes the new offset of the lodger window pext->t1 to lodger . offset. Writes the new coordinates of the top left point of the edit window pext->t1 to the t1 member of the SCRIMG_WIN Struct. eee 10 - 16 10 TEXT EDITORS Writes pext->height, which contains the new number of text lines visible, to the nines member of the SCRIMG_WIN struct. Sets the modified window data into the scrimc component by sending an s1_seT message to edwin.scrimg. If hand is non-zero, sends a method message to hand with as argument the pixel width of the text area: this allows for further processing before the document layout is rebuilt. Rebuilds the document layout and the view by sending an s1_sTYLE_CHANGED message to edwin. scrimg. VOID ew_set(SET_EDWIN *pset) ; Set the content and appearance of the edit window according to the content of the seT_=pwin struct specified by pset. The seT_EDWIN struct is defined as follows: typedef struct { UWORD flags; SE_EDWIN txt; UWORD cursor; cursor (moving point of select) UWORD anchor; anchor point (fixed end of select) } SET_EDWIN; The members of the ser_zpwrn struct have the following significance: flags see below. txt an SE_EDWIN struct specifying the text to set in the edit window: see the description of the wn_set method for details. cursor the candidate cursor position. anchor the candidate anchor position. The setting is controlled by oring into £1ags a suitable combination of the following flags: SET_EDWIN_EMPTY empty the content of the edit window SET_EDWIN_TXT set the content of the edit window SET_EDWIN_SEL_ALL select the entire content of the edit window SET_EDWIN_CUR_END move the cursor to the end of the document SET_EDWIN_ANCHOR set the position of the anchor for the selected region SET_EDWIN_CURSOR set the position of the cursor If pset->flags contains SET_EDWIN_EMPTY: © sets SET_EDWIN_TXT iN pset->flags and Set pset->txt.1len to zero If pset->flags contains SET_EDWIN_TXT: e _ sets the text in the edit window by sending an EP_sET_TEXxT message to edwin. doc and writes the length of the text as specified by pset->txt .len to edwin.clen e cancels any selection, moves the cursor to the start of the document and scrolls the view until the cursor is visible by sending an st_poc_REsET message to edwin. scrimg. Writes the cursor position to edwin.cpos. If pset->flags contains SET_EDWIN_SEL_ALL: e — sets both sET_EDWIN_CUR_END and SET_EDWIN_ANCHOR iN pset->flags and writes zero to pset->anchor 10-17 HWIM REFERENCE Se Ss SSS If pset->flags contains SET_EDWIN_CUR_END: e sets SET_EDWIN_CURSOR in pset->flags and writes edwin.clen-1 to pset->cursor If pset->flags contains SET_EDWIN_ANCHOR: e writes pset->anchor to edwin. cpos, cancels any selected region, moves the cursor to edwin.cpos and scrolls the view until the cursor is visible by sending an s1_MovE_cuRSoR message to edwin. scrimg. If pset ->£1ags contains sET_EDWIN_CURSOR and SET_EDWIN_ANCHOR: e — selects the region between edwin. cpos and pset->cursor, moves the cursor to pset->cursor and scrolls the view until the cursor is visible by sending an s1_MovE_cuRSOR message to edwin.scrimg. Writes TRUE to edwin.select. Writes the cursor position to edwin.cpos. If pset->flags contains sET_EDWIN_cuRsoR but not SET_EDWIN_ANCHOR: e cancels any selection, moves the cursor to pset->cursor and scrolls the view until the cursor is visible by sending an s1_MovE_cURSOR message to edwin. scrimg. Writes FALSE to edwin. select. Writes the cursor position to edwin.cpos. Note that the order of the above tests is significant: for example a region may be selected by oring both SET_EDWIN_ANCHOR and SET_EDWIN_CuRSOR into pset->flags. _ Sense cursor and select data INT ew_sense (SENSE_EDWIN *psense) ; Sense the anchor and cursor position of the selected region and write the results to the sENsE_EDWIN struct specified by psense. The sENSE_Epwrn struct is defined as follows: typedef struct { UWORD cursor; cursor (moving point of select) UWORD anchor; anchor point (may equal cursor) } SENSE_EDWIN; The members of the sensE_EDwIN struct have the following significance: cursor the cursor position of the selected region: equal to anchor plus the length of the selected region anchor __ the anchor position of the selected region The anchor and cursor positions are illustrated in the following picture: cursor position ban example JaGatecBye-stne] in a document anchor position (Note that it is quite possible for the cursor position to come before the anchor position.) Obtains the position of the first character and the length for the selected region by sending an SI_GET_SELECT message to edwin.scrimg and writes the anchor and cursor positions to psense. Returns the number of characters in the selected region: zero indicates that no selected region exists. 10-18 10 TEXT EDITORS EWINSERT == = _Insert at cursor VOID ew_insert (TEXT *buf£, UINT blen); Insert at the current cursor position bien characters from the buffer specified by but. Inserts the text into the document at the current cursor position by sending an EP_INSERT message to edwin.doc: the message is sent using p_entersend and on error an EW_LEAVE message is sent to self with the error code as argument. Writes the length of the document to edwin.clen. Moves the cursor to the end of the inserted text by sending an s1_MovE_CURSOR message to edwin. scrimg: the view is scrolled until the cursor is visible. Writes the cursor position to edwin. cpos. Writes Ew_CHANGE to edwin. change. Rebuilds the layout and view by sending an s1_Fwp_CHANGE message to edwin. scrimg: the top left corner of the view is kept fixed. face select and add surrounds VOID ew_snuggle_ insert (TEXT *before, TEXT *after, TEXT *replace) ; Replace the selected region with the before, replace and after strings (in that order) and select the inserted replace text: before, replace and after may each specify a nuuu address. Checks that the sum of the current document length and the length of each insert string does not exceed the maximum allowed document length. If the maximum document length is exceeded, sends se1¢ an EW_LEAVE message with argument of E_GEN_OVER. Obtains the length and position of the selected region by sending an s1_GET_sELECT message to edwin.scrimg. If no selection exists, inserts at the current cursor position the before, replace and after strings by sending EP_INSERT messages to edwin. doc. If a selection exists, inserts immediately after the selected region the before, replace and after strings by sending EP_INSERT messages to edwin. doc. Cancels the selection by sending an st_MovE_cURSOR message to edwin. scrimg, then deletes the once selected region by sending an Ep_DELETE message to edwin. doc. Writes EW_CHANGE to edwin. change and sends an sI_DOC_CHANGED message to edwin. scrimg. Selects the inserted replace string, moves the cursor to the end of the selected region, and scrolls the view until the cursor is visible by sending st_move_cuRSOR messages to edwin. scrimg. VOID ew_set_font (INT font, UINT style,EDWIN_LEADING *leading) ; Set the font as specified by font, the font style as specified by style, and the line spacing as specified by leading. Writes font to edwin. font. fid and writes style to edwin. font.style. Senses the window information for the scrime instance by sending an s1_sENSE message to edwin.scrimg with as argument a pointer to an scRIMG_wIN struct. Writes the line height in pixels to the 1height member of the scrimc_wrn struct: the line height is equal to the sum of leading->tota1 and the font height. Writes the line ascent in pixels to the ascent member of the scrimG_wrn struct: the line ascent is equal to the sum of leading->top and the font ascent. Sets the modified window information by sending an st_sET message to edwin. scrimg. This method is expected to be followed by a call to the ew_resize method. 10-19 HWIM REFERENCE EW VOID ew_leave (INT err); Leave handling Leave handling for the error code specified by err. If err is E_GEN_OVER, calls hBeep and if edwin. flags contains PR_EDWIN_NOTIFY_OVERFLOW, Calls hInfoPrint with an argument of -sys_ep1T_Ncuars. Calls ¢_1eave with an argument of RUN_ACTIVE_CLEANUP_NONOTIFY. Otherwise calls £_leave with an argument of err. INT ew_find(TEXT *pstr, UINT flags) ; Search the document for the zero terminated string specified by pstr ignoring strings that cross paragraph boundaries. The search starts at the selected region. The search mode is specified by the ored combination of flags in f1ags: EWP_CASESENS case sensitive matching: by default the matching is case insensitive. EWF_BACKWARDS search from the current cursor position moving towards the start of the document: by default the search moves towards the end of the document. Senses the length and start position of the select region by sending an s1_GET_SELECT message to edwin.scrimg. Senses the length of the document excluding the terminating zero by sending an EP_SENSE_LEN message to edwin.doc. If no selected region exists, starts the search from the current cursor position. If a selected region exists, starts the search from the position shown in the following picture: start of backward search an example sentence with akeeimculast included | start of forward search Since the search selects the first matching string the above ensures that repeated searches do not locate the same matching string, i.e. the method effectively supports find next. Starts the search for the first occurence of the required string. On success selects the matching text moving the cursor to the beginning or end of the selected region depending on the search direction by sending s1_Move_cURSOR messages to edwin.scrimg. Returns TRUE. On failure returns ranss. The cursor position remains unchanged. _ Replace select INT ew_replace (TEXT *replace, INT backwards) ; Replace the text in the selected region with that specified by repiace: the cursor is moved to the start (end) of the selected region if backwards is TRUE (FALSE). If edwin. flags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message is TRUE, calls hBeep then p_leave with RUN_ACTIVE_USED as argument. Inserts the replace string before the selected region by sending an EP_INSERT message to edwin. doc: the message is sent using p_entersend and on error the method sends an Ew_LEAVE message sent to self with the return value as argument. Deletes the selected region by sending an EP_DELETE message to edwin. doc. eS 10 - 20 10 TEXT EDITORS Cancels any selected region and moves the cursor to the end (start) of the inserted text if backwards is FALSE (TRUE) by sending an st_MovE_CuRSOR message to edwin. scrimg. Writes the cursor position to edwin.cpos. Writes EW_CHANGE to edwin. change. Rebuilds the layout and redraws the view by sending an st_poc_CHANGED message to edwin.scrimg. Confirms success by returning zero. é an expression VOID ew_evaluate (VOID) ; Evaluate an expression: the expression is assumed to be selected or, if no region is selected, the cursor is assumed to indicate the position of an expression. If edwin. flags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message is TRUE, calls hBeep then call p_leave with RUN_ACTIVE_USED as argument. Otherwise obtains the length and the position of the start of the selected region by sending an SI_GET_SELECT message to edwin. scrimg. If no region is selected attempts to select an expression as follows: ¢ moves the cursor towards the start of the document until it is positioned immediately before a word - i.e. a continuous sequence of characters containing no spaces or paragraph delimiters: the method sends an EP_SCAN_WORD message to edwin.doc and an SI_MOVE_cURSoR to edwin. scrimg. e — selects the word - i.e. the candidate expression - moves the cursor to the end of the word and scrolls the view until the cursor is visible: the method sends an st_Move_cuRsoR message to edwin.scrimg and an EP_SCAN_WORD message to edwin. doc. ¢ — obtains the length and start of the word by sending an st_GET_SELECT message to edwin. scrimg If no region is selected displays the text message specified by the sys_NOTHING_To EVAL system resource using the hInfoPrint utility routine. On English language machines this is "Nothing to evaluate". Returns. If the selected region contains more than 254 characters, displays the text specified by the SYS_TOOLONG_TO_EVAL System resource using the hInfopPrint utility routine. On English language machines this is "Too long to evaluate". Return. Copies the content of the selected region to a text buffer by sending an EP_ExTRACT message to edwin.doc and replaces all occurences of oxoo with a space - i.e.''. Evaluates the expression in the text buffer by sending a ws_EVALUATE message to w_ws. If the return value is less than zero indicating successful evaluation: © — inserts at the current cursor position an equals sign followed by the result of the evaluation by sending an EP_INSERT message to edwin.doc. The message is sent using p_entersend: on error sends self an EW_LEAVE message with the return value as the argument. ¢ writes EW_CHANGE to edwin. change and rebuilds the layout and the view by sending an SI_FWD_CHANGE message to edwin. scrimg. e — selects the expression and the equals character and moves the cursor to the end of the selected region by sending s1_MoVE_CURSOR messages to edwin.scrimg. Writes the cursor position to edwin.cpos. The view is scrolled until the cursor is visible. Otherwise: ¢ moves the cursor to the position in the expression where the error was detected by the WS_EVALUATE message and cancels any selected region by sending an st_MovE_CURSOR message to edwin.scrimg. The view is scrolled until the cursor is visible. 10-21 HWIM REFERENCE WHREPLACE CLIP Copy select to clipboard INT ew_replace_clip (VOID) ; Replace the text in the clipboard with the text in the selected region. Obtains the length and start of the selected region by sending an st_cET_SELECT message to edwin. scrimg. If no region is selected returns zero. Deletes the content of the clipboard excluding the terminating zero by sending an EP_cLEAR message to edwin.clip. Inserts the content of the selected region in the front of the clipboard by sending an EP_copy_To FRONT message to edwin. doc. Returns the number of characters copied. INT ew_paste_clip(VOID) ; Paste the content of the clipboard into the document at the current cursor position: the pasted text is selected and the cursor moved to the end of the selected region. If edwin. flags Contains PR_EDWIN_READONLY and the return value from an EW_READONLY message is TRUE, calls hBeep and then call p_leave with RUN_ACTIVE_USED as argument. If the clipboard is empty returns Fass - the length of the clipboard text excluding the terminating zero is sensed by sending an Ep_SENSE_LEN message to edwin.clip. Inserts the clipboard text into the document at the current cursor position and sets the cursor to the end of the inserted text by sending an Ep_pasTE message to edwin.doc. Note that the message is sent using p_entersend: on error send self an EW_LEAVE message with the return value as the argument. Writes the cursor position to edwin.cpos and writes EW_CHANGE to edwin.change. Rebuilds the layout and view as required by sending an s1_Fwp_CHANGE message to edwin. scrimg. Selects the inserted text maintaining the cursor at the end of the inserted text by sending s1_MovE_CURSOR messages to edwin. scrimg. Returms the number of characters inserted. INT ew_bring_in(INT pid, INT format) ; Insert into the document at the current cursor position one or more blocks of data of type format supplied by the process whose ID is pia. The blocks of data may each contain up to and not exceeding 256 bytes of data. The transaction can be terminated by sending a nuut block of data. If edwin. flags contains PR_EDWIN_READONLY and the return value from an EW_READONLY message is TRUE, calls hBeep then p_leave with RUN_ACTIVE_USED as argument. The following f1ag may be set in format: EW_BRING_SINGLE_SHOT specifies that the method should accept only one block of data containing up to 256 characters The individual bits of format indicate the type of data: the bit index and the type of data are as follows: DF_LINK_PARAS insert each block of data without modification. otherwise add a paragraph delimiter - 0x00 -to the end of each inserted block of data except the last. 10-22 10 TEXT EDITORS _— eS EAT EDITORS DF_LINK_TABTEXT each block of data is ASCII text possibly containing tab characters. DF_LINK TEXT each block of data is plain ASCII text. (The pF_LINK_TABTEXT and pF_LINK_TExT data types are handled identically.) Creates an instance of the u1nxct class and initialises by sending the L1nxcu instance an LC_START message. If format contains EW_BRING_SINGLE_SHOT, requests and receives one block of data and then sends an LC_SToP message to the link object. Otherwise repeatedly requests and receives blocks of data until a nuuu block of data is received. The method handles each block of data as follows: e — gets the block of data by sending an Lc_ceT_paTa message to the link object. © prepends an oxoo paragraph delimiter as required - see above - and insert the data into the document by sending self an EW_EP_INSERT message. N.B. If at any time the Ew_EP_INSERT message returns a non-zero value - indicating an error - the method deletes all blocks of inserted data by sending an Ep_DELETE message to edwin.doc and then sending self an EW_LEAVE message with as argument the non-zero return value. Writes the length of the document to edwin. clen and writes EW_CHANGE to edwin. change. Rebuilds the layout and view by sending an s1_Frwp_CHANGE message to edwin. scrimg. Selects the inserted text, moves the cursor to the end of the selected region and scrolls the view until the cursor is visible by sending s1_mMove_CURSOR messages to edwin. scrimg. Writes the cursor position to edwin.cpos. The PR_WSERV_RECEIVED_KEY flag is cleared in w_ws->wserv. flags. Returns FALSE. (Note that a more complete description of the link-paste mechanism can be found in the Link Paste chapter of the Object Oriented Programming Guide.) _ insert text INT ew_ep_insert (UINT pos, TEXT *buf, UINT blen) ; Insert blen characters from the buffer specified by buf into the document at offset pos. Inserts the text by sending an EP_INSERT message to edwin. doc. If the application needs to take special note of the insertion of paragraph terminators, this method may be subclassed to deal with any zeros in the buffer (a simple strategy could be to send an EP_ADD_PARA message to edwin.doc for each zero-terminated segment of the buffer). ess handling INT ew_return_key(INT shift); Non-standard Return key handling. The method is called from within the wn_key method - the default method retums rause indicating that Return keypresses are allowed. Subclassers may replace this method to provide the desired functionality. A subclass could for example constrain the document to contain a fixed number of lines and thus would return TRUE once the maximum number of lines had been reached. 10 - 23 HWIM REFERENCE INT ew_tab_key(INT shift) ; Non-standard Tab key handling. The method is called from within the wn_key method - the default method returns rause indicating that Tab keypresses are allowed. Subclassers may replace this method to provide the desired functionality. Style VOID ew_init_style(SCRLAY_STYLE *pstyle) ; The default method does nothing. The method is called from within the ew_init method immediately before the style specified by pstyle is set into property: it can be replaced by subclassers in order to modify the default initialisation style. INT ew_readonly (VOID) ; Return the read-only state of the current document. The default method returns TRUE. Subclassers may replace the method to provide the desired functionality. A subclasser could for example allow read-only access while in outline mode and read-write access in normal mode. PUNCTUED flags landlord scrimg select id offset scrlay change width doc flags cpos margins font PUNCTUED destees;: wn_calc_position wn_connect wn_dodraw destroy wn_visible lg_draw lg_self_check i ee ew_snuggle_insert wn_init ew_set_font wr—key ew_leave wn_draw ew_find wn_sense_ help ew_replace wn_set ew_evaluate wn_sense ew_replace clip wn_emphasise ew_paste clip 1lg_set_id_pos ew_bring_in lg_sense_width ew_ep insert ew_sense_size ew_return_key ew_set_ size ew_tab_key ew_set ew_init_style ew_sense ew_readonly ew_insert wn_key wn_position wn_redraw The punctuep class provides an edit window displaying a single punctuation character. An example puctuation editor is shown in the following picture: 10-24 10 TEXT EDITORS Set date and time formats ‘Date format ¢Day month year > ‘Date separator / ‘Time format am-pm ‘Time separator The punctuation editor is the fourth control in the above dialog and allows the user to alter the time separator character. The dialog is taken from the Time application. Class definition Defined in sub-category file edwin.cl (generated header file edwin.g). CLASS punctued edwin punctuation editor, one line editbox & it's a lodger REPLACE wn_key } Property None. Pe a Fir eS Sg | PUNCTUED methods e key input VOID wn_key(INT keycode, INT modifiers) ; Handle a keypress. If keycode is not a punctuation character, calls hBeep and return. Otherwise sets the punctuation character into the edit window by sending se1f a wn_SET message. 10 - 25 HWIM REFERENCE FLTEDIT destrey wn_cale position wn_connect wn_dodraw destrey wn_visible 1lg_draw wn_position wn_redraw tge—sense—width lg_update wn_emphasise 1g_set_id_pos 1lg_sense_width ew_sense_size ew_set_size ew_set ew_sense ew_insert margins font ew_snuggle_insert ew_set_font ew_leave ew_find ew_replace ew_evaluate ew_replace clip ew_paste_ clip ew_bring_in ew_ep_ insert ew_return_key ew_tab_key ew_init_style ew_readonly Page size (cm) ae i-Pagesize Custom Pidth | ‘Height 29.70 Orientation Portrait The second and third controls in the above dialog are both floating point editors with the display format set to fixed - i.e. a fixed number of decimal places. Class definition Defined in sub-category file /ltedit.cl (generated header file fltedit.g). CLASS fltedit edwin floating point editor; works in either general or fixed format REPLACE wn_init REPLACE wn_set REPLACE wn_sense REPLACE lg_self_check CONSTANTS { FLTEDIT_MAX_CHAR 20 /* -x.xx...x (13 dec places) E-99 */ SE_FLTEDIT_CURRENT 0x01 SE_FLTEDIT HIGH 0x02 SE_FLTEDIT_LOW 0x04 } 10 - 26 10 TEXT EDITORS ae TYPES { typedef struct { DOUBLE current; DOUBLE low; DOUBLE high; UBYTE vulen; UBYTE format; } IN_FLTEDIT; typedef struct { DOUBLE current; DOUBLE low; DOUBLE high; WORD set_flags; } SE_FLTEDIT; } PROPERTY { DOUBLE current; DOUBLE low; DOUBLE high; UBYTE point; /* /* /* /* /* current value */ lower bound */ upper bound */ view len, ie no. of char on display */ fixed no of dec places, or 0 for general */ current value lower bound upper bound which fields to set UBYTE format; stores #decPlaces, which determine format (fixed or general) } } Property fltedit.current the editable value. fltedit.low the lower limit on the editable value. fltedit high the upper limit on the editable value. fltedit.point the oe specific decimal separator character: a full stop on English language machines. fltedit. format the number of digits after the decimal point or zero indicating general format. SSeS a a a a a a FLTEDIT methods Initialise VOID wn_init (IN_FLTEDIT *init,PR_WIN *landlord) ; Initialise the floating point editor according to the content of the 1n_FLTeprT struct pointed to by init and the ID of the landlord window specified by landlord. Writes the country specific decimal separator character to fltedit .point. The 1n_FLTEDET struct is defined as follows: typedef struct { DOUBLE current; /* current value */ DOUBLE low; /* lower bound +*/ DOUBLE high; /* upper bound */ UBYTE vulen; /* view len, ie no. of char on display */ UBYTE format; /* fixed no of dec places, or 0 for general +*/ } IN_FLTEDIT; 10-27 HWIM REFERENCE ae The significance of the members of the 1n_FLTzEpIT struct is as follows: current the initial value for the editable value. low the lower limit on the editable value. high the upper limit on the editable value. vulen the maximum number of characters to represent the editable value in the edit window. format ae number of digits after the decimal separator character or zero to indicate general ormat. Sets the current value in the edit window by supersending a wN_InIT message. VOID wn_set(SE_FLTEDIT *pset) ; Set the content of the floating point editor according to the se_FLT=DrT struct specified by pset. The sE_FLTEDIT struct is defined as follows: typedef struct { DOUBLE current; DOUBLE low; DOUBLE high; WORD set_flags; } SE_FLTEDIT; The significance of the members of the sE_FLTEDIT struct is as follows: current the candidate editable value. low the candidate minimum allowed value. high the candidate maximum allowed value. set_flags see below. The setting is controlled by oring into the flags member of the se_FLTEp1IT struct a suitable combination of the following flags: SE_FLTEDIT_CURRENT indicates that the editable value should be set. SE_FLTEDIT_HIGH indicates that the upper limit should be set. SE_FLTEDIT_LOW indicates that the lower limit should be set. Converts £1tedit.current into a string representation and sets into the edit window by supersending a WN_SET message. ‘Sense current value VOID wn_sense (DOUBLE *pdbl) ; Sense the current value and write the result to the pousLe specified by pab1. Senses the content of the edit window by supersending a wn_SENSE message. Converts the string representation of the editable value into a double and writes the result to *pab1. 10 - 28 10 TEXT EDITORS LG SELF CHECK Validate fields INT lg_self_check{VOID) ; Check the editable value. On success returm TRUE. If the editable value is less than 1. o£-99 displays an appropriate error message using the hInfoPrintErr routine and returns E_GEN_UNDER. If the editable value is greater than 1.o£99 displays an appropriate error message using the hinfoprintErr routine and returns E_GEN_OVER. If the editable value is not a number - 123abc for example - displays the sys_INVALID_NUM system resource using the hinfoprintérr utility routine and returns FALSE. If the editable value is less than f1tedit .1ow, writes £1tedit .low to fltedit current, displays an appropriate error message using the hInfoPrint utility routine - the error message is constructed from the SYS_OUT_OF_RANGE and sys_MIN system resources and fltedit.1low - and returns -]. If the editable value is greater than fltedit .high, writes £1tedit .low to fltedit .current, displays an appropriate error message using the hinfoprint utility routine - the error message is constructed from the SYS_OUT_OF_RANGE and sys_MAX system resources and f1tedit.high - and returns 1. Otherwise if no error detected returns TRuE. XEDIT flags landlord offset width current data destroy destroy wn_cale_position wn_visible 1g_sense_width wn_connect 1lg_draw wn_key wn_dodraw 1g_self_check wn_draw whremphasise : wn_set wa-key wn_sense wn_position wn_redraw wn_emphasise tge—sense—width ig_update The xeprr class provides a single line text editer suitable for entering passwords of eight characters or less. An example password editor is shown in the following picture: Set password ‘Enter passwordyt-y-)-) Sa ‘Confirm password ‘Password set The characters typed in are indicated by the padlock symbols with the cursor position indicated by the solid black rectange. 10 - 29 HWIM REFERENCE ee SSeSSSSSSeeeEeSSSSSSSSSSSSSSSSSSSSSSSSSSSSSMhhhheeee Class definition Defined in sub-category file xedit.c/ (generated header file xedit.g). CLASS xedit lodger Secret editor with only 1 line of 8 chars to deal with keying in password. { REPLACE lg_sense_width REPLACE wn_key process key press REPLACE wn_draw REPLACE wn_sense REPLACE wn_set clears/blanks the data in property REPLACE wn_emphasise always return false in this case CONSTANTS { XEDIT_MAX_LEN 8 } TYPES { typedef struct { TEXT *pstr; } SE_XEDIT; } PROPERTY { UBYTE current; UBYTE width; TEXT data [(XEDIT_MAX LEN+2] ; } } Property xedit.current the length of the password. Warning: on the Series 3 this property is defined as a worn. xedit.width the width of a single character. Warning: on the Series 3 this property is not defined. xedit.data the password buffer containing the password - stored as a zero terminated string. See ee en ee ee en a i TT XEDIT methods Get required width INT lg_sense_width (VOID) ; Sense the width of the password editor. The method returns the width of the underscore character used in the password editor, multiplied by (EDIT_MAX_LEN+1). On the Series 3, on other machines running in compatibility mode and in a small font dialog on the Workabout, the character is the normal underscore (ASCII ox s¢£). In all other cases, the character is that specified by ws_syMBoL_PASS_UNDERLINE, defined in symbols.h. _Handie key input INT wn_key (INT keycode, INT modifiers) ; Handle a keypress. If keycode is W_KEY_DELETE LEFT, removes the last character from the password by writing zero to xedit .data[xedit.current] and decrementing xedit .current. Returns wN_KEY_CHANGED. 10-30 10 TEXT EDITORS Otherwise if keycode is less than oxoorr and the cursor position is less than xEDIT MAX LEN, adds the keypress to the password by writing keycode to xedit .data(xedit.current] and incrementing xedit.current. Returns wN_KEY_CHANGED. Otherwise calls hBeep and returns wN_KEY_NO_CHANGE. WN_DRAW = oy VOID wn_draw(VOID) ; Draw the password editor. Draws a ws_SYMBOL_PapLock character for each character of the password and an underscore character - as specified in the 1g_sense_width method - for the remaining characters in the display. If win. £1ags contains PR_WIN_EMPHASISED, draws a solid black rectangle to indicate the position of the cursor. os Sense data VOID wn_sense(SE_XEDIT *psense) ; Sense the content of the password editor and write the result to psense. Writes the address of the first character in xedit.data to sense->pstr. _ Clear password data VOID wn_set (VOID) ; Reset the password. Clears the password by writing zero to each element of xedit .data and writing zero to xedit.current. Draws the control by sending self an Lc_DRAw message. VOID wn_emphasise (INT flags) ; Emphasise the control if flags is non-zero, otherwise de-emphasise the control. If flags is non-zero, sets PR_WIN_EMPHASISED in win. flags. Otherwise clears PR_WIN_EMPHASISED in win. flags. Sends self an LG_DRAw message. 10-31 CHAPTER 11 GAUGE CLASSES This chapter describes the cauce and ponzwn classes which support graphical gauge controls for use as components in a dialog. Precursors Familiarity with the following topics will aid the understanding of this chapter: e the wn and Loncer classes described in the Windows chapter of the HWIM Reference manual. e the picBox class described in the Dialog Boxes chapter of the HWIM Reference manual. Class diagram GAUGE landlord size offset width colour destroy wn_cale position whoinit wn_connect wn_visible wn_dodraw lg_draw wn_emphasise lg_self_ check wn_draw wn_init wn_set 1g_sense_width wn_key lg_set_id_pos wn_position wn_redraw tg—sense—width wn_sense_help lg_update The Gauce class provides a graphical representation of a gauge with four segments each of which may be either, black, grey or white. An example of an instance of the cauce class used as a component in a dialog is shown in the following picture: 11-1 HWIM REFERENCE Memory 512K 8 Internal disk 293K OFree 189K Previous a The above example uses three segments to indicate the usage of memory: the width of the fourth segment is set to zero. This dialog may be obtained by selecting the Memory info menu item in the system screen. See also the ponewn class described in a later section of this chapter. Class definition Defined in sub-category file gauge.cl (generated header file gauge. g). CLASS gauge lodger Gauge Display with 3 colour graphical representation REPLACE wn_init Set item Dead and centre & setup landlord REPLACE wn_set Sets up the colour and size of each section of gauge REPLACE lg_sense_width Return min possible width for gauge REPLACE wn_draw Draws the gauge CONSTANTS { GAUGE_WHITE 1 GAUGE_GREY 2 GAUGE_BLACK 3 } TYPES { typedef struct { UWORD size[4]; UBYTE colour [4] ; } SE_GAUGE; } PROPERTY { UWORD size[4]; UBYTE colour [4] ; } } Property gauge.size an array of four elements each of which defines the width of a gauge segment. gauge.colour an array of four elements each of which defines the colour of a gauge segment. Available colours are GAUGE_WHITE, GAUGE_GREY and GAUGE_BLACK. SSS = ee ee er ry GAUGE methods lnitialise VOID wn_init (SE_GAUGE *par,PR_WIN *landlord) ; Initialise the gauge to appear as a dead and centred component in the window with id landlord. Writes landlord to lodger. landlord and sets DLGBOX_ITEM_ CENTRE and DLGBOX_ITEM_DEAD in the landlord flags property by sending a pL_sET_ITEM_FLAGS message to lodger. landlord. The par argument is included for use by subclassers: a replacement method might, for example, supersend a WN_INIT message and then send a w_SET message with initial values for the segment widths and colours as specified in the se_GaucE struct. 11-2 11 GAUGE CLASSES _ Set characteristics of gauge sections VOID wn_set(SE_ GAUGE *pset) ; Set the appearance of the gauge according to the content of the sz_Gauce struct with address pset. Scales the segment sizes specified in the s_Gavuce struct such that the gauge has width lodger. width. Writes the scaled sizes and the colours from the se_caucE struct to the gauge. size and gauge .colour property respectively. Draws the lodger window by sending an uc_praw message to self. INT lg_sense_width(VOID) ; Return the minimum width for the gauge. VOID wn_draw(VOID) ; Draw the gauge component in the lodger window. The gauge has height eight pixels on the Series 3 and thirteen pixels on the Series 3a and width lodger .width on both machines. The relative widths and the colours of the gauge segments are as specified by the last wn_sET message. DONEWN landlord size offset colour width destroy wn_draw wn_calc_ position wrh-init wn_init wn_connect wn_visible wh-set wn_dodraw 1lg_draw lg_sense_width wn_emphasise 1ig_self_check wn_key lg_set_id_pos wn_position wn_redraw ig—sense—nidth wn_sense_help lg_update wa-visible The povewn class supports a graphical gauge that can be used as a component in a dialog or ina compatible subclass of the Lopcsr class. An example of a ponewn gauge is shown in the following picture: Further examples can be obtained by selecting the Format disk and Copy disk commands from the Series 3 system menu. 11-3 HWIM REFERENCE SSS The dialog shown in the picture above can be created using the following resources: RESOURCE ACLIST_ARRAY replace_ac { button= { PUSH_BUT { keycode=W_KEY_ESCAPE; str="Cancel"; } }; } RESOURCE DIALOG replace_di_res { title="DONEWN gauge demonstration"; flags=DLGBOX_NOTIFY_ESCAPE|DLGBOX_RBUF_FILLED; controls= { CONTROL { class=C_DONEWN; } 7 CONTRO { class=C_ACLIST; info=ACLIST { rid=replace_ac; es ~ — } Class definition Defined in sub-category file donewn.cl (generated header file donewn.g). CLASS donewn gauge { REPLACE wn_set CONSTANTS { : SE_DONEWN_RANGE Ox01 SE_DONEWN_VALUE 0x02 SE_DONEWN_INCREMENT 0x04 /* val will be increased by 1 */ SE_DONEWN_INC_VAL 0x08 /* val will be increased by whatever val is set */ } TYPES { typedef struct { UWORD flags; ULONG val; ULONG range; } SE_DONEWN; } PROPERTY { ULONG val; ULONG range; } 11-4 11 GAUGE CLASSES Property donewn. val specifies the relative width of the first segment. This segment has colour grey. donewn.range _ specifies the relative width of the gauge display. The second segment has colour white and relative width range-val. DONEWN methods Set gauge VOID wn_set (SE_DONEWN *pset) ; Set the gauge according to the content of the sz_ponewn struct with address pset. The sE_Donewn struct is defined as follows: typedef struct ULONG flags ULONG val ULONG range } SE_DONEWN; The property to be set is specified by oring one or more of the following flags into the flags member of the above struct. SE_DONEWN_RANGE indicates that donewn. range should be set from member range SE_DONEWN_VALUE indicates that donewn.vai should be set from member val SE_DONEWN_INCREMENT indicates that donewn. vai should be incremented by one unit SE_DONEWN_INC_VALUE indicates that donewn.val should be incremented by member val Note that donewn.val is assumed to be less than or equal to donewn. range. Whenever this is not the case, it will be set equal to donewn. range. For the third and fourth segments, writes zero to the size and caucz_sxacx to the colour property. These segments will thus not be visible. Sets the values into the superclass property by supersending a wN_sET message. Using Gauges The following section includes examples of dialogs containing caucE and ponEwn controls. See also the gauge example code that can be installed from the SDK Optional disk into a \sibosdk\hwimdemo\ directory. A GAUGE class example The first example illustrates the use of the caucE class as a dialog component. The example dialog simply contains a title and a cauce control. The initial appearance of the cauce control is set by passing an appropriately initialised sz_Gaucs struct to the dialog on creation. The structure and content of the dialog is specified using the following dialog resource: 11-5 HWIM REFERENCE SESS RESOURCE DIALOG gauge_dl_res ( { title="GAUGE demonstration"; £lags=DLGBOX_NOTIFY_ESCAPE|DLGBOX_RBUF_FILLED; controls= { CONTROL { class=C_GAUGE; } }; } The caucepte dialog class subclasses picBox and replaces the d1_dyn_init method to allow dynamic initialisation of the dialog. The caucepte class is defined as follows: CLASS gaugedlg dlgbox REPLACE dl_dyn_init; } The code for the a1_dyn_init method is as follows: METHOD VOID gaugedlg_dl_dyn_init (PR_GAUGEDLG *self) f { p_sendé4 (self, WN_SET,1,self->dlgbox.rbuf) ; The dl_dyn_init method does no more than set the caucE control using the sE_caucE struct pointed to by self->dlgbox.rbuf. The following code may be used to launch the dialog: LOCAL_C INT LaunchDial(VOID *buf,INT id, INT class) { DL_DATA dl_data; dl_data.id=id; dl_data.rbuf=buf; dl_data.pdlg=NULL; return (p_sends (w_ws,O_WS_DO_DIAL,p_getlibh(CAT_DEMO_DEMO) , class, &dl_data)); } SE_GAUGE se_gauge; /* set the members of se_gauge as appropriate */ LaunchDial (&se_gauge,GAUGE_DL_RES,C_GAUGEDLG) ; A DONEWN class example The second example illustrates using the ponswn class as a dialog control to inform the user of memory usage. The initial appearance of the ponewn control is specified by means of an sE_ponewn struct passed to the dialog on creation. The structure and content of the dialog is specified by the following dialog resource: RESOURCE DIALOG gauge_dl_res { title="DONEWN demonstration"; flags=DLGBOX_NOTIFY_ESCAPE|DLGBOX_RBUF_FILLED; controls= { CONTROL { class=C_DONEWN; } hi 11-6 11 GAUGE CLASSES _—_—_ SS Ow CAGE CLASSES The ponent dialog class subclasses pigBox and replaces the d1_dyn_init method to provide application specific initialiation. The caucepue class and the d1_dyn_init method are defined as follows: CLASS donedlg dlgbox { REPLACE dl_dyn_init; } RESOURCE STRING { str="Memory used is %d Kbytes"; } METHOD VOID donedlg_dl_dyn_init(PR_DONEDLG *self) { TEXT buf [DONEDLG MAX TITLE] ; hAtob (&buf [0] , DONEDLG_TITLE_RES, self->dlgbox.rbuf->val) ; hDlgSetText (0, &buf [0]); p_send4 (self, WN_SET,1, self->dlgbox.rbuf) ; The dl_dyn_init method initialises the text in the title and the segment in the gauge according to the content of the sE_DonEwn struct pointed to by digbox. rbuf. The dialog may be launched as follows: SE_DONEWN se_donewn; /* set the members of se_donewn as appropriate */ LaunchDial (&se_donewn, GAUGE_DL_RES,C_GAUGEDLG) where the LaunchDia1 utility routine is defined in the previous section. A dynamic gauge A common use of the ponewn class is to inform the user of the progress of a lengthy operation: the length of the shaded region of the gauge - which is initially set to zero - is simply incremented after the completion of each step of the operation. This may be done by simply queueing a suitable active object before launching the dialog by sending a wWS_DO_DIAL message to the wsERv object. The active object will run as soon as the dialog is visible: the WS_DO_DIAL Message Causes an AM_START message to be sent to the application manager thus giving an opportunity to all queued active objects to run. This opportunity to run is cancelled by the dialog when on terminating it sends an am_sTop message to the application manager. In the example, a lengthy operation is simulated by an active object that does no more than queue a timer and then update the gauge control in the dialog. An example dynamic gauge is shown in the following picture: Loading data Cancel Sa The active object and the dialog are launched as follows: ULONG duration; duration=100; /* tenths of a second */ £_newsend (CAT_DUMP_DUMP,C_ATIMER,O_AO INIT, &duration) ; LaunchDial (&duration,GAUGE_DL_RES,C_GAUGEDLG) ; where duration specifies the length of the operation in tenths of a second. The initial content and appearance of the dialog are specified by means of the following resources: ee 11-7 HWIM REFERENCE SS RESOURCE ACLIST_ARRAY escape_ac { button= { PUSH_BUT { keycode=W_KEY_ESCAPE; str="Cancel"; } }; } RESOURCE DIALOG gauge_dl_res { £lags=DLGBOX_NOTIFY_ENTER |DLGBOX_RBUF_FILLED; controls= { CONTROL { class=C_TEXTWIN; £lags=DLGBOX_ITEM_CENTRE | DLGBOX_ITEM_DEAD; info=TXTMESS { flags=IN_TEXTWIN_AL CENTRE; str="Loading data"; }; } 7 CONTRO: { class=C_DONEWN; }, CONTROL { class=C_ACLIST; info=ACLIST { ridsescape_ac; }y }; } The GaucEpuc class subclasses pi¢cgox and replace the d1_dyn_init method to allow dynamic initialisation of the dialog. The caucepusc class is defined as follows: CLASS gaugedlg dlgbox REPLACE dl_dyn_init } The code for the dl_dyn_init method is as follows: METHOD VOID gaugedlg dl_dyn_init (PR_GAUGEDLG *self) { SE_DONEWN se_donewn; se_donewn.val=0L; se_donewn.range=* (ULONG *)self->dlgbox.rbuf; se_donewn . flags=SE_DONEWN_RANGE|SE_DONEWN_VALUE; p_send4 (self,O_WN_SET,1,&se_donewn) ; } The di_dyn_init method does no more than set the initial value and the range of the pongwn control. The arimer class provides the active object which updates the gauge every one tenth of a second. After the elapse of a predetermined interval the active object destroys both itself and the dialog. The arrmer class is defined as follows: 11-8 11 GAUGE CLASSES eo eee ON OD ES CLASS atimer timer { REPLACE ao_init REPLACE ao_run REPLACE ao_queue PROPERTY { ULONG count; ULONG total; } } The code for the ac_queue method is as follows: METHOD VOID atimer_ao_queue(PR_ATIMER *self,UINT lsw,UINT msw) { self->active.stat=E_FILE_ PENDING; self->active.isactive=TRUE; p_supersend4 (self,O AO QUEUE, 1sw,msw) ; } The ao_queue method queues a timer the duration of which is specified as a long integer broken down into the least significant word - 1sw - and the most significant word - msw. The code for the ac_init method is as follows: METHOD VOID atimer_ao_init (PR_ATIMER *self,ULONG *ptotal) { p_send3 (w_am,O_AM_ADD_TASK,self) ; self->active .priority=PRIORITY_ACTIVE_WSERV-1; self->atimer.count=0L; self->atimer.total=*ptotal; p_supersend2 (self,0_ AO INIT); p_send4 (self,O_AO_QUEUE,1,0); The ao_init method carries out the following actions: e adds se1¢ to the task queue, and sets the task priority to PRIORITY_ACTIVE_WSERV less one, to ensure that the timer does not interfere with keypresses. e — sets the initial count and stores the total duration. © opens a timer channel by supersending an ao_1nzT message and then queues a timer. The code for the ao_run method is as follows: METHOD INT atimer_ao_run(PR_ATIMER *self) { SE_DONEWN se_donewn; if (w_ws->wserv.dial) { self->atimer.count++; se_donewn. flags=SE_DONEWN_INCREMENT ; p_send4 (w_ws->wserv.dial,O_WN_SET,1,&se_donewn) ; if (self->atimer.countatimer.total) { p_send4 (self,O_AO QUEUE,1,0) ; return (RUN_ACTIVE_USED) ; } else p_send2 (w_ws->wserv.dial,O_ DESTROY) ; } p_send2 (self,O_ DESTROY) ; return (RUN_ACTIVE_USED) ; } The ao_run method carries out the following actions: e — if the dialog does not exist - i.e the user has pressed the Escape key - it sends self a DESTROY message and returns RUN_ACTIVE_USED. a SSSFSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSeeeeEeEeee 11-9 HWIM REFERENCE aS ee © if the maximum allowed number of timers has been reached, it sends pesTRoy messages to self and to the dialog and then returns RUN_ACTIVE_USED. e — otherwise it increments the cauce control display and queues the next timer. Annotating a gauge The following section illustrates a convenient means of labelling a gauge control The following example dialog indicates the current memory usage: Memory usage 8 Total used 188K O Free 412K The second item is a TexTwrn control with appropriate text set for the prompt and the body text. On the S3a the following resource may be used to create the above dialog: RESOURCE STRING used_kbytes res { str="%tc Total used %1luK"; } RESOURCE STRING free_kbytes_res { str="%c Free %luk"; } RESOURCE DIALOG demo_dl_res { £lags=DLGBOX_NOTIFY_ENTER |DLGBOX_RBUF_FILLED; title="Memory usage"; controls= { CONTROL { class=C_TEXTWIN; £lags=DLGBOX_ITEM_DEAD; prompts" "3 info=TXTMESS { flags=IN_TEXTWIN_AL RIGHT; }; } 7 CONTROL { class=C_DONEWN; } }i } Note that the prompt for the r=xTwrn control is defined as a space in order that the prompt may be redefined dynamically. The pemopxe class subclasses the piGsox class and replaces the di_dyn_init method to allow dynamic initialisation of the dialog. The pemonte class is defined as follows: CLASS demodlg digbox { REPLACE dl_dyn_init } The code for the dl_dyn_init method is as follows: 11-10 11 GAUGE CLASSES OO hr rrr — OE ES METHOD VOID demodlg_dl_dyn_init (PR_DEMODLG *self) { TEXT buf [40] , resbuf [40] ; ULONG free; ULONG used; p_send4 (self,O_WN_SET,2, (SE_DONEWN *)self->dlgbox.rbuf) ; used=((SE_DONEWN *) self->dlgbox. rbuf) ->val; p_send4 (w_am,O_AM_LOAD_RES_BUF,USED_KBYTES_RES, &resbuf [0] ); p_atos (&buf [0] ,&resbuf [0] ,WS_SYMBOL_GREY_BOX, used) ; hDlgSetPrompt (1, &buf [0] ) ; free=((SE_DONEWN *) self->dlgbox. rbuf) ->range-used; p_send4 (w_am,O_AM_LOAD_RES_BUF,FREE_KBYTES RES, &resbuf [0]) ; p_atos (&buf [0] ,&resbuf [0] ,WS_SYMBOL WHITE_BOX, free) ; hDlgSetText (1, &buf [0] ); } The method carries out the following actions: sets the ponEwn control using the sz_ponewn struct pointed to by digbox. rbuf. sets an appropriate prompt for the TexTwrn control indicating the memory usage. sets an appropriate body text for the TExtTwin control indicating the free memory. The following code may be used to run the dialog: METHOD VOID democom_com_run(PR_DEMOCOM *self) { SE_DONEWN se_donewn; se_donewn.val=100L; se_donewn.range=512L; se_donewn. flags=SE_DONEWN_VALUE|SE_DONEWN_RANGE; LaunchDial (&se_donewn, DEMO_DL_RES,C_DEMODLG) ; } where the hLaunchDial utility routine is defined in an earlier section. On the Series 3 boxes may be constructed as follows: a grey box may be constructed by concatenating the ws_symBoL_GREY_Boxi and WS_SYMBOL_GREY_BOx2 characters. a white box may be constructed by concatenating the ws_syMBOL_WHITE_Box1 and WS_SYMBOL_WHITE_BOx2 characters. a black box may be constructed by concatenating the ws_symMBoL_BLACK_Box1 and WS_SYMBOL_BLACK_Box2 Characters. 11-11 ? 8 CHAPTER 12 FILE SELECTORS This chapter documents some of the classes associated with the filing system. These classes are: e the vanev class which creates and stores a list of the available devices. e the pacxseE class which provides a dialog contro! that allows the user to select a pack. e the rneprt class which provides a dialog control that allows the user to edit a path and a filename. e and the rnsELwn class which provides a dialog control that allows the user to select an existing file. For a description of the FrLELrsrt class - which supports the graphical file list - see the FILELIST chapter of the HWIM Reference manual. Precursors Familiarity with the following topics will aid the understanding of this chapter: e the varoor and related classes described in the Variable Array Classes chapter of the OLIB Reference manual. VADEV size gran base len recno precno destroy va_copy va_count va_reclen va_delete Varnie va_init va_search va_pbuf va_sort va_key va_swap va_findisq va_init va_insertisq va_append va_insert va—seareh va_compare va_reset va_test va_compress va_capacity va_deletem va_insertm va_prec va-pbut The vapev class may be used to create a list of available devices stored as variable length text records. The class provides methods to search for a device and to retrieve the public device name. 12-1 HWIM REFERENCE ee SSS The list may be updated by simply creating a new instance of the class. An application that wishes to use the vapev class should ensure that: e the application manager creates an instance of the cLEanup class during initialisation. e the application manager property is stored in the w_am magic static. Both of the above conditions are satisfied by the Hwrmman application manager class. Class diagram Class definition Defined in sub-category file files.cl (generated header file files.g). CLASS vadev vastr { REPLACE va_init REPLACE va_search REPLACE va_pbuf PROPERTY TEXT buf [20]; } Property vadev. buf contains the public device specification written by the last va_psur message. If a vA_PBUF message has not been sent since instantiation the buffer contains the nuxt string. CEE I era ee ee ee a ee er VADEV methods VOID va_init (VOID) ; Scan the available devices and for each create a record containing a device specification with format node::device:. The first record specifies the local internal device: Loc: :m:. VA_SEARCH INT va_search(TEXT *target) ; Return the index of the record that matches the device specification pointed to by target. The device specification pointed to by target may omit the trailing colon thus obeying the format node: :device. This is not recommended as it increases the time required to locate the record. On failure return 1. VA_PBUF | Return public device specification TEXT *va_pbuf (UWORD num) ; Return a pointer to the public name of the device specified in record num. For the local internal device the public name is read from the sys_pEvrce_mEMoRY system resource. On English language machines it is "Internal". 12-2 2 FILE SELECTORS For all other local devices the public name for a device with specification Loc: : device: is device. (Thus the public form of oc: :a: is a.) For all other devices the public name is identical to the device specification. PACKSEL desteey landlord offset width wn_cale_positio n wn_connect wn_visible lg_ draw matcher matchlen nsel pop destroy 1lg_sense_width wn_draw wn_emphasise PACKSEL filsel err wn_init wn_set wn_key lg_self_check wn_dodraw tg—seif—eheek lg_set_id_pos ig—sense—width waaset wn_position = lg_update wn_redraw wn_sense_help The pacxsex class implements the pack selector control which allows the user to select the required device from the available list. The selection may be changed using the left and right arrow keys, first letter matching, or by pressing the Tab key to obtain a pop-out menu. An example pack selector control is shown in the following picture: Open .pic file ‘Name Dtedit ¢Internal+ Both the file name editor and file name selector controls may include a pack selector simply by oring the DLGBOX_ITEM_NEEDS_Pack flag into the £1ags member of the contro resource as follows: RESOURCE DIALOG demonstration { title="Open .pic file"; £lags=DLGBOX_NOTIFY_ENTERDLGBOX_RBUF_ FILLED; controls= { CONTROL { class=C_FNSELWN; flags=DLGBOX_ITEM_NEEDS_PACK; prompt=""; info=FNSELWN { fname="Dtedit.pic"; }; 12-3 HWIM REFERENCE Class diagram f ~~. ta ia ~~ t beat - $ ed i Cae: é mt ie: : > (7 Ghiist > _|/ packsel™> fnedit ~> ‘ / d i aes ; ‘Ss. mt a hy . f _ O a { me 1 me n ~~ 1 ~~ iN “~~ 1 . } : : . ‘ } ‘ a weer” y ye eee! 4 wa ee! oa meee y [yatta tee wee tee Se Cannel eae “a oi mae, % Serer ae poss cel ewe Nates > vmatcher> vadev > 8 : ¢ ‘ f ‘a Se 1 Nee ee, y ee ! , aie ae i \ eet? its See otal tee. ao ase Nn eee A asee / listbox > Class definition Defined in sub-category file files.cl (generated header file files.g). CLASS packsel chlist { REPLACE wn_init build data to pass on to chlist REPLACE wn_set convert text to nsel item f REPLACE wn_key notify filsel of any changes \ REPLACE lg _self_check checks whether drive is empty CONSTANTS { PR_CHLIST_PACKSEL_DODINFO 0x8000 } PROPERTY { PR_LODGER *filsel; fnedit or fnselwn WORD err; result of last dinfo on self } } Property packsel.filsel — this must contain the handle of an instance of either the rweprt class or the rnsELWN class. packsel.err this is a code giving the error status of the current device. It is obtained by calling the p_dinfo PLIB routine. Sy ee ee a ye PACKSEL methods VOID wn_init (TEXT *init,PR_WIN *landlord,PR_LODGER *filsel) ; Initialise the pack selector according to the landlord window ID specified by 1andlora and the handle of an instance of either the rwepzrt class, or the rNsELwn class, specified by filsel. Writes landlord to lodger. landlord. Writes £i1sel to packsel. filsel. The class uses a vapEV component to store the names of the available devices: creates an instance of the VaDEV Class, writes the handle to chiist .data and then initialises the vapzv component by sending a VA_INIT message to chlist.data. Note that the init argument is not used. 12-4 12 FILE SELECTORS Str oo er re ~ Set pack from file name INT wn_set (TEXT *pset,P_FPARSE *pcrk) ; Set the current pack. The pset and perk arguments are assumed to point to a full file specification and an associated p_FPARSE struct respectively: sets the current device according to the device specified by the arguments. If chiist .flags contains PR_CHLIST_PACKSEL_DODINFO: e obtains an error code for the current device by calling the p_dinfo pLzB routine and writing the return value to packsel.err. Returns packsel.err. INT wn_key (INT keycode,INT modifierss) ; Handle a keypress. Allows the superclass to handle the keypress by supersending a wn_KEy message. If the return value from the wn_key message is wN_KEY_CHANGED - in which case the current device has changed - displays the information message in the sys_SCANNING system resource: on English language machines this is "Scanning". If chlist . flags contains the PR_CHLIST_PACKSEL_popinFo flag: e obtains an error code for the current device by calling the p_dinfo pure routine and writing the return value to packsel.err. Ensures that keypresses are not absorbed by the control by writing FALSE to dlgbox.absorb. Sets the current device for the associated FNEDIT or FNSELWN control by sending an LG_UPDATE message to packsel.filsel passing as arguments a pointer to the current device specification, and an error status: if chlist.flags contains PR_CHLIST_PACKSEL_DODINFo, the error status is packsel.err, and zero otherwise. Ensures that any information message is cancelled. Returns the return value from the wn_xey message. IS TEPC CR ATS AO INT lg self check (VOID) ; Validate the current device. If packsel.err is non-zero, or PR_CHLIST_PACKSEL popInFro is set in chlist. flags, obtains an error code for the current device by calling the p_dinfo puzs library routine and then writes the error code to packsel.err. If packsel.err is still non-zero, displays an appropriate information message, and then returns FALSE. If packsel.err was previously non-zero: e displays the information message in the sys_scanwinc system resource: on English language machines this is "Scanning". e — sets the current device for the associated FNEDIT or FNSELWN control by sending an L¢_UPDATE message to packsel . filsel. © ensures that the information message is cancelled and then returns True. 12-5 HWIM REFERENCE FNEDIT select change flags margins font destrey ew_snuggle_insert wn_calc_position ins int ew_set_font wn_connect sd ew_leave wn_dodraw hd ew_find ew_replace 1lg_set_id_pos ew_evaluate wn_position ew_replace_ clip wn_redraw tg—sense—width : ew_paste_clip wn_sense_help ig_ update 1g_set_id_pos ew_bring_in lg_sense_width ew_ep insert ew_sense_size ew_return_key ew_set_size ew_tab_key ew_set ew_init_style ew_sense ew_readonly ew_insert wn_emphasise lg_self_check lg_update The repr class implements the file name editor control which allows the user to edit a file name. An example file name editor is shown in the following picture: Open .pic file ‘Name Dtedit ¢ Internal> A file name editor may have an associated pack selector control by oring the DLGBOX_ITEM_NEEDS_ PACK flag into the £1ags member of the Fneprt resource as follows: RESOURCE DIALOG demonstration { title="Open .pic file"; flags=DLGBOX_NOTIFY_ENTER | DLGBOX_RBUF_FILLED; controls= { CONTROL { class=C_FNSELWN; flags =DLGBOX_ITEM_NEEDS PACK H prompt=""; info=FNSELWN { fname="Dtedit .pic"; ); 12-6 12 FILE SELECTORS Class diagram ats Es artsy, ats. ® Parr i aa rs Om ae se ria eee Nag (Oot eee Mee, if Sa 1 te ee! oe ’ * . S ri . a , H as : at, / win > /“ lodger ©; /“ edwin > / fnedit ~> “ packsel > ¢ ——— 7 ¢ 2 ya ng 4 u v2 it an ‘ : Be : SS : on \ 1 on 4 Pe 4 Oca ‘ O-- 1 free 3%, (0 tt ee Sho POT tt ee fens ~~ * 3 ac ’ ~e pardee ~ se vo & 7 ye? scrlay 0 ve li b 5 eet ‘ Bison 1 a : SN : . i x ‘ H oo eee ‘ ed *, Not? Peele gee eee oS Le esees /— seri 5 Note that an instance of the packsel class is optional. Class definition Defined in sub-category file files.cl (generated header file files.g). CLASS fnedit edwin { REPLACE wn_init REPLACE wn_set REPLACE wn_sense REPLACE wn_key REPLACE wn_emphasise REPLACE lg self_check REPLACE lg update CONSTANTS { IN_FNEDIT_STANDARD H_FILE_STANDARD_INIT IN_FNEDIT_ALLOW_DIRS | § H_FILE ALLOW DIRS IN_FNEDIT_JUST_DIRS H_FILE_JUST_DIRS IN_FNEDIT_FORCE_NXIST H_FILE FORCE NXIST IN_FNEDIT_NO_AUTOQUERY H_FILE_NO_AUTOQUERY IN_FNEDIT_ACCEPT_NULL H_FILE ACCEPT NULL IN_FNEDIT_SET_DEFEXT H_FILE SET DEFEXT IN_FNEDIT_CAN WILDCARD H_FILE_CAN WILDCARD } TYPES { typedef struct { UBYTE flags; TEXT fname [1]; } IN_FNEDIT; } PROPERTY 1 { PR_LISTBOX *pop; handle of pop-out menu (NULL if un-squirted mode) PR_PACKSEL *pack; UWORD flags; TEXT *defext; TEXT extbuf [6] ; TEXT buf [P_FNAMESIZE] ; } } Property fnedit.pop this is either the handle of an instance of the FrLELrst class - in which case the user has pressed the Tab key - or wuut otherwise. fnedit.pack this is either the handle of an instance of the packset class or nuut if there is no associated pack selector control. fnedit.flags an ored combination of flags that specify the behaviour (see below) 12-7 HWIM REFERENCE a SSS fnedit.defext this is a pointer to the default file extension and points to either fnedit .but or w_am- >hwimman.defext. fnedit.extbuf this is a buffer for the default file extension. fnedit.buf this is the path for the current file, e.g. REM: : E: \SIBOSDK\OOPDEMO\. SS ee ee eS eee eer FNEDIT methods ‘Initialise VOID wn_init(IN_FNEDIT *par,PR_WIN *landlord, PR_PACKSEL *pack) ; Initialise the file name editor according to the content of par- >flags. Writes pack to fnedit .pack. If par->£lags contains IN_FNEDIT_JusT_prirRs, ensures that the remaining flags are valid: sets IN_FNEDIT_ALLOW_DIRs, and clears IN_FNEDIT_SET_DEFEXT, IN_FNEDIT_CAN WILDCARD and H_FILE_CAN_TAG. Writes par. flags to fnedit. flags. Writes w_am->hwimman.defext to fnedit.defext. If fnedit .£1ags contains both In_FNEDIT_SET_DEFEXxT and IN_FNEDIT_STANDARD, and DatUsedPathNamePtr points to a file specification, copies the extension from patUsedPathNamePtr to the extension buffer fnedit .extbuf, and writes the address of the extension buffer to Enedit .defext. Clears IN_FNEDIT_SET_DEFEXT from fnedit. flags as the default extension is now set. Otherwise if fnedit . flags contains just IN_FNEDIT_SET_DEFEXT, and par->fname specifies a filename followed by an extension, copies the file extension from par->£name to the extension buffer fnedit .extbuf, and writes the address of the extension buffer to fneait.defext. Clears the IN_FNEDIT_SET_DEFEXT flag from fnedit .f1ags as the default extension is now set. If fnedit . flags contains IN_FNEDIT_STANDARD, builds a full file specification from DatUsedPathNamePtr, using the p_fparse PLIB library function, and a wuzs related file specification. Truncates the full file specification at the filename and write to fnedit .bué. Otherwise, if fnedit .f£1ags does not contain IN_FNEDIT_STANDARD, builds a full file specification from par->fname using the p_fparse PLIB library function, and a wutu related file specification. Truncates the full file specification at the filename and writes the result to fnedit .bué. Sets the pack by sending a wn_sET message to fnedit. pack passing as arguments fnedit . buf and the address of the p_Fparse struct written by the previous call to p_fparse. Sets the text in the edit box by supersending a wn_inrT message passing as arguments a pointer to an init struct and landlord, the id of the landlord window. The init struct is defined as follows: struct { IN_EDWIN ed; TEXT buf [P_FNAMESIZE] ; } anit; If fnedit . flags Contains IN_FNEDIT_STANDARD, ed.contents [0] is set to zero. If fnedit .£1ags contains the 1n_FNEDIT_JUsT_pIrRs flag, par->fname is built into a full path specification, using the p_fparse PLIB library function, and a uu related file specification. The full file specification is then truncated before the trailing directory and copied to ea. contents. (Thus "Loc: :m:", "REM: :C:\SIBOSDK\" and "REM: :C\SIBOSDK\DEMO\" would become "Loc: :M: ", "REM::C:" and "REM: :C: \SIBOSDK\" respectively.) Note that the In_FNEDIT_gusT_prrs flags is ignored if par->£name specifies a filename. If neither the In_FNEDIT_STANDaRD nor the IN_FNEDIT_JuUsT_prrs flags are set, the text specified by par- >flags is built into a full file specification using the p_fparse PLIB library function and a wut related file specification, and then copied to ed. contents. — SSS 12-8 12 FILE SELECTORS Sets DLGBOX_ITEM_CAN_DEFER_X and DLGBOX_ITEM_X_PENDING in the dlgbox.item[] .flags dialog property associated with this control, and returns. VOID wn_set (TEXT *fname) ; Set file name Set the filename and, optionally, the default extension, according to the file specification pointed to by fname. If the first character in fname . buf is 'l', removes the first character and builds a full file specification from fname using the p_fparse PLIB library function, and a nutu related file specification. Writes the file extension to fnedit .extbuf, and truncates fname at the filename. Builds a full file specification from fname using the p_fparse PLIB library function, and a uuu related file specification, and copies the result to fnedit .buf. Sets the pack by sending a wn_seT message to fnedit .pack passing as arguments fnedit .buf, and the address of the p_Fparsz struct written by the previous call to p_fparse. If fnedit . flags contains IN_FNEDIT_JuST_DIRs and fnedit .buf does not specify a filename, truncates fnedit. buf before the trailing directory. (Thus Loc: :M:, REM: :C:\TMP\ and REM: :C\TMP\DEMO\ would become Loc: :M:, REM::C: and REM: :C: \TMP\ respectively.) Truncates fnedit .bué at the filename if present. Sets the full file specification into superclass property by supersending a wn_sET message. : name INT wn_sense (TEXT *fname) ; Write to fname the full file specification of the current directory, or non-directory, file. Thus fname should be a pointer to a buffer of length at least p_FNamesize. Senses the file name by supersending a wy_sensE message and copies the result to the buffer specified by fname. Builds a full file specification using the p_fparse PLIB library function, and a related specification of fnedit .buf. Writes the full file specification to fname. Retums the return value from the p_fparse function if it is non-zero. If the full file specification contains one or more wildcards, and the In_FNEDIT_CAN_WwILDcaRDs flag is set in fnedit .flags, returns -1 indicating legal use of wildcards. If the full file specification contains one or more wildcards, and the In_FNEDIT_CAN_WILDcaRDs flag is not set in fnedit. flags, returms E_FILE_NAME indicating illegal use of wildcards. If the full file specification contains a name, or an extension, and the 1In_FNEDIT_gusT_piRs flag is set in fnedit.flags, appends a delimiter character to the file specification if not already present. (Thus LOC: :M:\TMP and REM: :C:\TMP.Dos would become Loc: :m:\TMP and REM: :C:\TMP.Dos\ respectively.) Builds a full file specification using the p_fparse PLIB library function, with a nuzt related file specification, and returns the return value. If the full file specification contains a filename, and the In_FNEDIT_JUST_DIRs flag is not set in fnedit. flags, uses the p_fparse PLIB library function to appends the default extension in fnedit .defext to fnedit.buf and returns the return value. If the full file specification does not contain a name, and neither of the 1In_FNEDIT_ACCEPT_NULL and IN_FNEDIT_ALLOW_piRs flags are set in fnedit . flags, returns ERROR_RID_OFFSET-SYS_CHOOSE_FILENAME. INT wn_key (INT keycode, INT modifiers) ; Handle the keypress specified by keycode and modifiers. If a file selector is present and thus fnedit .pop is non-zero: 12-9 HWIM REFERENCE e allows the file selector to handle the keypress by sending a wN_KEY message to £nedit . pop with arguments Of keycode and modifiers. If the user selects a valid file, sets this as the current file by sending self a wN_SET message. If the user selects a file that for some reason is not valid, and fnedit .flags does not contain IN_FNEDIT_JusT_p1Rs, displays an appropriate information message and then returns WN_KEY_CHANGED. ¢ otherwise if the return value from the wi_xey message is not wN_KEY_NO_CHANGE, destroys the pop- up file list by sending a pEstRoy message to fnedit . pop and writing FALSE to fnedit.pop. Emphasises the file name editor by sending a wn_EMPHASISE message to self. Returns the return value from the wn_KEy message. If keycode is a Tab, and modifiers contains the Psion modifier, displays the contents of fnedit .buf as an information message, and then returns wN_KEY_NO_CHANGE. If keycode is a Tab and modifiers does not contain the Psion modifier, senses the full file specification for the current file by sending a wn_SENSE message to self: ¢ if modifiers contains the Control modifier, allows the user to edit the file name pattern and the full path for the current file by launching a File list dialog: if the user cancels the dialog, returns WN_KEY_NO_CHANGE. ¢ presents a list of the files in the parent directory of the current file by creating an instance of the FILELIST Class, writing its handle to fnedit .pop, and sending a wN_INIT message to fnedit .pop. ¢ de-emphasises the file name editor by supersending a wy_EMPHASISE message. ¢ — ensures that the control absorbs subsequent keypresses by returning wN_KEY_ABSORB_ON. Otherwise lets the superclass handle the keypress by supersending a wn_KEY message, passing arguments of keycode and modifiers and then returns the return value. mphasise “en VOID wn_emphasise (INT flags) ; Emphasise the control. If fnedit .pop is non-zero, sends fnedit .pop 4 WN_EMPHASISE message passing as the argument flags. Otherwise supersends a wN_EMPHASISE message passing as the argument flags. LG _SE INT lg_self check (VOID) ; _ Validate file name Validate the file name. On success, return TRuE. Otherwise, display an appropriate error message, using the hInfoPrintErr utility function, and return raLseE. Sends a wN_SENSE message to se1f. If the return value is either E_FILE_NXIST, E_FILE DIR or -1, returns TRuE. If the return value is non-zero, displays an appropriate error message and returns FALSE. Otherwise performs further checks, which may lead to the hinfoPrintErr utility function displaying an error messsage corresponding to one of the following error codes: E_FILE_NAME invalid file name E_FILE_DEVICE invalid device name or the device does not exist E_FILE_DIR invalid directory name or the directory does not exist E_GEN_FSYS invalid file system name, or the file system does not exist E_FILE_NOTREADY the device does not contain a medium E_FILE_NXIST the file does not exist E_FILE_RDONLY the file is read-only E_FILE EXIST the file is not a directory file and tnedit . flags contains IN_FNEDIT_FORCE_NXIST 12-10 12 FILE SELECTORS —_— ILE SELECTORS ERROR_RID_OFFSET- the file is a directory file and fnedit . £1ags contains SYS_CHOOSE_NEW_DIRECTORY IN_FNEDIT_FORCE_NXIST ERROR_RID_OFFSET-SYS_CHOOSE_FILENAME the file is a directory file and fnedit . flags does not contain 1N_FNEDIT_ALLOW_DIRS ERROR_RID_OFFSET-SYS_CHOOSE_DIREcToRY _ the file is not a directory file and tnedit. flags contains IN_FNEDIT_JUST_DIRS (The error codes are produced by the p_finfo and p_testpth PLIB library routines.) If the file already exists, and fnedit .f1ags does not contain IN_FNEDIT_NO_AUTOQUERY, presents a query dialog with the sys_exIstTs_over resource. This informs the user that the file exists and asks if it should be overwritten. If the user confirms, returns TRUE. Otherwise returns FALSE. (path VOID lg_update (TEXT *path) ; Update the current path. Builds a full file specification from path using the p_fparse PLIB library function, and a related file specification of fnedit .buf, and copies the result to fnedit .buf. Sets the DLGBOX_ITEM_X_PENDING flag in the dlgbox.item[i] .£lags property associated with the control. FNSELWN flags landlord data offset flags width matcher matchlen defext extbuf ork buf nsel pop destrey wn_calc_position wn_connect wn_dodraw destroy wn_draw wn_emphasise destroy wn_init wn_set wn_sense wn_key 1g_self_check lg_sense_width 1lg_update fns_insert_tags fns_extract_tags fns_subset fns_validate_flist wn_position wn_redraw wn_sense_ help The rwseLwn class implements the file name choice list control which allows the user to select an already existing file. An example file name choice list is shown in the following picture: Open file | ¢ gelacuti> ie Disk Internal 12-11 HWIM REFERENCE rr A file name choice list may have an associated pack selector control simply by oring the DLGBOX_ITEM_NEEDS_PACK flag into the flags member of the rnsELww resource. For details see the introduction to the rneprT control. Class diagram Class definition Defined in sub-category file files.cl (generated header file files.g). CLASS £fnselwn { REPLACE destroy REPLACE wn_init REPLACE wn_set REPLACE wn_sense REPLACE wn_key REPLACE lg_self_check REPLACE lg_sense_width REPLACE lg_update ADD fns_insert_tags ADD fns_extract_tags ADD f£ns_subset=p_dummy ADD fns_ validate_flist=p_true chlist CONSTANTS { IN_FNSELWN_STANDARD IN_FNSELWN_SHOW_DIRS IN_FNSELWN_HIDE_FILES IN_FNSELWN_RESTRICT_LIST IN_FNSELWN_CAN_TAG IN_FNSELWN_ACCEPT_NULL IN_FNSELWN_SET_DEFEXT IN_FNSELWN_CAN WILDCARD PR_FNSELWN_TAGSHERE PR_FNSELWN_AT ROOT PR_FNSELWN_WILDCARDED PR_FNSELWN_PRESERVE_TAGS PR_FNSELWN_ON_DIR PR_FNSELWN_CHANGED_DIR } TYPES { typedef struct { UBYTE flags; TEXT fname [1] ; } IN_FNSELWN; 12-12 H_FILE_STANDARD_INIT H_FILE_ALLOW_DIRS H_FILE_JUST_DIRS H_FILE_RESTRICT_LIST H_FILE_CAN_TAG H_FILE_ACCEPT_NULL H_FILE_SET_DEFEXT H_FILE_CAN_ WILDCARD 0x100 Tags in this directory 0x200 0x400 0x800 0x1000 0x8000 chiist es wi “inselwn ee “packsel-» G ‘matcher / “y J vadev >> 12 FILE SELECTORS ————_———— eee SELECTORS PROPERTY { PR_VASTR *tags; which files are tagged PR_PACKSEL *pack; UWORD flags; TEXT *defext; TEXT extbuf [6] ; P_FPARSE crk; cracked information on current file TEXT buf [P_FNAMESIZE] ; } } Property fnselwn.tags this is either uxt or the handle of an instance of the vastr class that is used to store references to tagged files. If the instance of vastr exists, its first record contains the full path of the directory containing the tagged files. Each subsequent record contains the name of a tagged file. Note that this means that all tagged files must be in the same directory. fnselwn.pack this is either the handle of an instance of the pacxsst class - used to select the pack - Or NULL. fnselwn. flags an ored combination of flags that determine the behaviour of the rnsetwn instance. fnselwn.defext this points to the default extension. fnselwn.extbuf this is the default extension. fnselwn.crk a P_FPARSE Struct corresponding to the full file specification in fnselwn. buf. fnselwn.buf the full file specification of the current file. Tagged files On pressing the Tab key when an instance of rnseLwn has focus, a file list is presented (using an instance of FILELIsT). One or more of the file names in this list may be shown as being tagged, and tags may be set or cleared by using two language-dependent keypresses - on English machines, these are '+' and '-' (see the FILELIST wn_key method in the FILELIST Window Class chapter). The current list of tagged files, if any exist, is maintained in an instance of the OLIB vastr class whose handle is stored in fnselwn. tags. The first entry of this instance contains the full path name of the directory containing the tagged files and subsequent entries contain the names of the tagged files. The vastr instance may optionally be created by ryseLWzn on initialisation or it may be supplied externally, via the fns_insert_tags method. This method provides an option for the instance to remain under the ownership of the supplier. If this option is selected, the instance of vastr will not be destroyed when FNSELWN receives a DEsTRoy message. If this option is not selected, or if the instance of vastr has been created by rnseLwn, destruction of rnsELwn will also destroy the tagged files list. FE RI so FT a a ea tl FNSELWN methods Destroy VOID destroy (VOID) ; Destroy the rnsELwn instance. If fnselwn. flags does not contain PR_FNSELWN_PRESERVE_TAGS, and fnselwn.tags is non-zero, sends a DESTROY message tO fnselwn.tags. Supersends a DESTROY message. 12-13 HWIM REFERENCE Initialise VOID wn_init (IN_FNSELWN *par,PR_WIN *landlord, PR_PACKSEL *pack) ; Initialise the file name choice list. Writes landlord, the ID of the landlord window, to 1odger.landiora, and sets DLGBOX_ITEM_CAN_DEFER_X and DLGBOX_ITEM_x_PENDING in the dlgbox.item(i] . flags property associated with the control. Then writes pack to fnselwn.pack and sets PR_CHLIST_PACKSEL_DODINFO in chlist. flags. If fnselwn. flags contains IN_FNSELWN_HIDE_FILES, sets IN_FNSELWN_SHOW_DIRs and clears IN_FNSELWN_CAN_WILDCARD, IN_FNSELWN_CAN_TAG and IN_FNSELWN_SET_DEFEXT. Creates an instance of the vastr class and writes its handle to chlist . data. Initialises the vastR component by sending an va_InIT message to chlist .data specifying a granularity of 16. Requests the VASTR component to sort the records alphabetically ignoring case by sending a va_KEY messsage to chlist.data. Creates an instance of the vmarcuer class and writes its handle to chlist .matcher. Initialises the vMaTCHER component by sending an Im_InrT message to chlist .matcher. The length of the match string is stored in chlist .matchlen, the maximum length of the match string is 128 and the data is stored in chlist. data. If par->flags contains IN_FNSELWN_CAN_TAG, creates an instance of the vastr class, writing its handle to fnselwn.tags, and sends a vA_INIT message with a granularity of 32. If par->flags contains IN_FNSELWN_STANDARD, the filename is taken from patUsedPathNamePtr, otherwise the filename is taken from zpar->fname [0]. If par->flags contains IN_FNSELWN_SET_DEFEXT, a NULL file name is specified, and w_ws->wserv. flags does not contain pR_WSERV_FROM_HwzF, returns. In this case it is intended that the filename will be set by a subsequent wN_SET message. Otherwise, sets the extension by writing w_am->hwimman.defext tO fnselwn.defext. Sets the filename by sending a wn_set message to self. Clears the IN_FNSELWN_STANDARD flag from énselwn. flags. @ directo VOID wn_set (TEXT *fname) ; Set the file or non-file directory specified by fname into property. If the first character in fname is 'l', sets the default extension by copying the extension in fname to fnselwn.extbuf and returns. Sets PR_FNSELWN_CHANGED_DIR, and clears PR_FNSELWN_AT_ROOT in fnselwn. flags. Builds a full file specification from fname by calling the p_fparse PLIB library routine with a nut related file specification. If the device specified in fname is invalid, substitutes the default device. Writes the full file specification to fnselwn.buf, and the associated p_FPaRsE struct to fnselwn.crk. If IN_FNSELWN_SHOwW_pirs is set, and neither the filename nor the extension is specified in fname, clears IN_FNSELWN_SET_DEFEXT in fnselwn. flags. If the file is in the root directory, sets PR_FNSELWN_AT_ROOT in fnselwn. flags. Otherwise removes the trailing delimiter. If fnselwn. flags contains IN_FNSELWN_SET_DEFExT, and the extension in fnselwn. but is less than five characters long, sets the default extension by copying the extension in fnseiwn. buf to the extension buffer fnselwn.extbuf, and writing the address of the extension buffer to nselwn.defext. Indicates that the extension has been set by clearing IN_FNSELWN_SET_DEFEXT in fnselwn. flags. Sets the current pack according to the content of fnselwn.buf and fnselwn.crk by sending a wN_SET message to £fnselwn.pack. The remaining step is to build a list of the files in the parent directory using the BuildFileList function. The second argument in the call is the return value from the earlier w_seT message. The handle for the variable array is stored in chlist.data. 12-14 12 FILE SELECTORS —_—— EEE SELECTORS Building a file list The BuildrileList function is declared as follows: LOCAL _C BuildFileList (PR_FNSELWN *self, INT derr); It is called by the wn_set, 1g update and fns_insert_tags methods. Displays a scanning busy message using the sys_SCANNING system resource and the hBusyPrint utility function. Resets the list of files by sending a va_RESET message to chlist .data, and sets the selection to item zero by supersending a wn_seT message. Clears PR_CHLIST_SUSPENDED in chlist. flags, and clears both PR_FNSELWN_TAGSHERE and PR_FNSELWN_WILDCARDED in fnselwn. flags. If fnselwn. flags contains the IN_FNSELWN_RESTRICT_List flag, and fnselwn.buf contains both a filename and an extension, replaces the filename in fnselwn.buf with an asterisk character. Thus LOC: :M: \DIR\FILENAME.ExT would become Loc: :M:\DIR\*.EXT. If £nselwn. flags Contains IN_FNSELWN_CAN_TAG, and either fnselwn. flags does not contain IN_FNSELWN_CAN_WILDCARD, OF fnselwn.crk. flags is Zero, and fnselwn.tags contains multiple files sharing the path specified in fnselwn.buf, sets PR_FNSELWN_TAGSHERE in fnselwn. flags, and PR_CHLIST_SUSPENDED in chlist . flags, adds a record containing the sys_ FILES TAGGED system resource by sending a vA_APPEND message to chlist . data, sets the selection to item zero by supersending a WN_SET message, and returns. If derr is non-zero but not B_GEN_NomEMory, adds a record containing an appropriate error message by sending a vA_APPEND message to chlist . data, sets the selection to item zero by supersending a wn_sET message, and returns. If derr is B_GEN_NOMEMoRY, Calls p_leave, with an argument of E_GEN_NOMEMORY. Otherwise attempts to open a channel to the directory in fnselwn.buf using the p_open PLIB library function and the p_rprr mode. If the return value is =_GEN_NoMEMoRY, Calls p_leave, with an argument of E_GEN_NOMEMORY. Otherwise, if the return value is non-zero, adds a record containing an appropriate error message by sending a VA_APPEND message to chlist .data, sets the current selection to item zero by supersending a WN_SET message, and returns. If fnselwn. flags contains PR_FNSELWN_AT_RooT, sends a VA_APPEND message to chlist data to adda record containing the delimiter character which for the Series 3 filing system would be "\". If fnselwn.buf contains wildcards (thus fnselwn.crk. flags is non-zero) and IN_FNSELWN_CAN_WILDCARD is set in fnselwn.f1ags, adds a record containing the filename and extension in fnselwn. buf by sending a VA_APPEND message to chlist .data. Sets the selection to item zero by supersending a wn_SET message. Sets PR_FNSELWN_WILDCARDED in fnselwn. flags and returns. Otherwise reads the files in the current directory, ignoring volume name directories, and any file whose name starts with a full stop character. Directory files are considered only if 1s_FNSELWN_ALLOW_pIRs is set in fnselwn. flags. For each directory file, appends a delimiter character (taken from fnselwn.buf), and creates a new record containing the filename. Non-directory files are considered only if 1n_FNsELWN_susT_pIRs is clear in fnselwn. flags. For each non- directory file, removes the extension from the file name if and only if it matches that in tnselwn.defext, and creates a new record containing the filename. The new records are added by sending a va_aPPEND message to chlist .data, followed by a VA_INSERT message if a duplicate filename already exists. (Duplicate filenames may occur when scanning remote filing systems). To allow subclassers to add their own functionality the method sends a rns_suBSET message to self once the file list has been built. The default method does nothing. Subclassers would thus replace the fns_subset method with their own variant. They may wish, for example, to further restrict the file list according to additional application specific flags. 12-15 HWIM REFERENCE a ee If the number of files in the file list is zero, adds a record containing the sys_No_FILES system resource and returns. Locates the file list index of the current file by sending a va_SEARCH message to chlist.data and then sets the current selection by supersending a wn_sET message. If fnselwn. flags Contains IN_FNSELWN_STANDARD, sets the selection to item zero, unless the current file matches the first record and the number of records is greater than one, in which case sets the selection to item one. Otherwise sets the current selection to either the record that matches the current file, or to the first record if no such record exists. Get file name VOID wn_sense (TEXT *fname) ; Write the filename to fname. Senses the filename by calling the rnselwnsense function with an argument of Fase. The FnselwnSense function The rnselwnSense function is declared as follows: LOCAL_C FnselwnSense (PR_FNSELWN *self, INT internal) ; It is called by the wn_sense and wm_key methods. If chlist .f£lags contains PR_CHLIST_SUSPENDED, and fnselwn. flags contains any of PR_FNSELWN_WILDCARDED, PR_FNSELWN_TAGSHERE, OF PR_FNSELWN_AT_ROOT, copies the contents of fnselwn.buf to fname and returns. If chlist . flags contains PR_CHLIST_SUSPENDED, and internal is TRUE, copies the contents of fnselwn.buf to fname and returns. Otherwise if chlist .£1ags contains pR_CHLIST_SUSPENDED, but none of the other conditions specified above are satisfied, sets the first element of fname to zero and returns. Senses the current selection by sending a va_psuF message to chlist.data with an argument of chlist.nsel. Builds a full file specification from the current selection using the p_fparse PLIB library routine and a related file specification of fnselwn.buf truncated at the filename. Writes the full file specification to fname. If the current selection is not a directory file, checks the content of fname using the p_finfo PLIB library routine. If the return value is non-zero or the status member of the p_rwro struct is P_FADIR, writes the default extension in fnselwn.defext to fname. w INT wn_key(INT keycode, INT modifiers) ; Handle the keypress. Ifa file list is present and thus chiist.pop is non-zero, sends a WN_KEY message to chlist.pop. e if the return value from the wi_xEy message is greater than zero - thus the user has selected a file - clears PR_FNSELWN_AT_ROOT in fnselwn. flags.If the selected file is in the root directory, sets PR_FNSELWN_AT_ROOT in fnselwn. flags. Validates the file by sending a rns_VALIDATE_FLIST message to self and if the file fails the validation, calls p_1eave with an argument of RUN_ACTIVE_USED. Otherwise, clears IN_FNSELWN_RESTRICT_LisT from fnselwn. flags, and sets the file into property by sending se1f a wN_sET message. Returns wN_KEY_CHANGED. ¢ ifthe return value from the wy_xey message is WN_KEY_NO_CHANGE, returns WN_KEY_NO_CHANGE. e ifthe return value from the wy_xey message is neither greater than zero, nor WN_KEY_NO_CHANGE, destroys the file list by sending a pesTRoy message to chlist .pop, and then writing zero to chlist.pop. Retums the return value from the wi_key message. 12 - 16 12 FILE SELECTORS —_—_—_—_— —__ —__—_ eee EE SELECTORS If keycode is a tab character, and modifiers contains the Psion modifier, displays the contents of fnedit .buf using the hInfoprint utility function, and returns wy_KEY_NO_CHANGE. If keycode is a tab character and modifiers does not contain the Psion modifier, sets IN_FNSELWN_CAN_TAG, IN_FNSELWN_HIDE_FILES, IN_FNSELWN_SHOW_DIRS and IN_FNSELWN_CAN_WILDCARD iN fnselwn. flags. Senses the current filename by calling the rnselwnsense function with an argument of TRUE (see the description of the wn_sense method for details), and, if it is not in the root directory, strips the terminating delimiter character, then: e if modifiers contains the Control modifier, allows the user to edit the file name pattern and the full path for the current file by launching a File list dialog: if the user edits neither the filename pattern nor full path, returns wn_KEY_NO_CHANGE. ¢ — ifthe last keypress included the Control modifier, validates the file specification by sending se1f an FNS_VALIDATE_FLIST message. If it fails the validation, calls p_leave with an argument of RUN_ACTIVE_USED. Otherwise, clears In_FNSELWN_RESTRICT_LisT from fnselwn. flags and sets the edited filename into property by sending self a wN_SET message. Returns wN_KEY_CHANGED. ¢ presents a list of files that match the current full file specification by creating an instance of the FILELIST file selector class, writing its handle to chlist .pop and sending it a wx_INrT message. Returns wN_KEY_ABSORB_ON. Otherwise clears PR_FNSELWN_CHANGED_DIR from fnselwn. flags and supersends a WN_KEY message with arguments of keycode and modifiers. Returns the return value. Validate file name INT 1lg_self_check(INT can_defer) ; If either fnselwn. flags contains any of PR_FNSELWN_WILDCARDED, PR_FNSELWN_TAGSHERE, IN_FNSELWN_ACCEPT_NULL OF PR_FNSELWN_AT_ROOT, Of chlist. flags does not contain PR_CHLIST_SUSPENDED, return TRUE. Otherwise beep using the hBeep utility routine and return FALSE. Sense width INT lg_sense_width(VOID) ; Return the pixel width of the control. The width is calculated as that of fifteen maximum-width characters in the appropriate font, plus a cushion of two pixels. VOID lg_update (TEXT *pack,INT derr) ; Update fnselwn. buf and fnselwn.crk according to the device specification in pack. Builds a full file specification from pack, using the p_fparse PLIB library routine and a related file specification of fnselwn. buf. Writes the full file specification and the associated p_FparsE struct to fnselwn.buf and fnselwn.crk respectively. Builds a list of the files in the parent directory of the current file using the BuildFilenist function with an argument of derr (see the description of the wn_set method), and writes the handle of the file list to chlist.data. Sets DLGBOx_ITEM_x_PENDING in the dlgbox.item[] . flags dialog property associated with this control, and sets PR_FNSELWN_CHANGED DIR in fnselwn. flags. 12-17 VOID fns_insert_tags(PR_VASTR *tags,INT preserve,TEXT *buf) ; Insert the list of tagged files in the vasTr array whose handle is tags and, optionally, set the path and/or default extension as specified by bu. Stores the new tags by sending a destroy message to fnselwn.tags, writing tags to fnselwn.tags and setting IN_FNSELWN_CAN_TAG in fnselwn. flags. If preserve is non-zero, adds PR_FNSELWN_PRESERVE_TAGS tO fnselwn. flags, recording the fact that the list is considered to remain under the ownership of the supplier. If but is non-zero, sets the path specified by but as the current path by sending a wy_sET message to self. Otherwise builds a list of the files in the current directory using the BuilaFilezist function with an argument of zero (see the description of the wn_set method), and writes the handle of the file list to chlist.data. PR_VASTR *fns_extract_tags (VOID) ; Return a pointer to the vastr instance used to store the list of tagged files or ratss if no valid list exists, Determines the number of tagged files by sending a va_counr message to fnselwn. tags. If no files are tagged, the method returns FALSE. Otherwise determines the path for the tagged files - this is stored in the first record - and if this does not match the path component in £nselwn. buf, returns FALSE. Otherwise sets the return value to fnselwn. tags and sets fnselwn.tags to zero (if FNsELWN owned the list, zeroing fnselwn.tags effectively removes this ownership). VOID fns_subset (VOID) ; The supplied method does nothing. It is intended that subclassers replace this method to provide additional application specific functionality when building a file list. Subclassers may, for example, wish to further restrict the filelist according to application specific flags in fnselwn. flags. For details see the description of the wn_set method. INT fns_validate_flist (TEXT *pbuf) ; The supplied method returns True. It is intended that subclassers replace this method to provide the desired application-specific functionality. 12 - 18 CHAPTER 13 FILE List GENERATOR CLASSES This chapter documents the nonopz and upset classes which together support the creation and storage of a list of the files which match a specified path and filename pattern. The list of files may include file related details as required. Precursors Familiarity with the following topics will aid the understanding of this chapter: e the file classes described in the OLIB Reference manual. e the actrve class described in the OLIB Reference manual. Class diagram / fnode ™ —/ pnode ~> / nonode > / active >> ” factive ~ Yr ae ee ie / fscan > a 4PSell * / hpsel > { <— << NONODE priority isactive pcb stat destroy aetna ao_queue ao_abrun fn_list ini ao_cancel ao_run fn_end_list fa_close £n_nodename fn_list The nonops class is provided for use by the upset class and generates a list containg the default device and a list of files matching the current path and filename pattern. 13-] HWIM REFERENCE Class definition ( Defined in sub-category file filelist.cl (generated header file filelist.g). CLASS nonode pnode { REPLACE fn_list } Property None. NONODE methods FALL VOID fn_list(); Initialise Create a node list containing the default device - e.g. toc: :m: - and start the creation of a list of files matching the current path and filename pattern. ( Resets the node list by sending a va_RESET message to factive .owner->psel .pdir and then clears both PSEL_RESET_DIR_ARRAY and PSEL_QUEUED_CMD in factive.owner->psel. flags. Adds the default device to the node list by sending a va_APPEND message to factive.owner->psel .pdir. Closes the node list in factive.owner->psel.pdir and creates in factive.owner- >psel .pfile a list of files matching the current path and filename pattern by sending an ao_run message as follows: fnode. flags |=FNODE_NODE_ARRAY; active.stat=E_FILE_EOF; active .isactive=TRUE; p_iosignal(); It is assumed that: e the handle of the owning object is stored in factive.owner. e the handle of an instance of the pse.var class is stored in factive.owner->psel .pfile - this component is used to store the file list. e the handle of an instance of the vastr class is stored in factive.owner->psel .pdir - this component is used to store the node list. e — the current path and filename pattern are stored as a zero terminated string in factive .owner- >psel.fspec. Returns zero. 13-2 13 FILE LIST GENERATOR CLASSES dirnum setpath isactive builderr peb i fck stat i fspec ae—inite ps_set_path ao_abrun ps_sense filename ao_cancel ps_select_direntry fs_matchname fs filename ps_drives fs_fscan fs_dirname ps_settag fs_fscan_end Ps_gettag ps_get_file ps_order fs_end_dirlist The HpsEL class supports the creation of a list of files that match the current path and filename pattern. Note that the owning class must support the £1_1ist_complete method. Class definition Defined in sub-category file filelist.cl (generated header file filelist.g). CLASS hpsel psel { REPLACE ao_init REPLACE ao_queue REPLACE fs_fscan REPLACE ps_new_list PROPERTY { PR_ROOT *owner; } } Property hpsel.owner _— The handle of the owning object, assumed to be an instance of (a subclass of) FILELIST. 2a ee ee ee eas HPSEL methods Initialise VOID ao_init (TEXT *fname,PR_ROOT *owner) ; Initialise the npsEx instance and create a list of files matching the possibly wildcarded path and filename pattern in fname. Records the handle of the owning object by writing owner to hpsel .owner. Supersends an ao_inrT message, to: © write the path and filename pattern specified by fname to psel. spec eee 13-3 HWIM REFERENCE See eS e create an instance of the vasrr class having a granularity of 32 and write the handle to psel.pdir © create an instance of the pszLvar class having a granularity of 32 and write the handle to psel.pfile ¢ create an instance of the pwope class and write the handle to pse1 .pnode., then initialise the pNoDE instance by sending an ao_INIT message to psel .pnode. Changes the class of which psel.pnode is an instance from PNoDE to NONODE. If an asynchronous request is outstanding, cancels the outstanding request and then adds a record holding the default device specification to pse1.pdir and adds to psel .pfile a record for each file matching the path and filename pattern in pse1. fspec. (The method sends ao_cance and FN_LIST messages to psel .pnode.) _ Queue VOID ao_queue (VOID) ; Queue a read request. If the request is to build the node list - i.e. scan. flags contains FS_DIRECTORIES - e clears both pszL_RESET_DIR_ARRAY and PSEL_QUEUED_cwp in psel.. flags. ® removes all records from the node list by sending a va_RESET message to psel. pdir. e adds the default device to the node list by sending a va_APPEND message to psel .pdir. ¢ — closes the device list and starts the creation of the file list using the following code: active.stat=E_FILE_EOF; active .isactive=TRUE; p_iosignal (); where the last line forces se1¢ to be sent an Ao_RUN message. Otherwise queues a request to add the next file to the file list by supersending an AO_QUEUE message. VOID fs_fscan (TEXT *path) ; Start the scan of the files and directories in the directory specified by path including hidden and system files - note that the file specification pointed to by path is overwritten Sets Fs_HIDDEN and Fs_sysTEM in fscan.flags and then starts the scan by supersending an FS_FSCAN message with an argument of path. VOID ps_new_list (VOID) ; Complete the processing of the file list. Allows the owning class to perform further processing of the completed file list by sending an FL_LIST_COMPLETE message tO hpsel .owner. 13-4 CHAPTER 14 THE FILELIST WiNDow CLASS This chapter documents the rrLELisT class which may be used to create a list box containing a list of files and directories in the specified path. Precursors Familiarity with the following topics will aid the understanding of this chapter: e the use of the file selector - obtained in the system screen by pressing the Tab key. The file selector is an instance of the FILELIsT class. e the vastr class described in the Variable Array Classes chapter of the OLIB Reference manual. e the vapgv class described in the File Selectors chapter of the HWIM Reference manual. FILELIST flags match current id va top flags first width last matchlen vastart curoff matchstart destrey wh-draw destrey ib_size_window waoinit ib_item_width warkey lb_take_focus wn_draw lb_inquire_focus wn_emphasise db—inguive—item 1lb_inquire last thisdir crk derr x dfree wild subd ser targ 1b_draw_emphasis wh_cale position |wh-emphasise wn_connect lb_enquire_item f£1_list_complete wn_dodraw £1_locchg 1lb_draw_item wn_position wn_redraw wn_sense_help wn_visible 14-1 HWIM REFERENCE eee SSS The rrLeList class implements the file list which presents the user with a list of the files in a given directory. The user may change the path using the cursor keys. The user may also select the node by pressing the appropriate letter e.g. ‘B'. An example file list is shown in the following picture: ¢ Disk(Bl,Flash,36K free + \NAPP\2 ll\APP\CHESSS 28938 16:69am 25/81/94 2247 1:88am 69/62/94 9856 4:87pm 14/82/94 5776 =. 18:89am 12/61/94+ The file list displays: ¢ the name and type of the current device and the amount of free memory: these constitte the first title line. e the current path and filename pattern which in the above example is \4PP\*. e the path of the parent directory: by selecting this line and pressing the Enter key the path ascends to the parent directory. In the above example this is |. e the current path which in the above example is \4PP\. * alist of the directories in the current path e.g. \apP\cuEss\ - by selecting a directory and pressing the Enter key the current path descends onto the selected directory. ¢ alist of the files in the current path and the associated file information. This consists of the a tag marker, the size of the file in bytes, the time at which the file was last modified and the date at which the file was last modified. Class diagram 14 THE FILELIST WINDOW CLASS ———____ S$ eee EL TE WINDOW CLASS Class definition Defined in the sub-category file filelist.cl (generated header file filelist.g). CLASS filelist listbox { REPLACE destroy remove from list kept by wserv REPLACE wn_init initialise listbox and do wn_set REPLACE wn_key convert \ to special and filter ENTER and arrows REPLACE wn_sense return current selection REPLACE 1b draw_item draw all the file infomation REPLACE 1b_draw_emphasis=pulldown_lb_draw_emphasis REPLACE lb inquire_item get pointer to text ADD f1_list_complete called by fsel when file list is complete ADD f1_locchg check for change in LOC:: CONSTANTS { PR_FILELIST_ISFILE Ox100 Set or cleared as each line is drawn PR_FILELIST_TAGS_CHANGED 0x0200 Need to start a new tag list PR_FILELIST_NOSCAN 0x0400 No file scan for this directory PR_FILELIST_SCANNING 0x0800 Scan in progress PR_FILELIST_LOCAL 0x1000 Logged to LOC:: PR_FILELIST_WILDCARDED 0x2000 Effects next wn_sense PR_FILELIST_SET_UNMARKED 0x4000 Called p_unmarka IN_FILELIST_ALLOW_DIRS H_FILE_ALLOW_DIRS IN_FILELIST_JUST_DIRS H_FILE_JUST_DIRS IN_FILELIST_CAN_TAG H_FILE_CAN_TAG IN_FILELIST_CAN WILDCARD H_FILE_CAN WILDCARD IN_FILELIST_NO_FORCE WILD 0x8000 FILENAME_WIDTH 12 FILESIZE_WIDTH 7 FILETIME WIDTH 7 FILEDATE_WIDTH 9 } TYPES { typedef struct { WORD dtype; disc type VOID *vadev; device list WORD ascoff; offset to where display should start UWORD tagoff; x-offset to filetag UWORD sizeoff; x-offset to filesize UWORD timeoff; x-offset to filetime UWORD dateoff; x-offset to filedate UWORD dateendoff; x-offset to end of filedate TEXT asc[P_FNAMESIZE]; ascend text } PR_FILELIST_X; 14-3 HWIM REFERENCE ek SSSSSSSSSSSSSSSSCeFe PROPERTY 4 { PR_HPSEL *hpsel; PR_VASTR *contexts; PR_TIME *date; PR_VASTR *tags; PR_VASTR **ptags; PR_ROOT *next; UWORD locmask; UWORD flags; WORD parent; WORD thisdir; P_FPARSE crk; WORD derr; file list generator contexts for all nodes encountered for file date display which files are tagged where to write back tags next filelist in list mask for locchg index of parent (if any) in list index of current directory in list parse info on wildcard string disc error (if any) PR_PILELIST_X *x; ULONG dfree; extra data size of free space on disc TEXT wild[P_FNAMESIZE]; holds wildcard string used by psel TEXT subd[P_FNAMESIZE]; used to generate subdir names TEXT scr ([P_FNAMESIZE] ; miscellaneous scratch buffer TEXT targ[P_FNAMESIZE]; where to position initial highlight } Property filelist.hpsel filelist.contexts filelist.date filelist.tags filelist.ptags filelist.next filelist .locmask filelist.flags filelist .parent filelist.thisdir filelist.crk filelist.derr The handle of an instance of the upsz1 class. This is used to create and store a list of files and subdirectories. The full path and filename pattern that control the search for files and directories is in filelist .hpsel->psel.fspec. A full path and filename pattern of Loc: :M:\wvE\* would list all files in the Loc: :m:\WvE\ directory. The handle of an instance of the vastr class. There is one record for each node holding the most recent scanning context for that node i.e. the most recent full path and filename pattern. The handle of an instance of the rrmz class. This is used to convert system time into textual representations of the time and date as required for the file list display. The handle of an instance of the vastr class. This is used to store details of the tagged files. The first record is used to store the full path. The remaining records hold the filenames. Thus the tagged files lie in the same directory as each other. A pointer to the handle of an instance of the vaste class: this is for use when seeding the file list, in which case the vaste array contains details of the currently tagged files. The user may supply the handle of this array on initialisation. Otherwise it is created by the wn_sense method if required. May be used to store the handle of the next FrLELrsT object in order to create a linked list of FrLELIST objects. A mask that is for internal use only. An ored combination of flags indicating the state of the file list. The index of the parent directory item. This is the first item in the main list unless the current directory is at the root. The user moves to the parent directory by highlighting this item and pressing the Enter key. The index of the current directory item. This is the second item in the main list unless the current directory is at the root. In this case the item is not included. This contains information about the length of the components and the presence of wildcards in the file specification pointed to by filelist .wild. The information is obtained by calling p_fparse witha file specification of filelist.wild and a nut related file specification. An error code indicating the status of the current device. The current device is in filelist .wild. The error code is generated using the p_dinfo routine. 14-4 14 THE FILELIST WINDOW CLASS — rn EAD filelist.x filelist.dfree filelist.wild filelist.subd filelist.scr filelist.targ A pointer to a PR_FILELIST_x struct the definition of which is machine specific. The following members may be accessed: vadev the handle of an instance of vapev which is used to store a list of the available devices e.g. Loc: :M:, LOC: :A: and Loc: :B: - may be read by a subclass. ascoff the offset of the path component from asc - may be read by a subclass. dtype stores the ID of a system resource: this resource contains information about the media type in the current device - may be read by a subclass. The system resource ID corresponds to an error message or to one of the following: SYS_MTYPE_FLOPPY specifies that the media is a floppy disk. SYS_MTYPE_HARD specifies that the media is a hard disk. SYS_MTYPE_RAM specifies that the media isa RAM disk. SYS_MTYPE_FLASH specifies that the media is a flash disk. SYS_MTYPE_ROM specifies that the media is a ROM disk and is thus read-only. SYS_MTYPE_PROTECTED _ specifies that the media is read-only. SYS_MTYPE_UNKNOWN specifies that the media type is unknown. tagoff the horizontal offset to the tag indicator - for internal use only. sizeoff the horizontal offset to the file size - for internal use only. timeoff the horizontal offset to the file time of last modification - for internal use only. dateoff the horizontal offset to the file date of last modification - for internal use only. dateendoff the horizontal offset to the end of the file date of last modification - for internal use only. asc points to the full path specification of the parent directory - stored as a zero terminated string - for internal use only. the amount of free space on the current device in units of Kb rounded to the nearest Kb. The current device is in £ilelist .wild - for internal use only. the current path and filename pattern - stored as a zero terminated string - for internal use only. The current path and filename pattern for a file list showing all files in Loc: :M:\WVE\ would be Loc: :M: \wvE\*, whereas the current path and filename pattern for a file list showing all files with extension wve in LOC: :M: \WVE\ would be Loc: :M: \WVE\*.WVE. a format string used internally to generate the full file specification of a directory in the current directory - for internal use only. The format string for a file list showing files in Loc: :m:\wve\ would be Loc: :m: \WVE\$s. a scrap buffer that is used internally - for internal use only. see the description of the wn_init method for details - for internal use only. 14-5 HWIM REFERENCE a FILELIST methods VOID destroy (VOID) ; Destroy the filelist. If filelist .flags contains PR_FILELIST_SET_UNMARKED, Calls p marka. Sends a WS_REMOVE_FILELIST message to w_ws and then calls wcance1BusyMsg. Supersends a DESTRoy message. VOID wn_init (INT flags, TEXT *fname,PR_VASTR **ptags) ; Initialise the file list according to the content of £1ags, the file specification pointed to by fname and the handle of the vastr array pointed to by ptags: the latter may be NULL. The flags argument may contain an ored combination of the following flags: IN_FILELIST ALLOW_DIRS specifies that directories are inlcuded in the file list. IN_FILELIST_JUST_DIRS specifie that only directories are included in the file list. IN_FILELIST_CAN TAG specifies that file tagging is allowed. IN_FILELIST_CAN WILDCARD __ specifies that wildcards are allowed. IN_FILELIST_NO_FORCE_WILD specifies that the filename pattern is not automatically wildcarded i.e. it is not automatically replaced with an asterisk. Writes ptags tO filelist .ptags and writes flags to filelist. flags. Defines the style of the file list window by setting 1n_BwrN_sHADOW_1, IN_BWIN_CUSHTON and PR_WIN_EMPHASISED in win. flags. Connects to the window server by sending se1£ a wN_connecr message specifying a width of FILELIST_WIDTH and a height of FILELIST_HEIGHT whilst ensuring that the file list is centred in the screen. On the Workabout, following connection to the window server, ors PR_LISTBOX_SMALL_FONT into win.flags. Creates an instance of the vmarcuer class - the incremental matcher class - and writes the handle to listbox.match. Initialises the vmarcuer component by sending an 1m_INIT message to 1istbox.match passing as arguments the address of 1istbox.matchlen and P_FNAMESIZE. Creates an instance of the vastr class and writes the handle to £ilelist .contexts. Initialises the vasTR component by sending an va_INIT message to filelist .contexts specifying a granularity of 32. Creates an instance of the Time class and writes the handle to filelist..date. Sets the format for the TrME instance (by sending To_sET_FoRMAT messages) so that the time is expressed in hours and minutes e.g. 14:32 or 2:32 pm and the date is expressed as the day, the month and the year e.g. 5/8/94. Sets PR_LISTBOX_KEEP_ARRAY and PR_LISTBOX_FORCE_WIDE in listbox. flags. Allocates a cell of sufficient size for a PR_FILELIST_x struct and writes the address of the cell to filelist.x. Creates an instance of the vapev class and writes the handle to filelist .x->vadev. Initialises the vastR component by sending an vA_inrT message to filelist.x->vadev. Builds a full file specification from fname using the f_fparse PLIB routine with a nut related file specification, writes the result to £ilelist .wild, and writes the associated P_FPARSE struct to filelist.ecrk. SSE 14-6 14 THE FILELIST WINDOW CLASS eee FILELIST WINDOW CLASS | If £ilelist .wild contains wildcards, copies the current filename pattern in £ilelist.wild to filelist.targ and, if filelist. flags does not contain IN_FILELIST_NO_FORCE_WILD, replaces the filename pattern in £ilelist .wild with an asterisk. Creates an instance of the HpsEx class and writes the handle to filelist .hpsel. Initialises the upsEL component by sending an ao_INIT message to filelist .hpsel with arguments of filelist.wild and self. Initialises items of Ltstsox property concerned with the display including the width which is FILELIST_INTERN_W1DTH and the cursor offset which is L1sTBOX_LEFT_EDGE plus LISTBOX_OBLOID_INDENT. If the current node in filelist .wild is Loc: :, sets PR_FILELIST LOCAL in filelist.flags. Otherwise, clears pR_FILELIST_LOCAL in filelist. flags. Writes an appropriate error code for the device specified by £ilelist .wild to filelist .derr - the error code is the return value from a call to p_dinfo thus zero corresponds to a useable device. Writes the ID of an appropriate strinc resource giving information on the status of the device to filelist .x->dtype and, if the device is invalid, returns. Writes the number of free bytes on the media, rounded to the nearest kilobyte, to filelist .dfree. Sets PR_FILELIST_SCANNING iN filelist .flags and displays the text in the sys_SCANNING system resource using the wsetBusymMsg window server routine. On English language machines this is "Scanning". Makes the file list visible by calling hinitvis, set PR_FILELIST_SET_UNMARKED in filelist.flags and calls p_unmarka. INT wn_key (INT keycode, INT modifiers) ; Handle a keypress that may lead to a change in the current scanning context and hence file list. If keycode is less than 27 and modifiers contains W_CTRL_MODIFIER: e displays a scanning busy message. e if keycode corresponds to a device - e.g. m or a or B, Searches filelist.contexts for a record which matches the device and copies the path and filename pattern in the record to filelist .wild. (If there is no matching record, add a record containing the device specification to filelist.contexts.) If the device is Loc: :, set PR_FILELIST LOCAL in filelist.flags, otherwise, clears PR_FILELIST_LOCAL in filelist.flags. ¢ writes information about the status of the device to filelist .derr, filelist.x->dtype and filelist.dfree. e creates a list of the files which match the path and filename pattern in filelist .wild as described in later paragraphs and returns wN_KEY_NO_CHANGE. If filelist . flags contains either PR_FILELIST_NOSCAN OF PR_FILELIST_SCANNING and the keypress is neither W_KEY_LEFT, Nor W_KEY_RIGHT, nor W_KEY_TAB, nor W_KEY_ESCAPE, beeps and returns WN_KEY_NO_CHANGE. If keycode is equal to w_ws->wserv.sc[H_SC_TPLUS] i.e. the special character that on English language machines is '+': e if filelist. flags does not contain IN_FILELIST_caNn_tac, or the current item is a directory, returns WN_KEY_NO_CHANGE. © sets PR_FILELIST_TAGS_CHANGED in filelist . flags and tags the current item by sending a PS_SETTAG message to filelist .hpsel, redraws the item and returns WN_KEY_NO_CHANGE. If keycode is equal to w_ws->wserv.sc [H_SC_TMINUS] i.e. the special character that on English language machines is '~': e if filelist..flags does not contain IN_FILELIST_caNn_Tac, or the current item is a directory, returns WN_KEY_NO_ CHANGE. 14-7 HWIM REFERENCE ae eee ¢ setS PR_FILELIST_TAGS_CHANGED in filelist. flags, untags the current item by sending a PS_SETTAG message to filelist .hpsel, redraws the item and returns wN_KEY_NO_CHANGE. If keycode is equal to w_ws->wserv.sc {H_SC_TSTAR) i.e. the special character that on English language machines is '*': e if £ilelist.flags does not contain IN_FILELIST_cCAN TAG, returns WN_KEY_NO_CHANGE. ° sets PR_FILELIST_TAGS_CHANGED in filelist . flags and tags each file in the file list by sending PS_SETTAG Messages to filelist .hpsel, redraws the display and returns wN_KEY_NO_CHANGE. If keycode is equal to w_ws->wserv.sc[H_SC_TSLasu] i.e. the special character that on English language machines is ‘/’: e if £ilelist.f1ags does not contain In_FILELIST_CAN_TAG, returns WN_KEY_NO_CHANGE. ¢ sets PR_FILELIST_TAGS_CHANGED in filelist .flags, untags each file in the file list by sending PS_SETTAG messages to filelist .hpsel, redraws the display and returns wN_KEY_NO_CHANGE. If keycode is either w_kEY_UP OF W_KEY_DOWN e ifmodifiers contains W_SHIFT MODIFIER, filelist.flags contains IN_FILELIST_CAN_TAG, and the current item is a file then sets pR_FILELIST_TAGS_CHANGED in filelist. flags. Toggles the tag status of the file by sending a ps_seTTac message to filelist .hpsei. Redraws the file and file details. e supersends a wN_KEY message with arguments of keycode and modifiers. ¢ cancels any scanning busy message and clears pR_FILELIST_SCANNING from filelist. flags. e returms WN_KEY_NO_CHANGE. If keycode is W_KEY_LEFT: ¢ searches filelist contexts for a record which matches the current device in filelist .wild. ¢ moves to the previous record and copies the scanning context - i.e. path and filename pattern - to filelist.wild. (If there is no previous record, moves to the last record and repeats the process.) ¢ creates a list of the files which match the path and filename pattern in filelist .wild as described in later paragraphs. e returns WN_KEY_NO_CHANGE. If keycode is W_KEY_RIGHT: e searches filelist.contexts for a record which matches the current device in filelist .wild. * moves to the next record and copies the scanning context - i.e. path and filename pattern - to filelist .wiid. (If there is no next record, moves to the first record and repeats the process.) * creates a list of the files which match the current path and filename pattern in filelist .wild as described in later paragraphs. e returns WN_KEY_NO_CHANGE, If keycode is W_KEY_TAB: ¢ — allows the user to edit the current path and filename pattern - stored in filelist .wild - by presenting a File list dialog : if the user modifies neither the full path nor the filename pattern, returns WN_KEY NO CHANGE. ¢ validates the full path in £i1e1ist .wi1a by removing trailing directories until the path exists. e searches filelist .contexts for a record which matches the current device in filelist .wild and copies the current scanning context - i.e. current path and filename pattern - to the record. (If there is no matching record, appends a record containing the path and filename pattern in filelist.wild.) ¢ if on exiting the file list dialog the Control modifier was pressed, and filelist. flags contains IN_FILELIST_CAN_WILDCARD, Sets PR_FILELIST_WILDCARDED in filelist.flags and returns eS ee a ee 14-8 14 THE FILELIST WINDOW CLASS —_—_— OO rr eee eee WN_KEY_ CHANGED. (The last key press is stored in w_ws->wserv.ws.u.key.keycode and the modifiers are in w_ws->wserv.ws.u.key.modifiers.) displays a scanning busy message and if the current path is on Loc: :, sets PR_FILELIST_LOCAL in filelist.flags, otherwise clears PR_FILELIST LOCAL in filelist. flags. writes information about the current device in filelist .wild to filelist.derr, filelist.x- >dtype and filelist.dfree. creates a list of the files which match the current path and filename pattern in filelist .wild as described in later paragraphs. returns WN_KEY_NO_CHANGE. If keycode is W_KEY_RETURN: if the current item is the parent directory, displays a scanning busy message, and writes the full path specification of the parent directory followed by the current filename pattern to filelist .wild. Creates a list of the files which match the current path and filename pattern in filelist .wild as described in later paragraphs. Returns wN_KEY_NO_CHANGE. if the current item is a directory file, modifiers contains w_PSION_MODIFIER and filelist.flags contains IN_FILELIST_ALLOW_DIRS, returns WN_KEY_ CHANGED. if the current item is the current directory, and filelist. flags contains IN_FILELIST_ALLOW_DIRS, returns WN_KEY_NO_CHANGE. if the current item is the current directory, and filelist. flags does not contain IN_FILELIST_ALLOW_DirRs, calls hinfoprint with an argument of sys_cHOosE_FILENAME and returns WN_KEY NO CHANGE. if the current item is a file, and filelist. flags contains IN_FILELIST_JUST_DIRS, calls hInfoPrint with an argument of sys_cHOOSE_DIRECToRY. Writes zero to listbox .matchlen and moves the focus to the current directory by sending self a LB_TAKE_Focus message. Returns WN_KEY_NO_ CHANGE. writes the current path and filename pattern to filelist.wild. displays a scanning busy message and creates a list of the files which match the current path and filename pattern in filelist .wild as described in later paragraphs. retumms WN_KEY NO CHANGE. If keycode is none of the above: if modifers contains W_SHIFT_MODIFIER and keycode is an alphanumeric character, searches the file list for a directory the first character in the name of which matches keycode and moves the focus to the matching directory by sending self an LB_TAKE_Focus message. If no matching directory is found, beeps. In either case returns wN_KEY_NO_CHANGE. supersends a wN_KEY message with arguments of keycode and modifiers. If the return value is non-zero indicating that the display has changed, clears pR_FILELIST_SCANNING in filelist.flags and cancels any scanning busy message. returns WN_KEY_NO_CHANGE. Creating a list of files matching the current path and filename pattern If filelist .flags contains PR_FILELIST TAGS CHANGED and filelist.flags contains IN_FILELIST_CAN_TAG: clears PR_FILELIST_TAGS_CHANGED in filelist. flags. ensures that filelist.tags contains the handle of an instance of the vastr class containing zero records of granularity 32. adds the current path and filename pattern in filelist .hpsel->psel. fspec to the tags array by sending a VA_APPEND message to filelist.tags. 14-9 HWIM REFERENCE eee eS * adds the name of each tagged file to the tags array by sending va_APPEND messages to filelist.tags. Writes information about the current path and filename pattern in £ilelist.wild to filelist.crk and writes zero to filelist.targ. If the current device is not useable - thus filelist.derr is non-zero: e calls hInfoprint with an argument of filelist .x->dtype. ¢ sets PR_FILELIST_NoScAN and Clear PR_FILELIST_SCANNING in filelist.flags and cancels any scanning busy message. * cancels any outstanding read request by sending an ao_caNcEL message to filelist .hpsel. Otherwise creates a list of files and directories as follows: * cancels any outstanding information message and displays a scanning busy message. ¢ set PR_FILELIST_SCANNING and Clear PR_FILELIST_NOSCAN in filelist. flags. ¢ — generates a list of files matching the full path and filename pattern in filelist .wild by sending a PS_SET_PATH message to filelist.hpsel. Sets PR_LISTBOX_UNSTABLE in listbox. flags. Resets the indices and redraws the file list. Returns WN_KEY_NO_CHANGE, Retur INT wn_sense (TEXT *buf) ; Sense the current item by writing a full file specification for the current item to but. If filelist. flags contains either pR_FILELIST_NOSCAN oF PR_FILELIST_SCANNING, beeps and calls p_leave with an argument of RUN_ACTIVE_USED. If £ilelist.flags contains IN_FILELIST_CAN TAG: e ensures that filelist.ptags points to the handle of an instance of the vastr class containing zero records of granularity 32. e adds the current path in filelist .npse1->psel. spec to the tags array by sending a vA_APPEND message to the array whose handle is pointed to by filelist .ptags. e adds the name of each tagged file to the tags array by sending a VA_APPEND message to the array whose handle is pointed to by £ilelist.ptags. If £ilelist . flags contains PR_FILELIST_WILDCARDED, copies the current path and filename pattern in filelist .wiid to buf. Returns zero. If the current item is neither the parent directory (i.e. listbox. current is not filelist -parent) nor the current directory (i.e. listbox. current is not filelist.thisdir) writes the full file specification for the current item to but. If the file is a directory file, returns 1_FILE_1s zr, otherwise returns zero. If the current item is the current directory (i.e. listbox .current is equal to filelist parent) copies the current path in filelist .wild to buf. If the current item is the parent directory (i.e. listbox. current is equal to filelist.thisdir) copies the full path of the parent directory in filelist .x->asc to buf. If the path in bug is at the root directory, returns H_FILE_1IS_ Root. Otherwise returns H_FILE_IS_ DIR. LB DRAW ITEM Draw an item VOID 1lb_draw_item(TEXT *txt,INT index, P RECT *parea) ; Draw the item specified by txt and index in the rectangle specified by parea. 14-10 14 THE FILELIST WINDOW CLASS If index is zero draws the zero terminated string specified by txt in a box specified by «parea. The text is drawn in normal style with centre alignment. The text should be the title. Returns. If index is one draws the zero terminated string specified by txt in the box specified by *parea. The text is drawn in a bold style with centre alignment. The text should be the current path and filename pattern e.g. \wve\*. Returns. If index is filelist .thisdir draws the zero terminated string specified by txt in the box specified by *parea. The text is drawn in a bold style with centre alignment. The text should be the name of the current directory e.g. \wve\. Returns. If index is filelist.parent draws the zero terminated string specified by txt in the box specified by parea. The text is drawn in a normal style with left alignment. The text should be the path for the parent directory e.g. "\". Returns. Otherwise draws the zero terminated string specified by txt in the box specified by parea. The text is drawn in a normal style with left alignment. The text should be the file/directory name. If filelist.flags contains PR_FILELIST_ISFILE the txt argument should point to the name member of a PSEL_REC struct. The PsEL_REc struct is defined as follows: typedef struct { UWORD flags; UWORD namlen; P_INFO info; UBYTE name [P_FNAMESIZE] ; } PSEL_REC; The significance of the members of the psEL_rec struct is as follows: flags contains PSEL_FLAG_Tac to indicate that the file is tagged, and zero otherwise. namlen the offset of the file extension in name. info additional file information including the time and date of last modification: see the PLJB Reference manual for details of the p_rnro struct. name the filename stored as a zero terminated string. Draws additional file information to the right of the filename - this consists of a tag symbol if required, the size of the file in bytes, and the time and date of last modification. TEXT *lb inquire_item(INT index) ; Return a pointer to the text of the item specified by index where the title has index zero. Clears PR_FILELIST_ISFILE from filelist. flags. If index is zero, returns a pointer to the title. If index is equal to one, returns a pointer to the current path and filename pattern - e.g. \app\+. Note the absence of the device specification. If index is equal to filelist .parent, returns a pointer to the path of the parent directory e.g. \. Note the absence of the device specification. If index is greater than or equal to self->1istbox.vastart and the item is a file sets PR_FILELIST_ISFILE in filelist.flags and retums a pointer to the name of the file e.g. "Chess.app". Note that the name forms part of a psEL_rRc struct as described in the description of the 1b_draw_item method. If index is greater than or equal to self->1istbox.vastart and the item is a directory returns a pointer to the name of the directory e.g. Loc: :M: \APP\CHESS. 14-11 HWIM REFERENCE FLL OMPLETE - __List has been generated VOID £1_list_complete (VOID) ; Complete the processing of the file list generated by the filelist .hpsel component. Cancels any scanning busy message and clears pR_FILELIST_SCANNING iN filelist. flags. If the paths in filelist .wild and filelist.hpsel->psel. fspec do not match - indicating that the file list has been reset for some reason: e calls htnfoprint with an argument of sys_FLIST_RESET. © copies the content of filelist .hpsel->psel.fspec to filelist.wild. e if the current node is Loc: :, sets PR_FILELIST_LOCAL in filelist .flags, otherwise clears PR_FILELIST_LOCAL in filelist. flags. ® writes information about the status of the device to filelist. derr, filelist.x->dtype and filelist.dfree. Ensures that the file list displays the list of file names generated by the HpsEL component by writing filelist .hpsel->psel.pfile to listbox.va. Enables incremental matching to the list of file names by writing filelist .hpsel->psel.pfile to listbox.match.vmatcher.va and sending an IM_SET_RANGE message to listbox .match. If the current path and filename pattern in £ilelist .hpsel->psel.pfile is the NULL string indicating that the machine is out of memory: ® sets PR_FILELIST_NOSCAN in filelist. flags. * — clears the file list by writing appropriate values to property - see the Property section for details - then redraws the display and returns. If the current directory is at the root e.g. REM: :D:, writes zero to f£ilelist .parent - since there is no parent directory - and writes two to filelist .thisdir. Writes appropriate values to the remaining items of property - see the Property section for details. If the name of a file in the current directory matches the zero terminated string in filelist.targ, sets the focus to that file. Otherwise if £i1e1ist.f1ags contains H_FILE_JuST_prrs, sets the focus to the current directory by sending self an LB_TAKE_FOCUS message. Otherwise sets the focus to the first file in the file list by sending se1f an LB_TAKE_Focus message. If there are no files then sets the focus to the last directory. If the focus is now at the last item, moves the focus to the preceding item. If f£ilelist . flags contains IN_FILELIST_can_Tac and the path stored in the tags array matches the path in filelist.wild:: e for each tagged file sets pseL_FLac Tac in the flags member of the PSEL_REC Struct stored in filelist.hpsel. Note that the method redraws the file list before sending an LB_TAKE_Focus message. nge in LOC:: VOID £1_locchg (VOID) ; Check for any changes on Loc: :. If filelist.flags contains PR_FILELIST_SCANNING OF filelist.flags does not contain PR_FILELIST_LOCAL, return. Determines whether the toc: : device has changed by calling p_locchg and if it has not changed, returns. 14-12 14 THE FILELIST WINDOW CLASS a pe If the current node in filelist .wild is Loc: :, sets PR_FILELIST_LOCAL in filelist .flags. Otherwise clears PR_FILELIST_LOCAL in filelist. flags. Writes information about the status of the device to filelist.derr, filelist.x->dtype and filelist.dfree. Sets PR_LISTBOX_UNSTABLE iN listbox. flags. If £ilelist .derr is non-zero - thus the current device is not useable: e moves the current path in filelist .wild to the root - €.g. Loc: :M:*. e calls hinfoprint with an argument of filelist .x->dtype. e sets PR_FILELIST_Noscan and clear PR_FILELIST_SCANNING in filelist. flags. e cancels any scanning busy message filelist. flags. e cancels any outstanding read request by sending an ao_cANCEL message to filelist.hpsel. Otherwise creates a list of files matching the path and filename pattern in fi1elist .wild as follows: © writes the current device specification to f£ilelist .wild and to the appropriate record in the filelist.contexts afray. e cancels any outstanding information message and display a scanning busy message. e sets PR_FILELIST_SCaNNING and clear PR_FILELIST_Noscan in filelist. flags. © sends a PS_SET_PATH message to filelist.hpsel. Sets PR_LISTBOX_UNSTABLE in listbox. flags. Resets the display and redraws the file list. 14-13 CHAPTER 15 GENERAL SYSTEM DIALOGS This chapter describes a number of dialog classes that are supplied, ready for use, by HWIM. The classes are as follows: the ERRORDLG class which provides a dialog containing an error message. the queryDLc class which provides a dialog containing one or two lines of text and an action list prompting the user for a Yes/No response. the rLisTpuc class which provides a dialog containing an editable path and filename pattern. the ronTsEL class which provides a dialog that allows the user to select the required font and font style. the EvaLp.c class which provides a dialog that allows the user to select the system Calculator and Evaluate settings. the seTPoRTDLG Class which provides a dialog that allows the user to select the serial port settings. the sETHSHKDLG class which provides a dialog that allows the user to select the serial port handshake settings. For details of the dialling dialogs see the Dialling Dialogs chapter of the HWIM Reference manual. Precursors Familiarity with the following topics would aid understanding of this chapter: the piGBox class which is described in the Dialog Boxes chapter of the HWIM Reference manual. the wor class which is described in the Printing chapter of the FORM Reference manual WDR files which are described in the WDR Printing chapter of the Additional System Information manual 15-1 HWIM REFERENCE Class diagram ¢ if Ns 1 SY 4 i gare ae, Sin ‘ i sy, c win : ‘ , c x. ae citaess ' ett ene roi os Ly” 2 - /setportdlg yi / evald lg ae rome. one é os, [ne a Lis _sethshkdlg 5 / fonidig "> oe in ie ( \ ow, amet . eae) ’ eed Se \ Phe } ae me querydig ; ee flistdig ; ee SAL be L a u A ae MD) 7 etrordig ERRORDLG DLGCHAIN | DLGBOX next count current underline absorb changed destroy wn_key wn_emphasise wn_sense_help wn_set wn_sense wn_draw di_item_lock dl_item_dim dl_set_item_flags dl_set_prompt dl_take_focus dl_item_replace dl_item_append dli_init di_dimmed_message dl_item_add dl_set_size dl_ing_minsize dl_key dl_changed dl_focus dl_handle_to_index dl_launch_sub dl_index_to_handle dl_item_new The ERorDLG class implements the Error dialog which presents the user with two lines of text followed by an action list containing a Continue button. An example Error dialog is shown in the following picture: eee 15-2 15 GENERAL SYSTEM DIALOGS The argument is 12 units Invalid arguments Continue SSS The simplest method of launching an Error dialog is to use the ws_error_dialog method of the wsERV object as described in the WSERV Class chapter of the HWIM Reference manual. Class definition Defined in sub-category file digbox.c/ (generated header file digbox.g). CLASS errordlg dlgbox { REPLACE dl_dyn_init TYPES { typedef struct { WORD error; TEXT message [50] ; } RBUF_ERROR; } Resources Defined in system resource file s_.rss. RESOURCE DIALOG sys_error_dialog { £lags=DLGBOX_RBUF_FILLED|DLGBOX_NO_DDP; controls= { CONTROL { class=C_TEXTWIN; £1ags=DLGBOX_ITEM_CENTRE |DLGBOX_ITEM_DEAD|DLGBOX_ITEM_ UNDERLINED; info=TXTMESS { flags=IN_TEXTWIN_AL CENTRE; }; } ’ CONTROL { class=C_TEXTWIN; £1lags=DLGBOX_ITEM_CENTRE|DLGBOX_ITEM_DEAD; info=TXTMESS { flags=IN_TEXTWIN_AL CENTRE; }; } t CONTROL { class=C_ACLIST; info=ACLIST { rid=sys_ac_continue; }; 15-3 HWIM REFERENCE Property None. = eee eee eee ee) ERRORDLG methods initi isation VOID dl_dyn_init (vozD) ; Initialise the items in the error dialog. It is assumed that a1gbox.rbuf contains the address of an RBUF_ERROR Struct. Writes -1 to dlgbox.helprid indicating that there is no associated help resource. Sets the TExTwzn control with index zero to display the text message specified in dlgbox. rbuf->message. The control is set by sending self a wN_SET message. Sets the rextwin control with index one to display the error message that corresponds to the error code in digbox. rbuf ->error. The error code is converted to an error message using the hzrrs utility routine. The control is set by sending self a wN_SET message. QUERYDLG flags next id destroy wa-draw wn_position wn_redraw wn—sense—heip wn_visible DLGBOX item count rbuf current dimrid underline helprid absorb changed destroy di_item_replace wn_key dl_item_append wn_emphasise dl_init wn_sense_heip dl_dimmed_message wn_set di—ttem_add wn_sense dl_set_size wn_draw dl_ing_minsize dl_item_lock di —dyn—init dl_item_dim dl_key dl_set_item_flags dl_set_prompt dl_changed dl_take_focus dl_focus dl_handle_to_index dl_launch_sub dl_index_to_handle dl_item_new dl_item_add dl_dyn_init The queryp1c class implements the Query dialog which presents the user with two lines of text followed by an action list containing Yes and No buttons. An example Query dialog is shown in the following picture: This is the first line of text This is the second line of text No Yes a 15 GENERAL SYSTEM DIALOGS A query dialog as its name suggest is most often used to request user confirmation as in the following example from the system screen: j Delete all files on "[B]"? No Yes Pa eee The simplest method of launching a Query dialog is to use the ws_query_dialog method of the wsERV object as described in the WSERV Class chapter of the HWIM Reference manual. Class definition Defined in sub-category file digbox.cl (generated header file digbox.g). CLASS querydlg dlgbox REPLACE dl_item_add REPLACE dl_dyn_init TYPES { typedef struct { WORD result; TEXT message [50] ; } RBUF_QUERY; } Property None. Resources Defined in system resource file s_.rss. RESOURCE DIALOG sys_query_dialog { flags = DLGBOX_ACTION_LIST|DLGBOX_REPORT_ACT_HORIZ; controls= { CONTROL { flags=DLGBOX_ITEM_CENTRE|DLGBOX_ITEM_DEAD|DLGBOX_ITEM_UNDERLINED; info=TXTMESS { flags=IN_TEXTWIN_AL CENTRE; }; }, CONTROL { class=C_ACLIST; info=ACLIST { rid=sys_ac_no_yes; be ‘3 } RESOURCE CONTROL sys_txtmess { class=C_TEXTWIN; £lags=DLGBOX_ITEM_CENTRE |DLGBOX_ITEM_DEAD; info=TXTMESS { flags=IN_TEXTWIN_AL CENTRE; }i 15-5 HWIM REFERENCE a a Se EE EI QUERYDLG methods VOID dl_dyn_init (vorD) ; Initialise the items in the dialog. It is assumed that digbox.rbuf contains the address of an RBUF_QUERY struct. Sets the TexTwrn control with index zero to display the text message specified by algbox. rbuf- omessage. The control is set by sending se1f a wN_SET message. Sets the TExTw1n control with index one to display the text in the resource whose id is dlgbox. rbuf - >result: no text is displayed if the ID is zero. The control is set by sending se1f a wN_SET message. Writes zero to digbox. rbuf->result. VOID di_item_add(AD_DLGBOX *par) ; Add textwrn controls for the text message and the resource text if specified. Adds the dialog item specified by par by supersending a pL_1T=m_app message with par as argument. If dlgbox. count is unity and digbuf .rbuf->result is non-zero, appends the TExTwrN control specified by the sys_txTmEss system resource. The control is appended by sending sei a DL_ITEM_APPEND message. FLISTDLG flags id desezey wn_position wn_redraw wn—sense—hetp wn_visible pew DLGCHAIN | DLGBOX next item count rbuf current dimrid underline helprid absorb changed whe-draw destroy dl_item_replace wn_key di_item_append wn_emphasise dl_init wn_sense_help dl_dimmed_message wn_set dl_item_add wn_sense dl_set_size wn_draw dl_ing_minsize dl_item_lock di—dyn—init di_item_dim di-key dl_set_item_flags dl_set_prompt dl_changed dl_take_focus di_focus dl_handle_to_index dl_launch_sub di_index_to_handle dl_item_new The FLIstTDLc class implements the File list dialog which presents the user with an editable file name pattern and an editable full path. An example File list dialog is illustrated in the following picture: 15-6 15 GENERAL SYSTEM DIALOGS Specify filelist ‘Filename pattern] ‘Full path LOC::B:\APP. An example of a File list dialog may be obtained while the file selector is present by pressing the Tab key. Class definition Defined in sub-category file digbox.c/ (generated header file digbox.g). CLASS flistdlg dlgbox { REPLACE dl_dyn_init REPLACE dl_key } Property None. Resources Defined in system resource file s_.rss. RESOURCE DIALOG sys_flist_dialog { title="Specify filelist"; £lags=DLGBOX_NOTIFY_ENTER | DLGBOX_RBUF_FILLED; controls= { CONTROL { class=C_EDWIN; prompt="Filename pattern"; info=EDWIN { maxlen=P_FNAMESIZE; vulen=18; flags=IN_EDWIN_VULEN_CHARACTERS; hi }, CONTROL { class=C_EDWIN; prompt="Full path"; info=EDWIN { maxlen=P_FNAMESIZE; vulen=18; flags=IN_EDWIN_VULEN_CHARACTERS; }; = ee A a FLISTDLG methods VOID dl_dyn init (VOID) ; Initialise the items in the dialog. Builds a full file specification from the file specification pointed to by digbox. rbuf, using the £_fparse PLIB library routine, and a wuz related file specification. If neither the filename, nor the extension, in the full file specification are wild carded, removes both the filename and the extension and appends a zero terminated asterisk. SSeS 15-7 HWIM REFERENCE Displays the filename component of the full file specification in the Filename pattern control. Displays the full path components of the full file specification in the Full path control. INT dl_key(INT id, INT keycode) ; Handle a key press. Builds a full file specification from the text displayed in the control with index ia, using the p_fparse PLIB library routine. The related file specification is the text displayed in the Epwrw control with index 3- id. If one or more components of the full file specification are invalid, displays an appropriate error message using the hinfoPrinterr utility function and retums wN_KEY_NO_CHANGE. If the full file specification does not contain wild cards, and both filename and extension are absent, appends a zero terminated asterisk. Writes the full file specification to the address in digbox.rbuf and returns WN_KEY CHANGED. FONTSEL flags next id destrey wh—draw wn_position wn_redraw wh—sense—heip wn_visible count rbuf current dimrid underline helprid absorb changed dl_item_replace wn_key dl_item_append wn_emphasise dl_init wn_sense_help dl_dimmed_message wn_set dl_item_add wn_sense dl_set_size wn_draw di_ing minsize dl_item_lock di—dyn—tnit dl_item_dim di—key dl_set_item_flags dl_set_prompt di—-changed dl_take_focus dl_focus dl_handle_to_index dl_launch_sub dl_index_to_handle dl_item_new The Fonts class implements the Font selector dialog which presents the user with selectable font, font size, font style and print position items. An example Font selector dialog is shown in the following picture: Font ¢Pica> ‘Size 12 ‘Underline No ‘Bold Yes ‘Italic No ‘Print position Normal (Note that the Font control displays typefaces and not fonts, although the meaning is clear.) 15-8 15 GENERAL SYSTEM DIALOGS Another example of a font selector dialog is provided by the Word application as illustrated in the following picture (the dialog is obtained by selecting the Font item from the Paragraphs menu): Font ‘Font Proportional ‘Size ‘Underline ‘Bold ‘Italic ¢ ‘Alter Superscript EG, Subscript The dialog also illustrates the pop-up menu for the Print position item: the user may select Normal, Superscript or Subscript. Notice the extra item that has been appended to the dialog. The dlgbox.rbuf property must point to a FonrsEL_pata struct defined as follows: typedef struct { VOID *wdr; SCRLAY_FONT *pf; UWORD ret; } FONTSEL_DATA; The significance of the members of the ronrsEL_para struct is as follows: wdr specifies the handle of the current wor object. pf specifies the address of a scrLay_Fonr struct containing the font data to be edited. ret the return value set by the di_key method - it is set to a non-zero value if any of the font characteristics have been edited and to zero otherwise. Class definition Defined in sub-category file fontdlg.cl (generated header file fontdlg.g). CLASS fontsel dlgbox { REPLACE dil_dyn_init REPLACE di_changed REPLACE dl_key TYPES { typedef struct { VOID *wdr; SCRLAY_FONT *pf; UWORD ret; } FONTSEL_DATA; } PROPERTY 1 PR_ROOT *names; font names list PR_ROOT *sizes; size list for current name VOID *wdr; printer queries SCRLAY_FONT *pf; target for new font data SCRLAY_FONT f; copy of original input font data } } Property fontsel.names | @ VASTR array containing the names of the typefaces supported by the current printer model fontsel.sizes | @ VASTR afray containing font heights in points for the current typeface 15-9 HWIM REFERENCE the handle of an instance of wor that accesses the current wor file: a wor file contains printer specific data including font details. (See the description of the wor class for further details.) a pointer to a ScRLAY_FonT struct which contains the edited font data fontsel.wdr fontsel.pf fontsel.f a SCRLAY_FONT struct which contains the input font data Resources Defined in system resource file s_.rss. RESOURCE DIALOG sys_font_dl { title="Font"; flags=DLGBOX_NOTIFY_ENTER | DLGBOX_RBUF_FILLED; controls= { CONTROL { £flags=DLGBOX_ITEM_NOTIFY_CHANGED; class=C_CHLIST; prompt="Font"; info=CHLIST{}; CONTROL { class=C_CHLIST; prompt="Size"; info=CHLIST{}; CONTROL { class=C_CHLIST; prompt="Underline"; info=CHLIST{rid=sys_no_yes;}; ). CONTROL { class=C_CHLIST; prompt="Bold"; info=CHLIST{rid=sys_no_yes;}; }. CONTROL { class=C_CHLIST; prompt="Italic"; info=CHLIST{rid=sys_no_yes;}; }. CONTROL { class=C_CHLIST; prompt="Print position"; info=CHLIST{rid=sys_prn_pos;}; } }; } RESOURCE MENU sys_prn_pos { items= { CHOICE_ITEM {str="Normal";}, CHOICE_ITEM {str="Superscript";}, CHOICE_ITEM {str="Subscript"; } }; } Additional items may be appended by sending one or more pb_tTEmM_App and/or DL_ITEM_APPEND messages during the initialisation of the dialog: see the Dialog Boxes chapter for further details. 15 - 10 15 GENERAL SYSTEM DIALOGS ee PR SR FONTSEL methods DL_DYN_INIT — VOID dl_dyn_init(vozp) ; lisation Initialise the items in the dialog. It is assumed that dlgbox. rbuf contains the address of a FONTSEL_DATA struct. Writes dlgbox. rbuf ->wdr to fontsel.wdr, Writes dlgbox.rbuf->pf to fontsel .pf and writes *dlgbox.rbuf->pf to fontsel.f. Creates an instance of the vastr class, writes its handle to font se1 .names, and initialises by sending a VA_INIT message to fontsel .names specifying a granularity of sixteen. Creates a second instance of the vastr class, writes its handle to fontsel.sizes, and initialises by sending a VA_INIT message to fontsel.sizes specifying a granularity of sixteen. Obtains the number of typefaces by sending a woR_SENSE_MODEL message to fontsel .wdr. Obtains the name of each typeface by sending a woR_TYPEFACE message to fontsel.war and adds to the names array by sending va_APPEND messages to fontsel .names. Sets the fontsel .names array as the data for the Font contro] by sending self a wN_SET message. Sets the fontsel . sizes array as the data for the Size control by sending self a wN_SET message. Obtains the index for the typeface with RTF/Word typeface index fontsel .pf->typeface by sending a WDR_SEARCH_TYPEFACE Message to fontsel .wdr, and sets as the selected item in the Font control by sending self a WN_SET message. Scans the current wor file for the available sizes in the current typeface and adds each size to the sizes array by sending va_APPEND messages to fontsel.sizes. (The steps are as described for the a1_changed method.) Sets the selected item in the Underline control to Yes if the least significant bit in fontsel -pf->style is set. Otherwise sets the selected item to No. Sets the selected item in the Bold control to Yes if the second least significant bit in gontse1 .p£- >style is set. Otherwise sets the selected item to No. Sets the selected item in the /talic control to Yes if the third least significant bit in fontsel .p£->style is set. Otherwise sets the selected item to No. Sets the selected item in the Print position control. This may be Normal, Superscript or Subscript depending on whether or not the wor_sTYLE_SUPER OF WDR_STYLE_sus flags are set in fontsel .pf->style: note that these flags are mutually exclusive. INT dl_key(INT index, INT keycode) ; Handle a key press. Senses the index of the item selected in the Font control, converts the index to an RTF/Word index by sending a WOR_TYPEFACE message to fontsel .wdr and then writes the result to gontsel.p£->fid. Senses the index of the item selected in the Size control, obtains the font height in twips by sending a WDR_FONT_HEIGHT message to fontsel.wdr and then writes the twips height to fontsel ._pf->height. Writes zero to fontsel.pf->style. If the selected item in the Underline control is Yes, sets the least significant bit in fontsel -pf->style. If the selected item in the Bold control is Yes, sets the second least significant bit in fontsel .pf->style. If the selected item in the Italic control is Yes, sets the third least significant bit in fontse1 -pf->style. Compares fontsel .pf and sfontsel.f using the p_bemp PLIB library routine writing the return value to digbox.rbuf->ret: zero indicates identical data. ee ee 15-11 HWIM REFERENCE Returns WN_KEY_CHANGED. DLE VOID dl_changed(INT changed) ; Set the data and the selected item for the Size control. Obtains the index of the item selected in the Size control and then resets the sizes array by sending a VA_RESET message to fontsel.sizes. Obtains the number of font heights by sending a wor_TYPEFACE message to fontsel. war. Obtains each font height in twips by sending wor_FonT_HEIGHT messages to fontsel .wdr, convert into points by dividing by twenty, and adds to the sizes array by sending a va_APPEND message to fontsel.sizes. Obtains the index of the font with twips height fontse1 .pf->height by sending a wOR_SEARCH_HEIGHT message to fontsel .wdr and then sets this as the index of the selected item in the Size control. EVALDLG flags next id destrey wa-draw wn_calc_position |wn—emphasise DLGBOX item count rbuf current dimrid underline helprid absorb changed destroy dl_item_replace wn_key dl_item_append wn_emphasise dl_init wn_sense_help dl_dimmed_message wn_set dl_item_add wn_sense di—set—size wn_draw dl_ing_minsize dl_item_lock éi—dyn—init dl_item_dim di—key dl_set_item_flags 4i—changed di_set_prompt di_take_focus di_focus di_handle_to_index di_launch_sub dl_index_to_handle dl_item_new dl_dyn_init dl_set_size wn_position wn_redraw wa_sense—heip wn_visible The EvaLDLG Class implements the Set Calculator format and Set "Evaluate" format dialogs. The Set Calculator format presents the user with the format, number of significant digits and trigonometry units as used by the calculator and which are stored in the system wide msv environment variable. An example Set Calculator format dialog is illustrated in the following picture: Set Calculator format ‘Format Scientific ‘Significant digits ‘Trigonometry units Degrees The Ser "Evaluate" format dialog presents the user with the format, number of decimal places and trigonometry units as used by the evaluator and which are also stored in the system wide msv environment variable. An example Set "Evaluate" format dialog is illustrated in the following picture: 15-12 15 GENERAL SYSTEM DIALOGS Set "Evaluate" format ‘Format Fixed ‘Decimal places 2 ‘Trigonometry units Ba eeulk iets The simplest method of launching either of the above dialogs is to use the ws_format_dialog method of the wsERv object as described in the WSERV Class chapter of the HWIM Reference manual. Class definition Defined in sub-category file evaldlg.cl (generated header file evaldlg.g). CLASS evaldlg dlgbox { REPLACE dl_dyn_init REPLACE dl_set_size REPLACE dl_changed REPLACE dl_key CONSTANTS { EVALDLG_CALCULATOR_EVALUATOR 0 /* set this flag in rbuf for calc evaluator */ EVALDLG_GENERAL_EVALUATOR 1 /* set this flag in rbuf for general evaluator */ } PROPERTY { WORD isEval; EXTENDED_MEM_VALUES eMem; } } Property evaldlg.isEval contains either EVALDLG_GENERAL_EVALUATOR for a Set "Evaluate" format dialog, or EVALDLG_CALCULATOR_EVALUATOR for a Set Calculator format dialog evaldlg.eMem an EXTENDED_MEM_VALUES struct that contains the current data 15-13 HWIM REFERENCE ee SSeSeSSSSeSeeSSeSeeSSSSSSSeeSSSSSSS Resources Defined in system resource file s_.rss. RESOURCE DIALOG sys_eval_dialog { title="Set Calculator format"; flags=DLGBOX_NOTIFY_ENTER |DLGBOX_RBUF_FILLED; controls= { CONTROL { flags=DLGBOX_ITEM_NOTIFY_CHANGED; class=C_CHLIST; prompt="Format"; info=CHLIST { rid=sys_format_chlist; }; }, CONTROL { class=C_NCEDIT; prompt="Significant digits"; info=NCEDIT { high=12; low=0; }: ys CONTROL { class=C_CHLIST; prompt="Trigonometry units"; | info=CHLIST { rid=sys_rad_deg; }; } yi } RESOURCE MENU sys_format_chlist { items = { CHOICE_ITEM { str="Fixed";}, CHOICE_ITEM { str="Scientific";}, CHOICE_ITEM { str="General";}, CHOICE_ITEM { str="Hexadecimal"; } }; } RESOURCE MENU sys_rad_deg { items = { CHOICE_ITEM { str= "Radians";}, CHOICE_ITEM { str= "Degrees"; } }; } RESOURCE STRING sys_evaldlg title { str="Set \"Evaluate\" format"; } BS ee ee ee a a a Sy EVALDLG methods Dynamic initialisation VOID dl_dyn_init (VOID) ; Initialise the items in the dialog and, if necessary, the msv environment variable. 15-14 15 GENERAL SYSTEM DIALOGS —_. $$ GENERAL SYSTEM DIALOGS Writes dlgbox.rbuf to evaldig.isEval: it is assumed that this points to an EXTENDED_MEM_VALUES struct which is defined as follows: typedef struct { UBYTE evalDegrees; UBYTE calcDegrees; MEM_VALUES memVal; } EXTENDED_MEM_VALUES; typedef struct { UBYTE evalFormat; /* Dtob format code for all except calc */ UBYTE evalDPlaces; /* Decimal places for all except calc */ UBYTE calcFormat; /* Dtob format code */ UBYTE calcDPlaces; /* Decimal places, if relevant */ DOUBLE values [MAX_MEMORIES] ; } MEM_VALUEs ; If no msv environment variable exists, creates one with the following default values: p_bfil(p, sizeof (MEM_VALUES) , 0) ; p->evalFormat= (EVAL_DEFAULT_FMT_TYPE|DEGREES MODE) ; p->calcFormat= (CALC_DEFAULT_FMT_TYPE|DEGREES MODE) ; p->evalDPlaces=EVAL_DEFAULT_PLACES; /* 2 for evaluator */ p~->calcDPlaces=CALC DEFAULT_PLACES; /* 14 for cale */ Writes the contents of the msv environment variable to evaldlg.eMem.memval. Initialises the remaining members of evaidig.eMem as follows: evaldig.eMem.evalDegrees=evaldlg.eMem.memVal.evalFormat&DEGREES MODE; evaldlg.eMem.calcDegrees=evaldlg.eMem.memVal.calcFormat&DEGREES MODE; evaldlg.eMem.memVal.evalFormat&=(~DEGREES_ MODE) ; evaldlg.eMem.memVal .calcFormat&=(~DEGREES_MODE) ; For the Set Calculator format dialog: e sets the Format control to display the item with index evaldig.eMem->memVal.calcFormat e — sets the Significant digits control to display the integer value in evaldig.eMem- omemVal .evalDPlaces ¢ — sets the Trigonometry units control to display either the item with index one, if evaldig.eMem- >memVal .calcDegrees is non-zero, or the item with index zero if it is zero For the Set "Evaluate" format dialog: e sets the Format control to display the item with index evaldlg.eMem- >memVal.evalFormat e — sets the Decimal places control to display the integer value in evaldig.emem- >memVal .evalDPlaces ¢ — sets the Trigonometry units control to display the item with index one if evaldig .emMem- >memVal .evalDegrees is non-zero. Otherwise sets the control to display the item with index zero. © — sets the dialog title from the text in the sys_EVALDLG_TITLE system resource. e key input INT dl_key(INT index, INT keycode) ; Write the current selection into the evaldig.eMem property and the msv environment variable. For the Set "Evaluate" format dialog: e writes the index of the item selected in the Format control to evaldlg.isEval.memVal .evalFormat ¢ if the format is either Fixed or Scientific, writes the value in the Significant digits/Decimal places control to evaidlg.isEval .memVal.evalDPlaces 15-15 HWIM REFERENCE ——— See SSS © writes the index of the item selected in the 7rigonometry units control to evaldig.isEval .memVal.evalDegrees For the Set Calculator format dialog: ® writes the index of the item selected in the Format control to evaldlg.isEval.memVal .calcFormat. ¢ if the format is either Fixed or Scientific, writes the value in the Significant digits/Decimal places contro] to evaldlg.isEval .memVal.calcDPlaces e writes the index of the item selected in the Trigonometry units control to evaldlg.isEval .memVal.calcDegrees Sets the content of evaldlg.isEval.memval: pV=&self->evaldlg.isEval; pV->memVal .calcFormat&=~DEGREES MODE; /* clear top bit before or'ring */ pV->memVal .calcFormat | =pV->calcDegrees; pV->memVal . evalFormat&=~DEGREES MODE; pV->memVal .evalFormat | =pV->evalDegrees; Writes the content of evaldig.isEval .memval to the sv environment variable: if this does not exist it is created. Returns wN_KEY_CHANGED. essages VOID dl_changed(INT changed) ; Set the prompt for the Significant digits/Decimal places control and dim or un-dim as appropriate. If the item selected in the Format control is either General or Hexadecimal, dims the Significant digits/Decimal places control. Otherwise if the item selected in the Format control is Scientific, sets the the sys_sIc_p1crTs system resource as the prompt for the Significant digits/Decimal places control and then un-dims the Significant digits/Decimal places control. Otherwise if the item selected in the Format control is Fixed, sets the sys_DEC_PLACEs system resource as the prompt for the Significant digits/Decimal places control and then un-dims the Significant digits/Decimal places control. _ Setn VOID dl_set_size (VOID) ; Supersend a pL_SET_SIZE message. Sets the prompt for the Significant digits/Decimal places control and dims or un-dims the control as appropriate. Reads the format specified in evaldig.eMem.memval .evalFormat if the dialog is a Set "Evaluate" format dialog, or evaldig.eMem.memval.calcFormat otherwise. If the format is either General or Hexadecimal, dims the Significant digits/Decimal places control. If the format is Scientific, sets the the sys_stc_p1c1Ts system resource as the prompt for the Significant digits/Decimal places control and then un-dims the Significant digits/Decimal places control. If the format is Fixed, sets the sys_pEc_PLACES system resource as the prompt for the Significant digits/Decimal places control and then un-dims the Significant digits/Decimal places control. 15 - 16 13 GENERAL SYSTEM DIALOGS SETPORTDLG flags id destrey whedraw wn_position wn_redraw wrh—sense—heip wn_visible SETPORTDLG next item count rbuf current dimrid underline helprid absorb changed destroy di_item_replace wn_key dl_item_append wn_emphasise dl_init wn_sense_help dl_dimmed_message wn_set di_item_add wn_sense dl_set_size wn_draw di_ing_minsize di_item_lock di—dyn—tnit dl_item_dim di-key dl_set_item_flags dl_set_prompt dl_changed dl_take_focus dl_focus dl_handle_to_index dl_launch_sub dl_index_to_handle dl_item_new The setportois class implements the Set serial port dialog which presents the user with editable serial port characteristics i.e. baud rate, number of data bits, number of stop bits, parity and parity mode. An example Set serial port dialog is shown in the following picture: Set Serial port +9686 ‘Data bits 8 ‘Stop bits 1 ‘Parity None ‘Ignore parity Yes The example dialog may be obtained by entering the Comms application and selecting the Port item in the Special menu. The digbox.rbuf property must point to a P_sRcuaR struct which is described in the Serial port chapter of the 1/O Devices Reference manual. Class definition Defined in sub-category file serdlgs.cl (generated header file serdigs.g). CLASS setportdlg dlgbox { REPLACE dl_dyn_ init REPLACE dl_key } Property There is no property associated with the sETpoRTDLG class. 15-17 HWIM REFERENCE ee See Resources Defined in system resource file s_.rss. The Series 3 version of the sys_BAUD_RATE_CHLIST system resource is as follows: RESOURCE MENU sys_baud_rate_chlist { items = { CHOICE_ITEM { str= "9600";}, CHOICE_ITEM { str= "4800";}, CHOICE_ITEM { str= "2400";}, CHOICE_ITEM { str= "1200";}, CHOICE _ITEM { str= "600";}, CHOICE_ITEM { str= "300";} He } The Series 3a version of the sys_BAUD_RATE_CHLIST system resource is as follows: RESOURCE MENU sys_baud_rate_chlist { items = { CHOICE_ITEM { str= "19200"; }, /* new for S3a */ CHOICE_ITEM { str= "9600";}, CHOICE_ITEM { str= "4800";}, CHOICE _ITEM { str= "2400";}, CHOICE_ITEM { str= "1200";}, CHOICE_ITEM { str= "600";}, CHOICE_ITEM { str= "300"; } }; } The remaining resources are common to both machines: RESOURCE MENU sys_data_bits_ chlist { items = { CHOICE_ITEM { str="5";}, CHOICE_ITEM { str="6";}, CHOICE_ITEM { str="7";}, CHOICE_ITEM { str="8";} }; } RESOURCE MENU sys_stop_bits chlist { items = { CHOICE_ITEM { str="1";}, CHOICE_ITEM { str="2";} }; } RESOURCE MENU sys_parity_chlist { items = { CHOICE_ITEM { str="None";}, CHOICE_ITEM { str="Even";}, CHOICE_ITEM { str= "Odd"; } }; 15-18 15 GENERAL SYSTEM DIALOGS RESOURCE MENU sys_no yes { items = { CHOICE_ITEM { str= "No";}, CHOICE_ITEM { str="Yes";} }; } RESOURCE DIALOG sys_set_port_dialog { title="Set Serial port"; flags=DLGBOX_NOTIFY_ENTER|DLGBOX_RBUF_FILLED; controls= { CONTROL { class=C_CHLIST; prompt="Baud rate"; info=CHLIST { rid=sys_baud_rate_chlist; nsel=0; }; }, CONTRO { class=C_CHLIST; prompt="Data bits"; info=CHLIST { rid=sys_data_bits_chlist; nsel=0; }; ys CONTROL { class=C_CHLIST; prompt="Stop bits"; info=CHLIST { rid=sys_ stop bits chlist; nsel=0; }i - CONTROL { class=C_CHLIST; prompt="Parity"; info=CHLIST { rid=sys_parity_chlist; nsel=0; ); }, CONTROL { class=C_CHLIST; prompt="Ignore parity"; info=CHLIST { rid=sys_no_yes; nsel=0; }i 15-19 HWIM REFERENCE ee en ee eS ee ee ED SETPORTDLG methods D INT : Initialise dialog items VOID dl_dyn_init (VOID) ; Initialise the content of the dialog. Sets the index of the item selected in the Baud rate control according to the flag in dlgbox .rbuf->tbaud. The flags and the corresponding indices are as follows: Series 3 flag Series 3a flag P_BAUD_9600 P_BAUD_19200 P_BAUD_4800 P_BAUD_9600 P_BAUD_2400 P_BAUD_ 4800 P_BAUD_2400 P_BAUD_2400 P_BAUD_600 P_BAUD_2400 P_BAUD_300 P_BAUD_600 none P_BAUD_300 If dlgbox.rbuf ->frame is non-zero, sets the index of the item selected in the Data bits control to P_DATA_8. Otherwise, sets the index of the item selected in the Data bits control to zero. If digbox. rbuf ->frame contains p_Two_stop, sets the index of the item selected in the Stop bits control to one. If digbox. rbuf->frame contains the p_parrry flag, sets the index of the item selected in the Parity control to dlgbox.rbuf.parity. If dlgbox. rbuf->frame contains the p_IGNORE_PARITY flag, sets the index of the selected item in the Ignore parity control to one i.e. Yes. Handle key input INT dl_key(WORD id, INT event) ; Handle a keypress. Senses the index of the item selected in the Baud rate control and then writes the corresponding flag to both digbox.rbuf->tbaud and dlgbox.rbuf->rbaud. The possible indices and the corresponding flags are as follows: Series 3a flag P_BAUD_19200 P_BAUD_9600 P_BAUD_4800 P_BAUD_9600 P_BAUD_2400 P_BAUD_4800 P_ BAUD 2400 P_BAUD_2400 P_BAUD_600 P_BAUD_2400 P_BAUD_300 P_BAUD_600 none P_BAUD_300 15 GENERAL SYSTEM DIALOGS |) —< << KOE NERAL STO TEM DIALOGS | Writes the index of the item selected in the Data bits control to digbox.rbuf->frame. If the index of the item selected in the Stop bits control is non-zero, ors the P_twosTop flag into digbox.rbuf->frame. Writes the index of the item selected in the Parity control to digbox.rbuf->parity, and, if the index is NnON-ZETO, ORS P_PARITY into dlgbox.rbuf->frame. Writes the index of the item selected in the Ignore parity control to digbox. rbuf->flags. Returns wN_KEY_CHANGED. SETHSHKDLG flags next id destroy wh—draw DLGBOX item count rbuf current dimrid underline helprid absorb changed SETHSHKDLG destroy dl_item_replace wn_key dl_item_append wn_emphasise di_init wn_sense_help di_dimmed_message wn_set dl_item_add wn_sense dl_set_size wn_draw dl_ing_minsize dl_item_lock di—dyn—inie dl_item_dim ai—key dl_set_item_flags dl_set_prompt di_changed @l_take_focus dl_focus d@l_handle_to_index dl_launch_sub dl_index_to_handle dl_item_new dl_dyn_init wn_cale position |wn-emphasise dl_key The sETHSHKDLG class implements the Set serial handshake dialog which present the user with editable serial port handshake settings i.e. the Xon/Xoff, Rts/Cts, Dsr/Dtr and Ded settings. An example Set serial handshake dialog is shown in the following picture: Set serial handshake ‘Ron Xoff On ‘Rts/Cts ¢+Off> ‘Dsr/Dtr Off ‘Ded Off Each control may be set to either On or Off. The digbox.rbuf property must point to a uBYTE containing an ored combination of handshake flags - the allowed flags are described in the Serial port chapter of the J/O Devices Reference manual. Class definition Defined in sub-category file serd/gs.cl (generated header file serdlgs.g). CLASS sethshkdlg dlgbox { REPLACE dl_dyn_init REPLACE dl_key } SSS 15-21 HWIM REFERENCE ee eee Property None. Resources Defined in system resource file s_.rss. RESOURCE DIALOG sys_set_hshk_dialog { title="Set serial handshake"; flags=DLGBOX_NOTIFY_ENTER |DLGBOX_RBUF_FILLED; controls= { CONTROL { class=C_CHLIST; prompt="Xon/Xoff"; info=CHLIST { rid=sys_offon_menu; nsel=0; }e }, CONTROL { class=C_CHLIST; prompt="Rts/Cts"; info=CHLIST { rid=sys_offon_menu; nsel=0; }i }, CONTROL { class=C_CHLIST; prompt="Dsr/Dtr"; info=CHLIST { rid=sys_offon_menu; nsel=0; a he CONTROL { class=C_CHLIST; prompt="Ded"; info=CHLIST { rid=sys_offon_menu; nsel=0; }; }; } RESOURCE MENU sys_offon_menu { items = { CHOICE_ITEM { str="0ff";}, CHOICE ITEM { str= "On";} }; 15 - 22 15 GENERAL SYSTEM DIALOGS a a oe a ar a ay a a] SETHSHKDLG methods DL_DYN_INIT ___—is.. _ _ dnitialise items VOID dl_dyn_init (VOID) ; Initialise the items in the dialog. If sel£->dlgbox.rbuf contains P_oBEY_xoFF, sets the Xon/Xoff control to display On. If sel£->dlgbox.rbué does not contain p_ien_crs, sets the Rts/Cts control to display On. If self->dlgbox.rbuf contains p_oBEY_pskr, sets the Dsr/Dtr control to display On. If self£->dlgbox.rbuf contains p_oBEY_pcp, sets the Ded control to display On. _ Handle key input INT dl_key(WORD id, INT event) ; Handle key input. Write zero to *dlgbox. rbuf. If the index of the item selected in the Xon/Xoff control is non-zero, ors P_OBEY_XOFF and P_SEND_XOFF into *dlgbox. rbuf. If the index of the item selected in the Rts/Cts control is zero, oRS P_IGN_CTS into *dlgbox. rbuf. If the index of the item selected in the Dsr/Drr control is non-zero, ors P_OBEY_DSR into *digbox. rbuf. If the index of the item selected in the Ded control is non-zero, ors P_OBEY_DsD into *dlgbox. rbuf. Retums wN_KEY_CHANGED. 15 - 23 — CHAPTER 16 PRINT CLASSES This chapter describes the xwim printing, print preview and print dialog classes which provide a convenient means of accessing the current printer parameters and performing a printing or print preview operation. Although these dialog classes are described in this chapter, the descriptions are included mainly for completeness since there will generally be no need for an application to subclass or to explicitly create any of them. The classes that are described in this chapter are as follows: e the LpRinTeR class which provides the basic framework for a printing operation and may be used, for example, to print multiple columns with a specific font and font style for each column. The class must be subclassed to be useful. e the ppgvpte class which implements the Printer configuration dialog allowing the user to edit the current printer settings. The edited settings are stored as environment variables so that they may be accessed by other applications. e the prnprev class which implements the Preview settings dialog allowing the user to edit the print preview settings. It is not available on the Series 3 machine. e the prncrri class which implements the Print setup dialog allowing the user to edit the current page layout settings. The edited settings are stored in the current PRINTER object so that they may be accessed by other objects used by the application. e the pacecrrt class which implements the Paging control dialog allowing the user to edit the page number style. The edited settings are stored in the current pRinTER object so that they may be accessed by other objects used by the application. e _ the marcins class which implements the Margins dialog allowing the user to edit the page margins. The edited settings are stored in the current printer object so that they may be accessed by other objects used by the application. e the HEapFoor class which implements the Header details and Footer details dialogs allowing the user to edit the header and the footer respectively. The edited settings are stored in the current PRINTER Object so that they may be accessed by other objects used by the application. e the prNMopEL class which implements the Set printer dialog allowing the user to select the printer model and default font. The edited settings are stored in the current PRINTER object so that they may be accessed by other objects used by the application. . e the pacrszze class which implements the Page size dialog allowing the user to edit the page size and orientation. The edited settings are stored in the current PRINTER object so that they may be accessed by other objects used by the application. e the printine class which provides the Printing dialog allowing a printing operation to be started, monitored and cancelled. A Printing dialog is launched by the LpRInTER class. e the pmopiocs class which is used as a component by the prwmopet class. This class is highly specialised and is thus unlikely to be used elsewhere. Any application may create and use the Print setup or Printer configuration dialogs by sending WS_EDIT_PRINT_CONTEXT OF WS_EDIT_PDEV_SETUP messages to the application's instance of (a subclass of) wseERV. All the dialogs described in this chapter are, directly or indirectly, components of either or both of these two dialogs. 16-1 HWIM REFERENCE The differences in screen size between the Series 3, Series 3a and Workabout result in different limits on the number of items that may appear in a dialog. In consequence, there are some differences of implementation of the print dialog classes between the different machine types. On the Series 3a, for example, the dialogs are related as shown below: Page size (inches) ‘Page size MRT ED Width ‘Number for first page ‘Allow widows/ ‘Page number style ¢HP LaserJet IIl+ 12 kon’ xXott ¢0n* ‘Rts/Cts Off ‘Dsr/Otr ‘Ded Gossen} +2 pages> ‘Margins _ Off All the dialogs are available from the Print setup dialog, which would normally be accessed via a Print setup option in one of the menus (generally the Special menu) of an application that can print data. Note that some of these dialogs, for example, the Set serial port and Set serial handshake dialogs, are described in other chapters of this manual. On the Workabout, the dialogs are again all accessible from the Print Setup dialog, but the organisation is somewhat different, as illustrated below: Pave setup T25y 1.25) 1.25) 1.25 Preview settings Wee ¢Z pages > ‘Margins Off [Set serial handshake | /Xon/Xott ¢One *htst ry Heprore ‘Sclect printer Rieter wry +Footer... -~ ‘Dofauit font. Pica 12 } \*Paging control. 1+ Nor 1529 Es f Set Serlotport 36887 8 Boud tate (Page size (inches) Italic No sPrint position Normal __ 16-2 16 PRINT CLASSES —_——— SSO CLASSES The main differences in appearance are in the Print setup and Page setup dialogs. The Print setup dialog is implemented on the Workadbout by an additional scprncti class. The Page setup dialog contains most of the items that appear in the Series 3a Print control dialog. In fact, it is implemented by another new class - ScPGSETUP. This subclasses the prNcTRL class, replacing only the a1_dyn_init method to change the title text and then supersend the pL_pyn_1nrT message. These two additional classes are not further documented in this chapter. Precursors Familiarity with the following topics will aid the understanding of this chapter: e the PRINTER class which supplies methods for both editing the current printer settings and starting a printing, pagination or print preview operation. e the paces active object class which is responsible for the printing. e the Locs class described in the OLIB Reference manual. The PRINTER and pacss classes are described in the Document Printing Classes of the FORM Reference manual. Class diagram c / Sieh M | a / bwin ; f / pom as ee, SAL 1 ws . Sh. pipe eee “i : / Pinter >’ wser > V Pd VES Ln { ¢ fd aad oat 4 ~S, ‘ ‘digchain ~> the / ‘4 ( i. \ f- pdevdlg - aed i printing ; / Iptinter - ae \ en 9 POR Doras ; oe ( ‘ oe. Sides oe di b x > : i seh OE ; be ene } se i iad sa © //headfoot 3 margins ,/pagectrl “> ~~>pmnmodel ee 16-3 HWIM REFERENCE 5 a A a i Oy ie LPRINTER LPRINTER defer wtab Lheight width subsqind destroy lpr_init lpr_read ipr_sense_buf_width ipr_sense_text The LPRinTER class provides the basic framework that allows an application to print one or more copies of a document using the services provided by the printer and paczs classes. The document is represented as a sequence of one or more print elements. The print elements are supplied by the 1pr_read method of the Lprinrer object and printed by the pacgs object. The 1pr_read method sets the print element in three steps as follows: e sets defaults for the line height, the line indentation, the line spacing and the font and ensures that the print element appears on a new line. ¢ sends self an LPR_SENSE_TEXT message: the LPR_SENSE_TEXT message may set the text and any other characteristics of the print element. * if the print element is too long for one line, it wraps the text onto the next line(s) thus creating two or more shorter print elements. The 1pr_sense_text method is deferred and - unless the 1pr_read method is replaced - must be supplied by the subclasser. Print elements Each print element is represented by a woR_PRINT struct defined as follows: typedef struct { WORD flags; WORD typf; WORD fheight; WORD style; WORD down; WORD indent; WORD height; WORD right; TEXT *buf; UWORD blen; } WDR_PRINT; The significance of the members of the wor_PRINT struct is as follows: flags an ored combination of the following flags: WDR_PRINT_START _ this flag indicates that the printer is to be initialised to allow printing. WDR_PRINT_PAGE _ this flag indicates that the print element is on a new page. WDR_PRINT_LINE this flag indicates that the print element is on a new line. 16-4 16 PRINT CLASSES ——$—$—$ ee CLASSES WDR_PRINT_FonT this flag indicates that the current printer font is to be set to the font specified by the typ£, height and style members. The current font is set before any text is printed. WDR_PRINT_RIGHT _ this flag indicates that the current print position is to be moved right by the number of printer units specified by the right member. The current print position is moved before any text is printed. WDR_PRINT_TExT this flag specifies that the text specified by the buf and 1en members is to be printed. WDR_PRINT_END this flag specifies that the print element is the last. typf£ this is the typeface index and uniquely identifies the typeface. This member is ignored unless the flags member contains WOR_PRINT_FONT. fheight this is the height of the font in units of twips. This member is ignored unless the flags member contains wOR_PRINT_FONT. style this specifies the font style and may contain an ored combination of the following flags: WDR_PRINT_NORMAL plain text. WDR_PRINT_UNDERLINE the text is to be printed as underlined text. WDR_PRINT_BOLD the text is to be printed as bold text. WDR_PRINT_ITALIC the text is to be printed as italic text. WDR_STYLE_SUPER the text is to be printed as superscripted text. WDR_PRINT_SUB the text is to be printed as subscripted text. This member is ignored unless the flags member contains woR_PRINT_FONT. down this is the downwards displacement of the print head in printer units. It is automatically set to zero by the pacss object if the print element is at the top of the page. This member is ignored unless the £1ags member contains woR_PRINT_LINE. indent this is the right indent of the print head in printer units. This member is ignored unless the flags member contains woR_PRINT_LINE. height this is the line height in printer units. When moving to a new line the print head is moved down by the sum of the height and down members. This member is ignored unless the flags member contains wOR_PRINT_LINE. right this is the right displacement of the print head in printer units. This member is ignored unless the flags member contains WOR_PRINT_RIGHT. buf this is the address of a buffer containing the text to print. This member is ignored unless the flags member contains woR_PRINT_TEXT. blen this is the length of the text to print. This member is ignored unless the £1ags member contains WOR_PRINT_TEXT. Class definition Defined in sub-category file /printer.cl (generated header file /printer.g). CLASS Ilprinter root { REPLACE destroy ADD lpr_init ADD lpr_read ADD lpr_sense_buf_width DEFER lpr_sense_text 16-5 HWIM REFERENCE SK eee PROPERTY { VOID *pages; Copy for reference only VOID *wdr; Copy for reference only SCRLAY_FONT f; The default font WDR_PRINT defer; In case previous data was too wide UBYTE *wtab; Width table UWORD lheight; Line height in printer units UWORD width; Width of region to print to UWORD subsqind; Indent for subsequent lines (if wrapped) } } Property lprinter.pages the handle of an instance of the paces class which is responsible for the printing. A description of the pacgs class may be found in the FORM Reference manual. lprinter.wdr the handle of an instance of the wor class. This class provides access to the current printer resource file. A description of the wor class may be found in the FORM Reference manual. lprinter.f a pointer to a scrLAY_Font struct which contains details of the default font. The SCRLAY_FONT struct is defined as follows: typedef struct { UWORD fid; UWORD style; UWORD height; } SCRLAY_FONT; The significance of the members of the above struct is as follows: fid this is the default font ID. style this is the default font style. height this is the default font height in units of twips. The default font characteristics are obtained from the current PRINTER object. lprinter.defer a WDR_PRINT struct containing details of deferred text. Deferred text results from the lpr_sense_text method providing too much text for one line. The deferred text is printed on subsequent line(s) with a line indentation of iprinter.subsqind. lprinter.wtab a pointer to the current printer width table. A monospace font table contains two bytes. The first byte is always equal to zero. The second byte specifies the width of a character . A proportional font table contains one byte per character. The width of the character with code c is specified by the byte with offset c. lprinter.lheight specifies the default line height in printer units used by the 1pr_read method. lprinter.width specifies the width of one line in printer units used by the 1pr_read method. lprinter.subsgind specifies the line indentation to be used when printing deferred text. ni Se SS EE LPRINTER methods STROY 3 Destroy VOID destroy (VOID) ; Destroy the LPRINTER instance. 16-6 16 PRINT CLASSES If w_ws->wserv.printer is non-zero, sends a PR_CLOSE_WDR Message tO w_ws->wserv. printer. Supersends a pEsTRoy message. LPR_INIT o ee Start printing dialog VOID lpr_init (VOID) ; Initialise the LpRINTER object property and then start the printing operation. Ensures that an instance of the prinrer printer manager class exists by sending a WS_ENS_PRINT_CONTEXT message to w_ws. Obtains a pointer to a PRINTER_PARAMS struct - which contains the current printer parameters - by sending a PR_GET_PARAMS message to w_ws->wserv.printer. Stores the width of the printing region in property by writing the p.pg.body. width member of the PRINTER_PARAMS Struct to lprinter.width. Stores the default printer font in property by writing the a. member of the pRINTER_PARans struct to lprinter.f. Not on the Series 3: if iprinter . subsqind is non-zero, writes FALSE to lprinter. subsqind and returns. A non-zero value for lprinter.subsqind indicates that the LpRINTER object is being used for a print preview operation. Specifies the paces active object that is to handle the printing by writing iprinter.pages to the ppages member of an RBUF_PRINTING struct. Specifies the call-back handle for reading the next line of text - in the form of a wor_pRInT struct - by writing se1£ to the calls hread member of the above rBUF_PRINTING struct. Specifies the call-back message for reading the next line of text by writing o_LpR_reap to the calls hread member of the above RBUF_PRINTING struct. Starts the printing operation by launching a Printing dialog with the address of the above RBUF_PRINTING struct as the data - details of the Printing dialog and the RBUF_PRINTING struct may be found in the description of the PRINTING class. ead call-back VOID lpr_read(INT x,WDR_PRINT *pr) ; Write to the wor_PRINT struct specified by pr details of the next portion of text to print. This call-back method is called by the pacgs active object when it requires the next print element. The first step is to ensure that all property has been initialised. Thus if iprinter.wdr is zero: e — sets the default line height as specified by lprinter.1height to be equal to the height of the default font specified by iprinter.£.height. e converts the default line height - iprinter.1height - into vertical printer units. e converts the default line width - iprinter .width - into horizontal printer units. e — sets the handle of the wor printer resource object specified by printer .wdr to the pages. in.wdr member of lprinter.pages - this is assumed be the handle of a wor object used by the current PAGES object. e writes the address of the printer width table for the default font specified by printer. to lprinter.wtab - the method obtains the address by sending a woR_GET_WIDTH_TABLE message to lprinter.wdr. If lprinter.defer.blen is non-zero, the content of the wor_PRINT struct pointed to by pr is set from the deferred text specified by printer. defer: e writes lprinter.defer to «pr. e — sets the line indentation specified by pr->indent to printer. subsqind. 16-7 HWIM REFERENCE SSS eee Otherwise the content of the wor_PRINT struct pointed to by pr is set as follows: * writtes default values for the font, line height, line indentation and line separation and indicates that the print element is to appear on a separate line: pr->flags=WDR_PRINT_FONT|WDR_PRINT_LINE|WDR_PRINT_TEXT; pr->typf=self-slprinter.f.fid; pr->fheight=self->lprinter.£.height; pr->style=self->lprinter.f.style} pr->height=self->lprinter.lheight; pr->down =0; pr->indent=0; e sends self an LPR_SENSE_TEXT Message with an argument of pr. ¢ ifthe LPR_sENSE_TExT message indicated that the printing is complete - i.e. the return value is FALSE - Writes WOR_PRINT_END to pr->flags and then returns. Writes «pr to lprinter. defer. If the line indentation specified by pr->indent exceeds the line width specified by lprinter .width, the indentation is reset to zero. Determines the number of characters in the buffer pointed to by pr->bug that will fit on the current line assuming the current font and line width. The current line is broken at a word boundary if at all possible. The difference between the result and the value specified by pr->1en defines the length of any deferred text i.e. text that wraps onto one or more subsequent lines. Writes the length of the text that will fit on the current line to pr->bien. Writes the length of the deferred text to lprinter.defer.blen. If there is deferred text: ® writes the address of the first deferred character to iprinter.defer. buf. e writes the length of the deferred text to lprinter.defer.blen. e not on the Series 3: sets WDR_PRINT_LINE in iprinter. defer. flags. ¢ — obtains the address of a pRinreR_PARaMs struct containing the current printer parameters by sending a PR_GET_PARAMS message to w_ws->wserv.printer. e ifthe ¢.wo_control member of the PRINTER_PARAMs struct is zero - indicating that widows and orphans are not allowed - sets WoR_PRINT_KEEP in pr->flags. INT Ipr_sense_buf_width(TEXT *buf,INT len); Return the width in printer units of the first 1en characters pointed to by buf. The method evaluates the length of the text using the current printer width table at address lprinter.wtab. Sa a a ET Deferred LPRINTER methods SE TEXT : — Get text to print INT lpr_sense_text (WDR_PRINT *pr) ; Get the next portion of text to print - this method is called by the 1pr_read method For the simplest printing requirements the replaced method should write the address and length of the text to print to pr->buf and pr->1en respectively. 16-8 16 PRINT CLASSES _ — OOENINTE GLASSES For more sophisticated printing requirements the default line height, line indentation, line spacing and font may be overridden by writing appropriate values to the appropriate members of the wor_PRINT struct pointed to by pr. In all cases the replaced method should return rause if no more text remains. Note that it may be better to replace the 1pr_read method, and ignore the 1pr_sense_text method, ifa significant amount of processing would otherwise have to be carried out in the lpr_sense_text method. PDEVDLG flags next id destroy wa—draw wn_position wn_redraw wa—sense—heip wn_visible DLGBOX item count rbuf current dimrid underline helprid absorb changed destroy dl_item_replace wn_key dl_item_append wn_emphasise qdl_init wn_sense_help dl_dimmed_message wn_set dl_item_add wn_sense di—set—size wn_draw dl_ing_minsize dl_item_lock di—dyn—init dl_item_dim di—key dl_set_item_flags dal_set_prompt di—changed dl_take_focus dl_focus dl_handle_to_index 42—tauneh—sub dl_index_to_handle dl_item_new dil_launch_sub dl_dyn_init The ppevoie class implements the Printer configuration dialog allowing the user to select the printer device and edit the associated settings. An example Printer configuration dialog for the Series 3 is shown in the following picture: Printer configuration “Printer device ¢ Parallel + Serial characteristics .. Serial handshaking ... File: Name Disk *Units Inches and examples of the equivalent dialogs for the Series 3a and Workabout are shown below: Printer configuration ‘Printer device ¢Parallel+ Serial characteristics ... Serial handshakins ... File: Name Disk ‘Units Inches ‘Print preview... 2 pages, Margins off Series 3a Printer configuration dialog 16-9 HWIM REFERENCE eee Printer configuration "Printer device Parallel» Serial characteristics .. Serial handshaking... File? Name Disk Workabout Printer configuration dialog For the Series 3a dialog, the important difference is the extra Print preview control which allows the user to edit the print preview settings. On the Workabout, this additional facility is provided from the Print setup dialog, as indicated at the beginning of this chapter. The edited values - with the exception of the printer units - are stored in system-wide environment variables as follows: P$D PSF PSS PSP this stores the printer port type and may be set to one of the following values: PRINTER_PORT_PARALLEL indicates that the current printer device is the parallel port. PRINTER_PORT_SERIAL indicates that the current printer device is the serial port. PRINTER_PORT_ FILE indicates that the current printer device is a file. PRINTER_PORT_FAX indicates that the current printer device is the fax. this stores the full file specification of a file to which printing may be directed. The name is stored as a zero terminated string this stores the serial port characteristics organised as a P_SRCHAR struct. Not used the Series 3. This environment variable, which is four bytes long, stores the print preview settings as a zero terminated string containing two characters. The first character specifies the print preview mode as follows: ‘0' specifies that print preview operations are to display facing pages. ‘T' specifies that print preview operations are to display one page. ‘2"_ specifies that print preview operations are to display two pages. ‘3' specifies that print preview operations are to display three pages. ‘4' specifies that print preview operations are to display four pages. The second byte specifes the margins mode as follows: ‘0 specifies that print preview operations are not to display the margins. ‘l' specifies that print preview operations are to display the margins. The printer units is stored as a system wide setting - for details see the p_getcta and p_setcta PLIB routines in the PLIB Reference manual. Class definition Defined in sub-category file prntdlgs.cl (generated header file prntdlgs.g). 16-10 CLASS pdevdlg dlgbox { REPLACE destroy REPLACE dl_launch_sub REPLACE dl_dyn_init REPLACE dl_key REPLACE dl_set_size REPLACE dl_changed 16 PRINT CLASSES rE ES PROPERTY 1 { PR_ROOT *printer; P_SRCHAR srchar; WORD filechanged; WORD own_printer; PVV_DISPLAY Disp; } } Property pdevdlg.printer pdevdlg.srchar pdevdlg.filechanged pdevdlg.own_printer pdevdlg.Disp Resources The handle of an instance of the printer class. This object supports the setting and sensing of data required for print, pagination and print preview operations. A P_SRCHAR struct containing the current serial port characteristics. These are either copied from the psr environment variable, or, if this does not exist, set to default values. Set to Trus if the user has edited either the characteristics associated with one or more devices or the printer units - selecting a new printer device does not set this property to TRUE. The default value is FALSE. Set to True if the ppzvpic object creates its own PRINTER object on initialisation. Set to Fause if the ppevp.e object uses the PRINTER object with handle W_ws->wserv.printer. This property is not available on the Series 3. Contains the current print preview settings stored as a pvv_DIspay struct - see the description of the prwerev class for details. This property is not available on the Series 3. Defined in the system resource file s_.rss. RESOURCE CONTROL sys_print_preview_settings { Class=C_TEXTWIN; prompt="Print preview"; info=TXTMESS { str="Facing pages,Margins off"; /* widest possible text */ flags=IN_TEXTWIN_POPOUT; }; } RESOURCE DIALOG sys_printer_ config dialog { title="Printer configuration"; flags=DLGBOX_NOTIFY_ENTER; controls= { CONTROL { class=C_CHLIST; prompt="Printer device"; flags=DLGBOX_ITEM_NOTIFY_CHANGED; info=CHLIST }, { rid=sys_printer_device_chlist; i 16-11 HWIM REFERENCE eee SSSeSSSSSeSeeSeeeeeSSSSSSSSFSSSSSSSSSSSSSFSsee CONTROL { class=C_TEXTWIN; prompt="Serial characteristics "; info=TXTMESS { str="19200 "; /* changed for S3a */ flags=IN_TEXTWIN_POPOUT; }; }, CONTROL { class=C_TEXTWIN; prompt="Serial handshaking "; info=TXTMESS { str="Xon/Xoff Off "; flags=IN_TEXTWIN_POPOUT; }; }, CONTROL { £lags=DLGBOX_ITEM_NEEDS_PACK|DLGBOX_ITEM_NOTIFY_CHANGED; class=C_FNEDIT; prompt="File:"; info=FNEDIT { flags=IN_FNEDIT_NO_AUTOQUERY; }; }, CONTROL { class=C_CHLIST; prompt="Units"; info=CHLIST { rid=sys_printer_units chlist; : }; } Note: on the Series 3, the text "19200" in the Serial characteristics contro] is replaced by "9600". See ee ee en a en ee a a eT PDEVDLG methods Destroy VOID destroy (VOID) ; Destroy the ppEvpic object. If pdevdlg.own_printer is non-zero, sends a destroy messsage to pdevdlg. printer. Supersends a DESTRoy message. This method is not replaced on the Series 3. Launch sub-dialog VOID dl_launch_sub(INT index) ; Launch either a Set serial port dialog or a Set serial handshake dialog according to the value of index. If index is two, launches a Set serial port dialog - details of this dialog may be found in the General dialogs chapter of the HWIM Reference manual - in order to edit some of the serial port characteristics stored in pdevdlg.srchar. 16-12 16 PRINT CLASSES ———————$S—.:s $e ENNE CLASSES Otherwise, launches a Set serial handshake dialog - details of this dialog may be found in the General dialogs chapter of the HWIM Reference manual - in order to edit the serial port handshake settings stored in pdevdlg.srchar.hand. Stores the new serial port settings in the ps environment variable by sending a PR_STORE_CHAR message to pdevdlg.printer specifying the address of pdevdig.srchar as argument. Sets the Serial characteristics control to display appropriate text: the text is either the nut string, or the appropriate item in the sys_BAUD_RATE_CHLIST system resource followed by an ellipsis symbol. Sets the Serial handshake control to display appropriate text: the text is either the nu string, or the concatenation of the sys_xoNxXOFF_STRING, an appropriate item from the sys_oFFoN_MENU system resource and an ellipsis symbol. The following actions are not performed on the Series 3. If index is seven, allows the user to edit the print preview settings stored in pdevalg. Disp by launching a Preview settings dialog. Stores the edited print preview settings as a zero terminated string containing two characters in the psp environment variable. See the introduction for details of the psp environment variable. Sets appropriate text in the Print preview control. VOID dl_dyn_init (VOID) ; Dynamically initialise the content of the dialog. The following actions are not performed on the Series 3: e enables appropriate context sensitive help by writing -sys_HELP_PRINT to dlgbox.helprid. e if w_ws->wserv. printer is non-zero - and is thus assumed to store the handle of the current printer object - writes w_ws->wserv.printer tO pdevdlg. printer. e otherwise writes TRUE to pdevdlg.own_printer, creates an instance of the pRInTER class, writes its handle to pdevdig.printer and then initialises the prinreR object by sending a PR_INIT message to pdevdlg.printer. The following actions are only performed on the Series 3: ® creates an instance of the printer class, writes its handle to pdevdig.printer and then initialises the PRINTER object by sending a pR_INIT message to pdevdlg. printer. Obtains the current serial port characteristics - in the form of a p_sRcuar struct - and the name of the current file to which printing is directed by sending a pR_poRT_DATA message to pdevdlg. printer. Writes the current serial port characteristics to pdevdlg.srchar. Sets the File name control to display the name of the file to which printing is directed. Obtains the current system wide units - i.e. either = METRIC or E_IMPERIAL - and sets this as the index of the item selected in the Units control - for further details see the description of the E_conrze struct in the PLIB Reference manual. If the item with index one is selected in the Printer device control - i.e. the Serial item - undims the Serial characteristics and Serial handshaking controls and then dims the File name control. If the item with index two is selected in the Printer device control - i.e. the File item - dims the Serial characteristics and Serial handshaking controls and then undims the File name control. Otherwise, dims the Serial characteristics, Serial handshaking and File name controls. The following actions areonly performed on the Series 3. If w_ws->wserv. flags Contains PR_WSERV_FULLSCREEN: e — adds to the dialog an underline separating the Disk and Units controls, and then appends to the dialog the Print preview control defined by the sys_PRINT_PREVIEW_SETTINGS system resource. ee SSSeFeSSSSSSSSSSSSSSSSSSSSSSSSSSSSSeeSsSSSSSeSeeeeeeeeeeee 16-13 HWIM REFERENCE e retrieves the print preview settings stored in the psp environment variable and writes appropriate values to dpevdlg.Disp. DE XEY ss Handle key input INT dl_key(INT index, INT keycode) ; Store the current selections as system wide settings. Senses the index of the item selected in the Printer device control and sets the result into the psp environment variable by sending a pR_SET_PORT_TYPE message to pdevdlg. printer. If pdevdlg.£ilechanged is TRUE, senses the file name displayed in the File name control and sets the result into the p$r environment variable by sending a pR_STORE_FILE message to pdevdlg.printer. Senses the index of the item selected in the Units control and sets this as the system wide units - for further details see the description of the &_conrte struct in the PLIB Reference manual. Not on the Series 3: if the system units are currently set to metric, sets PR_WSERV_METRIC in w_ws- >wserv. flags, otherwise clears PR_WSERV_METRIC in w_ws->wserv. flags. Returns wN_KEY_CHANGED. VOID dl_set_size (VOID); Set the size of the dialog and the text in the Serial characteristics and Serial handshaking controls. Supersends a DL_SET_SIZE message. Sets appropriate text in the Serial characteristics control - the text is created by concatenating an appropriate item from the sys_BAUD_RATE_CHLIST system resource and an ellipsis symbol. Sets appropriate text in the Serial handshaking control - the text is created by concatenating the SYS_XONXOFF_STRING system string resource, an appropriate item from the sys_oFFon_MENU system resource and an ellipsis character. Not on the Series 3: sets appropriate text in the Print preview control. ed messages VOID dl_changed(INT index) ; Set the dim status of the Serial characteristics, Serial handshaking and File name controls according to the item selected in the Printer device control. If index is one - i.e. the content of the Printer device control has changed - senses the index of the item selected in the Printer device control and e if the index is one, i.e. the Serial item, undims the Serial characteristics and Serial handshaking controls and then dims the File name control. © if the index is two, i.e. the File item, dims the Serial characteristics and Serial handshaking control and undims the File name control. e otherwise, dims the Serial characteristics, Serial handshaking and File name controls. Otherwise, indicates that an item in the dialog has changed by writing TRUE to pdevdlg.filechanged. 16-14 16 PRINT CLASSES PRNPREV DLGBOX item item rbuf rbuf dimrid dimrid helprid helprid flags flags focus focus count count current current underline underline absorb absorb changed changed destroy dl_item_replace wn_key dl_item_append wn_emphasise dl_init wn_sense_help di_dimmed_message wn_set dl_item_add wn_sense dl_set_size wn_draw dl_ing minsize di_item_lock di—dyn—tnie dl_item_dim di—tey dl_set_item_flags dl_set_prompt dl_changed dl_take_focus dl_focus dl_handle_to_index dl_launch_sub dl_index_to_handle dl_item_new wn_position wn_redraw wnosense—hetp wn_visible The prnprev class implements the Preview settings dialog allowing the user to edit the current settings for print preview operations. An example Preview settings dialog is shown in the following picture: Preview settings ¢2 pages > ‘Margins Off The prnprev class is not available on Series 3 machines. Class definition Defined in sub-category file prntdigs.cl (generated header file prntdlgs.g). CLASS prnprev dlgbox { REPLACE dl_dyn_init REPLACE dl_key } Property There is no property associated with the prnprEv class. Resources Defined in the system resource file s_.rss. 16 - 15 HWIM REFERENCE eee RESOURCE MENU sys_offon_menu { items = { CHOICE_ITEM { str="0f£";}, CHOICE_ITEM { str= "On";} }i } Defined in the system resource file sx_.ra. RESOURCE MENU sys_preview_options_chlist { items= { CHOICE_ITEM {str="Facing pages";}, CHOICE_ITEM {str="1 page";}, CHOICE_ITEM {str="2 pages";}, CHOICE_ITEM {str="3 pages";}, CHOICE_ITEM {str="4 pages"; } ‘7 } RESOURCE DIALOG sys_preview_settings_dl { title="Preview settings"; £lags=DLGBOX_NOTIFY_ENTER|DLGBOX_RBUF_ FILLED; controls= { CONTROL { class=C_CHLIST; prompt="Display"; info=CHLIST{rid=sys_preview_options_chlist;}; }, CONTROL { class=C_CHLIST; prompt="Margins"; info=CHLIST(rid=sys_offon_menu;}; } EER a ae ee a ee ee ee ee] PRNPREV methods VOID dl_dyn_init (VOID) ; Dynamically initialise the content of the dialog from the pvv_prspzay struct pointed to by dlgbox. rbuf. The pvv_pisptay struct is defined as follows: typedef struct { UBYTE Mode; UBYTE Flags; } PVV_DISPLAy; The significance of the members of the struct is as follows: Mode _ this may take a value from zero to four inclusive to specify that either facing pages, one page, two pages, three pages or four pages are to be displayed in print preview operations. Flags this may be rruz to specify that the margins are to be shown in print preview operations. It should be rause otherwise. Set the index of the item selected in the Display control to digbox. rbuf - >Mode. 16-16 16 PRINT CLASSES Set the index of the item selected in the Margins control to digbox. rbuf->Flags. Handle key input INT dl_key (INT index, INT keycode) ; Store the edited content of the dialog in the pvv_pispuay struct pointed to by dlgbox.rbuf. Sense the index of the item selected in the Display control and write the result to aigbox. rbuf->Mode. Sense the index of the item selected in the Margins control and write the result to digbox . rbuf- >Flags. PRNCTRL E pene next item count rbuf current dimrid underline helprid absorb changed dl_item_replace wn_key dl_item_append iwn_emphasise q@l_init wn_sense_help d1_dimmed_message wn_set dl_item_add wn_sense dl_set_size wn_draw di—ing-minsize dl_item_lock di—dyn—inst dl_item_dim ai—key di_set_item_flags dl_set_prompt dl_changed dl_take_focus dl_focus dl_handle_to_index di—tauneh—sub d1l_index_to_handle d1_item_new The prnctru class implements the Print setup dialog allowing the user to edit the current page layout settings. An example Print setup dialog is shown in the following picture: Be S156 ‘Margins. 1,25, 1.25, 1.25, 1.25 “F *Header.., »Footer.. “P "Paging control. 13 Nos 15253 «Printer model. Canon BJ-1@e The user may press the Tab key after having selected: e the Page size control to obtain a Page size dialog - see the description of the pacrszze class in the current chapter for further details. e the Margins control to obtain a Margins dialog - see the description of the marcrns class in the current chapter for further details. e the Header control to obtain a Header details dialog - see the description of the HEapFoot class in the current chapter for further details. e the Footer control to obtain a Footer details dialog - see the description of the HEADFoot class in the current chapter for further details. 16-17 HWIM REFERENCE a e the Paging control to obtain a Paging control dialog - see the description of the pacectru class in the current chapter for further details. ¢ the Printer model contro] to obtain a Set printer dialog - see the description of the PRNMODEL Class in the current chapter for further details. The members of the PRINTER_PARAMs struct relevant to the prncrru class are as follows: p.pdrflags Pp.pg.width P.pg. height Pp.pg.body.tl.x p.pg.body.tl.y p.pg. body. width P-pg. body. height P.pgnum.style p.pgnum.offset d.size_choice d.wo_control may contain WDR_PDR_LANDSCAPE to specify landscape page orientation. By default the page orientation is portrait. specifes the total page width in units of twips. specifies the total page height in units of twips. specifies the horizontal offset of the printing region from the left edge of the page in units of twips. specifies the vertical offset of the printing region from the top edge of the page in units of twips. specifies the width of the printing region - i.e. the page width minus the width of the left and right margins - in units of twips. specifies the height of the printing region - i.e. the page height minus the height of the top and bottom margins - in units of twips. specifies the index of an item in the sys_pGno_CHOICE system resource and the style used for page numbers. specifies the page number offset i.e. the value by which all page numbers are to be offset. specifies the the index of an item in the sys_paGE_s1zE system resource containing the name of the current page size e.g. A4. specifies whether widows and orphans are allowed and may be either TRUE or FALSE. Some of the above members are illustrated more clearly in the following picture: p.pg.height p.pg.width p.pg.body. height p.pg.body.width The outer square represents the page whilst the inner one represents the printing region i.e. the page minus the margins. The page layout settings are stored in the curent pRinTER object the handle of which must be stored in W_ws->wserv.printer. nr rr 16-18 16 PRINT CLASSES $e PO PRINT CLASSES | Class definition Defined in sub-category file prntdlgs.cl (generated header file prntdlgs.g). CLASS prnctrl dlgbox { REPLACE dl_dyn_init REPLACE dl_launch_sub REPLACE dl_ing minsize REPLACE dl_key TYPES { typedef struct { UWORD tmarg; UWORD lmarg; UWORD rmarg; UWORD bmarg; } TMARG; } PROPERTY { TMARG tm; } } Property prnctrl.tm a TMARG Struct used to temporarily store the page margins. The tmare struct is defined as follows: typedef struct { unsigned short int tmarg; unsigned short int Ilmarg; unsigned short int rmarg; unsigned short int bmarg; } TMARG; tmarg specifies the height in twips of the top margin. lmarg specifies the width in twips of the left margin. rmarg member specifies the width in twips of the right margin. bmarg specifies the height in twips of the bottom margin. Resources Defined in the system resource file sx_.ra. RESOURCE CONTROL sys_print_control_device { class=C_TEXTWIN; prompt="Printer device"; info=TXTMESS { str= Witt 7 flags=IN_TEXTWIN_POPOUT; }i } Defined in the system resource file s_.rss. 16-19 HWIM REFERENCE a RESOURCE DIALOG sys_print_control_dl { title="Print setup"; £lags=DLGBOX_NOTIFY_ENTER |DLGBOX_NOTIFY_ESCAPE; controls= { CONTROL { class=C_TEXTWIN; prompt="Page size "; info=TXTMESS { str=""; flags=IN_TEXTWIN_POPOUT; }; }, CONTROL { class=C_TEXTWIN; prompt="Margins "; info=TXTMESS { str= imi ; flags=IN_TEXTWIN_POPOUT; }; }, CONTROL { class=C_TEXTWIN; prompt="Header "; info=TXTMESS { str= mt ; flags=IN_TEXTWIN_POPOUT; }; }, CONTROL { class=C_TEXTWIN; prompt="Footer "; info=TXTMESS { str=" "Ww i: flags=IN_TEXTWIN_POPOUT; }; }, CONTROL { class=C_TEXTWIN; prompt="Paging control "; info=TXTMESS { str= uit : flags=IN_TEXTWIN_POPOUT; }; }, CONTROL { class=C_TEXTWIN; prompt="Printer model "; info=TXTMESS { str= nu 7 flags=IN_TEXTWIN_POPOUT; }; 16 - 20 16 PRINT CLASSES aa Oe ae) PRNCTRL methods DE_DYN_INIT | _ . Dynamic initialisation VOID di_dyn_init (VOID); Dynamically initialise the content of the dialog. Obtains a pointer to a PRINTER_PARAMS struct containing the current printer parameters by sending a PR_GET_PARAMS Message tO w_ws- >wserv.printer. Writes the page margins to prnctrl. tm. Sets the text in the Page size control according to the value stored in the d.size_choice member of the PRINTER_PARAMS struct. Sets the text in the Margins control according to the content of prnctr1.tm. Sets the header text in the Header control: the header text is obtained by sending a pR_GET_HD message to W_wS->wserv.printer. Sets the footer text in the Footer control: the footer text is obtained by sending a pR_GET_HD message to W_wsS- >wserv.printer. Sets the text in the Paging control control according to the values stored in the p. pgnum. offset, d.wo_control and p.pgnum. style members of the PRINTER_PARAMS struct. Opens the current wor file by sending pr_s=NSE_MODEL and PR_OPEN_WDR messages to the PRINTER object and then senses the name of the printer model by sending a woR_SENSE_MODEL_NAME message to the wor object. Sets the name of the printer model as the text in the Printer model control and then closes the current wor file by sending a pR_cLOSE_wpR message to the PRINTER object. The following actions are not performed on the Series 3. If w_ws->wserv. flags contains PR_WSERV_FULLSCREEN: e adds a horizontal line between the Paging control and Printer model controls. e appends a Printer device control as defined by the sys_PRINT_CONTROL_DEVICE system resource. e if the Printer device displays neither Parallel, nor Serial, nor File, locks the Printer device control using the hDlgItemLock utility routine. Enables content sensitive help by writing -sys_HELP_PRINT to dlgbox.helprid. lalog VOID di_launch_sub (INT index) ; Launch an appropriate sub-dialog. If index is one, launches a Page size dialog - for details see the description of the pacEs1z= class in the current chapter. If index is two, launches a Margins dialog - for details see the description of the marczns class in the current chapter. The dialog edits the content of prnctr1.tm. If index is three, launches a Header dialog - for details see the description of the HEADFoot class in the current chapter. If index is four, launches a Footer dialog - for details see the description of the yzaproor class in the current chapter. If index is five, launches a Paging control dialog - for details see the description of the pAGECTRL class in the current chapter. 16-21 HWIM REFERENCE ———eSeeSSSSSSSSSFSSSeSeSSsSSSSeeeeeeSSSFSSESSSSSS If index is six, launches a Printer model dialog - for details see the description of the prNmopeEt class in the current chapter. Sets the text in the Page size control according to the value stored in the d. size_choice member of the PRINTER_PARAMS struct. Sets the text in the Margins control according to the content of prnctr1.tm. Sets the text in the Header control: the header text is obtained by sending a PR_GET_HD message to w_ws- >wserv.printer. Sets the text in the Footer control: the footer text is obtained by sending a pR_GET_HD message to w_ws- >wserv.printer. Sets the text in the Paging control control according to the values stored in the p.pgnum. offset, d.wo_control and p.pgnum.style members of the PRINTER_PARaMs struct. Opens the current wor file by sending PR_sENSE_MODEL and PR_OPEN_WDR messages to the PRINTER object and then senses the name of the printer model by sending a woR_SENSE_MODEL_NAME message to the WOR object. Sets the name of the printer model as the text in the Printer model control and then closes the current wor file by sending a pR_CLOSE_wDR message to the PRINTER object. VOID dl_inq_minsize(INT *pOverallWidth, INT *pPromptWidth, INT *pControlWidth) ; Write the width of the control to the int pointed to by pcontrolwidth. If w_ws->wserv. flags contains PR_WSERV_FULLSCREEN, writes 160 to address pcontrolwidth. Otherwise writes 120 to address pcontrolwidth. The poverallwidth and ppromptWidth arguments are not used. _ Handle key input INT dl_key(INT index, INT keycode) ; Store the edited content of the dialog in the pRInTER object. Obtains a pointer to a PRINTER_PARAMS Struct containing the current printer parameters by sending a PR_GET_PARAMS Message tO w_ws->wserv.printer. Writes the offset of the printing region to the p.pg.body.ti member of the PRINTER_PARAMS struct. Writes the width of the printing region to the p.pg. body. width member of the PRINTER_PARAMS Struct. Writes the height of the printing region to the p.pg.body. height member of the PRINTER_PARAMS struct. Not on the Series 3: if the margins are too wide/high for the page: © — sets the width of the printing region equal to the width of the page: writes the p .pg. width member of the PRINTER_PARaMs Struct to the p.pg. body. width member. e _ sets the height of the printing region equal to the height of the page: writes the p.pg. height member of the PRINTER_PARAMS struct to the p.pg.body .height member. ¢ asks the user to confirm the resetting of the margins to zero by calling hconfirm with an argument of -SY¥S_INVALID_MARGINS. e if the user confirms the resetting of the margins: writes zero to each member of prnctri.tm. writes the page height to the p.pg.body.height member of the PRINTER_PARAMS Struct. writes the page width to the p.pg.body.width member of the PRINTER_PARAMS struct. 16 - 22 16 PRINT CLASSES sets appropriate text in the Margins control. e returns WN_KEY_NO_CHANGE. If either the width or the height of the printing region is less than 720 twips: e asks the user to confirm the resetting of the margins to zero by calling hconfirm with an argument of -syS_INVALID_MARGINS. writes zero to each member of prnctri.tm. writes the page height to the p.pg. body. height member of the PRINTER_PARAMS struct. writes the page width to the p.pg.body.width member of the PRINTER_PARAMS struct. sets appropriate text in the Margins control. e = returms WN_KEY_NO_CHANGE. Returns wN_KEY_CHANGED. Otherwise returns wN_KEY_CHANGED. PAGECTRL flags next item count id rbuf current dimrid underline helprid absorb changed Eesesey WEdaw destroy dl_item_replace wn_key dl_item_append wn_emphasise dl_init wn_sense_help dl_dimmed_message wn_set dl_item_add wn_sense dl_set_size wn_draw di_ing_minsize dl_item_lock di—dyn—init dl_item_dim di—-key dl_set_item_flags dal_set_prompt di_changed dl_take_focus dl_focus dl_handle_to_index di_launch_sub dl_index_to_handle di_item_new wn_calc_position |wnh-emphasise wn_position wn_redraw wn-sense—heip wn_visible The pacectrt class implements the Paging control dialog allowing the user to edit the current page control settings. An example Paging control dialog is shown in the following picture: Paging control ‘Number for firstpage 1 ‘Allow widows/orphans No ‘Page number style €1,2,3% The Series 3 and Series 3a Paging control dialogs are identical apart from the different border style. The members of the prinTER_PaRans struct relevant to the pRNcrRx class are as follows: 16 - 23 HWIM REFERENCE ee Sse p.pgnum.style specifies the style used for the page numbering. It also provides an index into the SYS_PGNO_CHOICE system resource. p.pgnum.offset specifies the page number offset i.e. the value by which all page numbers are to be offset. d.wo_control specifies whether widows and orphans are allowed and may be either rrvE or FALSE. The page control settings are stored in the current printer object the handle of which must be stored in W_wsS->wserv.printer. Class definition Defined in sub-category file prntdigs.cl (generated header file prntdlgs.g). CLASS pagectrl dalgbox { REPLACE dl_dyn_init REPLACE dl_key } Property There is no property associated with the pacEcTrt class. Resources Defined in the system resource file s_.rss. RESOURCE DIALOG sys_paging_ control_dl { title="Paging control"; £lags=DLGBOX_NOTIFY_ENTER|DLGBOX_RBUF_FILLED; controls= { CONTROL { class=C_NCEDIT; prompt="Number for first page"; info=NCEDIT { low=1; high=9999; }i } ' CONTRO: { class=C_CHLIST; prompt="Allow widows/orphans"; info=CHLIST(rid=sys_no_yes;}; CONTROL { class=C_CHLIST; prompt="Page number style"; info=CHLIST({rid=sys_pgno_choice;}; [aS SS eS a ee ee a ee Se PAGECTRL methods DL OYN INIT _ Dynamic initialisation VOID dl_dyn_init(vozp) ; Dynamically initialise the dialog using current values stored in the PRINTER object. 16 - 24 16 PRINT CLASSES Obtains the address of a PRINTER_PARAMS Struct containing the current printer parameters by sending a PR_GET_PARAMS message tO w_ws->wserv.printer Sets the content of the Number for first page control to the p.pgnum.offset member of the PRINTER_PARAMS Struct plus one. Sets the index of the item selected in the Allow widows/orphans control to the d.wo_contro1 member of the PRINTER_PARAMS struct. Sets the index of the item selected in the Page number style control to the p.pgnum. style member of the PRINTER_PARAMS struct. Returns wN_KEY_CHANGED. ey input INT dl_key (INT index, INT keycode) ; Store the edited content of the dialog in the printer object. Obtains the address of a pRINTER_PARAMs struct containing the current printer parameters by sending a PR_GET_PARAMS Iessage to w_ws- >wserv.printer. Senses the value in the Number for first page contro] and writes the result less one to the p. pgnum.offset member of the PRINTER_PARAMS struct. Senses the index of the item selected in the Allow widows/orphans control and writes the index to the d.wo_control member of the pRINTER_PARAMs struct. Senses the index of the item selected in the Page number style control and writes the index to the p.pgnum.style member of the PRINTER_PARAMs struct. MARGINS flags next item count id rbuf current dimrid underline helprid absorb changed destrey whedray destroy dl_item_replace wn_key dl_item_append wn_emphasise dil_init wn_sense_help dl_dimmed_message wn_set di_item_add wn_sense di_set_size wn_draw dl_ing minsize dl_item_lock 4i—dyn—tnit dl_item_dim di-key dl_set_item_flags dl_set_prompt dl_changed dl_take_focus dl_focus dl_handle_to_index di_launch_sub dl_index_to_handle dl_item_new wn_position wn_redraw wh—-sense—heip wn_visible The marcins clas implements the Margins dialog allowing the user to edit the current page margins. An example Margins dialog is shown in the following picture: 16-25 HWIM REFERENCE Margins (inches) 1.25 ‘Left 1.25 ‘Right 1.25 ‘Bottom 1.25 The margins in shown in the current printer units. The page margins are effectively stored in the current pRinTER object the handle of which must be stored in W_WS->wserv.printer. Class definition Defined in sub-category file prntdigs.cl (generated header file prntdlgs.g). CLASS margins digbox { REPLACE di_dyn_init REPLACE dl_key } Property There is no property associated with the marcins class. Resources Defined in the system resource file s_.rss. RESOURCE DIALOG sys_margins_dl { title="Margins"; £1ags=DLGBOX_NOTIFY_ENTER|DLGBOX_RBUF_FILLED|DLGBOX_APPEND_UNITS TITLE; controls= { CONTROL { class=C_FLTEDIT; prompt="Top"; info=FLTEDIT { low=0; high=9.99; ndec=2; }; }, CONTROL { class=C_FLTEDIT; prompt="Left"; info=FLTEDIT { low=0; high=9.99; ndec=2; }; te CONTROL { class=C_FLTEDIT; prompt="Right"; info=FLTEDIT { low=0; high=9.99; ndec=2; hs 16 - 26 16 PRINT CLASSES ——_—$——— SSS NE EO CONTROL { class=C_FLTEDIT; prompt="Bottom" ; info=FLTEDIT { low=0 3 high=9.99; ndec=2; ); arr a a a ee MARGINS methods Dynamic initialisation VOID dl_dyn_init (VOID); Dynamically initialise the content of the dialog. It is assumed that algbox.rbuf stores the address of a Tare struct defined as follows: typedef struct { unsigned short int tmarg; unsigned short int Ilmarg; unsigned short int rmarg; unsigned short int bmarg; } TMARG; The significance of the members of the mare struct is as follows: tmarg specifies the height in twips of the top margin. lmarg specifies the width in twips of the left margin. rmarg specifies the width in twips of the right margin. bmarg specifies the height in twips of the bottom margin. Converts the margins into the current printer units and then sets them as the content of the dialog controls. key input INT dl_key (INT index, INT keycode) ; Write the content of the dialog to the Tare struct pointed to by digbox. rbuf. Senses the margins in the dialog controls, converts them into units of twips and then writes the results to the Tmare struct pointed to by dlgbox. rbuf. Returns WN_KEY_CHANGED. 16-27 HWIM REFERENCE HEADFOOT flags id wn_calc_position |wn—emphasise wn_connect wn_dodraw IDLGCHAIN |DLGBOX next item count rbuft current underline helprid absorb changed dl_item_replace wn_key dl_item_append wn_emphasise qadl_init wn_sense_help di_dimmed_message wn_set dl_item_add wn_sense dl_set_size wn_position wn_draw di_ing_minsize wn_redraw idi_item_lock di—dyn—tnit Sense hetp al_item_dim di-key dl_set_item_flags dl_set_prompt dl_changed ase d@l_take_focus di_focus A—SenSe @1_handle_to_index di—launek—sub dl_index_to_handle dl_item_new The HEapFoor Class implements the Header details and Footer details dialogs allowing the user to edit the the header and the footer respectively. An example Header details dialog is shown in the following picture: Enter header details wserv.printer. 16 - 28 16 PRINT CLASSES —_— OS PRINT CLASSES Class definition Defined in sub-category file prntdigs.cl (generated header file prntdlgs.g). CLASS headfoot dlgbox { REPLACE dl_dyn_init REPLACE dl_key REPLACE dl_launch_sub PROPERTY { VOID *ph; points to PAGES_HEADER UWORD *offset; points to positional offset value } } Note: on the Series 3 the offset property is declared as a signed word i.e. worn. Property headfoot .ph a pointer to a PAGES_HEADER struct stored by the prrnTER object. The PAGES HEADER struct is defined as follows: typedef struct { SCRLAY_FONT f; unsigned char align; unsigned char first_page; } PAGES_HEADER; the £ member specifies the default font. the align member contains a value between zero and five inclusive specifying either left, right, centred, justified, two column or three column alignment respectively. the £irst_page member contains a value which specifies whether or not the header/footer is to appear on the first page. A non-zero value indicates that it is to appear on the first page. headfoot.offset a pointer to a worn stored by the prrnTER object. Specifies the vertical offset of the header/footer. Resources Defined in the system resource file s_.rss. RESOURCE STRING sys_header_str { str="Enter header details"; } RESOURCE STRING sys_footer_str { str="Enter footer details"; } RESOURCE DIALOG sys_headfoot_dl { titles"*",; £lags=DLGBOX_NOTIFY_ENTER |DLGBOX_RBUF_FILLED|DLGBOX_APPEND_UNITS TITLE; controls= { CONTROL { class=C_EDWIN; prompt="Text"; info=EDWIN { flags=IN_EDWIN_VULEN_CHARACTERS | IN_EDWIN_ACCEPT_TABS; maxlen=80; vulen=20; }; } ' CONTROL { class=C_CHLIST; prompt="Alignment"; info=CHLIST{rid=sys_headfoot_align;}; }, 16 - 29 HWIM REFERENCE SS SSS CONTROL { class=C_CHLIST; prompt="0n first page"; info=CHLIST{rid=sys_no_yes;}; }, CONTROL { class=C_TEXTWIN; prompt="Font "; info=TXTMESS { flags=IN_TEXTWIN POPOUT; a } ’ CONTROL { class=C_FLTEDIT; prompt="Vertical offset"; info=FLTEDIT { low=0; high=9.99; ndec=2; }; ESS ee ee ee ae er SE HEADFOOT methods DL_D VOID dl_dyn_init (VOID) ; Dynamic initialisation Dynamically initialise the content of the dialog. Note that for a header, digbox.rbuf should point to an integer value set to PRINTER_HDR_ToP, whilst for a footer, it should point to an integer value set to PRINTER_HDR_BOT. Obtains the address of a PRINTER_PARAMS struct containing the current printer parameters by sending a PR_GET_PARAMS message tO w_ws->wserv.printer. If the integer pointed to by digbox.rbuf is equal to pRINTER_HDR_TOP, writes the address of the p.top and P-pg-hdtop members of the PRINTER_PARAMS struct to headfoot .ph and headfoot .offset respectively and then sets the dialog title from the sys_HEADER_sTR system resource. Otherwise, writes the address of the p.bot and p.pg.hdbot members of the PRINTER_PARAMS struct to headfoot .ph and headfoot .offset respectively and then sets the dialog title from the sys_FooTEeR_sTR system resource. Sets the header/footer text in the Header/Footer control: the header/footer text is obtained by sending a PR_GET_HD message tO w_ws->wserv.printer. Sets the index of the selected item in the Alignment control to headfoot .ph->align. Sets the index of the selected item in the On first page control to headfoot .ph->first _page. Sets the text in the Font control according to the font details in headfoot .ph. £. Converts the value pointed to by headfoot .offset to the current printer units and sets this value in the Vertical offset control. 16 - 30 16 PRINT CLASSES DL_KEY INT dl_key(INT index, INT keycode) ; ie key input Store the edited content of the dialog in the prinrEr object. Senses the text in the Header/Footer control as appropriate, and then sets this as the header/footer by sending a PR_SET_HD message to w_ws->wserv. printer. Senses the index of the item selected in the Alignment control and then writes the result to head£oot . ph- >align. Senses the index of the item selected in the On first page control and then writes the result to headfoot .ph->first_page. Senses the value in the Vertical offset control, converts it from current printer units to twips and then writes the result to the address pointed to by headfoot .offset. Returns WN_KEY_CHANGED. dialog VOID dl_launch_sub(INT index) ; Allow the user to edit the current font by launching a Font selector dialog. Opens the current printer resource file by sending a pR_OPEN_wDR message tO w_ws->wserv. printer. Writes appropriate values to a FONTSEL_pata struct defined as follows: typedef struct { VOID *wdr; SCRLAY_FONT *pf; UWORD ret; } FONTSEL_DATA; The significance of the members of the ronrsEL_pata struct is as follows: wdr set to the handle of the current wor object opened by sending a pR_oPEN_wDR message to w_ws- >wserv.printer. pf the address of headfoot .ph->f i.e. a scRLAY_Fonr struct containing default font data. ret set to zero - the Font selector dialog sets this to a non-zero value if the font data has been edited Launches a Font selector dialog as described in the General dialogs chapter of the HWIM Reference manual with as the argument a pointer to the above ronTsEL_pata struct. Closes the current printer resource file by sending a pR_CLOSE_wDR message to w_ws->wserv.printer. Sets the text in the Font control according to the font specified by headfoot .ph->£. 16 - 31 HWIM REFERENCE PRNMODEL a next count current destroy di_item_replace wn_key dil_item_append wn_emphasise dl_init wn_sense_help dl_dimmed_message wn_set dl_item_add wn_sense di_set_size wn_draw dl_ing minsize dl_item_lock dl_item_dim dl_set_item_flags dl_set_prompt dl_take_focus wn_position wn_redraw wa—sense—heip wn_visible di_index_to_handle |dl_item_new The PRNMODEL Class implements the Set printer dialog allowing the user to select the desired printer and default font. An example Set printer dialog is shown in the following picture: Set printer Sane diiiad ¢ Canon BJ-16e> ‘Default font... Pica 12 The selected printer and the default font are both stored in the curent pRinTER object the handle of which must be stored in w_ws->wserv.printer. Class definition Defined in sub-category file prntdlgs.c/ (generated header file prntdlgs.g). CLASS prnmodel digbox { REPLACE dl_key REPLACE dl_launch_sub REPLACE dl_changed REPLACE dl_dyn_init TYPES { typedef struct { INT path; entry containing file path in pf INT index; index of printer model info in file } MLIST_ITEM; 16 - 32 16 PRINT CLASSES —_—— ——s— eeeeeeeSSSSSSOERINE GLASSES PROPERTY 3 { PR_VASTR *pm; handle of object used to store printer models PR_VASTR *pf; stores names of files where model data is stored PR_VAFLAT *pi; info for each printer model: where stored UWORD model; WORD nsel; index of current model in overall list SCRLAY_FONT sf; TEXT wdrfile [P_FNAMESIZE] ; } } Property prnmodel.pm the handle of an instance of the vastr class - this stores the names of the available printer models and provides the data for the Select printer control. prnmodel .pf the handle of an instance of the vastr class - this stores the names of the WDR files from which the printer models were obtained. prnmodel.pi the handle of an instance of the varuat class - this is used to store the index of each printer model in its parent WDR files. The n™ record stores a cross reference for the n"* printer model in the prnmodel .pm array. Each record is organised as an Murst_para struct defined as follows: typedef struct { INT path INT index } MLIST_ITEM; the path member specifies the index of the parent WDR file in the prnmodel . pf array. the index member specifies the index of the printer model within the WDR file. prnmodel .model specifies the model number of the current printer. prnmodel .nsel specifies the index of the current printer model in the prnmode1 .pm array. prnmodel.sf @ SCRLAY_FONT struct containing current default font data. prnmodel.wdrfile a buffer containing the name of the current printer resource file. Resources Defined in the system resource file s_.rss. RESOURCE DIALOG sys_printer_model { title="Set printer"; flags=DLGBOX_NOTIFY_ENTER | DLGBOX_RBUF_FILLED; controls= { CONTROL { prompt="Select printer"; flags=DLGBOX_ITEM_NOTIFY_CHANGED; class=C_CHLIST; info=CHLIST{}; ’ 16 - 33 HWIM REFERENCE TE CONTROL { class=C_TEXTWIN; prompt="Default font "; info=TXTMESS { flags=IN_TEXTWIN_POPOUT; Hy I a a ae TS) PRNMODEL methods VOID dl_dyn_init (VOID) ; Dynamically initialise the content of the dialog. Obtains the address of a PRINTER_PARAMs struct containing the current printer parameters by sending a PR_GET_PARAMS Message tO w_ws->wserv.printer. Obtains the current printer model number and the name of the associated WDR file by sending a PR_SENSE_MODEL message tO w_ws->wserv.printer and writes the results to prnmodel.model and prnmodel .wdrfile respectively. Writes the d.£ member of the pRInTER_PaRams struct to prnmodel sf. Sets suitable text, based on the content of prnmodel. sé, in the Default font control. Creates an instance of the vastr class and writes its handle to prnmode1 .pm. Initialises the vastR component by sending a va_INIT message to prnmodel .pm specifying a granularity of 20. Creates an instance of the vastr class and writes its handle to prnmodel . pf. Initialises the vastR component by sending a va_INIT message to prnmodel .p£ specifying a granularity of 32. Creates an instance of the varuat class and writes its handle to prnmodel .pi. Initialises the vaFLAT component by sending a va_INIT message to prnmodel .pi specifying records of length equal to the size of an MLIST_ITEM struct and a granularity of four. Creates an instance of the pmopiocs class and then sends an Ls_scan message to the pmopLocs object: this scans the rom device and the root and WDR directories of all devices on the Locs: : node for WDR printer resource files. This message adds records: * containing the names of the located WDR files: these records are appended to the variable array whose handle is stored in the prnmodel . pf property. ¢ containing the names of the printer models listed in the located WDR file: these records are added to the variable array whose handle is stored in the prnmode1 . pm property. Note that on the Series 3a the records are ordered alphabetically and that a duplicate printer model located on a flash pack will replace the rom version. ¢ containing a cross reference for each printer model in the WDR file: these records are appended to the variable array whose handle is stored in the prnmode1 .pi property. The n™ record stores a cross reference for the n"* printer model in the prnmodel . pm array. Each printer.pi record is organised as an MLIST_ITEM struct. The MLIsT_ITEM struct is defined as follows: typedef struct i path INT index } MLIST_ITEM; 16 - 34 16 PRINT CLASSES The significance of the members of the mu1st_1TeEm struct is as follows: path specifies the index of the parent WDR file in the prnmodel .p£ array. index specifies the index of the printer model within the parent WDR file. Sets the Select printer control to display the data in prnmodel . pm array with the current selection set to prnmodel .nsel. If w_ws->wserv. flags Contains PR_WSERV_OWN_DEFAULT_FonT then the method locks the Default font control - in consequence the text is visible but may not be edited by the user. ile key input INT dl_key (INT index, INT keycode) ; Store the edited content of the dialog in the printer object. Obtains the address of a PRINTER_PARaMs struct containing the current printer parameters by sending a PR_GET_PARAMS message tO w_ws->wserv.printer. Senses the index of the item selected in the Select printer control and then copies the name of the corresponding printer resource file to prnmodel . wdrfile. Writes the current printer model number to prnmode1 .modei and then sets this as the current printer model by sending a PR_SET_MODEL message to w_ws->wserv.printer. Stores the default font in the prinTER object by writing prnmodel.sf to the a. £ member of the PRINTER_PARAMS struct. sub-dialog VOID dl_launch_sub(INT index) ; Allow the user to modify the default font characteristics by launching a Font selector dialog. Senses the index of the item selected in the Select printer control and then obtains a pointer to the corresponding mLIsT_TTem item in the prnmodel .pi array. Copies the name of the printer resource file associated with the selected printer model to prnmodel .wdrfile. Writes the index member of the mursT_1rTem struct to prnmodel .model. Creates an instance of the wor class and then sends a wor_rnrT message specifying prnmodel .wdrfile and prnmodel .model. as the name of the current wor file and the current printer model number respectively. Allows the user to modify the default font characteristics stored in prnmode1.sf by launching a Font selector dialog: for further details of the Font selector dialog see the description of the rowtsEt class in the General dialogs chapter of the HWIM Reference manual. Sets appropriate text in the Default font control. VOID dl_changed(INT changed) ; m changed messages Update the content of the dialog according to the content of the Select printer control. Senses the index of the item selected in the Select printer control and then obtains a pointer to the corresponding MLISsT_ITEM item in the prnmodel . pi array. Writes the name of the selected printer resource file to prnmodel . wdrfile and then writes the index member of the MLIST_ITEM struct to prnmodel.model. Sets appropriate text for the Default font control. 16-35 HWIM REFERENCE ay fawrw—_fpccua IN |DLGBOX a aoe next item count rbuf current dimrid underline helprid absorb changed destroy dl_item_replace wn_key dl_item_append wn_emphasise dl_init wn_sense_help dl_dimmed_message wn_set dl_item_add wn_sense dl_set_size wn_draw di_inq_minsize dl_item_lock di—dyn—taie dl_item_dim di—key dl_set_item flags dal_set_prompt di—-ehanged dl_take_ focus dl_focus dl_handle_to_index di_launch_sub dl_index_to_handle dl_item_new wn_position wn_redraw wnrsense—heip wn_visible The paces1zz class implements the Page size dialog allowing the user to specify the desired page size and orientation. An example of a Page size dialog is shown in the following picture: Page size Cinches} +Ad> Width 8.27 Height 11.69 ‘Orientation Portrait The page size and orientation are stored in the current PRINTER object the handle of which must be stored in W_wS->wserv.printer. Class definition Defined in sub-category file prntdigs.cl (generated header file prntdlgs.g). CLASS pagesize dlgbox REPLACE dl_dyn_init REPLACE dl_changed REPLACE dl_key } Resources Defined in the system resource file s_.rss. The following is defined in hwim.rh: STRUCT PAGE SIZE { WORD width; WORD length; } The following is defined in s_.rss: 16 - 36 16 PRINT CLASSES eee OEE ELAS SED RESOURCE PAGE_SIZE_ARRAY sys_page_dimensions { page_size= { PAGE_SIZE {width=PAGE_WIDTH_A4; length=PAGE_LENGTH_A4;}, PAGE_SIZE {width=PAGE_WIDTH_A4; length=PAGE_LENGTH_A4;}, PAGE_SIZE {width=PAGE_WIDTH_EXECUTIVE; length=PAGE_LENGTH EXECUTIVE; }, PAGE_SIZE {width=PAGE_WIDTH_LEGAL; length=PAGE_LENGTH_LEGAL; }, PAGE_SIZE {width=PAGE_WIDTH_ LETTER; length=PAGE_LENGTH_LETTER;}, PAGE_SIZE {width=PAGE_WIDTH_MONARCH; length=PAGE_LENGTH MONARCH; }, PAGE_SIZE {width=PAGE_WIDTH_DL; length=PAGE_LENGTH_DL; } }; } RESOURCE DIALOG sys_pagesize_dl { title="Page size"; £1ags=DLGBOX_NOTIFY_ENTER | DLGBOX_RBUF_FILLED|DLGBOX_APPEND_UNITS TITLE; controls= { CONTROL { class=C_CHLIST; £lags=DLGBOX_ITEM_NOTIFY_CHANGED; prompt="Page size"; infosCHLIST{rid=sys page_size;}; }, CONTROL { class=C_FLTEDIT; prompt="Width"; info=FLTEDIT { low=1; high=45; ndec=2; }; } ' CONTRO: { class=C_FLTEDIT; prompt="Height"; info=FLTEDIT { low=1; high=45; ndec=2; 1s }, CONTROL { class=C_CHLIST; prompt="Orientation"; info=CHLIST{rid=sys_orient;}; } eS ee ee ee er LT PAGESIZE methods Dynamic initialisation VOID dl_dyn_init (VOID) ; Dynamically initialise the content of the dialog. Obtains a pointer to a PRINTER_PARAMS Struct containing the current printer parameters by sending a PR_GET_PARAMS message tO w_ws->wserv.printer. 16 - 37 HWIM REFERENCE ee SeeeSSSSSSSSSSSSSSSSSSee Sets the index of the item selected in the Page size control to the d. size.choice member of the PRINTER_PARAMS struct. Not on the Series 3: if w_ws->wserv. flags contains PR_WSERV_METRIC, sets the upper and lower bounds for the Width and Height controls to one hundred units and two units respectively. If the d. size. choice member of the pRINTER_PARAMs struct is set to the value 1 (corresponding to the second item - the string "Custom" - in the sys_pacE_s1zE system resource) specifying the custom page size: ¢ converts the p.pg.width member of the PRINTER_PaRams struct from twips to the current printer units, and then sets this as the value in the Width control. e converts the p.pg.height member of the pRINTER_PaRaws struct from twips to the current printer units, and then sets this as the value in the Height control. Otherwise sets the content of the Width and Height controls as described for the DL_CHANGED message. If the p.pdr£1ags member of the PRINTER_PARAMS struct contains wOR_PDR_LANDSCAPE, sets the index of the item selected in the Orientation control to one. Otherwise sets the index of the selected item in the Orientation contro] to zero. DE KEYS INT dl_key(INT index,INT keycode) ; Handle key input Store the selections in the dialog in the printer object. Obtains a pointer to a PRINTER_PARAMs struct containing the current printer parameters by sending a PR_GET_PARAMS Message tO w_ws->wserv.printer. Senses the index of the item selected in the Page size control and then writes the index to the d.size_choice member of the pRInTER_PARAms struct. Senses the width in the Width contro], converts the value to the current printer units - i.e. cm or inches - and then writes the value to the p.pg.width member of the PRINTER_PARAMS Struct. Senses the height in the Height control, converts the value to the current printer units - i.e. cm or inches - and then writes the value to the p.pg.height member of the PRINTER_PARAMS struct. Senses the index of the item selected in the Orientation control and then writes the index to the p -pdrflags member of the PRINTER_PARams struct. Returns wN_KEY_CHANGED. VOID dl_changed (INT changed) ; Set the content of the Width and Height controls according to the item selected in the Page size control. The s¥S_PAGE_DIMENSIONs system resource contains a list of PAcE_s1zE structs. The method loads the PAGE_S1ZE Struct having the same index as the item selected in the Page size control. The PAGE_szzz struct is defined as follows: STRUCT PAGE_SIZE { WORD width; WORD length; } The significance of the members of the above struct is as follows: width specifies the width of the page in units of twips. length specifies the height of the page in units of twips. 16-38 16 PRINT CLASSES Converts the width member of the above struct into the current printer units and then sets the result into the Width control. Converts the height member of the above struct into the current printer units and then sets the result into the Height control. PRINTING flags next id destroy wn_draw count rbuf current dimrid underline helprid absorb flags changed destroy dl_item_replace dl_dyn_init wn_cale_ position |wn_emphasise wn_key di_item_append di_set_size wn_emphasise dl_init Printing set_title wn connect wn_dodraw wn_sense_help d1_dimmed_message Printing do_print wn_emphasise wn_set dl_item_add iorinting done wn_key wn_sense dl_set_size wn_position wn_draw dl_ing_minsize @l_item_lock dl_dyn_init di_item_dim di_key dl_set_item_flags dal_set_prompt dl_changed dl_take_focus dl_focus dl_handle_to_index dl_launch_sub di_index_to_handle dl_item_new The PRINTING Class supports the Printing dialog allowing the starting, monitoring and cancelling of printing. An example Printing dialog is shown in the following picture: Printing to Plis (page 2) Abandon {_ The handle of the current prinTER object must be stored in w_ws->wserv.printer. The digbox.rbuf property must point to an RBUF_PRINTING struct which is defined as follows: typedef struct { PAGES CALLS calls; VOID **ppages; } RBUF_PRINTING; 16 - 39 HWIM REFERENCE eee The significance of the members of the above struct is as follows: calls a PAGES_CALLS struct which specifies the call backs required by the pacgs object. The Paces_cauus struct is defined as follows: typedef struct { VOID *hread; WORD mread; VOID *hdone; WORD mdone; } the hread member specifies the handle of the object that is to receive read call-back messages from the paczs active object. the mread member specifies the read call-back message that is to be sent by the paczs active object when it requires the next line of text. the hdone member specifies the handle of the object which is to receive completion call-back messages from the pacss active object. the mdone member specifies the completion call-back message that is to be sent by the pacEs active object when it has completed either the current page or the entire document. ppages either nu or a pointer to the handle of the pacss active object. (The hread and mread members of the above paGES_caLLs struct must be set by the owning application.) Class definition Defined in sub-category file printing.cl (generated header file printing g). CLASS printing dlgbox { REPLACE dl_dyn_init REPLACE dl_set_size ADD printing_set_title ADD printing do print ADD printing_done CONSTANTS { PR_WIN_WILL SKIP 0x4000 Re-use this bit } TYPES { typedef struct { PAGES_CALLS calls; VOID **ppages; } RBUF_PRINTING; } PROPERTY 1 { VOID *pages; pages active object } Property printing.pages the handle of an instance of the paces active object class - this handles the printing operation. A description of the paces class may be found in the Document Printing Classes chapter of the FORM Reference manual. 16 - 40 16 PRINT CLASSES $$$ Se OEIINT CLASSES Resources Defined in the system resource file s_.rss. RESOURCE DIALOG sys_ printing dialog { flags=DLGBOX_RBUF_FILLED; controls= { CONTROL { class=C_TEXTWIN; £lags=DLGBOX_ITEM_CENTRE|DLGBOX_ITEM_DEAD|DLGBOX_ITEM UNDERLINED; info=TXTMESS { flags=IN_TEXTWIN_AL CENTRE; }i } ' CONTROL { class=C_TEXTWIN; £lags=DLGBOX_ITEM_CENTRE|DLGBOX_ITEM_DEAD; info=TXTMESS { flags=IN_TEXTWIN_AL CENTRE; }; } e CONTROL { class=C_ACLIST; info=ACLIST { rid=sys_ac_abandon; }; SS ee ee ee Oe een a a a ey PRINTING methods VOID dl_dyn_init (VOID) ; Dynamically initialise the content of the dialog and start the printing. Note: dlgbox.rbuf must point to an appropriately initialised raur_PRINTING struct. Sets the text in the Page number control - the text is created from the format string in the sys_PaGE_1s system resource and an argument of 9999. Sets the dialog title by sending self a PRINTING_SET_TITLE message. Specifies the completion call-back method by writing o_pRINTING_DONE to dlgbox.rbuf->calls.mdone. Specifies the completion call-back handle by writing se1£ to dlgbox. rbuf->calls.hdone. Starts the printing by sending self a PRINTING_DO_PRINT message with as argument the address of dlgbox.rbuf->calls. Writes the handle of the current pacgs active object to printing.pages. If digbox. rbuf->ppages is non-zero, writes printing.pages to the address pointed to by digbox.rbuf- >ppages. 16-41 HWIM REFERENCE DLLSET SE Set size of dialog VOID dl_set_size (VOID) ; Set the size of the dialog and the content of the Page number control. Supersends a DL_SET_s1zE message. Sets the text in the Page number control: ¢ ifwin.flags contains PR_WIN_WILL_sKIP and the printer.p -p.pgbeg member of w_ws- >wserv.printer is greater than one, the text is created from the SYS_SKIPPING_PAGE system resource with an argument of one. e otherwise the text is created from the sys_pacE_zs system resource with an argument of one. The sys_SKIPPING_PAGE and sys_PaGE_Is system resources are defined as follows: RESOURCE STRING sys_skipping_ page { str="(skipping page tu)"; RESOURCE STRING sys_printing_to { str="Printing to ts"; } “Setttitie VOID printing_set_title (VOID) ; Set the title and the content of the control with index one. Obtains the name of the printer device - i.e. Serial, Parallel or a filename - by sending a WS_SENSE_PDEV_TEXT message to w_ws. Sets the text in the dialog title - the title is created from the SYS_PRINTING_TO system resource and the name of the printer device. If the printer.p.p.pgbeg member of w_ws->wserv.printer is not equal to one: * — indicates that the first page(s) is (are) to be skipped by setting PR_WIN_WILL_SKIP in win. flags. e _ sets the text in the Page number control - the text is created from the SYS_SKIPPING_PAGE system resource and an argument of 9999. PRINTING_DO_PRINT VOID *printing_do_print (PAGES CALLS *pcalls) ; Start the printing operation. Starts the printing operation by sending a pR_PRINT message to w_ws->printer with an argument of pcalls. Returns the handle of the pacgs active object which is handling the printing. INT printing_done (PAGES_DONE *d) ; Handle page and document completion. If the event member of the paces_pone struct pointed to by a is PAGES _DONE_PAGE - indicating that printing of the current page is complete - sets the text in the Page number control and then retums FALSE: ¢ ifwin. flags contains pR_WIN_WILL_sxrp and the page number of the first page to be printed i.e. w_ws->.printer->printer.p.p.pgbeg is greater than the current page number i.e. d- >page, the text is created from the sys_sKIPPING_PAGE system resource and the current page number. a SSeeeeeeeSSeSSSSSFSSFSFSSeEEeeeee 16 - 42 16 PRINT CLASSES eS PRINT CLASSES ¢ — otherwise the text is created from the sys_pacE_1s system resource and the current page number in d->page. If the event member of the paczs_pone struct pointed to by d is PAGES_DoNE_poc - in which case the printing of the document is complete - indicates that no further copies of the document are to be printed by retuming FALSE. If the event member is none of the above - in which case either the printing is complete or an error has occurred while printing - writes NULL to printing.pages, destroys the PRINTING object by sending selfa destroy message and then returns FaLseE. For a more detailed explanation of the completion call-back method see the description of the pagedoc_mdone method in the Formatted Document Content Classes chapter of the FORM Reference manual. (This method is called by the paczs active object when it finishes printing the current page/document.) PMODLOCS PMODLOCS dl flags peb pname match info name wildname is_matchname 1ls_scan 1ls_filename ds—Sleseme The pmoptocs class is provided for use by the prnmopeL class (or a subclass thereof) described in the current chapter. The class may be used to scan the desired devices and directories for WDR printer resource files and extract the names of the printer models supported. The scan adds records: * containing the names of the located WDR files. These records are added to the variable array whose handle is stored in the prnmode1 .pf property of the owning class. e containing the names of the printer models listed in the located WDR files. These records are added to the variable array whose handle is stored in the prnmodel. pm property of the owning class. ¢ containing for each printer model the index of the record storing the name of the printer model and the index of the printer model in the parent WDR file. These records are added to the variable array whose handle is stored in the prnmodel .pi property of the owning class. Class diagram / los > _/ pmodlocs + 16 - 43 HWIM REFERENCE eo SSSSSSSSSSSSMSSSSSSSSS Class definition Defined in sub-category file pmodlocs.cl (generated header file pmodlocs.g). CLASS pmodlocs locs REPLACE ls filename PROPERTY { PR_PRNMODEL *dl; Owning dialog } } Property pmodlocs.dl the handle of the object which uses the pmopLocs component. PMODLOCS methods LS FILENAME = = |. Process matching filename INT ls_filename (TEXT *buf) ; Process a matching filename. This method is called when a matching file has been located: the matching file is assumed to be a WDR printer resource file the name of which is specified as a zero terminated string by buf. The method adds records: * containing the name of the located WDR file. This record is appended to the variable array whose handle is stored in the prnmode1 .pf property of the owning class. ® containing the names of the printer models listed in the located WDR file. These records are added to the variable array whose handle is stored in the prnmode1 . pm property of the owning class. Note that on the Series 3a the records are ordered alphabetically and a duplicate printer model located on a flash pack will replace the rom version. e containing a cross reference for each printer model in the WDR file. These records are appended to the variable array whose handle is stored in the prnmode1 .pi property of the owning class. The n® record stores a cross reference for the n* printer model in the prnmodel . pm array. Each record is organised as an MLIST_ITEM struct. The mutstT_ITEM struct is defined as follows: typedef struct INT path INT index } MLIST_ITEM; The significance of the members of the murst_rrem struct is as follows: path specifies the index of the parent WDR file in the prnmode1 . pé array. index specifies the index of the printer model within the parent WDR file. Returns FALSE. 16-44 CHAPTER 17 DIALLING DIALOGS This chapter documents classes associated with tone dialling. These classes are: e the HarpuE class which provides an idle active object especially suited for use with tone dialling. e the prazao class which supports tone dialling and which is used as a component by the praLpLG class. e the praupic class which provides a common base for the rpraLpLc and spraxpuc classes. e the rreEprat class which provides a dialog control that allows free-form tone dialling. e the rpraxotc class which provides a dialog that supports free-form tone dialling. e — the cwrrypxe class which provides a dialog that allows the user to select a country from the list supported by the World database. e the spranpuc class which provides a dialog that allows editing and tone dialling one or more dialling string. Precursors Familiarity with the following topics will aid the understanding of this chapter: e the AIDLE active object class described in the OLIB Reference manual. e the picox class described in the Dialog Boxes chapter of the HWIM Reference manual. HAIDLE q priority isactive peb stat destroy ao_init ao_init ao_run ao_cancel ao_abrun ao_queue ao_run The HAIDLE class provides an idle active object, and is used by for example, the prazao class described later in this chapter. The Hazpzé class allows the idle active object to be cancelled at any time by pressing the Escape key. The following illustrates the use of the yazpze class: 17-1 HWIM REFERENCE es ESSE /* compute intensive loop starts here */ WORD stat; haidle=f_newsend(CAT_DEMO_HWIM,C_HAIDLE,O_AO_INIT); for (i=0;i1<=1000;i++) { psend (haidle,AO_ QUEUE, &stat) ; The ao_QuEUE message returns once all active objects in the queue have run thus ensuring that the compute intensive loop does not monopolise the processor. An example of the use of the HarpzE class is tone dialling thus ensuring that the tone dialling does not interfere with other tasks and may be cancelled at any moment. Class diagram active) / aidle ~} “ haidle Class definition Defined in sub-category file hactive.c/ (generated header file hactive.g). CLASS haidle aidle { REPLACE ao_queue ADD hai_key PROPERTY { VOID *rbuf; } } Property haidel.rbuf used to store the status word for the idle active object. Ee ee ee ee ee ee ee eer HAIDLE methods idle object INT ao_queue (VOID *xbuf) ; Allow queued active objects to run by starting an idle object. Writes rbuf to haidle.rbuf. If the unsigned word pointed to by rbuf contains zero, signals the process i/o semaphore - i.e. call p_iosignal. Writes TRUE to active.isactive. Directs all future keypresses to its own key method by writing self to w_ws->wserv. filter and writing O_HAI_KEY tO w_ws->wserv.filmethod. Ensures that queued active objects have an opportunity to run by sending an am_sTaRT message to w_am- this message send only returns once all queued active objects have run. Writes the original key filter and filter method to w_ws->wserv. filter and w_ws->wserv.filmethod respectively. The Series 3a version returns active.stat. The Series 3 version does not return a value. ——eeSSSeSeeSeSSSSSSSSeSSSSSSSSSESESE 17-2 17 DIALLING DIALOGS INT hai_key (INT keycode, INT modifiers) ; Handle a keypress that may potentially terminate the Harpzz idle active object. If keycode is W_KEY_ESCAPE, cancels the idle object as follows: ¢ indicates that the request was cancelled by writing E_FILE_ CANCEL to haidle.rbuf. e — ensures that the last am_starT message send returns by sending an am_sTop message to w_am. e indicates that the Harpe active object is not active by writing FALSE to active .isactive. Returns wN_KEY_CHANGED. DIALAO priority isactive pcb stat destroy ao_init ae-init ao_run ao_cancel ao_abrun The pzaxao class may be used to make an asynchronous request to generate a sequence of dialling tones. The class allows the user to cancel the dialling at any time after the request has been made by pressing the Escape key. Note that the class directs all keypresses to its own hai_key method. For a description of the sound device see the 1/O Devices Reference manual. Class diagram / ative / aidle “> / haidle~; / dialao Class definition Defined in sub-category file hactive.c/ (generated header file hactive.g). CLASS dialao haidle Active object supervising dialling { REPLACE ao_queue REPLACE hai_key } Property None. 17-3 HWIM REFERENCE i ee eee SS ee DIALAO methods ig object INT dialao_ao_queue (VOID *pcb,TEXT *str,E DIAL *c); Queue a request to write a tone sequence to the sound channel. Makes an asynchronous request to the sound channel to play the required tone sequence using active.stat as the status word. The handle of the sound channel should be stored in peb - note that an invalid handle will panic the calling process. The tone sequence should be stored as a zero terminated string specified by str. The timing for the tone dialling is specified by the E_prax struct pointed to by c. The £_pzaz struct is defined as follows: typedef struct { UBYTE toneLengthTicks; UBYTE delayLengthTicks; UWORD pauseLengthTicks; } E_DIAL; The members of the &_prau struct have the following significance: toneLengthTicks the length of a dial tone in units of 1/32 seconds. delayLengthTicks _ the time between dial tones in units of 1/32 seconds. pauseLengthTicks _ the length of the pause corresponding to the comma and space characters in units of 1/32 seconds. Further details of the tone dialling may be found in the Sound chapter of the /O Devices Reference manual. Supersends an ao_QUEUE message with an argument of pcb. The Series 3a version returns the value returned by the ao_QuEUE message. The Series 3 version does not return a value. INT dialao_hai_key(INT keycode, INT modifiers) ; Handle a keypress that may potentially cancel the prazao idle active object. If keycode is W_KEY_ESCAPE: e cancels any outstanding write request on the sound channel the handle of which is assumed to be in haidle.rbuf. e waits for the cancel request to complete by calling p waitstat with the address of active.stat as the argument. * ensures that the last am_sTarT message send retums by sending an am_sTop message to w_am. e indicates that the pranao active object is not active by writing FALSE to active.isactive. Returns wN_KEY_CHANGED. 17-4 17 DIALLING DIALOGS DIALDLG flags next id destrey wh-draw DLGBOX item count xvbuf current dimrid underline helprid absorb changed destroy dl_item_replace wn_key dl_item_append wn_emphasise di_init wn_sense_help dl_dimmed_message wn_set dl_item_add wn_sense di—set—size dl_set_size wn_position wn_draw dl_ing_minsize wn_redraw dl_item_lock al_dyn_init wh—sense—heip dl_item_dim dl_key wn_visible dl_set_item flags dl_set_prompt dl_changed dl_take_focus dl_focus dl_handle_to_index d1_launch_sub dl_index_to_handle dl_item_new The prazpue class provides a common base class for the rpraLpic and sptaxpie classes. It provides the basic functionality required by a dialog that supports tone dialling. Class diagram oes ans. ony - ons, atts / in > (4 bwin} / digchain’ |/ digbox; / dialdig > Class definition Defined in sub-category file dialdlgs.cl (generated header file dialdlgs.g). CLASS dialdlg dlgbox Add active object to appman { REPLACE dl_set_size PROPERTY 1 { VOID *dialao; } } Property dialdig.dialao handle of an instance of the pranao class - this is used to play a tone sequence. 17-5 HWIM REFERENCE Ez eT EE eS ee] DIALDLG methods DL_SET SIZE = Create a dial active object VOID d@l_set_size (VOID) ; Initialise the help resource and create and initialise a dial active object. Supersends a pL_SET_SIZE message. Writes -syS_HELP_DIALLING to dlgbox.helprid. Creates an instance of praLao and writes the handle to dialdlg.dialao. Initialises the pranao component by sending an ao_INIT message tO dialdlg.dialao. FREEDIAL FREEDIAL current str landlord offset width destroy wn_calc_positio wn_init n wn_visible wn_draw wn_connect lg_draw wn_key wn_dodraw lg_self_check ig_sense_width wn_emphasise lg_set_id_pos orakey wn_position wn_redraw lig_update wn_sense_help The FREEForM class provides a dialog control that supports free-form tone dialling - thus the corresponding tone is generated when a key is pressed. An example of a FREEFORM control used as a dialog component is shown in the following picture: Free-form dialling where the FREEFoRM control is the second item in the dialog. Class diagram Hao Fre se (rm ee ‘ os f Hy ‘ * , 4 = F, i ‘ / | ry / freedial > 4 é ta ia f . 17-6 17 DIALLING DIALOGS ——__———<$S—_. eS IALLING DIALOGS Class definition Defined in sub-category file dialdlgs.cl (generated header file dialdlgs.g). CLASS freedial lodger { REPLACE destroy REPLACE wn_init REPLACE wn_draw REPLACE wn_key REPLACE lg _sense_width PROPERTY { WORD current; /* index of current cursor */ TEXT str (WR_MAX_DIAL STRING+2] ; /* +2 for ZTS. Max of 24 char */ } } Property freedial.current the length of the number to tone dial. freedial.str the number to tone dial - stored as a zero terminated string. See the Sound chapter of the /O Device Reference manual for details of the allowed characters. ats Se a SS a a ay FREEDIAL methods _ Destroy VOID destroy (VOID) ; Destroy the FREEDIAL instance. Ensures that the key click is re-enabled by calling woisablekeyClick with an argument of FALSE. Clears PR_WSERV_FREEFORM_DIALLING in w_ws->wserv. flags and supersends a DESTROY message. dialling VOID wn_init (UBYTE *init,PR_WIN *landlord) ; Initialise the FREEDIAL instance. Writes an underscore character - '_' - to the first wR_MAX_DIAL_STRING elements of freedial.str. Writes zero to freedial. current. Writes landlord tO lodger. landlord. Sets PR_WSERV_FREEFORM_DIALLING in w_ws->wserv. flags. Disables the key click by calling woisablekeyclick with an argument of TRUE. “Draw dial string VOID wn_draw (VOID) ; Draw the dial string. Draws the dial string stored in the first wR_MAX_DIAL_sTRING elements of freedial.str. The width of the control is taken from the width of the lodger window. The offset of the control is taken from the offset of the lodger window. The text is drawn in a monospace font with left alignment. 17-7 HWIM REFERENCE WN_KEY ~ oS : _ Add input and dial INT wn_key (INT keycode, INT modifiers) ; Add keycode to the dial string and play the corresponding tone. If keycode is greater than or equal to 0x100, returns wn_KEY_NO_CHANGE. If keycode is neither a comma, an asterisk, a hash - i.e. #, nora digit: e converts the character to uppercase. e if keycode is not in the range 'A' to 'F' inclusive, calls hrnfoprint with an argument of -SYS_INVALID_CHAR and returns WN_KEY_NO_CHANGE. If freedial.current is equal to wR_MAX_DIAL_STRING, resets the dial string by writing an underscore character to the first wR_MAX_DIAL_STRING elements of freedial.str and writing zero to freedial.current. Writes keycode to freedial.str[freedial. current), increments freedial .current and then draws the control by sending self an LG_DRAW message. Clears &_SOUND_DISABLE and sets E_SOUND_DEVIcE in the current sound flags: see the description of the p_getsnd and p_setsnd routines in the PLIB reference manual for details. Attempts to open a channel to the sound device (snp: ) and on success writes the handle of the sound channel to peb. On failure restores the sound flags to their original state, calls hinfoprint with an argument of -sys_sounD_Fart and then calls p_leave with an argument of RUN_ACTIVE_CLEANUP_NONOTIFY. Makes an asynchronous request to the sound channel to play the tone specified by keycode using the timing paramters stored in the psx environment variable - these are the system wide timing parameters and are stored in the form of an E_pzat struct. Details of the z_pzax struct may be found in the Sound chapter of the I/O Devices Reference manual. Closes the sound channel and restores the sound flags to their original state. Returns wN_KEY_CHANGED. LG INT lg_sense_width (VOID) ; se lodger width Sense the width in pixels of the lodger window. Returns WR_MAX_DIAL_STRING multiplied by the maximum width of a character in the system font. 17-8 17 DIALLING DIALOGS FDIALDLG flags item count dialao id rbuf current dimrid underline helprid absorb flags changed destrey wn-draw destroy dl_item_replace dl_set_size| ||dl_key wn_calc_position |wn—emphasise wn_key dl_item_append wn_emphasise dl_init wn_sense_help dl_dimmed_message wn_set dl_item_add wn_sense di—set—size wn_position wn_draw di_ing minsize di_item_lock dl_dyn_init dl_item_dim di_key dl_set_item_flags wn_redraw wh-sense—heip wn_visible al_set_prompt dl_changed dl_take_focus dl_focus dl_handle_to_index dl_launch_sub dl_index_to_handle dl_item_new The FDIALDLc class provides a dialog that supports free-form tone dialling. An example of a rp1atptc is shown in the following picture: Free-form dialling Redial Cea = where the second item in the dialog is a FREEFoRM control as described in the previous section. Class diagram .. eee orn a ao Sricioes gern Mente Pain bs . > . ee’ por ’ see eee / win “7 bwin; / dlgchain —_’ digbox™; = / dialdig™-_” fdialdig™> t—. +, — \ Ris 1 ion oe eres / dialao ~> Class definition Defined in sub-category file dialdlgs.cl (generated header file dialdlgs.g). CLASS fdialdlg dialdlg dialog for freeform dial { REPLACE di_key } Property None. 17-9 HWIM REFERENCE aS eee Resources Defined in system resource file s_rss. RESOURCE ACLIST_ARRAY sys_freedial_aclist { button = { PUSH_BUT { keycode=W_KEY_DELETE_LEFT; str="Clear"; } ' PUSH_B { keycode=W_KEY_ TAB; str="Redial"; } }; }RESOURCE DIALOG sys_freedial_dialog { title="Free-form dialling"; flags = DLGBOX_NO_WAIT|DLGBOX_NO_DDP; controls= { CONTROL { class=C_FREEDIAL; prompt=; } ’ CONTROL { class=C_ACLIST; info=ACLIST { vid=sys_freedial_aclist; }; a ee ae a ee eee FDIALDLG methods INT dl_key(INT id, INT keycode) ; Handle a keypress. If keycode is W_KEY_DELETE LEFT: ¢ if freedial current is equal to wR_MAX_DIAL_STRING, resets the dialling string by writing an underscore character to the first wR_MAX_DIAL_sTRING elements of freedial.str and writing zero to freedial.current. ¢ draws the reset dial string by sending an L¢_uppaTE message to the FREEDIAL item with index one. e returns WN_KEY_NO_ CHANGE. If keycode is mot W_KEY_TAB, retumms WN_KEY_NO CHANGE. Clears £_souND_DISABLE and sets E_SOUND_DEVICE in the current sound flags: see the description of the p_getsnd and p_setsnd routines in the PLIB reference manual for details. Attempts to open a channel to the sound device and on success writes the handle of the sound channel to peb. On failure restores the sound flags to their original state, calls hinfoprint with an argument of -SY¥S_SOUND_FAIL and calls p_leave with an argument of RUN_ACTIVE_CLEANUP_NONOTIFY. eee 17-10 17 DIALLING DIALOGS The dialling string is stored in dlgbox.item(1] .hand->freedial.str whilst its langth is stored in dlgbox.item(1) .hand->freedial.current. If the length of the dialling string is one or zero, makes an asynchronous request to the sound channel to play the dialling sequence. Otherwise plays the dialling sequence, whilst ensuring that the user may at any time cancel the playing, as follows: e disables exit and task switch messages by entersending a ws_LocK message to w_ws. ® sends an AO_QUEVE message to dialdlg.dialao. e removes the extra level of locking by sending ws_Lock message to w_ws. In either case the timing parameters are read from the psx environment variable - this contains the system timing parameters stored in the form of an £_prax struct. Closes the snp: channel and restores the sound flags to their original state. Calls £_leave: the argument is either zero or the return value from the ws_Locx entersend. Returns WN_KEY_NO_CHANGE. CNTRYDLG flags next item count id rbuf current dimrid underline helprid absorb changed destroy wa-draw destroy dl_item_replace wn_key dl_item_append wn_emphasise dl_init wn_sense_help dl_dimmed_message wn_set dl_item_add wn_sense dl_set_size CNTRYDLG dl_key wn_calc_ position |wnh-emphasise wn_position wn_draw dl_ing_minsize wn_redraw dl_item_lock dal_dyn_init wh—-sense—heip dl_item_dim di-key wn_visible dl_set_item_flags dl_set_prompt dl_changed dl_take_focus dl_focus dl_handle_to_index dl_launch_sub di_index_to_ handle dl_item_new The cyrryb.c class allows the user to select a country from the extensive list stored in the World database. An example country selector dialog is shown in the following picture: Append country ¢ Izbekistan> Append PaaS The second item in the dialog is a wwpsELwn control which supports selection using the arrow keys or via incremental matching. Further details of the wLpseLwn class may be found in the Incremental Matchers chapter of the HWIM Reference manual. 17-11 HWIM REFERENCE TT n— ees Class diagram Class definition Defined in sub-category file dialdlgs.cl (generated header file dialdlgs.g). CLASS cntrydlg digbox REPLACE dl_key } Property None. Resources RESOURCE ACLIST_ARRAY sys_append_aclist { button = { PUSH_BUT { keycode=W_KEY RETURN; str="Append"; } }; } RESOURCE DIALOG sys_country_selector_dialog { title="Append country"; flags=DLGBOX_NOTIFY_ENTER|DLGBOX_ACTION_LIST|DLGBOX_RBUF_FILLED; controls= { CONTROL { class=C_WLDSELWN; prompt="Country"; info=WLDSELWN {flags=IN_WLDSELWN_COUNTRY | IN_WLDSELWN_SETHOME; }; }, CONTROL { class=C_ACLIST; info=ACLIST { rid=sys_append_aclist; }; i a Se en a CNTRYDLG methods _ Handle key INT dl_key(INT id, INT key); Senses the name of the country selected in the w.psELwn control with index one. Senses the wLDSELwn dialog control with index one and writes the name of the selected country to digbox.rbuf - the name is enclosed in square brackets with a leading space asfollows " [Germany]". Returns WN_KEY_CHANGED. — eee 17-12 17 DIALLING DIALOGS SDIALDLG flags next item count id rbuf current dimrid underline helprid absorb flags changed destroy watdraw DIALDLG dialao destroy dl_item_replace dl_set_size wn_key dl_item_append wn_emphasise dl_init wn_sense_help al_dimmed_message wn_set di—item—add wn_sense di—set—size wn_draw dl_ing_ minsize dl_item_lock 4i—dyn—init dl_item_dim di—tey dl_set_item_flags wn_position wn_redraw wn-sense—heip wn_visible d@l_set_prompt dl_changed di_take_focus dl_focus dl_handle_to_index dl_launch_sub dl_index_to_handle dl_item_new The spra.pic class supports tone dialling, editing of dial strings, and free-form tone dialling. An example SDIALDLG dialog is shown in the following picture: Dial 4815218521 ‘'R 6712196189 Cancel Free input Dial Dial out SS Ge Ges Ee) Note that pressing the menu key launches an rpraupic dialog as described in an earlier section of this chapter. On the Series 3a and the Workabout the Dial dialog may contain up to six dial items - i.e. phone numbers - whilst on the Series 3 it may contain up to four dial items. Class diagram ant, ea ane / no} “ bwin 3 |/digchain> “ digbox + / dialdig > _” sdialdig > S) 3K, i. ~—. eee Mee i ‘ eed 1 es ‘ ert! 4 Lorne ¢ i es teem meee! 7 ‘i = / dialao ~s Bantonk [renee - [or ee Class definition Defined in the sub-category file dialdigs.cl (generated header file dialdlgs.g). CLASS sdialdlg dialdlg { REPLACE dl_item_add REPLACE dl_dyn_init REPLACE dl_key 17 - 13 HWIM REFERENCE ESS CONSTANTS { PAN_TONE_LENGTH_TICKS 4 PAN_DELAY _LENGTH_TICKS 4 PAN_PAUSE_LENGTH_TICKS 32 PC_TONE_LENGTH_TICKS 6 PC_DELAY_LENGTH TICKS 4 PC_PAUSE_LENGTH_TICKS 18 SMART_DIAL_MAX_PROMPT 11 /* max prompt length */ } TYPES { typedef struct { TEXT pmt [SMART_DIAL_MAX PROMPT+1] ; TEXT str {WR_MAX_IN_STRING+2] ; } SMART DIAL ITEM; typedef struct { WORD count; how many separate numbers SMART_DIAL_ ITEM it [DLGBOX_MAX_ITEM-3] ; } SMART_DIAL_DATA; typedef struct { WORD count; equals 1 SMART_DIAL ITEM it; } SMART_DIAL_DATA_S; uses less stack than SMART_DIAL DATA typedef struct { UWORD toneLengthTicks; UWORD delayLengthTicks; UWORD pauseLengthTicks; UBYTE dialoOutCode [6] ; to access an external line } DIAL_ENVAR; } Note: on the Series 3 some of the constants are assigned slightly different values. The Series 3 versions are as follows: PAN_TONE_LENGTH_TICKS 8 PAN_DELAY_LENGTH TICKS 8 PAN_PAUSE_LENGTH TICKS 48 Property None. Resources Defined in the system resource file s_rss. RESOURCE CONTROL sys_smart_dial_item { class=C_EDWIN; prompt=; info=EDWIN { maxlen=WR_MAX_DIAL_ STRING; vulen=20; flags=IN_EDWIN_VULEN_CHARACTERS | IN_EDWIN_NO_AUTOSELECT; }; 17-14 17 DIALLING DIALOGS RESOURCE ACLIST_ ARRAY sys_smart_dial_aclist { button = { PUSH_BUT { keycode=W_KEY_ESCAPE; str="Cancel"; }, PUSH_BUT { keycode=W_KEY_ MENU; str="Free input"; } ' PUSH_BUT { keycode=W_KEY_ TAB; str="Dial"; } # PUSH_BUT { keycode=W_KEY_RETURN; str="Dial out"; } }i } RESOURCE DIALOG sys_smart_dial_dialog { flags=DLGBOX_NOTIFY_ENTER | DLGBOX_ACTION_LIST|DLGBOX_RBUF_ FILLED; controls= { CONTROL { class=C_TEXTWIN; flags=DLGBOX_ITEM_CENTRE | DLGBOX_ITEM_DEAD |DLGBOX_ITEM_UNDERLINED; info=TXTMESS; { flags=IN_TEXTWIN_AL CENTRE; str="Dial"; }; } ’ CONTROL { class=C_ACLIST; info=ACLIST { rid=sys_smart_dial_aclist; }; SDIALDLG methods DL_ITEM_ADD _ Add one or m INT dl_item_add(AD_DLGBOX *par); 0 the dialog Add one or more items to the dialog. If dlgbox.count is non-zero, adds an item to the dialog by sending seif a pL_ITEM_ADD message with an argument of par - this item must specify an appropriate action list. Returns. If dlgbox .rbuf->count is greater than six on the Series 3a or four on the Series 3, then set it equal to either six or four respectively. 17-15 HWIM REFERENCE If dlgbox. rbuf->count is less than than six on the Series 3a or four on the Series3, adds the first item which must specify a title to the dialog by sending se1f a pL_ITEM_ADD message with an argument of par. Adds digbox.rbuf->count EDWIN controls by sending digbox. rbuf->count DL_ITEM_APPEND messages to self with an argument of -sys_SMART DIAL ITEM. VOID dl_dyn_init (VOID); Initialise the content of the dialog controls. Note that the digbox.xbuf property must point to either a sMaRT_DIAL_ pata struct, or a SMART_DIAL_DATA_s struct followed by zero or more sMART_DIAL_rTeEM structs, containing the initialisation data. The sMART_DIAL_pata struct is defined as follows: typedef struct ee count; SMART_DIAL_ITEM it [DLGBOX_MAX_ITEM-3]; } SMART_DIAL DATA; The significance of the members of the smart_pzaL_pata struct is as follows: count the number of smart dial items in the dialog. it an array of sMART_DIAL_1ITEM structs which stores the data required by the smart dial items. The sMART_DIAL_ITEM struct is defined as follows: typedef struct { char pmt [SMART _DIAL MAX _PROMPT+1] ; char str {WR_MAX_IN_STRING+2] ; } SMART_DIAL ITEM; The significance of the members of the smarT_pIAL_1TeEM struct is as follows: pmt the prompt text for the smart dial item - stored as a zero terminated string. str the dialling string stored as a zero terminated string. The dialling string may contain, the digits 0 to 9, upper or lower case alphabetic characters in the range A to F, the characters # (0x23) and * (0x2A) which are converted to F and E respectively and space and comma characters which are interpreted as pauses while dialling. A space followed by the name of a country enclosed in square brackets e.g. [Germany] may be appended to the dialling string - e.g. 41 35 25 84 [France] - in place of the country code. Opens a channel to the World database and for each smarT_p1AL_rvTem item in the sMaRT_praL pata struct: ¢ converts the str member into a dialling string using the World database wR_GET_DIAL_STRING service. e if the conversion succeeds, sets the dialling string into an epwrn control - the order of the SMART_DIAL_ITEm structs matches the order of the EDwrn controls. e if conversion fails, sets the text in the sys_INVALID_NuM resource into the corresponding EDWIN control and ensures that pLGBox_ITEM_DEAD is set in the control flags. SS ”FF”—e———“ “ROU INT dl_key(INT id, INT keycode) ; Handle a keypress. If one of the dialog control holds keyboard focus - i.e. dlgbox. focus is non-zero: e obtains a dialling string by sensing the content of the epwzn control with index id. 17 - 16 17 DIALLING DIALOGS Otherwise if keycode is either W_KEY_RETURN OF W_KEY_TAB: calls hInfoPrint with an argument of -sys_INVALID_Num and returns WN_KEY_NO_CHANGE. If keycode is W_KEY_MENU, Creates, initialises and makes visible the free-form dialling dialog by sending a WS_FREE_DIAL message to w_ws and then returns wN_KEY_NO_CHANGE. If keycode is either w_KEY_RETURN OF W_KEY_Tas, tone dials the dialling string as follows: if keycode is W_KEY_RETURN, prepends the content of the sys_pIAL_our system resource to the dialling string - this defines the dial-out code. clears —_SOUND_DISABLE and sets E_SOUND_DEVIcE in the current sound flags: see the description of the p_getsnd and p_setsnd routines in the PLIB reference manual for details. attempts to open a channel to the sound device and on success writes the handle of the sound channel to pcb. On failure restores the sound flags to their original state, calls htnfoprint with an argument of -sys_sounD_FAIL and calls p leave with an argument of RUN_ACTIVE_CLEANUP_NONOTIFY. if the length of the dialling string is one or zero, makes an asynchronous request to the sound channel to play the dialling sequence. otherwise, disables exit and task switch messages by entersending a ws_LocK message to w_ws, plays the tone sequence for the dialling string by sending an ao_QuEvE message to dialdig.dialao and removes the extra level of locking by sending a ws_Lock message to w_ws. in either case the timing parameters are read from the psx environment variable - this contains the system timing parameters stored in the form of an £_prat struct. closes the swp: channel and restores the sound flags to their original state. calls £ leave: the argument is either zero or the return value from the ws_Locx entersend. If keycode is W_KEY_ESCAPE: returns WN_KEY_CHANGED. 17-17 CHAPTER 18 HELP CLASSES This chapter describes the HELPLIsT and HELPDLG classes that support the built-in help mechanism: note that these classes are described for interest only since the help mechanism is managed by the system. It is thus unlikely that an application would directly use either class. The first level of help list may be obtained by simply pressing the Help key and usually contains just a title and a list of help topics as illustrated in the following picture: Help: first example A second level of help list may be obtained from the first level by selecting a topic (with the exception of the index topic) and pressing the Return key. The second level of help list usually includes a title and one or more lines of text as illustrated in the following picture: Help: Mainframes >This help screen displays information about the mainframes topic. It may also include a list of topics thus allowing the user to progress to a third level. An index help list is a special form of help list and may be obtained by selecting the index topic and pressing Return. It contains a title and a list of system and application help topics. The topics are sorted alphabetically as illustrated in the following example: Help: Index »Mainframes *Menu/dialog tips =Micros «No system memory «On/off =Printing/print preview l=sjcreen display The content of the help lists is defined by the help resources in the application's resource file. The ID of the first such resource must be written to the wserv.help_index_id property of the wserv object. This may be conveniently done in the di_dyn_init method of the wserv object as follows: wserv.help_index_id=FIRST_EXAMPLE_HELP; An application can also provide context sensitive help by simply re-setting the wserv.help_index_id property as and when required. 18-1 HWIM REFERENCE Sv SSS The structure of the help resources is perhaps best illustrated by an example. The resources described in the following paragraphs (with one exception) were used to create the help lists shown above. The content of each help list is specified by means of a HELP_ARRay resource. The following example is for the first help list illustrated earlier and specifies the title with the topic member, and the list of topics with the topic_id member: RESOURCE HELP_ARRAY first_example_help { topic="first example"; /* title text */ topic_id=example_index; /* id of topic array */ } A later example also includes some lines of text that appear between the title and the topic list: the lines of text are specified with the str1st member as follows: RESOURCE HELP_ARRAY second_example_help { topic="second example"; /* title text */ topic_id=example_index; /* id of topic array */ strist= { STRING {"One or more lines of text may";}, STRING {"preceed the bulleted items.";} i } The topic_id member always contains the ID of a roprc_array resource: the TOPIC_aRRay that was used for the first example shown earlier is as follows: RESOURCE TOPIC_ARRAY example_index { id_ist= { example_main_frames, /* ids for help screens */ example minis, example_micros } } The resource simply contains a list of HELP_ARRay IDs each of which defines a futher topic help list: the HELP_ARRAY resources for the example Topzc_ARRAY resource shown above are as follows: RESOURCE HELP_ARRAY example _main_frames { topic="Mainframes"; strlst= { STRING (str="This help screen displays information"; }, STRING {str="about the mainframes topic.";} } } RESOURCE HELP_ARRAY example_minis topic="Minis"; strlst= { STRING {str="This help screen displays information";}, STRING {str="about the minis topic.";} } 18-2 18 HELP CLASSES a SSSSSSSSSSSeSSeSSsSSeSeeeeeeee EER ASSES RESOURCE HELP ARRAY example micros topic="Micros"; topic_id=example_micros_index; strist= { STRING {str="This help screen displays information"; }, STRING {str="about the micros topic.";} } } Usually the help mechanism is used with only two levels of help list. However there is nothing preventing the inclusion of further levels if desired: this is illustrated by the help list defined by the above example_micros HELP_ARRAY resource which includes a list of topics specified by the example_micros_index TOPIC_ARRAY as follows: RESOURCE TOPIC_ARRAY example_micros_index { id_ist= { example_micros_386, example_micros_486 } } The topics in this list are in turn defined by the following three HELP_ARRAY resources: RESOURCE HELP_ARRAY example_micros_386 { topic="386 micros"; strlst= { STRING {str="Some text describing the";}, STRING {str="386 processor goes here."; } } } RESOURCE HELP_ARRAY example_micros_486 { topic="486 micros"; strlst= { STRING {str="Some text describing the";}, STRING {str="486 processor goes here."; } } } Precursors Familiarity with the following topics will aid the understanding of this chapter: e the wserv object described in the The WSERV Class chapter. e the wrn and swrn classes described in the Windows chapter. e the LrsTsox class described in the List Boxes and Menus chapter. e the variart and vastr classes described in the OLIB Reference manual. e the vmarcuer class described in the Incremental Matchers chapter. 18-3 HWIM REFERENCE HELPLIST wn_calec_position wn_connect wn_dodraw wn_position wn_redraw wn_sense_help wn_visible wn_set wn_sense HELPLIST list ids firsttop title match va flags width matchien curofft offset current top first last vastart matchstart destroy wn_init ind wn_key ib_draw_item lb_draw_emphasis 1ib_inquire_item 1b_item_width wn_draw wn_emphasise 1b_size_window lb_item_width lb_take_focus 1b_inquire_focus 13 ives 1lb_inquire_last The HELPLIsT class may be used to create a help list containing a title, zero or more lines of text and a list of zero or more topics. An example help list is shown in the following picture: Help: Second example >One or more lines of text may preceed the bulleted items. «Mainframes The help list always has a title - in this case "Help: Second example”. The title always starts with "Help:". The help list may include zero or more lines of unbulleted text: these simply provide useful information as illustrated by the second and third lines in the above example. The help list may also include a list of one or more bulleted topics as illustrated by lines four to eight inclusive in the above example. The user may obtain further information in the form of a help list on a specific topic simply by pressing the Enter key. 18-4 18 HELP CLASSES EE Class diagram = | 4 vaflat > ons, 4 Weep oot, ‘ t (ona Loney 4 aes i { eer ¥ ~ \ e rs vmatche rT : af YO ete ee ’ ri 1 Bd ‘ See a 1 " a4 / helplist ~> Class definition Defined in sub-category file help.cl (generated header file help.g). CLASS helplist listbox Help topic and topic text list { REPLACE wn_init REPLACE wn_key REPLACE lb _draw_item REPLACE lb draw_emphasis REPLACE 1b inquire_item REPLACE lb item width TYPES { typedef struct { UWORD topic_id; TEXT topic(1]; 2TS string followed by UBYTE count of ids } HELP_RSC; } PROPERTY 2 { PR_VASTR *list; Text for list PR_VAFLAT *ids; Resource ids for list UWORD firsttop; Index of first related topic TEXT title [50]; } 18-5 HWIM REFERENCE oa eeSeSSSSSSSSSSSSSSSSShFeeeeee Property helplist.list this stores the handle of an instance of the vastr class. The records contains the lines of text that follow the help list title. There is one record per line of text. helplist.ids this stores the handle of an instance of the vartat class. The records contain the IDs of HELP_ARRAY resources associated with the topics. When the user selects a topic and presses the return key, a help list appears. The associated HELP_ARRAY resource defines the content of the topic help list. helplist.firsttop this is an index into the helplist .1ist array of the record corresponding to the first topic. helplist.title this is the help list title text and is stored as a zero terminated string. SS SS SE Se ES ae ee HELPLIST methods VOID wn_init(INT start_id); Initialise the help list specified by the HELP_aRRay resource with ID start_id. The content and appearance of a help list is specified by means of a HELP_arRRay resource defined in hwim.rh as follows: RESOURCE HELP_ARRAY { LINK topic_id=0; /* TOPIC_ARRAY id */ TEXT topic; /* title text +*/ LEN BYTE STRUCT strist[]; /* list of STRINGs */ } The significance of the members of the HELP_array resource is as follows: topic_id this member specifies the ID of a roprc_array resource: this resource contains a list of HELP_ARRAY resource IDs each of which defines a topic in the topic list. This member may be set to sys_HELP_1nDEx_pata for an index help list: i.e a help list containing application and system help topics ordered alphabetically which may be selected using incremental matching. This member may be ignored. topic this member specifies the title text e.g. "Word basics". strist this member is an array of sTRING resources: these define the lines of informative text that appear immediately beneath the title. This member may be ignored. The Toprc_array resource is defined in hwim.rh as follows: RESOURCE TOPIC ARRAY ‘5 BYTE LINK id_lst[]; } The significance of the members of the roprc_array resource is as follows: id_ist this member is an array containing one or more HELP_aRRay resource IDs: each HELP_ARRAY resource defines the content and appearance of a topic help list. Creates the title from the sys_HELP_sTRiNG format string resource and the text specified by the topic member of the start_id resource. Creates an instance of the vastr class and writes its handle to helplist.1list. linitialises the vasTR component by sending a va_1nrIT message to helplist .list specifying a granularity of 16. eee 18 -6 18 HELP CLASSES Creates an instance of the varzat class and writes its handle to filelist.ids. Initialises the varLat instance by sending a va_in1T message to helplist .ids specifying a record length of two anda granularity of sixteen. If the topic_id member of the start_id resource is equal to sys_HELP_INDEX_DATA: e creates an instance of the vmarcuer class and writes its handle to 1istbox.match. Initialises the VMATCHER component by sending an IM_INIT message with suitable arguments. e loads the topics specified by the sys_HELP_INDEX_DATA system resource and then adds records to the helplist.list and helplist.ids arrays e — loads the topics in the application topic list: the wserv.help_index_id property of the wsERV object is assumed to specify the application help resource ID. Otherwise creates an unsorted help list: e loads the str1Nc resources specified by the start_id resource and adds the text to the helplist.list alray. e — loads the topics specified by the topic_ia member of the start_id resource and then adds records to the helplist.list and helplist.ids arrays. e ifwserv. flags does not contain pR_WSERV_BASIC_HELP, add the topics specified by the SYS_HELP_X_HELP system resource. This includes only the About Help topic. e ifwserv.flags does not contain pR_WSERV_HELP_INDEX, add the topics specified by the SYS_HELP_X_INDEX system resource. This includes only the Index topic. Writes unity to listbox. current and listbox. first. Writes an appropriate value to helplist. first. Writes the index of the last item in the help list help1ist .1ast. The index of the last item is obtained by sending a vA_CouNnT message to helplist.list. Sends an LB_SIzE_WINDow message to self with an argument of zero. _ Handle keys VOID wn_key(INT keycode, INT modifiers) ; Handle a keypress. If keycode is W_KEY_RETURN and listbox.current is greater than or equal to helplist.. firsttop, launches a help list for the selected topic by sending a ws_po_HELP message to the wsErv object. Otherwise supersends a wN_KEY message with arguments of keycode and modifiers. LB_INQUIRE_IT TEXT *lb inquire_item(INT index) ; Get item text Return a pointer to the text for the item at line index. If index is zero, return the address of the first character in the helplist .title property. Otherwise, return the address of the appropriate record in the helplist. list array. Get width of item INT lb_item_width(INT index) ; Return the width of the help list item at line index. The item width includes the left margin and the width of the text, obtained by sending self a LB_INQUIRE_ITEM message. 18-7 HWIM REFERENCE LE VOID 1b_draw_item(TEXT *text,INT index, P RECT *area) ; Format and draw an item Draw the item with index index in the box specified by area with text specified by text. If index is zero, the text is drawn in a bold font, with centre alignment, and a left margin of width LISTBOX_OBLOID_INDENT. If index is greater than or equal to helplist . firsttop, the text is drawn in a bold font, with left aligment and a left margin. A bullet character is inserted before the text. Otherwise, the text is drawn in a system font, with left aligment and a left margin. for remove emphasis on item VOID lb_draw_emphasis(INT index,P_RECT *area,INT flag); Emphasise or de-emphasise the item with index index. If index is greater than or equal to helplist..£irsttop, the bullet character and the text are drawn in white on a black background. In this case area.t1 should specify the top left corner of the item box. If index is less than helplist .f£irsttop and flag is rrue, emphasise the item by drawing a right arrow in the left gutter. Otherwise de-emphasise the item by clearing the right arrow from the left gutter. In either case area should specify the rectangle that encloses the item including the left margin. HELPDLG HELPDLG inal destroy wn_init wn_key wn_emphasise wn_visible wn_calc_position wn_connect wn_dodraw whremphasise wrrkey wn_position wn_redraw wh-sense—heip visible wn_set wn_sense wrhrdrayw en The description of this class is included for completeness and interest only. 18-8 18 HELP CLASSES SSS HELP CLASSES Class diagram fe WI aa { ~ } ar | , eee 2 “bwin > é c ie ft ~~ 1 . ; \ oa ” digchain °} / helplist > 7 ‘ 7 f te H M H har } RSs 1 H ne ; ace we) Boh pen See / helpdig > t Class definition Defined in sub-category file help.cl (generated header file help.g). CLASS helpdlg dlgchain Help '‘dialog' REPLACE destroy REPLACE wn_init REPLACE wn_key REPLACE wn_emphasise REPLACE wn_visible PROPERTY 1 { PR_HELPLIST *listbox; } } Property helpdlg.listbox the handle of an instance of the nELPLisrt class. ae Ne FR SR a SE eS See eT HELPDLG methods dialog VOID destroy (VOID) ; Destroy the HELPDLc instance. If win. flags contains HELPDLG_BASIC_HELP, Clears PR_WSERV_BASIC_HELP from the wserv. flags property of the wserv object. These flags indicate that the highest level of help is the basic help dialog. Otherwise, if win. £1ags contains HELPDLG_HELP_INDEX, Clears PR_WSERV_HELP_INDEX from the wserv.flags property of the wseRv object. These flags indicate that the highest level of help is the help index dialog. If win. flags Contains PR_WIN_INITIALISED, removes the highest level of help dialog by sending a WS_REMOVE_DIAL message to the wsERV object with se1f as argument, and decrements the wserv .help property of the wserv object. Supersends a DesTRoy message. 18-9 HWIM REFERENCE WNSENET 7 oe Initialise help dialog VOID wn_init (INT start_id); Initialise the help dialog whose contents are specified by start_id. If start_id is SYs_HELP_ON_HELP, sets PR_WSERV_BASIC_HELP in the wserv. flags property of the wSERV object, and sets HELPDLG_BASIC_HELP in win. flags. Otherwise, if start_id is sys_HELP_ON_INDEX, sets PR_WSERV_HELP_INDEx in the wserv. flags property of the wseRv object, and sets HELPDLG_HELP_INDEX in win. flags. Sets PR_WIN_NO_DDP in win. flags, creates an instance of HELPLIST and writes its handle to helpdlg. listbox. Initialises the HELPLIST component by sending a wn_InIT message to helpdlg. listbox with an argument of start_id. e keys INT wn_key (INT keycode, INT modifiers) ; Handle a keypress. If keycode is W_KEY_ESCAPE, and modifiers contains the Control modifier, destroys all levels of help dialog by repeatedly sending a pEstRoy message to the wserv.dial property of the wserv object until its wserv.help property is zero. (See the description of the wsERv property for further details). If keycode is W_KEY_ESCAPE, and modifiers does not contain the Control modifier, destroys the highest level of help dialog by sending a pestroy message to the wsERV object wserv.dial property. If keycode is W_KEY_HELP, and modifiers does not contain the Control modifier, adds a help screen for the Help topic by sending a ws_po_p1aL message to the wseRv object with an argument of sys_HELP_ON_HELP. The method does nothing if the help screen is already present. If keycode is W_KEY_HELP, and modifiers contains the Control modifier, adds an index help list by sending a WS_DO_DIAL message to the wsERv object with an argument of sys_HELP_1nDEX. The method does nothing if the index help list is already the highest level. Otherwise, if keycode is none of the above, passes the keypress to the HELPLIST component by sending a WN_KEY message to helpdlg. listbox, passing arguments of keycode and modifiers. Returns wN_KEY_NO_CHANGE. VOID wn_emphasise(UINT flag); Emphasise the help dialog if flag is Truz, otherwise de-emphasise the help dialog. Sends a wN_EMPHASISE message with an argument of flag to helpdig. listbox. VOID wn_visible(UINT flag); Make the help dialog visible if ag is true, otherwise make it invisible. The method simply sends a wn_v1sIBLE message to helpdlg.1istbox with flag as the argument. 18-10 CHAPTER 19 OPL AND COMMs SCRIPT SUPPORT This chapter describes the following classes: e the procrran class which may be used either to translate or to locate an error in a source module. e the procexec class which may be used to run a translated source module. e the procrinp class which may be used to locate either of the OPL or Comms script translator modules. In all cases the source module may contain either OPL code or Comms script commands. Precursors Familiarity with the following topics will aid the understanding of this chapter: e the acrive class described in the OLJB Reference manual. e the sERveR class described in the OLIB Reference manual. PROGTRAN sv_run pt_start Pt_getline pt_complete The pRocTRAN class may be used to translate either an OPL or a Comms script source module. The class supports both translation of the source file and the location of errors, if they exist. Class diagram [Tt wee? ¢ /SENEr } _? Progtran Z ————s nes \ ~~ ‘ . 19-] HWIM REFERENCE eee SSE Class definition Defined in sub-category file program.cl (generated header file program.g). CLASS progtran server { REPLACE sv_init Supersend with parameters REPLACE sv_run Process message ADD pt_start Start translation of a module DEFER pt_getline Get line of source DEFER pt_complete Report completion CONSTANTS { ! Message types PT_PROGTRAN_LINE 0x10 Get a line of source PT_PROGTRAN_DEATH 0x11 OPL translator death } TYPES { typedef struct { WORD stat; Completion status UWORD mode; Translation mode UWORD line; Line number UWORD offset; Offset to syntax error } PROGTRAN_STATUS; ! Describes the source typedef struct { UWORD pid; Process id of source TEXT *buffer offset; Offset of buffer in source process PROGTRAN_STATUS *status_offset; Offset of status block in source process } PROGTRAN_SOURCE; } PROPERTY { PROGTRAN_STATUS st; TEXT buf [256]; line buffer } } Property progtran.st the translator process writes to this property: the significance of the members of the PROGTRAN_STATUs struct is as follows: stat the completion status code: on success this is zero and on failure it is the corresponding error number. mode the translation mode, which may be one of: FULL_TRANSLATE for translation of the source module. ERROR_LOCATIon to locate an error in an already translated source module, CHECK_TRANSLATION to check the source module without translating it. line the line number of the line of source that contains the error: this member is written to by the translator process on location of an error. offset the offset into the line of the error: this member is written to by the translator process on location of an error. progtran.buf the full file specification of the OPL module or Comms script file that is to be translated. 19-2 19 OPL AND COMMS SCRIPT SUPPORT Ee ee ee ee eee PROGTRAN methods SVINT : _ Initialise VOID sv_init (VOID) ; Initialise the message server. Sets PT_PROGTRAN_LINE and PT_PROGTRAN_DEATH as the allowed message types by supersending an SV_INIT message. SV BUN = = _ Process message VOID sv_run(MESS *pmsg) ; Process a message. If pmsg->type is PT_PROGTRAN_DEATH, frees the message slot with a reply of zero by calling p_mfree. Writes zero to server.cid and then sends self a PT_COMPLETE message. Returns. If pmsg->type is PT_PROGTRAN_LINE, gets the next line of source by sending self a PT_GETLINE message with pmsg->1ine as argument. Then frees the message slot by calling p_mfree. The reply sent via this call is the return value from the pt_GETLINE message. of a module INT pt_start (INT type,TEXT *pname,PROGTRAN STATUS *pstatus) ; Start translation of the source module specified by pname. The type argument should be set to either 'O' or 'C' to translate OPL or Comms script source modules respectively. The pstatus argument should point to a progtran.status Struct. Copies the source file specification pointed to by pname into progtran. buf and then obtains the full file specification for the translator program by creating an instance of the procrinn class and sending an LS_SCAN message with type as the first argument. Copies the contents of the procTRAN_STATUs struct pointed to by pstatus into progtran.st. Sets the translator program running in a suspended state by calling p_execc with appropriate command line arguments. Writes the id of the translator process to server .cid and ensures that on abnormal termination of the translator process a PT_PROGTRAN_DEATH message is sent by calling p_logon. Sets the process running by calling p presume. Returns FALSE. Deferred PROGTRAN methods Get line of source INT pt_getline(UWORD line); Copy the line of the source file with index 1ine to the buffer with address progtran buf: the line argument is in the range zero to 32K. The replacement method should return either the number of bytes copied or = _FILE_Eor if there are no more lines of source. 19-3 HWIM REFERENCE PT_COM: VOID pt_complete (VOID) ; “Report completion This method is called by the sv_run method on abnormal termination of the translator process. If the translator process is being used to locate an error in the source module, then the line and offset elements of progtran.st give the location of the error. PROGEXEC result priority stat isactive destroy ao_init ao_init ao_cancel ao_cancel ao_abrun ao_queue ao_run The procexec class may be used to run either a translated OPL module or a translated Comms script module. Class diagram / active ~} // Progexec > Class definition Defined in sub-category file program.cl (generated header file program.g). CLASS progexec active Runs a process of sys$prg?.img, handling inter process communication Completes when sysS$prg? terminates { REPLACE ao_init Initialise and queue REPLACE ao_cancel so that destroy is clean CONSTANTS { s PROGEXEC_SIGNAL 0x01 signal on completion PROGEXEC_NOTIFY 0x02 call notifier on error H_COMMAND_TRANSLATE FILE 'T' H_COMMAND_RUN_FILE 'R! } 19-4 19 OPL AND COMMS SCRIPT SUPPORT ee ANE CUMIMIS SCRIPT SUPPORT TYPES { ! Used to receive data from sys$prg?.img, on completion typedef struct { WORD error; runtime error UWORD line; line no of start of proc containing runtime error UWORD offset; Q code offset to runtime error TEXT err [40]; runtime error string TEXT src[P_FNAMESIZE] ; to take source module name } PROGEXEC_RESBUF; ! Used to pass parameters to sys$prg?.img in p_execc() typedef struct { UWORD flags; mode information for sys$prg? UWORD pid; requestor process id PROGEXEC_RESBUF *result_offset; result buffer offset } PROGEXEC_PAR; } PROPERTY { PROGEXEC_RESBUF result; to take result } } Property progexec.result the result buffer that on completion contains details of the run aS a a ae a eT PROGEXEC methods AQ_ VOID ao_init (INT type, INT flags,TEXT *pname) ; Initialise and queue Queue for running the translated file specified by pname. The following flags may be passed to the ao_init method: PROGEXEC_NOTIFY indicates that the translator is to create an alert or a notify on error PROGEXEC_SIGNAL indicates that the translator is to signal caller of error condition Copies the filename specified by pname to progtran. buf. Obtains the full file specification of the required translator program by creating an instance of the PROGFIND class and sending it an ns_scan message. Writes & _GEN_FAIL to progexec.result.error. Starts the translator running by calling p_execc under the protection of £_leave with appropriate command line arguments including the address of progexec. result and flags. If flags contains PROGEXEC_SIGNAL: ® writes PRIORITY_ACTIVE_COMPUTE tO active.priority. e adds seif to the task queue by sending an am_aApD_TASK message to w_an. ¢ requests asynchronous notification of the abnormal termination of the translator process by calling p_logona with the address of active.stat as argument. Otherwise sends self a DESTROY message. Sets the translator process in a running state by calling p presume. 19-5 HWIM REFERENCE AO_ CANCEL irminated VOID ao_cancel (VOID) ; Ensure termination of the translator process. If active.isactive is TRUE, Writes FALSE to active. isactive, terminates the translator process by calling p_pkill with an argument of active .pcb and then waits until the process terminates by calling p_waitstat with an argument of active.stat. Write zero to active .pcb. PROGFIND PROGFIND flags pbuf pcb pname match info name wildname 1s_matchname is_scan is—sean is_filename The procFinp class may be used to locate either: e the OPL module translator with filename syssprco. IMG. e the Comms script module translator with filename syssprec. Mc. In either case the search starts in the Rom device and then continues in the mmc directory of each node on the Loc: : device until the required file is located. Class diagram fogs. 7 progfind XY f t ae ~s Class definition Defined in sub-category file program.cl (generated header file program.g). CLASS progfind locs Find the SYS$PRG?.IMG program translator { REPLACE ls_scan Start the scan off REPLACE 1ls_filename Local/Rom file system name found PROPERTY { UBYTE *pbuf; Where match name is } } Property progfind.pbuf the full file specification of the located translator program. 19 -6 19 OPL AND COMMS SCRIPT SUPPORT ae ee ee TE PROGFIND methods LS_SCAN _C | | | Start the scan VOID ls_scan(INT type,UBYTE *pbuf); Search for the translator program specified by type and write its full file specification to the buffer at address pbuf A type of either 'O' or 'C’ indicates that the method is to search for the OPL module translator SYS$PRGO.IMG or the Comms script translator SYS$PRGC.IMG respectively. Initialises the result buffer by writing zero to progfind.pbuf. Searches for the required file by sending se1f an LS_FILENAME message. Terminates the scan by sending self a DESTROY message. LS FRENAME = = = © Fit m name found INT 1s_filename(UBYTE *pname) ; Write the name of the located translator file to the buffer specified by pname. Writes pname to progfind.pbuf. Stores the filename in property by copying p_rwamesizeE characters from 1ocs .name to progfind.pbuf. Returns TRUE. 19-7 CHAPTER 20 INCREMENTAL MATCHERS This chapter describes classes associated with incremental matchers and the World database. These classes are: e the matcuer class which provides a common base class for the vmaTCHER and wMATCHER Classes. e the vmartcuer class which supports searching an alphabetically ordered sequence of variable length text records using incremental matching, exact matching and sequential access. e the wwatcuer class which supports searching the World database for matching cities and countries using incremental matching, exact matching and sequential access. e — the wupseLwn class which provides a choice list control for accessing information in the World database. Precursors Familiarity with the following topics will aid the understanding of this chapter: e _ the varoor and related classes described in the Variable Array Classes chapter of the OLIB Reference manual. e the Lopcer class described in the Windows chapter of the HWIM Reference manual. e the pieBox class described in the Dialog Boxes chapter of the HWIM Reference manual. e the Series 3 World application. MATCHER im_key im_init im_set_buf im_sense_buf im_set_val im_sense_val im_try_match im_transition The MATCHER class provides a common base class for the vmMaTCHER and wmatcuer classes described in later sections of this chapter. The class provides the basic functionality for record retrieval via incremental matching, exact matching and sequential access. 20-1 HWIM REFERENCE ESSE Class definition Defined in sub-category file matcher.cl (generated header file matcher. g)- CLASS matcher root { DEFER im_init DEFER im_set_buf DEFER im_sense_buf DEFER im_set_val DEFER im_sense_val DEFER im_try_match DEFER im_transition ADD im_key CONSTANTS { IM_NEW_LEN 1 IM_NEW_DISPLAY 2 IM_NO_CHANGE 3 } PROPERTY { TEXT *ptyped; Pointer to the typed string UBYTE *plen; Pointer to length byte } } Property matcher .ptyped a pointer to the zero terminated match string matcher .plen a pointer to the length of the match string SSS ee a ee eee MATCHER methods Handle key input INT im_key(INT keycode, INT modifiers) ; Handle a key input that might lead to a new current record. If keycode is W_KEY_DELETE_LEFT, removes the last character from the match string at address matcher .ptyped, and writes the length of the match string to the length byte at address matcher.plen. Locates a matching record by sending an 1m_TRY_mMATCH message to sel and then returns. If keycode is W_KEY_ESCAPE, resets the MATCHER instance by replacing the match string with won, and writing zero to the length byte at address matcher .pien. Returns IM_NEW_LEN. If keycode is either w_KEY_RIGHT, W_KEY_LEFT, W_KEY HOME or W_KEY_END, resets the MATCHER instance by replacing the match string with uu, and writing zero to the length byte at address matcher .plen. Sends an IM_TRANSITION message to self with keycode as the argument. Returns IM_NEW DISPLAY. Otherwise, if keycode is a printable non-control character, adds the character to the end of the match string, and increments the length byte at address matcher .plen. Attempts to locate a record matching the new match string by sending an 1M_TRY_MATCH message to self. If the return value from the IM_TRY_MATCH message is IM_NO_CHANGE, beeps, then restores the match string by removing the last character and decrementing the length byte at address matcher .plen and returns IM_NO_CHANGE. Otherwise returns the return value from the IM_TRY_MATCH message. 20-2 20 INCREMENTAL MATCHERS Deferred MATCHER methods VOID im_init(UBYTE *plen,UINT maxlen,PR_VAROOT *va) ; — Initialise Initialise the MATCHER instance. Allocate buffer space as required and initialise any property. INT im_set_buf (TEXT *str) ; Set the current record by locating a record that exactly matches the text specified by str. _. Sense current record data TEXT *im_sense_buf (VOID) ; Return the address of the current record. VOID im_set_val(UINT index) ; Set the current record by index: the records are assumed to be uniquely indexed. INT im_sense_val (VOID) ; Return the index of the current record. INT im_try_match(VOID) ; Locate a record that matches the match string at matcher. ptyped. The subclass would normally allow incremental matching whereby the first record whose initial text matches that at matcher.ptyped would be selected. The method returns the index of the matching record. IM_TRANSITION = =——i(asti‘(‘é‘ ‘é‘ééé Handle transition VOID im_transition(UINT type) ; Handle a keypress that might lead to the selection of a new current record. The subclass may wish to add extra functionality such as limiting the range of allowed records, adding an offset from which the matching commences, or restricting records to those terminating with the .pic extension, for example. 20-3 HWIM REFERENCE VMATCHER index first last txtoff destroy im_init im_set_buf im_sense_buf im_set_val im_sense_val im_try_match im_transition im_set_range The vMaTCHER class may be used to search an alphabetically ordered sequence of variable length text records. Incremental matching, exact matching and sequential access are supported. Examples of the use of the vwarcuer class may be found in the descriptions of the rneprt and cuLrst classes. Class diagram ae ot ae! ~ , ve 7 Mmatcher™> = / vmatcher» Class definition Defined in sub-category file matcher.cl (generated header file matcher.g). CLASS vmatcher matcher Variable array matcher { REPLACE destroy REPLACE im_init REPLACE im_set_buf REPLACE im_sense_buf ; REPLACE im_set_val REPLACE im_sense_val REPLACE im_try_match REPLACE im_transition ADD im_set_range PROPERTY { PR_VAROOT *va; Handle of associated variable array UWORD index; Index into array of current match UWORD first; Index of first item in array to match UWORD last; Index of last item in array to match (0 = VA_COUNT-1) UWORD txtoff; Offset within buffer returned by pbuf to text } } Property vmatcher.va the handle of an array of variable length text records vmatcher. index the index of the current record vmatcher.first the index of the first record in the search range 20-4 20 INCREMENTAL MATCHERS vmatcher.last the index of the last record in the search range: a zero index indicates that the search is to extend to the last record in the array. vmatcher.txtoff an offset into each record from which the matching should commence. ES a a eS VMATCHER methods VOID destroy(PR_VMATCHER *self) ; Free the match string buffer at address matcher .ptyped and supersend a pesTRoY message. VOID im_init(UBYTE *plen, UINT maxlen,PR_VAROOT *va) ; Initialise the instance of vmaTcuER. Initialises the records by writing va to vmatcher. va, allocates at least maxlen bytes for the match string and writes the address of the first byte to matcher. ptyped. INT im_set_buf (TEXT *str) ; Locate the first record that exactly matches the text specified by str excluding records outside of the current range: see the description of the im_set_range method for details of the range. If a matching record is located, writes its index to vmatcher . index and return zero. Otherwise return -1. TEXT *im_sense_buf (VOID) ; Return the address of the current record data offset by vmatcher. txtofé. Obtains the address of the current record data by sending a va_pBur message to vmatcher.va with an argument of vmatcher. index. VOID im_set_val(UINT index) ; Set the current record by writing index to vmatcher. index. CL _. Sense current record INT im_sense_val (VOID) ; Sense the index of the current record: the method does no more than return vmatcher . index. 20-5 HWIM REFERENCE IM_TRY_MATCH | ent match INT im_try_match (VOID) ; Locate the first record that matches the text at address matcher .ptyped excluding records outside of the current range. See the description of the im_set_range method for details of the current range. The matching is case insensitive. Searches the records to locate the first one that matches the text at address matcher .ptyped. A matching record is found when the first 1en characters match those stored at address matcher .ptyped. The length len is read from address matcher .plen. If there is no matching record, returns IM_NO_CHANGE. If the matching record is the current record, and thus has index vmatcher . index, returns IM_NEW_LEN. Otherwise if the matching record is not the current record, makes it the current record by writing its index to vmatcher. index, and returns IM_NEW_DISPLAY. VOID im_transition(UINT keycode) ; Handle a keypress that might lead to the selection of a new current record. Only records in the range are considered: see the description of the im_set_range method for details of the range. If vmatcher.1ast is invalid as it is both non-zero and less than vmatcher . first, returns. If keycode is either W_KEY_RIGHT, Or W_KEY_Down, and the last record has not been reached, moves to the next record by incrementing vmatcher . index. If keycode is w_KEY_HoME, moves to the first record by writing vmatcher. first to vmatcher. index. If keycode is W_KEY_END, moves to the last record by writing its index to vmatcher . index. If type is either w_KEY_LEFT, or W_KEY_up, and the first record has not been reached, moves to the previous record by decrementing vmatcher. index. VOID im_set_range(UWORD first,UWORD last,UWORD txtoff); .. Set range Set the record range to start at the record with index first and to extend to either the record with index last or the last record in the array. Ensure that the matching starts at an offset into each record of txtof£, i.e. the first txtof£ characters are skipped when matching. Writes first to vmatcher. first, writes last to vmatcher. last and writes txtoff to vmatcher.txtoff. The record range extends either to the record with index vmatcher . last, or to the last record in the array if vmatcher. last is zero. 20 - 6 20 INCREMENTAL MATCHERS WMATCHER wfcb iscountry tleng tbuf res resco im_key im_destroy im_init im—inie im_set_val im_set_buf im_try_match im_sense_buf im_transition The wMaTCHER Class may be used to search the World database for matching cities or countries. Incremental and exact matching are supported as well as sequential access. An example of the use of the wmarcuer class is provided by the wLpsELwn class described in the following section of this chapter. Note that the wmaTcHER class does not support data retrieval: it simply provides a means of navigating the World database. Class diagram a ety omke, aan 10 a ee ss! e ee’ ~ / Matcher; wmatcher} Class definition Defined in sub-category file w/dselwn.cl (generated header file widselwn.g). CLASS wmatcher matcher { REPLACE destroy REPLACE im_init REPLACE im_set_val REPLACE im_try_match REPLACE im_transition CONSTANTS { GEOG_MAX_NAME 22 Actually 20 but room needed for trailing zero PR_WMATCHER_INDETERMINATE 0x02 Neither city nor country } PROPERTY { VOID *wficb; Control block for world UBYTE iscountry; TRUE for country mode UBYTE tleng; The current typed length TEXT tbuf (GEOG_MAX_NAME] ; The current typed string WR_FIND_RES res; Holds latest result WORD resco; TRUE if restricted } } Property wmatcher .wfcb the handle of a channel to the World database: for details of the World database see the World chapter of the I/O Devices Reference manual. 20-7 HWIM REFERENCE wmatcher.iscountry TRUE to access countries: FALSE to access cities wmatcher.tleng the current length of the match string: this must not exceed WR_MAX_NAME wmatcher.tbuf a buffer holding the current match string wmatcher. res The wR_FIND_REs struct is defined as follows: typedef struct { TEXT city [(WR_MAX_NAME+1] ; TEXT country [WR_MAX_NAME+1] ; } WR_FIND_RES; The city member specifies the name of the current city as a zero terminated string. The country member specifies the current country as a zero terminated string. wmatcher. resco TRUE if the search is restricted to cities within the current country WMATCHER methods Stroy VOID destroy (VOID) ; Destroy the wMarcner instance by closing the i/o channel specified in wmatcher.wfcb and supersending a destroy message. VOID im_init (VOID) ; Initialise the wMATCHER instance. Writes the address of the match string buffer to matcher .ptyped and writes the address of wmatcher.tleng tO matcher.plen. Opens an i/o channel to the World database and writes the handle of the channel to wmatcher.w£cb. Sets the current record to the first city in the database and writes the names of the city and the country in which the city resides to wmatcher.res. VOID im_set_val(WR_FIND_RES *match) ; Set the current record by an exact match to the city, or if this is sux, the country specified in the WR_FIND_RES Struct with address match. The matching is not case sensitive. The wR_FIND_REs struct is defined as follows: typedef struct { TEXT city [WR_MAX_NAME+1] ; TEXT country (WR_MAX_NAME+1]) ; } WR_FIND_RES; The members of the wr_FinD_REs struct have the following significance: city either nut or the name of the target city specified as a zero terminated string. country either nun or the name of the target country specified as a zero terminated string. Ifa matching city is found, writes the names of the city and country in which the city resides to wmatcher.res and returns IM_NEW_DISPLAY. —- eS 20-8 20 INCREMENTAL MATCHERS If a matching country is found, writes the names of the country and its capital city to wmatcher.res and returns IM_NEW DISPLAY. Ifno matching record is found, returns 1m_No_CHANGE. IM_TRY_MATCH ~—|/ | Try INT im_try_match (VOID) ; lligent match Set the current record to the first record that matches the current match string. The matching is not case sensitive. If wmatcher.tleng is greater than wR_MAX_NAME returns IM_NO_CHANGE. If wmatcher .iscountry is TRUE, searches for a matching country, writes the names of the country and its capital city to wmatcher.res and returns IM NEW_DISPLAY. If wmatcher .iscountry is FALSE, searches for a matching city, writes the names of the city and the country in which the city resides to wnatcher .res and returns IM_NEW DISPLAY. If no match is found, returns IM_NO_CHANGE. sition VOID im_transition(UINT keycode) ; Handle the keypress specified by keycode. If wmatcher. resco is TRUE, sets the current record to the next city in the current country and returns. If keycode is W_KEY_RIGHT, and wmatcher.iscountry is TRUE, sets the current record to the next country. If keycode is W_KEY_RIGHT, and wmatcher.iscountry is FALSE, Sets the current record to the next city. If keycode is W_KEY_LEFT, and wmatcher.iscountry is TRUE, sets the current record to the previous country and returns. If keycode is W_KEY_LEFT, and wmatcher.iscountry is FALSE, sets the current record to the previous city and returns. If keycode is W_KEY_HOME, sends an IM_TRY_MATCH message to self and returns. Otherwise, sends an IM_TRY_MATCH message to se1f. If wmatcher. country is TRUE, sets the current record to the previous country. If wmatcher. country is FALSE, sets the current record to the previous city. 20-9 HWIM REFERENCE WLDSELWN landiord offset width destroy wn_calc_position wn_init wn_connect wn_visible wn_dodraw lg_draw wn_draw wn_set wn_key wn_sense wn_emphasise lg_sense_width wid_restrict 1g_self_check ig_set_id_pos wn_position wn_redraw wn_sense_help lg_update The wLDsewn class provides for the retrieval of information from the World database and supports sequential access and incremental matching via the keyboard. An instance of the wLpsELwn class may be used as a control in a lodger window. An example of the wupsELwn class being used as a control in a dialog is shown in the following picture: Set home city ¢London Inner + ‘Country United Kingdom In the above picture the controls are coupled in that the current city always resides in the current country. The current city could also be restricted to cities in the current country. This is known as restriction. Class diagram “ Win > / ledger ~ _¢ widselwn > Se hi———4 a mane 1 ,/ wmatcher » Class definition Defined in sub-category file w/dselwn.cl (generated header file widselwn.g). CLASS wldselwn lodger { REPLACE destroy REPLACE wn_init REPLACE wn_draw Draw whole city/country name REPLACE wn_set Set current city/country to str REPLACE wn_key REPLACE wn_sense REPLACE wn_emphasise REPLACE lg_sense_width Returns max width ADD wld_restrict SE eee ee 20-10 20 INCREMENTAL MATCHERS oon nnn nn ERD CONSTANTS { PR_WLDSELWN_COUNTRY PR_WLDSELWN_FIRST_PARTNER PR_WLDSELWN_NOT_IN DIALOG PR_WLDSELWN_RESTRICTED IN_WLDSELWN_CITY IN_WLDSELWN_COUNTRY IN_WLDSELWN_FIRST_PARTNER IN_WLDSELWN_NOT_IN_ DIALOG IN_WLDSELWN_SECOND_PARTNER IN_WLDSELWN_SETHOME IN_WLDSELWN_SETDFLT } TYPES { typedef struct { UWORD flags; PR_WIN *other; } IN_WLDSELWN; typedef struct { VOID *wicb; WR_EXTRA_DATA data; } SENSE_WLDSELWN; } PROPERTY } Property wldselwn.mat widselwn.tleng wldselwn. flags { PR_WMATCHER *mat; UBYTE *tleng; UWORD flags; PR_WIN *other; } description below. PR_WLDSELWN_COUNTRY PR_WLDSELWN_FIRST_PARTNER PR_WLDSELWN_NOT_IN_DIALOG 0x10 0x20 0x40 io channel use WR_FIND_RES for wn_set If non-NULL, then one of a pair the handle of an instance of waarcuEr. a pointer to the current length of the match string. an ored combination of flags that determine the behaviour of the component: see the widselwn.other the handle of a second instance of wLDSELWN Or NULL. The initial behaviour and content of a wupsELwn control is specified by oring a suitable combination of the following flags into the flags member of the wLpsEzwn resource struct: IN_WLDSELWN_FIRST_PARTNER IN_WLDSELWN_SECOND_PARTNER IN_WLDSELWN_NOT_IN_DIALOG IN_WLDSELWN_SETDFLT IN_WLDSELWN_SETHOME specifies that the control is the first partner in a coupled pair. If the control is in a dialog, then it must be placed immediately above the second control. specifies that the control is the second partner in a coupled pair. If the control is in a dialog, then it must be placed immediately below the first control. specifies that the control is a component in a non-dialog lodger window specifies that the control is to display the default country or city as appropriate. This flag must not be set for the first partner in a pair: setting this flag for the second partner is sufficient. specifies that the control is to display the home city or country as appropriate. This flag must not be set for the first partner in a pair: setting this flag for the second partner is sufficient. 20-11 HWIM REFERENCE a SR SE ee SEED] WLDSELWN methods DESTROY. : oS Destroy VOID destroy (VOID) ; Destroy the wLDSELWN component. If wldselwn. flags does not contain IN_WLDSELWN_FIRST_PARTNER, and wldselwn.mat is non-zero, destroys the wMaTcHER component by sending a DEsTRoy message to wldselwn.mat. Supersend a DESTROY message. Ww VOID wn_init (IN_WLDSELWN *par,PR_WIN *landlord) ; Initialise Initialise the control according to the content of the 1n_wLDSELwn struct pointed to by par. Write landlord to lodger. landlord and write par->flags tO wldselwn. flags. If the control is either an isolated wupseLwn control, or the second partner in a coupled pair, creates an instance of wMATCHER and writes its handle to widselwn mat. Initialises the wmaTcHER component by sending an IM_INIT message to wldselwn.mat and writes the matcher .plen property of the wMATCHER instance to wldselwn.tleng. If the control is the second partner in a pair, writes the handle of the first partner to wldselwn. other. The handle of the other control is either copied from par->other, in which case the control is not a dialog component, or obtained via the sending of pL_HANDLE_TO_INDEX and DL_INDEX_TO_HANDLE messages to the dialog. Writes the handle of the wwarcHer component to the wldselwn.mat property of both controls. Writes the address of w1dselwn.tleng to the wldselwn.tleng property of the first partner. If par->flags contains IN_WLDSELWN_SETHOME, sets the current record to the home city, or country, according to the content of widselwn. flags, and draws the control by sending a wn_pRaw message to self. If par->flags contains IN_WLDSELWN_SETDFLT, sets the current record to the default city, or country, according to the content of widselwn. flags, and draws the control by sending a wy_praw message to self. VOID wn_draw (VOID) ; Draw the control. Displays the name of the current record in the system font and, if win. flags contains PR_WIN_EMPHASISED, emphasizes the control. The current record is the name of the current country if widselwn. flags contains PR_WLDSELWN_COUNTRY, Otherwise it is the name of the current city. If widselwn. flags contains both IN_WLDSELWN_NOT_IN_DIALOG and PR_WLDSELWN_counTry and the control is one of a pair the other of which has pR_WLDSELWN_RESTRICTED Set in its wldselwn. flags property, then the method draws the text in the snT_space_onLy system resource after the name of the country. On English language machines the srt_sPACE_oNLY system resource is defined as follows: RESOURCE STRING srt_space_only { str="" (only) "; } _ Set current record VOID wn_set (WR_FIND RES *pset) ; Set the current record by an exact match to the text specified in the WR_FIND_RES Struct pointed to by pset. The wR_FIND_REs struct is defined as follows: 20 - 12 20 INCREMENTAL MATCHERS —_ SOOO MATCHERS typedef struct { TEXT city [WR_MAX_NAME+1] ; TEXT country [WR_MAX_NAME+12] ; } WR_FIND_RES; The members of the wR_FIND_REs struct have the following significance: city either NULL or the name of the target city specified as a zero terminated string. country either NuLL or the name of the target country specified as a zero terminated string. Sets the current record by sending an IM_sET_vaL message to wldselwn.mat passing as argument pset. A NULL city should be specified when setting the country. Resets the current match string by writing the nu. string to the matcher .ptyped property of wldselwn.mat and zero to the matcher.plen property of widselwn.mat. Sets PR_WMATCHER_INDETERMINATE in the wmatcher.iscountry property of the wmaTcHER component. Draws the contro] by sending an Lc_praw message to self, and if the control is one of a pair, draws the other control by sending an Lc_pRaw message to widselwn. other. Je key input INT wn_key(UINT keycode,UINT modifiers) ; Handle a keypress that might lead to the selection of a new current record. Sends an IM_KEY message to wldselwn.mat passing keycode and modifiers as arguments: the wMATCHER component is primed to ensure that it matches either by country if widselwn. flags contains IN_FNSELWN_COUNTRY, Or by city if wldselwn. flags contains IN_FNSELWN_CITY. If the return value is Im_NEW_LEN, draws the cursor one character to the right of its previous position and returns IM_NEW_LEN. If the return value is Im_wzw_DIsPLay, draws the new current record in the control by sending an LG_DRAW message to self. If the control is one of a pair and widselwn. flags contains PR_WLDSELWN_RESTRICTED, draws the other control by sending an L¢_praw message to wldselwn. other. Returns wN_KEY_CHANGED. VOID wn_sense (SENSE_WLDSELWN *psense) ; Sense the handle of the database channel and the data for the current record. The SENSE_WLDSELWN struct is defined as follows: typedef union { WR_CITY_DATA ci; WR_COUNTRY_DATA co; } WR_EXTRA_DATA; typedef struct { VOID *wfcb; io channel WR_EXTRA_DATA data; } SENSE_WLDSELWN; The wr_cITy_pata and wr_counTRy_pata structs are described under the wR_GET_crTy_para and WR_GET_COUNTRY_DATA services respectively in the Series 3 World Database chapter of the I/O Devices Reference manual. The significance of the members of the sznsE_wLDsELwn struct is as follows: wicb the handle of the channel to the World database device driver. data contains the data for the current record which may be either a city or a country as appropriate. 20 - 13 HWIM REFERENCE The method writes the wmatcher.wfcb property of the wmaTCHER component to psense->wfcb. If wldselwn. flags contains IN_WLDSELWN_COUNTRY, writes the data for the current country to the WR_EXTRA_DATA union pointed to by the data member of psense. Otherwise, if widselwn.£1ags does not contain IN_WLDSELWN_couNTRY, writes the data for the current city to the wR_EXTRA_DATA union pointed to by the data member of psense. Emphasise VOID wn_emphasise(UINT flag); Emphasise the control if f1ag is TRuE, otherwise de-emphasise it. If flag is TRUE, Sets PR_WIN_EMPHASISED in win. flags. Resets the match string by sending an 1m_KEY message to wldselwn.mat, with arguments of w_kKEy_EScAPE and zero. Draws the control by sending an LG_DRAW message to self. Otherwise, if £1ag is rans, clears the cursor from the control, clears pR_WIN_EMPHASISED from win.flags,and sends an LG_DRAW message to self. Returns required width UINT lg_sense_width (VOID) ; Return the width of the control. If the control is a component in a dialog, returns GEoG_MAX_NAME*SYSTEM_FONT_NUM_WIDTH. Otherwise, returns (GEOG_MAX_NAME-2) *SYSTEM_FONT_NUM_WIDTH. Set restriction VOID wld_restrict (INT IsRestricted) ; Set restriction. Writes IsRestricted to the wmatcher. resco property of the wMATCHER component. If IsRestricted is TRUE, sets PR_WLDSELWN RESTRICTED in wldselwn. flags, resets the wMATCHER component by writing the nuLt string to its matcher.ptyped property, and zero to its matcher.plen property . Draws the control by sending an Lc_pRaw message to self. Otherwise, if tskestricted is FALSE, Clears PR_WLDSELWN_RESTRICTED from wldselwn. flags. This message may be sent to either partner in a coupled pair: the effect is the same in each case. This message may not be sent to an isolated control whose wldselwn. flags property contains IN_WLDSELWN_COUNTRIES. 20-14 CHAPTER 21 LINK PASTE SUPPORT This chapter documents the ewLnxsv class which supports extraction of text from the selected region of an edit window, providing a supply of data for the Link Paste mechanism. Precursors Familiarity with the following topic will aid the understanding of this chapter: e the Epwzn class described in the EDWIN Edit Window Class chapter of the HWIM Reference manual. EWLINKSV doc state pos parend posend buf ewls_ init ewls_ extract The EwLinxsv class supports the extraction of text from the selected region of an edit window as follows: e — the extraction of text including paragraph delimiters - the content of the selected region may thus be copied as one block. e the extraction of text up to and excluding the next paragraph delimiter - the content of the selected region may thus be copied and stripped of paragraph delimiters - and optionally the replacement of tab characters in the text with spaces. The class may be used when implementing an edit window as a link-paste server. Class diagram 7 ewlinksv "5 / doc > 21-1 HWIM REFERENCE es SSeS Class definition Defined in sub-category file edwin.cl (generated header file edwin.g). CLASS ewlinksv root Component of linksv class, extracts data from edwin { ADD ewls_init ADD ewls_extract PROPERTY { VOID *doc; WORD state; UWORD pos; UWORD parend; UWORD posend; TEXT buf [256] ; } } Property ewlinksv.doc the handle of a document - this is usually an instance of either Eppoc or EPFDOC. The document is assumed to be a component in an edit window - i.e. an instance of EDWIN. ewlinksv.state see the description of the ewis_exrracr message for the significance of ewlinksv.state. ewlinksv.pos the current position in the document. ewlinksv.parend for use by subclassers. ewlinksv.posend the end position of the selected region. ewlinksv.buf a buffer that stores text extracted from the document. Se cea eT a a ny EWLINKSV methods _ Initialise VOID ewls_init (PR_EDWIN *edwin, INT state) ; Determine the position and length of the selected region in the document edited by the edit window with handle edwin and record the extraction mode specified by state. Records the handle of the document by writing edwin->edwin.doc to ewlinksv.doc. Writes the start position of the selected region to ewlinksv.pos and writes the end position of the selected region plus one to ewlinksv.posend - the method obtains the start and end positions of the selected region by sending an sI_GET_SELECT message to edwin->edwin. scrimg. Records the extraction mode by writing state to ewlinksv.state. INT ewls_extract (TEXT **ppb,UINT blen) ; Extract up to blen characters from position ewlinksv.pos in the selected region of the document and write the address of the extracted characters to *ppb. If no region is selected, returns -1. If the maximum number of characters that can be extracted from the document - ewlinksv.posend- ewlinksv.pos - is less than blen, writes ewlinksv.posend-ewlinksv.pos tO blen. Extracts blen characters from position ewlinksv.pos in the document by sending an EP_EXTRACT message to ewlinksv.doc. The characters are written to ewlinksv. buf. —_— SS SSS 21-2 21 LINK PASTE SUPPORT ——_—-_—r—————————————XnYv—— a ee ee Writes sewlinksv.buf [0] to «ppb. If ewlinksv.state is equal to pr_EQUAL_PARAs, increments ewlinksv.pos by the number of characters extracted from the document and returns the number of characters extracted. If ewlinksv.state is equal to DF_LINK_TEXT, replaces any tab characters in ewlinksv.buf with spaces. If the text written to ewlinksv.buf contains no paragraph delimiters - i.e. 0x00 - increments ewlinksv.pos by bien and returns bien. Otherwise increments ewlinksv.pos by one plus the number of characters before the first paragraph delimiter in ewlinksv.buf and returns the number of characters before the first paragraph delimiter. 21-3 CHAPTER 22 REPRESENTATIONS OF TIME AND DATE This chapter documentsthe nrime class which may be used to convert to and from textual representations of time and date. Precursors Familiarity with the following topic will aid the understanding of this chapter: e the rime class described in the The Time Class chapter of the OLIB Reference manual. HTIME tDay tMonth to_set to_set_format to_get_sysdat to_set_abbreviatio ns to_sense to_add_years to_add_months to_add_ days to_add_secs to_sense_format te—get—sysdat The uTIMe class supports conversion to and and from textual representations of time where time is used to denote time and date. While based on the trmz class in the ours object library the urime class adds the following functionality: e — the ability to truncate the day and month names after a given number of characters. e — the ability to sense machine specific format parameters such as time and date separator characters. Class diagram 22-1 HWIM REFERENCE Class definition Defined in sub-category file htime.cl (generated header file Atime.g). CLASS htime time { REPLACE to_set REPLACE to_set_format REPLACE to_get_sysdat ADD to_set_abbreviations CONSTANTS { PR_TIME_ABBREVIATE 0x1000 PR_TIME_FORCE_UPDATE_FORMAT 0x2000 HTIME_FIRST_DAY 29219L ist Jan 1980 HTIME_LAST DAY S4786L 31st Dec 2049 HTIME_FIRST_SEC oL HTIME_LAST SEC 86399L (P_NSECDAY-1) HTIME_FIRST_MIN OL HTIME_LAST_ MIN 86340L (P_NSECDAY-60) } PROPERTY { UBYTE tDay; UBYTE tMonth; } } Property htime.tDay the length of the abbreviated form of the day name. Thus if htime.tDay were 3 the abbreviated form of "Wednesday" would be "Wed". htime.tMonth the length of the abbreviated form of the month name. Thus if htime.tMonth were 3 the abbreviated form of "December" would be "Dec". HTIME methods TO INT to_set (INT format, UBYTE *pdata) ; Set the current date and time using the representation specified by format. If format contains SET_TIME_Now and time. f.flags contains PR_TIME_FORCE_UPDATE_FORMAT, sets as many as possible of the format parameters using system services by sending self a TO_SET_FORMAT message with an argument of nut. Sets the current date and time stored in the prime object by supersending a To_sET message with arguments of format and pdate and returns the return value. VOID to_set_format (SE_TIME_FORMAT *pf,UWORD mask) ; Set the format parameters for the conversion to and from textual representations of time. Sets the format parameters by supersending a To_SET_FORMAT message with arguments of pf and mask. Sets the following in time.£.flags if present in pf->flags: PR_TIME_ABBREVIATE indicates that the day of the week text is to be truncated after htime.tDay characters, and that the day of the month text is to be truncated after htime.tMonth characters. 22-2 22 REPRESENTATIONS OF TIME AND DATE PR_TIME_FORCE_UPDATE_FORMA _ controls the behaviour of the ro_seT message. T TO_GET_SYSDAT : Get system data INT to_get_sysdat (UBYTE *buf,UINT type,UINT n); Write a zero terminated time-related name to but or, if type is TY_TIME_FORMAT write machine specific format parameters in an SE_TIME_FoRMAT struct to buf. If type is neither ry_TIME_DAY, Nor TY_TIME_MONTH Nor TY_TIME_FORMAT, supersends a TO_GET_SYSDAT message with arguments of buf, type and n, and returns the return value, If type is Ty_TIME_SUFFIX obtains the day suffix name - e.g. "st", "nd", "rd" or "th" on English language machines - corresponding to the day number specified by n in the range 0 to 31. Writes the string to buf and returns the length of the string. If type is Ty_TIME_AMPM obtains the am/pm string specified by n - where 0 is am and 1 is pm. Writes the string to buf and return the length of the string. If type is Ty_TIME_pay obtain the day text - e.g. "Tuesday" - for the day number specified by n in the range 0 to 6 inclusive where 0 is Monday. If time. £.£1ags contains PR_TIME_ABBREVIATE truncates the day text after htime .tDay characters. Writes the string to buf and returns the length of the string. If type is Ty_TIME_MonTH, obtains the month text - e.g. "March" - for the month number specified by n in the range 0 to 11 inclusive where 0 is January. If time. £.f£lags contains PR_TIME_ABBREVIATE truncates the month text after htime.tMonth characters. Writes the string to buf and returns the length of the string. If type is TY_TIME_FORMAT, Creates an SE_TIME_FORMAT struct and copies the content of the struct to bug. The sE_TIME_FoRMaT struct is defined as follows: typedef struct { UWORD flags; UBYTE dsep; UBYTE tsep; } SE_TIME_FORMAT; The members of the se_TIME_Format struct are set as follows: flags on all machines the following flags are set: PR_TIME_DAY_NAME write the day name with a trailing comma before the date. PR_TIME_SUFFIX_NAME write the day number followed by a suffix e.g. 15th. PR_TIME_MONTH_NAME show the month as a name rather than a numer. the following flags may be set depending on the machine and the current settings: PR_TIME_MMDDYY set on USA machines only. PR_TIME_YYMMDD set on Japanese machines only. PR_TIME_DDMMYY set on all other machines including European. PR_TIME_AMPM set if the system time format is am/pm. PR_TIME_ABBREVIATE set if present in time.£.flags. PR_TIME_FORCE_UPDATE_FORMAT set if present in time. f. flags. dsep the system date separator character - on English language machines this is usually a backslash - 12/3/1994 for example. tsep the system time separator character - on English language machines this is usually a colon - 3:42 pm for example. Returns the length of the data written to bur. 22-3 HWIM REFERENCE TO_SET_ABBREVIATIO VOID to_set_abbreviations(INT aDay,INT aMonth) ; Set abbreviations Set the length of the day and the month strings. Writes aDay to htime.tDay and writes aMonth to htime. tMonth. 22-4 CHAPTER 23 THE GATE CLAss waotstat lastmods concb atpid xadd atson flags today_hook dialres shift_txt x prevdisp getkeys dx lastkey g gt_init gt_choice_close gt_menu_open gt_button_open gt_menu_add gt_button_add gt_menu_run gt_button_close gt_menu_close gt_dial_position gt_dial_open gt_xw_enable gt_dial_add gt_return_signals gt_dial_run gt_check_ats_on gt_dial_close gt_last_key gt_card_open gt_wdr_print gt_card_add gt_wdr_print_setup gt_card_close gt_do_help gt_choice_open gt_set_rscfile gt_choice_add gt_dial_sopen The care class is essentially a private class whose principal task is to support the graphics functionality of OPL/w and the HWIF library. In consequence, the majority of its methods and items of property are not suitable for use by application programmers. This chapter documents only those aspects that could reasonably be of value to such programmers. Note that none of the features documented in this chapter are available on the Series 3. All HWIM applications create and initialise an instance of the cate class during the application's initialisation. This instance remains in existence for the lifetime of the application. The handle of the application's instance of the care class is written to the magic static patcate. In the interest of future compatibility, an application should not subclass cate. 23-1 HWIM REFERENCE a SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSsSSSSSSSSSSSSSseseseeese Class definition Defined in sub-category file gate.c/ (generated header file gate. g). CLASS gate root Gateway to hwim menus and dialogs { ADD gt_init ADD gt_menu_open ADD gt_menu_add ADD gt_menu_run ADD gt_menu_close ADD gt_dial_open ADD gt_dial_ada ADD gt_dial_run ADD gt_dial_close ADD gt_card_open ADD gt_card_add ADD gt_card_close ADD gt_choice_open ADD gt_choice_add ADD gt_choice_ close ADD gt_button_open ADD gt_button_add ADD gt_button_close ADD gt_dial_position ADD gt_xw_enable ADD gt_return_signals ADD gt_check_ats_on check if process supports ATS ADD gt_last_key return last key used ADD gt_wdr_print ADD gt_wdr_print_setup ADD gt_do_help ADD gt_set_rscfile ADD gt_dial_sopen Workabout ONLY - init dlg with small font (Romans) CONSTANTS { PR_XWSERV_SHUTDOWN 0x01 PR_XWSERV_QUERY_ALERT 0x02 PR_XWSERV_S3FS 0x04 Workabout ONLY - full-screen S3 compatibility PVV_TEXT_MAX LEN 50 OPRINTER_DO_PREVIEW 1 OPRINTER_PRINT_AFTER 2 } TYPES { typedef struct { WORD class; VOID *data; } DITEM_LIST; typedef struct { UWORD xwim; UWORD nmenus; VOID **menus; UWORD ulines [16]; UWORD count; DITEM_LIST dialret [9]; UWORD nrec; VOID *orec; UWORD preview; } PURE_GATE; typedef struct { UBYTE Mode; UBYTE Flags; } PVV_DISPLAY; 23-2 23 THE GATE CLASS rr EE AS typedef struct { UWORD UWORD UWORD UWORD UWORD UWORD UWORD UWORD UWORD UWORD UWORD UWORD UWORD UWORD UWORD UWORD } X_CONSTANTS; fht; fds; fas; fnw; fmw; echt; mbht ; bfid; bulyo; bulht; ninlb; SSww; bsww; hlig; samo; damo; typedef struct { UWORD UWORD UWORD UWORD UWORD UWORD UWORD UWORD UWORD fht; fds; fas; fnw; fmw; cht; bulyo; bulht; ninlb; height of system font descent of system font ascent of system font width of numeric character in system font width of maximum normal character height of a line in dialogs or listboxes height of menubar id of bold font y-offset to start of bullet height of bullet max number of lines in listbox width of small status window width of large status window help list left gutter menu offset for single accelerator menu offset for double accelerator height of font descent of font ascent of font width of numeric character width of maximum normal character height of a line in dialogs or listboxes y-offset to start of bullet height of bullet max number of lines in listbox } DLG_X_CONSTANTS; Workabout ONLY - extras for dialogs using another font } PROPERTY { VOID *waotstat; VOID *concb; HANDLE xadd; UWORD flags; UWORD dialres; X_CONSTANTS x; VOID *getkeys; UWORD lastkey; UWORD lastmods; UWORD atpid; UWORD atson; VOID *today_hook; TEXT shift_txt [10]; connection pseudo-constants where to send copy of key received last key received last keyboard modifiers received pid of process attached to ATS supported PVV_DISPLAY prevdisp; DLG_X_CONSTANTS dx; dialog PURE_GATE g; } } Property gate.x gate.getkeys gate. lastkey gate.lastmods gate.atpid Workabout ONLY - constants of additional fonts of Pseudo-constant connection data, described below. This data may be read by application code. Either nuxu or the handle of the instance of the XADD arssv class that is sent a copy of each key received. The keycode of the last key received. This data should be read by means of the gt_last_key method. The modifiers associated with the last key received. This data should be read by means of the gt_last_key method. Either zero or the process ID of the process to which the application is attached. 23-3 HWIM REFERENCE EES gate.atson TRUE if the application supports the automatic test system (ATS) mechanism. gate.dx Pseudo-constant connection data, described below, for Workabout dialogs. This data may be read by Workabout application code. The remaining items of property are reserved for internal use and are not documented and should not be accessed by application software. The pseudo-constant connection data, gate .x, is a collection of values that are constant within a particular running application, but will, in general, vary with the type of the machine on which the application is running. The data is evaluated during the application's initialisation and is used by system code to determine the position and size of system-created objects, such as dialog boxes and the menu bar. Application code is free to read any of this data. The meaning of each item is given in the following table: DatGate->gate.x.fht The height of the system font. DatGate->gate.x.fds The descent of the system font. DatGate->gate.x.fas The ascent of the system font. DatGate->gate.x.fnw The width of a numeric character in the system font. DatGate->gate.x. fmw The width of of the widest 'normal' character. DatGate->gate.x.cht The height of a line in a dialog or a listbox. DatGate->gate.x.mbht The height of the menubar. DatGate->gate.x.bfid The ID of the bold font. DatGate->gate.x.bulyo The y-offset to the top of a bullet displayed in a text window (an instance of TEXTWIN). DatGate->gate.x.bulht The height of a bullet displayed in a text window (an instance of TExtTwrn). DatGate->gate.x.ninlb The maximum number of lines that can appear in a listbox. DatGate->gate.x.ssww The width of the small status window. DatGate->gate.x.bsww The width of the large status window. DatGate->gate.x.hllg The width of the left gutter of a help list. DatGate->gate.x.samo The offset, from the right hand side of a pull-down menu, to the position to display an unshifted accelerator. DatGate->gate.x.damo The offset, from the right hand side of a pull-down menu, to the position to display the 'Shift' text for a shifted accelerator. The Workabout pseudo-constant connection data, gate . dx, is a collection of values that are used to determine the appearance of system-crated objects, particularly dialogs, that use a font other than the system font. These values are constant within a particular running application. Although currently only defined for the Workabout, they will, in general, vary with the type of the machine on which the application is running. The data is evaluated during the application's initialisation. Application code is free to read any of this data. The meaning of each item is given in the following table: DatGate->gate.dx. fht The height of the dialog font. DatGate->gate.dx. fds The descent of the dialog font. DatGate->gate.dx. fas The ascent of the dialog font. DatGate->gate.dx.fnw The width of a numeric character in the dialog font. DatGate->gate.dx. fmw The width of of the widest ‘normal’ character in the dialog font. Eee 23-4 23 THE GATE CLASS DatGate->gate.dx.cht The height of a line in a dialog or a listbox. DatGate->gate.dx.bulyo = The y-offset to the top of a bullet displayed in a text window (an instance of TEXTWIN). DatGate->gate.dx.bulht The height of a bullet displayed in a text window (an instance of TEXTWIN). DatGate->gate.dx.ninlb | The maximum number of lines that can appear in a listbox. ~~ Se ee ee et ee See GATE methods CHE INT gt_check_ats_on(INT pid) ; Return the ATS status of the process with process ID pia. Returns zero if the specified process supports ATS, otherwise a (negative) error number. A return value of E_GEN_NsupP indicates that the specified process does not support ATS. Other errors are possible if, for example, the specified process has terminated before the gt_check_ats_on method is executed. Note that the process with process ID pid may terminate at any time. A zero return value from the gt_check_ats_on is thus no guarantee that future ATS operations on that process will succeed. INT gt_last_key(UWORD *mods) ; Sense the keycode and modifiers of the last keypress received by the application. The method returns the keycode and writes, to «mods, the corresponding modifier flags. Both values will be zero if the application has not received any keypress. 23 -5 — CHAPTER 24 HWIM UTILITY FUNCTIONS HWIM utility and convenience functions have been developed in response to a number of observations and pressures: e The need to minimise memory used by application code. ¢ The observation that a large range of applications have many code fragments that are in common use. By formalising these code fragments into commonly available functions, application code can be made easier to read and can achieve savings in memory. At first sight, the use of "free standing" functions seems to violate the most basic principles of object oriented programming. This is not the case. They can legitimately be used where similar actions are done repeatedly in various parts of the application code, even if that action involves the sending of messages. For example, utility functions are very often used to send a standard message to system generated objects such as the application manager which exist throughout the lifetime of an application. There is nothing to stop a developer from writing his/her own utility functions and is, in fact, encouraged to do so. It is appropriate in a situation where similar pieces of code are used over and over again. It is particularly suitable where code involving the sending of a message to a particular object may be repeated. There is no problem involved in encapsulating the sending of messages within utility functions. The use of utility functions can save memory by: ¢ - allowing a reduction in the number of parameters passed from application code. While this might save one or two bytes per call, the total saving in memory across a whole range of applications can be substantial e avoiding the duplication of code fragments The next sections describe the utility functions available for use by any HWIM application. Each section describes a set of functions grouped under the following headings: © General utilities e Text management e User notification e Running a dialog © Dialog box utilities In many cases, the implementation of utility functions is given in full or in skeleton form. This will assist developers to create their own utility/convenience functions. Note that the HWIM utility functions are prototyped in Awim.h. 24-1 HWIM REFERENCE General utilities As indicated by the title of this section, this is a group of miscellaneous functions with no connecting theme. INT p_true(VOID) ; This is a simple function that returns the value TRUE. It is particularly useful as a default method for a class where the method must return a simple TRUE or FALSE value. For example, in the definition of the HWIM comman class, p true is assigned to the method com_acc1_check which means that when the method com_accl_check is called, p true is executed, thus returning a value of TRUE. INT p_false (VOID) ; This is a simple function that returns the value rause. It is particularly useful as a default method for a class where the method must return a simple TRUE or FALSE value. See the earlier description of p_true for an example of how this could be implemented. VOID hDestroy(VOID *hand) ; This is a function which will destroy an object by sending it the p—esTroy message: psend2 (hand, O_ DESTROY) ; The handle of the object to be destroyed must be passed as a parameter to this function. If the handle is nui, the function does nothing. VOID hInitVis (VOID *win) ; This can be used in one of two ways depending on the current state of the window object with handle win: e if the window has not yet been initialised, then it will be both initialised and made visible e if the window has already been initialised, then it will be made visible. The function is implemented by sending a wN_vIsIBLE message to the window with handle win as shown below. The handle passed as a parameter must point to an object instanced from the win class ora subclass of win. psend3 (win,O WIN_VISIBLE,WV_INITVS) ; For further discussion on windows, see the Windows chapter. VOID hWservComSend(INT comid) ; This utility simply sends the message with message (method) number comid and the same message (method) number as a parameter to the command manager. This is implemented as shown below: P_send3 (w_ws->wserv.com, comid, comid) ; 24-2 24 HWIM UTILITY FUNCTIONS ——————_—. EEE EERUUNG HONS The additional comida parameter that is passed with the message is for the convenience of the receiving command manager method, which may choose to ignore it. This function is particularly useful where a number of methods are implemented using the same code. Passing the method number as a parameter allows the code to identify the context of the call and to take appropriate action if it so wishes. For further discussion on the command manager, see the Command Manager chapter of this manual and the Commands and Command Menus chapter of the Object Oriented Programming Guide. hEnsurePath _ Ensure path exists VOID hEnsurePath (TEXT *fname) ; If the path indicated by the file specification at gname does not exist, the function attempts to create the required directory structure. The file specification is parsed using the Plib function p_fparse. If this is successful, the directory component of the parsed file specification is created, provided it does not already exist, using the Plib function p_mkdir. No errors are reported. If this function fails, this could be due to a bad file specification in *fname or a problem with the device/medium when attempting to create the directory itself. For example, suppose fname contains the string: "FILES \\DOCS\\FRED.DOC" and the default path is: LOC: :M:\ then the function will attempt to create the directory structure: \FILES\DOCS\ at node LOC:: on device M: For further information on file specifications see the files chapter in the PLIB Reference manual. Text management This group of functions is concerned with building text from various sources, displaying text in a variety of contexts and with text manipulation. INT hLoadResource (INT rid, VOID *ppdata) ; This is a convenience routine which allocates a cell of suitable length from the heap, loads the resource referenced by the resource id ria into the cell and returns the length of the loaded resource. The address of the cell is placed in *ppadata. The function is implemented by sending an am_load_resource message to the application manager as shown below: p_send4 (w_am,O_AM LOAD RESOURCE, rid, ppdata) ; Remember that the address of the application manager object is found in the magic static variable w_am. If an error occurs, the function calls p leave. 24-3 HWIM REFERENCE hLoadResBuf . Load resource into buffer INT hLoadResBuf (INT rid, VOID *buf); This is a convenience routine which loads the resource referenced by the resource id ria into the buffer pointed to by bug and returns the length of the loaded resource. The function is implemented by sending an am_load_res_buf message to the application manager as shown below: p_send4 (w_am,O AM _LOAD RES BUF, rid, buf) ; It is similar to the previously described function hLoadresource except that it is the caller's responsibility to provide the buffer and to ensure that it is large enough to contain the loaded resource. If an error occurs, the function calls p_ leave. As an example, consider the following code fragment that could come from any typical window subclass drawing method which, as part of its functionality, loads a resource string and prints it at a given point within the window: hLoadResBuf (self->resid, &buf[0]); p_supersend2 (self,O_WN_DRAW) ; gPrintText (50,50, &buf[0],p_slen(&buf[0]); 4 The important point to note here is that buf must be large enough to hold the loaded resource String. hLoadChlistResB TEXT *hLoadChlistResBuf (INT rid, INT choice, TEXT *buf); oice list item into buffer This is a convenience routine which loads a single choice list item from a choice list resource into a buffer. The choice list resource is identified by the parameter ria within a resource file while the parameter choice identifies the particular choice list item within the resource. The function returns a pointer to the string's terminating zero. The function is implemented by sending a ws_load_chlist_res message to the window server object as shown below: return ( (TEXT *)p_sendS(w_ws,O_WS_LOAD CHLIST_RES, rid, choice, buf) ; It is the caller's responsibility to ensure that the buffer provided is large enough to contain the loaded choice list item. If an error occurs, the function calls p_leave. _ Generate error text VOID hErrs(TEXT *buf, INT err); This is a convenience routine that writes the error text specified by the error number err to the buffer at buf. If err is negative it is interpreted as a system error number and the text is obtained by calling the Plib function p_errs; the buffer must be at least E_MAX_ERROR_TEXT_SIZE bytes. If err is non-negative it is assumed to refer to a resource string which is loaded from a resource file with resource id err-ERROR_RID_oFFsET (see the wrn class definition). The buffer supplied must be large enough to contain the maximum size string expected. Because the resource id is given as err-ERROR_RID_OFFSET, then this must evaluate to a number greater than 1 in order to access resources within the application resource file. Consequently, err must be greater than ERROR_RID OFFSET + 1. SNS 24-4 24 HWIM UTILITY FUNCTIONS EIN The function is implemented as follows: { if (err<0) p_errs(buf,err); else hLoadResBuf (err-ERROR_RID_OFFSET, buf) ; } If an error occurs, the function calls p_ leave. For further detail on resource files, see the chapter on Resource Files in this manual. RAtob = = ~==©~©~©6—— Generate formatted string INT hAtob(TEXT *buf, INT rid, INT *pargs) ; This is a useful function which generates a zero terminated string in the buffer pointed to by buf and returns its length. The string is generated from a format string and a number of arguments pointed to by pargs. The format string is loaded from the resource ria in a resource file. For more detail on the structure of the format string, see the description of the PLIB function p_atob in the PLIB Reference manual. There are a number of important points to note: e — the length of the format string in the resource file, when loaded, must not be greater than 80 bytes. * — it is the caller's responsibility to ensure that the buffer pointed to by buf is large enough to contain the generated string. If an error occurs, the function calls p_ leave. The following routine and code fragment together provide a simple example of the use of this function. For the sake of argument, assume that file is a static variable that contains the channel of an opened text file. GLDEF_C CDECL SampleRoutine (INT rid,INT arg,...) { INT len; TEXT buf [25]; len = hAtob(&buf [0] , rid, &arg) ; p_write (file, &buf [0] ,len); INT rid; INT num; num = 65; rid = MY_FORMAT_ STRING; SampleRoutine (rid, num, num, num, num, num, num) ; Given that the string resource referenced by the resource ID my_FoRMAT_sTRING is defined as: RESOURCE STRING my_format_string {str="[tb tc %d %o tu %x]";} then the the following string of characters would be written to the text file: [1000001 A 65 101 65 41] 24-5 HWIM REFERENCE hAtos —s Generate formatted string, vari iment count TEXT *hAtos(TEXT *buf, INT rid, ...); This is a useful function which generates a zero terminated string in the buffer pointed to by buf and retums a pointer to its zero terminator. The string is generated from a format string and a number of arguments. The format string is loaded from the resource rid in a resource file while the arguments are interpreted as for the PLIB function p_atos. For more detail on the structure of the format string, see the description of the PLIB functions p_atob and p_atos in the PLIB Reference manual. As with the function hatob, described earlier, the same important points must be noted. To recap: ¢ — the length of the format string in the resource file, when loaded, must not be greater than 80 bytes. * it is the caller's responsibility to ensure that the buffer pointed to by bug is large enough to contain the generated string. If an error occurs, the function calls p leave. For example, given that the string resource referenced by the resource ID my_ForMAT_sTRING is defined as: RESOURCE STRING my_format_string {str="%b %c %d to %u &x";} the effect of the following code fragment: INT num; TEXT buf [23]; INT rid; num = 65; rid = MY_FORMAT_ STRING; hAtos (&buf [0] , rid, num, num, num, num, num, num) ; is to build the string: 12000001 A 65 101 65 41 in the buffer at but. Append ellipsis to text VOID hAppendEllipsis(TEXT *p) ; This is a simple convenience function that writes the ellipsis character, WS_SYMBOL_ELLIpsis, followed by a zero terminator into the two bytes pointed to by p. The ellipsis character is commonly used as an appendage to a choice list prompt to indicate that a subsidiary dialog is available. For example the code fragment: TEXT buf[5] = {'A','B','¢'}; hAppendEllipsis (&buf [3]); would result in buf containing the four characters ABC... followed by the zero terminator. Set text mode VOID hSetGTmode(UINT tmode) ; This simple convenience function uses the window server function gsetcc to set the text mode of the current graphics context to that specified by tmode. Possible values of tmode are defined in the Graphics Output chapter of the Window Server Reference manual. For example, as part of the drawing method of a win subclass, the following code fragment would create a a permanent graphics context with default values and then change the textmode so that when writing text, the 1's and 0's of the font characters overwrite the destination area: 24-6 24 HWIM UTILITY FUNCTIONS —_—__—$ eee ML YE FUNCTIONS ‘ wValidateWin (self->win.id) ; p_supersend2 (self,O WN_DRAW) ; self->mywin.gcid = gCreateGCo0 (self->win.id) ; hSetGTmode (G_TRMODE_REPL) ; gPrintText (50,50, &buf[0],p_slen(&buf[0]); wFree (self->mywin.gcid) ; hSetGFont : __ Set font VOID hSetGFont (UINT fid); This simple convenience function uses the window server function gsetcc to set the text font of the current graphics context to that specified by ¢id. Possible values of fia are defined in the Graphics Output chapter of the Window Server Reference manual. For example, as part of the drawing method of a win subclass, the following code fragment would create a a permanent graphics context with default values and then change the text font to the ROM based monospaced font wS_FONT_BASE+3: wValidateWin (self->win.id) ; Pp_supersend2 (self,O_WN_DRAW) ; self->mywin.gcid = gCreateGCo0 (self->win.id); hSetGFont (WS_FONT_BASE+3) ; gPrintText (50,50, &buf (0],p_slen(&buf[0]); wFree (self->mywin.gcid) ; VOID hSetGStyle(UINT style) ; This simple convenience function uses the window server function gsetcc to set the text style of the current graphics context to that specified by style. Possible values of style are defined in the Graphics Output chapter of the Window Server Reference manual. For example, as part of the drawing method of a win subclass, the following code fragment would create a a permanent graphics context with default values and then change the text style so that text characters are displayed in bold: wValidateWin (self->win.id) ; p_supersend2 (self,O_WN_DRAW) ; self->mywin.gcid = gCreateGC0 (self->win.id) ; hSetGStyle (G_STY_BOLD) ; gPrintText (50,50, &buf[0],p_slen(&buf [0]); wFree (self->mywin.gcid) ; GetBV INT hGetBWid (TEXT *buf, INT len); This function uses the window server function grextwidth to calculate and return the width, in pixels, of the first 1en characters in the buffer pointed to by but . This function assumes that the text would be displayed using the current system font (i.e system_ronT_rp) and a normal style (i.e G_STY_NORMAL ). This is useful for planning the size and positioning of text in relation to surrounding text and graphic objects. 24-7 HWIM REFERENCE hGetSWid _ Get normal text width for string INT hGetSWid (TEXT *pzts) ; This is similar to the function hcetBwid. It calculates and returns the width, in pixels, of the zero terminated string pointed to by pzts. Like hGetBwid, this function assumes that the text would be displayed using the current system font (i.e SYSTEM_FONT_ID) and a normal style (i.e G_stTy_ NORMAL ). This function is useful for planning the size and positioning of text in relation to surrounding text and graphic objects. for buffer INT hGetBBWid (TEXT *buf, INT len); This is similar to the function hcetBwid in that it uses the window server function gTextwidth to calculate and return the width, in pixels, of the first 1en characters in the buffer pointed to by but . This function assumes that the text would be displayed using the font with id Bo.p_FowrT_rp and a normal style (i.e G_STY_NORMAL ). This is useful for planning the size and positioning of text in relation to surrounding text and graphic objects. User notification This group of functions is concerned with informing, warning and alerting the user in a variety of ways. VOID hIinfoPrint (INT rid, ...); ay ani information message This function prints an information message window in the bottom right hand corner of the screen for 2 to 2.5 seconds or until cancelled. The zero terminated text of the message is generated from a format string and the arguments which follow the parameter rid. The format string is loaded from the resource rid in a resource file. For more detail on the structure of the format string, see the description of the PLIB function p_atob in the PLIB Reference manual There are a number of important points to note: e the length of the format string in the resource file, when loaded, must not be greater than 80 bytes e if the generated text is greater than w_INFo_MsG_MAX_LEN bytes then the message will appear truncated e the generated text including the zero terminator must not, in any event, be greater than 80 bytes. If an error occurs, p_leave is called. The following code fragment provides a simple example of the use of this function. The string in the resource file referenced by the resource id RID_OF_MY_FORMAT_STRING contains the 25 character sequence: The numbers are td and %d the effect of the following code fragment: 24-8 24 HWIM UTILITY FUNCTIONS —.— EE ILI YY BUNCTIONS INT numl,num2; INT rid; numl = 65; num2 = 66; rid = RID_OF_MY_FORMAT_ STRING; hInfoPrint (rid, numl,num2) ; is to display the message: The numbers are 65 and 66 in the bottom right hand corner of the screen. VOID hInfoPrintErr(INT err) ; This function prints an error information message window in the bottom right hand comer of the screen for 2 to 2.5 seconds or until cancelled. The text of the message is related to the error number in err and is obtained in exactly the same way as described in the function hErrs; see the description of herrs for more information. If an error occurs, p_leave is called. a ge VOID hBusyPrint (INT delay, INT rid, ...); This function prints a flashing message window in the bottom left hand corner of the screen. The display of the message can be delayed by the number of half-seconds specified in the delay parameter; this can range from 0 to 63. The zero terminated text of the message is generated from a format string and the arguments which follow the parameter rid. The format string is loaded from the resource rid in a resource file. The message may be removed by a call to the window server function wcancelBusyMsg. For more detail on the structure of the format string, see the description of the PLIB function p_atob in the PLIB Reference manual There are a number of points to note: © the generated text including the zero terminator must not be greater than 30 bytes. (Note that this is less than the 80 bytes common for other functions) e the length of the format string in the resource file, when loaded, must not be greater than 80 bytes If an error occurs, p_leave is called. A common use of a flashing message area in the bottom left hand comer of the screen is to display a "busy" type messge to inform the user that the work in progress could take some time to complete. hBeep VOID hBeep (VOID) ; This is a convenience function that makes a short beep sound suitable for accompanying an error notification. It can, of course, be used wherever an application sees fit. The function is implemented by making the following call: P_sound(-5,320); The beep is sounded for a duration of 5 system ticks (that is 5/32 sec) at a frequency of 512/320 KHz (that is 1.6 KHz). 24-9 HWIM REFERENCE SS a ae a a) Run a dialog This group of functions is concerned with starting some standard dialogs and launching dialogs in general. hLaunchDial oe Launch a dialog INT hLaunchDial(P_CATID cat, INT class, DL_DATA *data); This is a convenience routine which loads, initialises and runs a dialog. The parameter cat is the category number of the dialog class while the parameter class is its class number. The pi_para struct is defined in hwimman.g as: typedef struct { UWORD id; /* resource id of a DIALOG resource*/ VOID *rbuf; /* address of result buffer, or NULL */ PR_DLGBOX **pdlg; /* address of where to write handle of dialog, or NULL */ } DL_DATA; The function is implemented as shown below by sending a o_ws_po_pIaL message to the wseRv object. p_sends (w_ws,O_WS_DO DIAL,p_getlibh(cat) ,class, data) ; hLaunchDial returns whatever value that the method o_ws_po_prau returns. This will be zero for dialogs cancelled without the intervention of application code. INT hConfirm(INT rid,...); This is a convenience routine which presents a standard one line query dialog which returns a TRUE or FALSE value. This type of dialog is often used to ask a user to confirm an intended action. The text of the dialog is generated from a format string and (optionally) a number of arguments. The format string is loaded from the resource rid in a resource file while the arguments (if any) are interpreted as for the PLIB function p_atos. More information on p_atos can be found in the PLIB Reference manual. The function is implemented as shown below by sending a o_ws_QUERY_DIALOG message to the WSERV object. p_sends (w_ws,O_ WS QUERY _DIALOG,0,rid,&rid+1l) ; hConfixrm returns whatever value that the method o_ws_QuERY DIALOG retims. This will be rruz if the user confirms the action. There are a number of points to note: e — the length of the format string in the resource file, when loaded, must not be greater than 80 bytes. e the resulting text string must not be greater than 100 bytes. If the resulting text string is sufficiently large to force the width of the resulting dialog box to exceed the width of the window, then a panic will result. _ Run a two: n dialog INT h2LineConfirm(INT secondrid, INT rid, ...); This is a convenience routine which presents a two line query dialog which returns a TRUE or FALSE value. This type of dialog is often used to ask a user to confirm an intended action. The function is very similar to the function hconfirm described earlier. The first line of text of the dialog is generated from a format string and (optionally) a number of arguments. The format string is loaded from the resource rid in a resource file while the arguments (if any) are interpreted as for the PLIB function p_atos. The second line of text is basic text and is loaded from the resource secondrid in a resource file. 24-10 24 HWIM UTILITY FUNCTIONS 2 —S$S ee EI MITT POUNCTIONS | The function is implemented as shown below by sending a o_ws_QUERY_DIALOG message to the wSERV object. p_sends (w_ws,O_WS_QUERY_DIALOG, secondrid, rid, &rid+1) ; h2LineConfirm returns whatever value that the method o_ws_QueRY_praLoc retums. This will be rRus if the user confirms the action. There are a number of points to note: e the length of the format string in the resource file, when loaded, must not be greater than 80 bytes. e the resulting text string must not be greater than 100 bytes. e the second line of text in the resource file must not be greater than 100 bytes. If either of the resulting text strings is sufficiently large to force the width of the resulting dialog box to exceed the width of the window, then a panic will result. INT hErrorDialog(INT err, INT rid, ...); This is a convenience routine which presents an error dialog with text derived from the error number and a string resource. It returns a zero if the dialog was presented successfully. It returns a non-zero value if the dialog presentation failed due to an out of memory error, in which case the dialog remains to be cleaned up (use the OLIB convenience function ci_clean_level, described in The CLEANUP Class chapter in the OLIB Reference manual). The text derived from the resource file is generated from a format string and (optionally) a number of arguments. The format string is loaded from the resource with ID ria, while the arguments (if any) are interpreted as for the PLIB function p_atos. The function is implemented as shown below by sending a o_ws_ERROR_DIALOG message to the WSERV object. p_sends (w_ws,O WS_ERROR_DIALOG, err, rid, &rid+1) ; There are a number of points to note: e the length of the format string in the resource file, when loaded, must not be greater than 80 bytes. e the resulting formatted text string must not be greater than 80 bytes. This type of dialog is often used for the reporting of errors of a moderately serious nature; minor errors should use hinfoprintError described earlier and more serious errors should use the application manager's am_notify method. Dialog box utilities The following utility functions are available for performing standard operations on the component controls of a dialog. They may be used directly by an application, or used as models for the construction of application-specific utilities. The code of each used utility function is included in the application. These functions have optimised calling conventions and therefore offer a modest saving over the equivalent function supplied by the application itself. Note that these utilities assume that the dialog handle is stored in the magic static patpialogPtr. Thus they may not be used with any dialog which contains the pL¢Box_no_pnp flag in dlgbox. flags. _ Set an item VOID hDigSet (UBYTE index, VOID *pset); This function is a generalised way of setting data (or property) into the control of one of the components of the current dialog and is used in the more specialised dialog box utility functions described later. 24-11 HWIM REFERENCE As stated in the introduction to this section, it is assumed that patpialogPtr points to the current dialog object. The particular component within the dialog is identified by the index parameter (the first component is identified by an index value of 0). The parameter pset is assumed to point to the appropriate structure containing the information to be set . The class which defines the referenced dialog box component control, will have defined a o_wn_seT method and will "know" how to interpret the data pointed to by pset. The function is implemented by sending a o_wn_seT message to the current dialog object as shown below: p_send4 (DatDialogPtr,0O_WN_SET, index, pset) ; hbigsé VOID hDlgSetText (UBYTE index, TEXT *buf) ; This function sets text into the control of one of the current dialog's components. The control is assumed to be an instance of rextwrn or a subclass. The particular component within the dialog is identified by the index parameter (the first component is identified by an index value of 0). The parameter bu is assumed to point to a zero terminated string containing the text to be set. This function is implemented as shown below. Note that it uses the more generalised function npigset described earlier. GLDEF_C VOID hDigSetText (UBYTE index, TEXT *buf) { SE_TEXTWIN settxt; settxt .buf=buf; settxt.len=p slen(settxt.buf); settxt.flags=