® For XTND 1.3 XTND Programmer’s Guide ® Developer Technical Publications © Apple Computer, Inc. 1991 Apple Computer, Inc. States and other countries. ARE ASSUMING THE ENTIRE RISK AS Adobe Illustrator and PostScript are TO ITS QUALITY AND ACCURACY. © 1991, Apple Computer, Inc. registered trademarks of Adobe Systems IN NO EVENT WILL APPLE BE LIABLE All rights reserved. Incorporated. FOR DIRECT, INDIRECT, SPECIAL, No part of this publication or the software ITC Garamond and ITC Zapf Dingbats are INCIDENTAL, OR CONSEQUENTIAL described in it may be reproduced, stored in registered trademarks of International DAMAGES RESULTING FROM ANY a retrieval system, or transmitted, in any Typeface Corporation. DEFECT OR INACCURACY IN THIS form or by any means, mechanical, Microsoft is a registered trademark of MANUAL, even if advised of the possibility electronic, photocopying, recording, or Microsoft Corporation. of such damages. otherwise, without prior written permission Claris, MacDraw, and MacWrite are THE WARRANTY AND REMEDIES SET of Apple Computer, Inc., except in the registered trademarks of Claris FORTH ABOVE ARE EXCLUSIVE AND normal use of the software or to make a Corporation. IN LIEU OF ALL OTHERS, ORAL OR backup copy of the software. The same DataViz is a trademark of DataViz, Inc. WRITTEN, EXPRESS OR IMPLIED. No proprietary and copyright notices must be QuickDraw and ResEdit are trademarks of Apple dealer, agent, or employee is affixed to any permitted copies as were Apple Computer, Inc. authorized to make any modification, affixed to the original. This exception does THINK C is a trademark of Symantec extension, or addition to this warranty. not allow copies to be made for others, Corporation. Some states do not allow the exclusion or whether or not sold, but all of the material Simultaneously published in the United limitation of implied warranties or liability purchased (with all backup copies) may be States and Canada. for incidental or consequential damages, so sold, given, or loaned to another person. the above limitation or exclusion may not Under the law, copying includes translating LIMITED WARRANTY ON MEDIA AND apply to you. This warranty gives you into another language or format. You may REPLACEMENT specific legal rights, and you may also have use the software on any computer owned by If you discover physical defects in the other rights which vary from state to state. you, but extra copies cannot be made for manual or in the media on which a software this purpose. product is distributed, APDA will replace the XTND Technology © 1989-1991 Claris media or manual at no charge to you Corporation. All rights reserved. This work provided you return the item to be replaced contains confidential and proprietary with proof of purchase to APDA. information and therefore must be used only ALL IMPLIED WARRANTIES ON THIS in accordance with the license provided MANUAL, INCLUDING IMPLIED Printed in the United States of America. WARRANTIES OF MERCHANTABILITY The Apple logo is a registered trademark of AND FITNESS FOR A PARTICULAR Apple Computer, Inc. Use of the “keyboard” PURPOSE, ARE LIMITED IN DURATION Apple logo (Option-Shift-K) for commercial TO NINETY (90) DAYS FROM THE purposes without the prior written consent DATE OF THE ORIGINAL RETAIL of Apple may constitute trademark PURCHASE OF THIS PRODUCT. infringement and unfair competition in Even though Apple has reviewed this violation of federal and state laws. manual, APPLE MAKES NO WARRANTY Apple Computer, Inc. OR REPRESENTATION, EITHER 20525 Mariani Avenue EXPRESS OR IMPLIED, WITH RESPECT Cupertino, CA 95014-6299 TO THIS MANUAL, ITS QUALITY, 408-996-1010 ACCURACY, MERCHANTABILITY, OR Apple, the Apple logo, APDA, LaserWriter, FITNESS FOR A PARTICULAR PURPOSE. and Macintosh are trademarks of Apple AS A RESULT, THIS MANUAL IS SOLD Computer, Inc., registered in the United “AS IS,” AND YOU, THE PURCHASER, Contents Contents i Figures and Tables iii Chapter 1 Overview 1 About XTND 2 The XTND document model 3 The XTND User Interface 4 The XTND Programming Interface 8 Data Types and Conventions 9 General Information 9 Reserved Characters 10 Paragraph attributes 11 Units of measurement 12 Tabs 12 Chapter 2 Writing XTND-Capable Applications 15 Locating the XTND library 16 Importing a file 17 Implementation of XTNDGetFile 17 Using the XTND Translator to read in the file 24 Saving a file 31 Implementation of XTNDPutFile 31 Using XTND to write the file 32 Matching a file to a translator 39 Selecting a list of translators 41 Rebuilding the list of available translators 44 XTND localization 44 Application localization 45 Translator localization 45 Language matching algorithm 46 i Chapter 3 Writing XTND Translators 47 Translator file structure 48 The 'FTYP' resource 48 Primary version check method—Version bytes 50 Secondary version check method—The 'FDIF' resource 51 An alternative—The 'FINI' resource 51 Translator programming interface 52 Errors 52 Writing a PICT (or Picture) import translator 53 Writing a text import translator 54 Writing the translator 54 Import translator actions 54 directive Values 55 Special characters 58 “Offset” special characters 59 Footnotes 60 Mapping objects and attributes 60 Writing a text export translator 61 Writing to the translator 61 Export translator actions 61 directive values 61 Special characters 64 Footnotes 64 Closing 65 Appendix A 'FTYP' resource format 67 Appendix B Parameter block formats 71 Picture translator parameter block 72 Appendix C Header samples 83 Import directives 84 Export directives 85 Appendix D Code samples 87 FDIF' sample code 88 Picture translator sample code 88 Text import translator sample code 89 Export translator sample code 91 ii XTND Programmer’s Reference Figures and Tables Figure 1-1 Objects imported and exported by XTND translators 3 Figure 1-2 Icon for an XTND translator 5 Figure 1-3 XTND System icon 5 Figure 1-4 A list of files in an Open dialog box 5 Figure 1-5 A pop-up menu in a Save As dialog box 6 Figure 1-6 XTND Translator List icon 7 Figure 1-7 Bit 7 is the most significant 10 Table 1-1 Reserved characters 10 Table 1-2 Structure of the NumParaFmts record 11 Table 1-3 Units field values and corresponding size field types 12 Table 1-4 Sample units field values and corresponding size field types 12 Table 1-5 Tab definitions 13 Table 2-1 TransDescribe block 18 Table 2-2 SFParamBlock 20 Table 2-3 XTNDPutFile-specific parameters 31 Figure 2-1 XTND version (short integer) 45 Table 3-1 PictMisc definition 58 Table 3-2 miscData values 59 Table 3-3 headerStatus and footerStatus variables 63 Table A-1 'FTYP' resource format 68 Table B-1 Picture translator parameter block 72 Table B-2 Import translator parameter block 73 Table B-2 Import translator parameter block (Continued) 74 Table B-2 Import translator parameter block (Continued) 75 Table B-2 Import translator parameter block (Continued) 76 Table B-2 Import translator parameter block (Continued) 77 Table B-2 Import translator parameter block (Continued) 78 Figures and Tables iii Chapter 1 Overview This chapter is an overview of the XTND architecture. It summarizes the XTND document model, user interface, and programming interface. At the end of Chapter 1 is a description of the data types and conventions used throughout this document. 1 About XTND XTND is an architecture that allows Macintosh® applications to read and to write files in a potentially unlimited number of file formats. The XTND architecture includes the following components: n XTND-capable applications, which are linked with a small library of “glue” routines. n The XTND System, a file dynamically loaded by the glue routines. The XTND System enumerates the open-ended set of file translators via the standard XTND search path by displaying a modified Standard File dialog box to select the file and format for reading or writing, loads the appropriate translator, and steps aside to allow the application to communicate directly with the translator. n A standard text document model which specifies the “grammar” of text documents, as well as an Application Programming Interface (API) for reading and writing such standard documents. This API is used to communicate between the application and the translator. n An open-ended set of XTND translator files stored on the Standard XTND search path. Each translator file contains resources for reading and writing one or more file formats. The benefits of this architecture include the following: n The process of importing and exporting foreign file formats is seamlessly integrated into the Open and Save As dialog boxes, minimizing the number of extra steps required to read and write such files. n Users can customize their machines by installing only the required translators. n Applications can share translators. n XTND-capable applications and translators can be released independently, as long as compatibility rules are observed. This document shows you how to implement XTND translator capability in your application. Although this document describes only the importing and exporting of text documents, you can use the XTND System library with other types of translators; only the communication between the application and the translator will change. This document is a part of the XTND Developer’s Kit. The first chapter provides an overview of the XTND document model, user interface, programming interface, and programming conventions. The second chapter describes how to use XTND technology to allow your application to communicate with external code resources, such as file translators. The third chapter describes how to implement XTND-compatible file translators. The appendixes include resource templates and C header files as well as extracts from sample translators. The XTND Developer’s Kit also includes 3.5” floppy disks containing the complete header files and other components necessary to build XTND-capable applications and translators.