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
This is the Win32 (Windows 95, 98, ME, NT and 2000) 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.gmd.de/if-archive/programming/glk/
and Andrew’s Glk web page
http://www.eblong.com/zarf/glk/
The source code and compiled Glk DLL in this package are copyright 1998-2001 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.
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.
As of Windows Glk 1.12, MFC is dynamically linked to Windows Glk, rather than statically linked. This makes the Glk DLL much smaller, but it also means that the MFC DLLs must be installed on your system. In the unlikely case that your system does not have these installed already, download the following file using Internet Explorer
http://activex.microsoft.com/controls/vc/mfc42.cab
Opening the cab file should reveal an executable. Running this will install the MFC DLLs.
Windows Glk supports AIFF sound files. For these to play, you must have Microsoft's Windows Media Player installed. If you don't, you can download the latest version from Microsoft at
http://www.microsoft.com/windows/mediaplayer/
Problems have been reported with earlier versions of Media Player causing the input focus to be removed from the Glk window. If this happens to you, please make sure that you have the latest version.
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.
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.
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.
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().
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 either or both of a custom menu and a custom toolbar. The function takes the numeric identifier of the menu and toolbar 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.
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 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.
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.
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 npmod32.dll, which is part of the ModPlug player by Olivier Lapicque.
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.