Windows Glk 1.21

Contents

Overview
License
Installation
Using a Windows Glk Program
Using Windows Glk with Visual C++
Using Windows Glk with other C compilers
Start-up of a Windows Glk program
Windows specific Glk functions
Example Programs
Graphics and Sound Resources
Acknowledgements
Release History

Overview

Glk API version 0.61, Windows Glk release 1.21

Windows Glk written by David Kinder d.kinder@btinternet.com
Glk devised by Andrew Plotkin erkyrath@eblong.com

This is the Win32 (Windows 95, 98, ME, NT, 2000 and XP) port of Andrew Plotkin’s Glk library, an attempt to define a portable API for text adventures, and more generally, any program with primarily textual input and output.

This help file describes the specifics of the Windows version of Glk, and should be read in conjunction with Andrew’s Glk specification document. This and other relevant files on Glk can be found at the Interactive Fiction Archive, in the directory

ftp://ftp.ifarchive.org/if-archive/programming/glk/

and Andrew’s Glk web page

http://www.eblong.com/zarf/glk/

License

The source code and compiled Glk DLL in this package are copyright 1998-2002 by David Kinder. You may copy and distribute both the source code and the compiled DLL freely, by any means and under any conditions, as long as the code and documentation is not changed. You may also incorporate this code into your own program and distribute that, or modify this code and use and distribute the modified version, as long as you retain a notice in your program or documentation which mentions my name and the Glk web page.

Note that MOD music resources are played using Olivier Lapicque’s ModPlug package. For details of ModPlug’s license, see the ModPlug web page.

Installation

This Windows version of Glk is implemented as a dynamic link library Glk.dll, which must be either in the Windows system directory or the same directory as the Glk application.

Microsoft Speech Engine

As of Windows Glk 1.20, Windows Glk can use Microsoft's Speech Engine API 4.0 to speak text. Microsoft's Speech Engine is often included with speech recognition software. If you have not got the engine installed, it can be downloaded from Microsoft

http://www.microsoft.com/downloads/release.asp?ReleaseID=26299

From this page download and then run "SAPI4SDKSUITE.exe", which is approximately a 40MB download. Microsoft have released a version 5 of their Speech Engine, however I have not yet been able to test whether this will work with Windows Glk.

Translations

Windows Glk supports localization into languages other than English. If the appropriate translation DLL (such as GlkEspañol.dll for Spanish) is present for the language Windows is configured to use, then all Glk dialogs and menus are localized.

Using a Windows Glk Program

Programs using Windows Glk appear to the user as a single Windows frame window containing child windows that correspond with the Glk definition of windows.

By default, Windows Glk adds a toolbar and menu to the frame window, which allows the user to bring up the options dialog, change font settings and review the previous output shown in text buffer windows. These options can also be accessed from the system menu (this is the menu which appears when single-clicking on the icon at the left of the title bar), which is the only means of access if toolbars and menus have been switched off in the options dialog.

If Microsoft's Speech Engine API 4.0 is installed, Windows Glk can speak the text printed in text buffer windows. If the Speech Engine is installed, a "Speech..." button is available on the Options dialog. This opens a further dialog in which speech can be switched on and a voice chosen for the speech.

Using Windows Glk with Visual C++

To use Windows Glk with Microsoft Visual C++ (version 4 or later), use the AppWizard accessed by the File/New menu item to create a new Win32 application.

The application should include the file Glk.c and a file winglk_startup.c, which should contain an implementation of the function winglk_startup_code(). An example of this function is given in the example programs.

The application must also be linked with Glk.lib, which is the import library for Glk.dll.

Using Windows Glk with other C compilers

In general, how Windows Glk is used with other compilers is very dependant on that compiler. However, the following rules must be followed.

The application produced must be a standard Win32 application (not a Win32 console application), whose entry point is the WinMain() function.

The application should include the file Glk.c and a file winglk_startup.c, which should contain an implementation of the function winglk_startup_code(). An example of this function is given in the example programs.

The application must be linked with a suitable import library to ensure dynamic linking with Glk.dll. For most compilers a tool is supplied which takes a dynamic link library and produces a suitable import library (for Microsoft Visual C++ this tool is lib.exe; for Borland C++ it is implib.exe). The supplied import library Glk.lib is for Microsoft Visual C++, but may work with other compilers. For further information, you should consult your compiler documentation.

Start-up of a Windows Glk program

A Windows Glk program should include the source file Glk.c, which implements the WinMain() entry point into the program. The implementation of WinMain() initializes Glk.dll and checks that the version of Glk is suitable for the program. After this, the function winglk_startup_code() is called. This is a function that must be supplied by the author of the Windows Glk program, though at its simplest the function need not do anything at all.

Experienced Win32 developers may wish to implement their own WinMain() function, bypassing the normal Windows Glk startup code. If you do this, you should make sure that InitGlk() is called before glk_main().

Windows specific Glk functions

The prototypes for all these functions can be obtained by including the file WinGlk.h. These functions are all implemented by Windows Glk, except for winglk_startup_code().

int winglk_startup_code(const char* cmdline)

This function must be supplied by the author of the Windows Glk program, and is called before glk_main() in order to allow platform specific initialization. The function should return zero if an error occurred, or a non-zero value if successful. The simplest implementation of the function is

  int winglk_startup_code(const char* cmdline)
  {
    return 1;
  }

The cmdline argument passed to winglk_startup_code() is a pointer to the command line with which the program was started up. See the example program WinGlkStart for an example of this routine which sets the application name and window title, then brings up a file dialog to request a file from the user.

This function is only called from within the WinMain() function in Glk.c. If you decide to write your own WinMain() (only recommended for experienced Win32 developers) then there is no need to supply the winglk_startup_code() function.

void winglk_app_set_name(const char* name)

Call this function to set the name of the Windows Glk program. This name is used as the title for the main window, and for storing user settings such as font and window size. This function should be called in winglk_startup_code(), e.g.

  int winglk_startup_code(void)
  {
    winglk_app_set_name("Glk Example");
    return 1;
  }

void winglk_window_set_title(const char* title)

Call this function to change the window title. This function can be called at any point, either before or after the main window opens. It should be called after winglk_app_set_name().

const char* winglk_get_initial_filename(const char* cmdline, const char* title, const char* filter)

This function is designed to simplify writing startup code for a Windows Glk program. It examines the cmdline argument (which will usually be the cmdline argument passed to winglk_startup_code()) and attempts to extract a file name from it. If you don’t want a command line string to be processed, just pass NULL for cmdline.

If a file name cannot be extracted from cmdline, a file dialog appears prompting the user for a file. The title argument will be used as the title of the file dialog, and the filter argument used as the file dialog’s filter.

The filter string contains pairs of strings, the first part of which is the text describing the file type and the second is the actual filter. Each part is separated by a vertical bar and the end of the filter indicated by two vertical bars. For example, the filter string in Windows Glulxe is

"Glulx Files (.blb;.ulx)|*.blb;*.ulx|All Files (*.*)|*.*||"

The function returns a pointer to the file name if successful, or NULL. If the function does not return NULL, it will also use the filename to set the default filenames for calls to glk_fileref_create_by_prompt().

See the example program WinGlkStart for an example of this routine.

void winglk_set_resource_directory(const char* dir)

Call this function to change the directory from which Glk.dll will attempt to load resources. The default is the current directory for the program.

void winglk_set_gui(unsigned int id)

Call this function in winglk_startup_code() to set up any or all of a custom menu, a custom toolbar and a custom icon for the application's window. The function takes the numeric identifier of the menu, toolbar and icon in your application, e.g.

  winglk_set_gui(IDR_EXAMPLE);

When setting up menus and toolbars, you should keep resource identifiers below 0x7500 and command identifiers below 0xD000. This is not usually a problem as most development environments generate identifiers well below these values.

If the user selects a menu item or clicks on a toolbar button, your application will receive an event of type winglk_evtype_GuiInput. val1 will be the command identifier, and val2 zero.

See the example program WinGlkStart for an example of this routine.

void winglk_load_config_file(const char* gamename)

Call this function to load a Windows Glk configuration file appropriate to the given game file name. For example, if the function is passed an argument of "Photopia.blb", it will attempt to load a configuration file called "Photopia.cfg".

The configuration file is a text file where each line contains a key name, followed by an equals sign, then a value, e.g. "WindowBorders=no". Possible keys are:
WindowBorders=[yes/no] Turns on or off borders between Glk windows
WindowFrame=[yes/no] Turns on or off the Glk application window frame, that is, the title bar and the border around the whole window
WindowMask=[number] Uses the given Blorb resource number to set the mask for the window from the graphic. If a particular pixel in the graphic is white then the window is transparent at that point, else it is opaque.
WindowWidth=[width] Sets the width of the Glk application window to the given value.
WindowHeight=[height] Sets the height of the Glk application window to the given value.
FontName=[font] Sets the font used for proportional text to the given font name, e.g. "Times New Roman".
FontSize=[size] Sets the size of the font used for proportional text to the given value, measured in points.
FixedFontName=[font] Sets the font used for fixed width text to the given font name.
FixedFontSize=[size] Sets the size of the font used for fixed width text to the given value.

strid_t winglk_stream_open_resource(const char* name, const char* type, glui32 rock)

This function opens a Glk memory stream using a resource. The first two arguments specify the name and type of the resource. For example, if data has been stored in the resources of the executable as "EXAMPLE" in the resource type "DATA", then the stream could be opened with rock value 1 by the following call: 

  strid_t str = winglk_stream_open_resource("EXAMPLE","DATA",1);

void* winglk_get_resource_handle(void)

This function returns a handle to the resource module being used by Glk.dll. This is the resource handle of Glk.dll itself unless a translation is being used, in which case it is the resource handle of the translation DLL.

void sglk_set_basename(char *s)

This function sets the default filenames for calls to glk_fileref_create_by_prompt(), which may be useful if you do not use winglk_get_initial_filename() in your startup code. This function is part of L. Ross Raszewski’s (maintainer of DOS Glk) suggested additions to Glk.

Example Programs

The Examples directory contains three example programs. Model and Multiwin are generic Glk example programs written by Andrew Plotkin. WinGlkStart is a Windows Glk specific example, which demonstrates the common requirement of asking the user for a file name at startup.

If you have Visual C++, load up the workspace Examples.dsw, which contains each example as a separate project.
If you are not using Visual C++, then for each example you need to compile the following source files:

Model model.c, winglk_startup.c, Glk.c
Multiwin multiwin.c, winglk_startup.c, Glk.c
WinGlkStart WinGlkStart.c, Glk.c

where Glk.c is the standard Windows Glk source file in the main Glk directory. To create executables you will need to link all the source files in each example together and link along with a suitable import library for Glk.dll.

Graphics and Sound Resources

Windows Glk supports resources stored either in Blorb files or as separate files.

If a Glk program is to use resources from a Blorb file, the standard Blorb function giblorb_set_resource_map() (which is part of Glk.dll) must be called with the identifier of a stream opened on the Blorb file. If this is done then Windows Glk will first look for resources in the Blorb file.

If Windows Glk cannot find a requested resource in the Blorb file (or no Blorb file has been set up), it will look for a suitably named file in the current directory (or the directory specified by a call to winglk_set_resource_directory(), if such a call has been made).

If a resource was found in either the Blorb file or in a directory, it will be loaded. The resource formats currently supported are shown below, along with the filename for which Windows Glk will look if the resource is not in the Blorb file (as an example, the filename is for resource number 1):

Format Type Example Filename
PNG image pic1.png
JPEG image pic1.jpg
AIFF sound snd1.aif or snd1.aiff
MOD music mus1.mod

If PNG images have an alpha channel or transparency information, Windows Glk will use it. In graphics windows PNG images are alpha blended with the graphic window bitmap; in text buffer windows PNG images are alpha blended with the default background colour.

MOD music resources are played using mppsdk.dll, which is part of the ModPlug player by Olivier Lapicque.

Acknowledgements

Spanish translation by Javier San José.

Windows Glk uses the following libraries:

jpeglib by the Independent JPEG Group.
libpng by Guy Eric Schalnat, Andreas Dilger, Glenn Randers-Pehrson, and others.
zlib by Jean-loup Gailly and Mark Adler.
ModPlug by Olivier Lapicque.

Windows Glk also contains source code written by Brent Corkum, Joerg Koenig and Chris Maunder.

Release History

1.21

1.20

1.17

1.16

1.15

1.14

1.13

1.12

1.11

1.10

1.03

1.02

1.01

1.00