HyperCard Script Language Guide The HyperTalk Language Apple Computer, Inc. Adobe Illustrator and PostScript are © 1996 Apple Computer, Inc. trademarks of Adobe Systems All rights reserved. Incorporated, which may be No part of this publication may be registered in certain jurisdictions. reproduced, stored in a retrieval FileMaker, MacPaint, and MacWrite system, or transmitted, in any form are trademarks of Claris or by any means, mechanical, Corporation. electronic, photocopying, recording, FrameMaker is a registered or otherwise, without prior written trademark of Frame Technology permission of Apple Computer, Inc. Corporation. Printed in the United States of Helvetica and Palatino are America. registered trademarks of Linotype The Apple logo is a trademark of Company. Apple Computer, Inc. Use of the ITC Zapf Dingbats is a registered “keyboard” Apple logo (Option- trademark of International Typeface Shift-K) for commercial purposes Corporation. without the prior written consent of Microsoft is a registered trademark Apple may constitute trademark of Microsoft Corporation. infringement and unfair competition in violation of federal and state laws. Simultaneously published in the No licenses, express or implied, are United States and Canada. granted with respect to any of the technology described in this book. Apple retains all intellectual property rights associated with the technology described in this book. LIMITED WARRANTY ON MEDIA This book is intended to assist AND REPLACEMENT application developers to develop ALL IMPLIED WARRANTIES ON THIS IN NO EVENT WILL APPLE BE applications only for Apple MANUAL, INCLUDING IMPLIED LIABLE FOR DIRECT, INDIRECT, Macintosh computers. WARRANTIES OF MERCHANTA- SPECIAL, INCIDENTAL, OR Apple Computer, Inc. BILITY AND FITNESS FOR A CONSEQUENTIAL DAMAGES 20525 Mariani Avenue PARTICULAR PURPOSE, ARE RESULTING FROM ANY DEFECT OR Cupertino, CA 95014 LIMITED IN DURATION TO NINETY INACCURACY IN THIS MANUAL, 408-996-1010 (90) DAYS FROM THE DATE OF THE even if advised of the possibility of such ORIGINAL RETAIL PURCHASE OF damages. Apple, the Apple logo, APDA, THIS PRODUCT. AppleCD SC, AppleLink, THE WARRANTY AND REMEDIES AppleTalk, ImageWriter, Even though Apple has reviewed this SET FORTH ABOVE ARE EXCLUSIVE HyperCard, HyperTalk, LaserWriter, manual, APPLE MAKES NO AND IN LIEU OF ALL OTHERS, ORAL Macintosh, MPW, MultiFinder, WARRANTY OR REPRESENTATION, OR WRITTEN, EXPRESS OR IMPLIED. PowerBook, SANE, and Stackware EITHER EXPRESS OR IMPLIED, WITH No Apple dealer, agent, or employee is are trademarks of Apple Computer, RESPECT TO THIS MANUAL, ITS authorized to make any modification, Inc., registered in the United States QUALITY, ACCURACY, MERCHANTA- extension, or addition to this warranty. BILITY, OR FITNESS FOR A and other countries. Some states do not allow the exclusion PARTICULAR PURPOSE. AS A AppleScript, Chicago, Finder, or limitation of implied warranties or RESULT, THIS MANUAL IS SOLD “AS Geneva, Macintosh Quadra, liability for incidental or consequential IS,” AND YOU, THE PURCHASER, Monaco, New York, QuickDraw, damages, so the above limitation or ARE ASSUMING THE ENTIRE RISK QuickTime, ResEdit, System 7, and exclusion may not apply to you. This AS TO ITS QUALITY AND WorldScript are trademarks of warranty gives you specific legal rights, ACCURACY. Apple Computer, Inc. and you may also have other rights which vary from state to state. Contents Figures and Tables xiii Preface About This Guide xix What’s in This Book? xix Notation Conventions xxi Changes Since the First Edition of This Guide xxii Apple Developer Programs xxiii Chapter 1 What’s New Since 2.0? 1 HyperCard System Requirements 1 HyperCard Enhancements 2 WorldScript Compatibility 3 HyperCard and Other Scripting Systems 3 Open Scripting Architecture 4 AppleScript 5 Script Attachability 6 Script Editor Enhancements 7 Button Dialog Modifications 7 New Button Features 8 Field Dialog Modifications 12 New Field Features 13 Integrated Stand-Alone Application Builder 14 Enhanced HyperTalk 15 Chapter 2 HyperTalk Basics 23 What Is HyperTalk? 23 Objects 24 Buttons and Fields 24 Cards, Backgrounds, and Stacks 25 iii Messages 25 Scripts 26 Message Handlers 26 Function Handlers 27 Windows 28 Card Windows 28 HyperCard’s Built-in External Windows 30 Menus 30 Chapter Summary 32 Chapter 3 The Scripting Environment 33 Getting to the Script 33 The Script Editor 35 Manipulating Text 37 Searching for Text 38 Replacing Text 39 Entering Comments 39 Formatting Scripts 40 Line Length and Script Size 41 Script Editor Command Summary 41 The Debugger Environment 43 Setting Checkpoints 45 HyperTalk Debugger Windows 45 Message Watcher 46 Variable Watcher 47 Custom Message Watcher and Variable Watcher XCMDs 48 Debugger Command Summary 49 Chapter Summary 50 Chapter 4 Handling Messages 51 The HyperCard Environment 51 Sending Messages 52 System Messages 52 Statements as Messages 53 iv Message Box Messages 53 Messages Resulting From Commands 54 Receiving Messages 55 Message-Passing Hierarchy 56 Where Messages Go 56 Messages to Buttons and Fields 58 The Current Hierarchy 59 The Target 61 The User-Defined Hierarchy 62 The Dynamic Path 67 The Go Command and the Dynamic Path 67 The Send Keyword and the Dynamic Path 69 Handlers Calling Handlers 71 Subroutine Calls 71 Recursion 72 Using the Hierarchy 73 Sharing Handlers 73 Intercepting Messages 76 Parameter Passing 77 Chapter Summary 79 Chapter 5 Referring to Objects, Menus, and Windows 81 Names, Numbers, and IDs 81 Object Names 83 Object Numbers 84 Part Numbers 85 Button Families 87 Special Ordinals 87 Object Numbers and Tab Order 87 Object ID Numbers 88 Special Object Descriptors 89 Identifying a Stack 89 Naming a Stack 91 Combining Object Descriptors 92 Referring to Menus and Menu Items 93 v Menu and Menu Item Names 93 Menu and Menu Item Numbers 93 Referring to Windows 96 Chapter Summary 97 Chapter 6 Values 99 Constants 99 Literals 100 Functions 100 Properties 101 Numbers 101 Standard Apple Numerics Environment 102 Precision 102 Number Handling 103 Containers 103 Fields 104 Buttons 104 Variables 105 Scope of Variables 106 Parameter Variables 106 The Variable It 106 Menus 107 The Selection 107 The Message Box 108 Chapter Summary 109 Chapter 7 Expressions 111 Complex Expressions 111 Factors 111 HyperTalk Operators 113 Operator Precedence 117 Operators and Expression Type 118 Chunk Expressions 118 Syntax of Chunk Expressions 119 vi Characters 120 Words 120 Items 120 Lines 121 Ranges 121 Chunks and Containers 122 Chunks as Destinations as Well as Sources 123 Nonexistent Chunks 124 Chapter Summary 124 Chapter 8 System Messages 125 Messages and Commands 125 Messages Sent to a Button 126 Messages Sent to a Field 128 Messages Sent to the Current Card 131 Message Order 138 Chapter 9 Control Structures and Keywords 141 Keywords in Message Handlers 141 Message Handler Example 144 Keywords in Function Handlers 145 Function Handler Example 149 Repeat Structure 149 Repeat Statements 150 If Structure 155 Single-Statement If Structure 155 Multiple-Statement If Structure 156 Nested If Structures 157 Chapter 10 Commands 165 Redefining Commands 165 Syntax Description Notation 166 vii System 7 Commands 167 Command Descriptions 167 Chapter 11 Functions 289 Function Calls 289 Syntax Description Notation 290 Function Descriptions 291 Chapter 12 Properties 357 Retrieving and Setting Properties 357 Object Properties 358 Stack Properties 359 Background Properties 360 Card Properties 361 Field Properties 362 Button Properties 365 Rectangle Properties 367 Environmental Properties 368 Global Properties 369 Painting Properties 372 Window Properties 374 Menu, Menu Bar, and Menu Item Properties 375 Message Watcher and Variable Watcher Properties 376 HyperCard Property Descriptions 377 Appendix A External Commands and Functions 503 Definitions, Uses, and Examples 503 XCMD and XFCN Resources 503 Uses for XCMDs and XFCNs 504 Using an XCMD or XFCN 504 Invoking XCMDs and XFCNs 505 Message-Passing Hierarchy 505 viii Guidelines for Writing XCMDs and XFCNs 507 Attaching an XCMD or XFCN 508 Parameter Block Data Structure 509 Passing Parameters to XCMDs and XFCNs 510 ParamCount 510 Params 510 Passing Back Results to HyperCard 510 ReturnValue 510 PassFlag 511 Callbacks 511 EntryPoint 511 Request 511 Result 511 InArgs 512 OutArgs 512 Callback Procedures and Functions 512 HyperTalk Utilities 513 Memory Utilities 514 String Utilities 514 String Conversions 515 Field Utilities 518 Miscellaneous Utilities 519 Creating and Disposing of External Windows 522 Window Utilities 525 Text Editing Utilities 529 Script Editor Utilities 530 Variable Watcher Support 532 Debugger Support 533 External Windows 534 Events in External Windows 536 Handling Events 537 Closing an External Window 540 Special XCmdBlock Values 540 Message Watcher 541 Variable Watcher 541 Script Editor 541 Debugger 542 ix XTalkObject 542 Window Layer Management 543 Flash: An Example XCMD 545 Flash Listing in MPW Pascal 546 Flash Listing in MPW C 548 Flash Listing in 68000 Assembly Language 550 Appendix B Constants 553 Appendix C Enhancing the Execution Speed of HyperCard 555 Change Stacks as Seldom as Possible 556 Use Variables, Not Fields, for Operations 556 Refer to a Remote Card Rather Than Going There 557 Migrate to XCMDs and XFCNs for Repetitive Tasks 558 Set LockScreen to True to Avoid Needless Redrawing 558 Set LockMessages to True During Card-to-Card Data Collection 558 Combine Multiple Messages 558 Take Unnecessary Code Out of Loops 559 Use In-Line Statements Rather Than Handler Calls 559 Do Complex