Overview
License
Installation
Using a Windows Glk Program
Using Windows Glk with Visual C++
Using Windows Glk with Cygwin
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 a Windows implementation of Andrew Plotkin's Glk library specification, an attempt to define a portable API for text adventures, and more generally, any program with primarily textual input and output. It works with any version of Windows from Windows 95 onwards.
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
http://www.ifarchive.org/indexes/if-archiveXprogrammingXglulx.html
and Andrew's Glk web page
http://www.eblong.com/zarf/glk/
Windows Glk is copyright 1998-2023 by David Kinder, and is distributed under the MIT license:
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Ogg Vorbis music resources are played using libogg and libvorbis by the Xiph.org Foundation. The license for these libraries is as follows:
Copyright (c) 2002, Xiph.org Foundation
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of the Xiph.org Foundation nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This Windows version of Glk is implemented as a dynamic link library Glk.dll, which should be in the same directory as the Glk application.
Windows Glk can use Microsoft's Speech Engine to speak text. This is included in most recent versions of Windows, and for earlier versions is available as a download from Microsoft.
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 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 the toolbar and menus have been switched off in the options dialog.
To use Windows Glk with Microsoft Visual C++, use the 'New Project' wizard accessed from the File/New menu to create a new Win32 application project.
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.
Although not required, the appearance of the application under will be improved if an application manifest is included that specifies a dependency on version 6.0 of the common controls library. The details of how to set up a manifest vary significantly between Visual C++ versions, so you should consult the Visual C++ help for more information.
To use Windows Glk with Cygwin's version of the GCC compiler (available from http://www.cygwin.com/), open a Cygwin Bash shell and generate an import library to link against:
dlltool --dllname=Glk.dll --def=Glk.def --output-lib=libglk.a
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 the library libglk.a; should not use the Cygwin DLL; and should be marked as being a Windows GUI application. For example, the command line to build the example model program under Cygwin is
gcc model.c winglk_startup.c Glk.c -o model -lglk -L. -mno-cygwin -mwindows
As noted above, though not required, it is good practice to include an application manifest. To use this with Cygwin, create a file Glk.manifest that contains the XML. Create a resource compiler script containing the following line
1 24 "Glk.manifest"
Compile the manifest to an object file with the command line
windres Glk.rc GlkRes.oFinally, include the generated GlkRes.o file in the list of files passed to the compiler in order to create the final executable.
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.
As noted above, though not required, it is good practice to include an application manifest. How this is to be done will depend on the compiler: most Windows compilers include some way to generate an object file containing resources that can then be linked into the final executable.
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().
void winglk_set_about_text(const char* text)
Call this function to set the text that appears in the first line of the About dialog box. The text should contain the name and version number of the application.
void winglk_set_menu_name(const char* name)
Call this function to set the name of the default Glk menu. The short cut key is indicated by a leading ampersand; for example, a name of "&Glulxe" produces the menu name Glulxe. The menu name is also used in the name of the menu item showing the About dialog, and in the text in that dialog.
void winglk_set_help_file(const char* filename)
Call this function to set the path of a HTMLHelp format help file. Calling this function causes a "Help" item to appear in the menu and a "Help" button on the toolbar.
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 (.ulx;.blb;.blorb;.glb;.gblorb)|*.ulx;*.blb;*.blorb;*.glb;*.gblorb|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 a custom icon for the application's window, and also optionally a custom menu. The function takes the numeric identifier of the icon and menu resources in your application, e.g.
winglk_set_gui(IDR_EXAMPLE);When setting up menus, 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 custom menu item, 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. This key only takes effect if "WindowFrame=no". WindowWidth=[width] Sets the width of the Glk application window so that a single, full-size Glk window will have a width of the given value. WindowHeight=[height] Sets the height of the Glk application window so that a single, full-size Glk window will have a height of the given value. FullScreen=[yes/no] If set to "yes", the Glk application window opens filling the entire screen. FontName=[font] Sets the font used for proportional text to the given font name, e.g. "Times New Roman". FixedFontName=[font] Sets the font used for fixed width text to the given font name. FontSize=[size] Sets the size of the fonts to the given value, measured in points. FontFile=[filename] The name of a font file (usually ending in ".ttf") to load fonts from. strid_t winglk_stream_open_resource(const char* name, const char* type, glui32 rock)
This function opens a Glk memory stream from a Windows resource (that is, a Win32 resource embedded in the executable). The first two arguments specify the name and type of the Win32 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.
frefid_t winglk_fileref_create_by_name(glui32 usage, char *name, glui32 rock, int validate)
This function is the same as glk_fileref_create_by_name(), except that it takes an extra validate argument. If validate is non-zero then the name argument is validated to remove directory separator characters; if it is zero then the name argument is not checked.
void winglk_show_game_dialog(void)
This function tells Glk.dll to show the "About This Game" dialog when a Blorb file is set by a call to giblorb_set_resource_map(), provided that the Blorb file contains an "IFmd" chunk, and that the dialog has not been shown for this game before. If the "IFmd" chunk is present, an "About This Game" menu item is also added to the application's menu, the game's title is included in the title of the Windows Glulxe window, and an option to control whether the dialog is shown initially appears in the options dialog.
void void garglk_set_zcolors_stream(glui32 fg, glui32 bg)
If the given stream is a window stream, this function sets the foreground and background colours, independent of what the selected window style is. If either argument is -1 the appropriate colour is the default for the current style, if either is -2 the colour is not changed.
void garglk_set_zcolors(glui32 fg, glui32 bg)
As above, but acting on the default stream.
void garglk_set_reversevideo_stream(strid_t str, glui32 reverse)
If the given stream is a window stream, this function sets whether the foreground and background colours are reversed, independent of what the selected window style is.
void garglk_set_reversevideo(glui32 reverse)
As above, but acting on the default stream.
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 (the 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.
For example, with Cygwin, the command to build the model example would be:
gcc model.c winglk_startup.c Glk.c -o model -lglk -L. -mno-cygwin -Wl,--subsystem,windows
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 Ogg Vorbis music mus1.ogg text data data1.txt binary data data1.bin
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.
The user interface for Windows Glk has been translated into Spanish by Javier San José, into Italian by Tommaso Caldarola, and into Russian by Nikita Tseykovets.
Windows Glk contains bitmap scaling code written by Eran Yariv. The code that handles Ogg Vorbis music resources is based on code submitted by David Moreno.
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.
libogg and libvorbis by the Xiph.org Foundation.
ModPlug by Olivier Lapicque.