Glk: A Portable Interface Standard for IF API specification version 0.7.5 Maintained by IFTF: <[email protected]> Copyright 2020 by the Interactive Fiction Technology Foundation. This specification is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License: http://creativecommons.org/licenses/by-nc- sa/3.0 The API described by this document is an idea, not an expression of an idea, and is therefore not copyrightable. Anyone is free to write programs that use the Glk API or libraries that implement it. This document and further Glk information can be found at: https://github.com/iftechfoundation/ifarchive-if-specs 0. Introduction 0.1. What Glk Is 0.2. What About the Virtual Machine? 0.3. What Does Glk Not Do? 0.4. Conventions of This Document 0.5. Credits 1. Overall Structure 1.1. Your Program's Main Function 1.2. Exiting Your Program 1.3. The Interrupt Handler 1.4. The Tick Thing 1.5. Basic Types 1.6. Opaque Objects 1.6.1. Rocks 1.6.2. Iterating Through Opaque Objects 1.7. The Gestalt System 1.8. The Version Number 1.9. Other API Conventions 2. Character Encoding 2.1. Testing for Unicode Capabilities 2.2. Output 2.3. Line Input 2.4. Character Input 2.5. Upper and Lower Case 2.6. Unicode String Normalization 2.6.1. A Note on Unicode Case-Folding and Normalization 3. Windows 3.1. Window Arrangement 3.2. Window Opening, Closing, and Constraints 3.3. Changing Window Constraints 3.4. A Note on Display Style 3.5. The Types of Windows 3.5.1. Blank Windows 3.5.2. Pair Windows 3.5.3. Text Buffer Windows 3.5.4. Text Grid Windows 3.5.5. Graphics Windows 3.6. Echo Streams 3.7. Other Window Functions 4. Events 4.1. Character Input Events 4.2. Line Input Events 4.3. Mouse Input Events 4.4. Timer Events 4.5. Window Arrangement Events 4.6. Window Redrawing Events 4.7. Sound Notification Events 4.8. Hyperlink Events 4.9. Other Events 5. Streams 5.1. How To Print 5.2. How To Read 5.3. Closing Streams 5.4. Stream Positions 5.5. Styles 5.5.1. Suggesting the Appearance of Styles 5.5.2. Testing the Appearance of Styles 5.6. The Types of Streams 5.6.1. Window Streams 5.6.2. Memory Streams 5.6.3. File Streams 5.6.4. Resource Streams 5.7. Other Stream Functions 6. File References 6.1. The Types of File References 6.2. Other File Reference Functions 7. Graphics 7.1. Image Resources 7.2. Graphics in Graphics Windows 7.3. Graphics in Text Buffer Windows 7.4. Testing for Graphics Capabilities 8. Sound 8.1. Sound Resources 8.2. Creating and Destroying Sound Channels 8.3. Playing Sounds 8.4. Other Sound Channel Functions 8.5. Testing for Sound Capabilities 9. Hyperlinks 9.1. Creating Hyperlinks 9.2. Accepting Hyperlink Events 9.3. Testing for Hyperlink Capabilities 10. The System Clock 10.1. Time and Date Conversions 10.2. Testing for Clock Capabilities 11. Porting, Adapting, and Other Messy Bits 11.1. Startup Options 11.2. Going Outside the Glk API 11.2.1. Memory Management 11.2.2. String Manipulation 11.2.3. File Handling 11.2.4. Private Extensions to Glk 11.3. Glk and the Virtual Machine 11.3.1. Implementing a Higher Layer Over Glk 11.3.2. Glk as a VM's Native API 12. Appendices 12.1. The Dispatch Layer 12.1.1. How This Works 12.1.2. Interrogating the Interface 12.1.3. Dispatching 12.1.3.1. Basic Types 12.1.3.2. References 12.1.3.3. Structures 12.1.3.4. Arrays 12.1.3.5. Return Values 12.1.4. Getting Argument Prototypes 12.1.5. Functions the Library Must Provide 12.1.5.1. Opaque Object Registry 12.1.5.2. Retained Array Registry 12.1.6. Table of Selectors 12.2. The Blorb Layer 12.2.1. How This Works 12.2.2. What the Program Does 12.2.3. What the Library Does 12.2.4. What the Blorb Layer Does 12.2.5. Blorb Errors 0. Introduction 0.1. What Glk Is Glk defines a portable API (programming interface) for applications with text UIs (user interfaces.) It was primarily designed for interactive fiction, but it should be suitable for many interactive text utilities, particularly those based on a command line. Rather than go into a detailed explanation of what that means, let me give examples from the world of text adventures. TADS, Glulx, and Infocom's Z-machine have nearly identical interface capabilities; each allows a program to... · print an indefinite stream of text into an output buffer, with some style control · input a line of text · display a few lines of text in a small separate window · store information in a file, or read it in and so on. However, the implementation of these capabilities vary widely between platforms and operating systems. Furthermore, this variance is transparent to the program (the adventure game.) The game does not care whether output is displayed via a character terminal emulator or a GUI window; nor whether input uses Mac-style mouse editing or EMACS-style control key editing. On the third hand, the user is likely to care deeply about these interface decisions. This is why there are Mac-native interpreters on Macintoshes, stylus and touch-screen interpreters on mobile devices, and so on – and (ultimately) why there are Macintoshes and iPads and terminal window apps in the first place. On the fourth hand, TADS and Inform are not alone; there is historically a large number of text adventure systems. Most are obsolete or effectively dead; but it is inevitable that more will appear. Users want each living system ported to all the platforms in use. Users also prefer these ports to use the same interface, as much as possible. This all adds up to a pain in the ass. Glk tries to draw a line between the parts of the text adventure world which are identical on all IF systems, and different on different operating systems, from the parts which are unique to each IF system but identical in all OSs. The border between these two worlds is the Glk API. My hope is that a new IF system, or existing ones which are less-supported (Hugo, AGT, etc) can be written using Glk for all input and output function. The IF system would then be in truly portable C. On the other side of the line, there would be a Glk library for each operating system and interface (Macintosh, X-windows, curses-terminal, etc.) Porting the IF system to every platform would be trivial; compile the system, and link in the library. Glk can also serve as a nice interface for applications other than games – data manglers, quick hacks, or anything else which would normally lack niceties such as editable input, macros, scrolling, or whatever is native to your machine's interface idiom. 0.2. What About the Virtual Machine? You can think of Glk as an IF virtual machine, without the virtual machine part. The "machine" is just portable C code. An IF virtual machine has been designed specifically to go along with Glk. This VM, called Glulx, uses Glk as its interface; each Glk call corresponds to an input/output opcode of the VM. For more discussion of this approach, see section 11.3, "Glk and the Virtual Machine". Glulx is documented at http://eblong.com/zarf/glulx/. Of course, Glk can be used with other IF systems. The advantage of Glulx is that it provides the game author with direct and complete access to the Glk API. Other IF systems typically have an built-in abstract I/O API, which maps only partially onto Glk. For these systems, Glk tends to be a least-common-denominator interface: highly portable, but not necessarily featureful. (Even if Glk has a feature, it may not be available through the layers of abstraction.) 0.3. What Does Glk Not Do? Glk does not handle the things which should be handled by the program (or the IF system, or the virtual machine) which is linked to Glk. This means that Glk does not address · parsing · game object storage · computation · text compression 0.4. Conventions of This Document This document defines the Glk API. I have tried to specify exactly what everything does, what is legal, what is illegal, and why. Sections in square brackets [like this] are notes. They do not define anything; they clarify or explain what has already been defined. If there seems to be a conflict, ignore the note and follow the definition. [Notes with the label "WORK" are things which I have not yet fully resolved. Your comments requested and welcome.] This document is written for the point of view of the game programmer – the person who wants to use the Glk library to print text, input text, and so on. By saying what the Glk library does, of course, this document also defines the task of the Glk programmer – the person who wants to port the Glk library to a new platform or operating system. If the Glk library guarantees something, the game programmer can rely on it, and the Glk programmer is required to support it. Contrariwise, if the library does not guarantee something, the Glk programmer may handle it however he likes, and the game programmer must not rely on it. If something is illegal, the game programmer must not do it, and the Glk programmer is not required to worry about it.