Readme for GLKDos 0.19.1 by L. Ross Raszewski Based upon GlkTerm 0.7.2 by Andrew Plotkin Implements Glk 0.6.1 Library source for DJGPP and compatable compilers. This implementation of the GLK specification is mostly compatable with GlkTerm, with the following features: Sound (AIFF and MOD) support Color run-time configuration (press Alt-F1 to access the menu) screen capture user macro keys Shell-to-dos Copy buffer ("clipboard") graphics-mode output User-settable fonts Scrollable virtual screen Graphics windows Blorb images in graphics and textbuffer windows. Open file listbox sglk extensions User-configurable keybindings Mouse The sound, configuration, and output modules are optional at compile-time; it may be useful to use a less-fully featured glkDOS if the application does not require certain features, as it will reduce compile time and executable size (or if you don't want to be bothered to go out searching for the required libraries) the makefile includes targets for building eight different versions of the library: glkDOS classic: (glkt) supports sound and user configuration files. Sound support is provided via Allegro and JGMod, which are required for compilation of glkDOS programs. Text output is provided by PDCurses (compatable curses libraries may be substituted), which is required for compilation. Config file support is provided by GNU Flex, which is required for compilation glkDOS without sound: (glks) glkDOS classic without sound support. Allegro and JGMod are not required for compilation. glkDOS without config files: (glkc) glkDOS classic without config file support. Flex is not required. glkDOS bare-bones: (glkn) The smallest version of the glkDOS library. Provides neither sound nor configuration files, and thus requires only curses. glkDOS classic, PC-BIOS accelerated version: (glkd) This version is almost identical to glkDOS classic, but uses DJGPP specific functions for accessing PC video memory in an optimized manner. Allegro glkDOS: (glka/glkan) In addition to sound, Allegro may also be used for text output. This build supports several graphical resolutions, several user fonts, and a "virtual screen", which can be used to simulate a higher resolution than is actually in use. This build requires Allegro, JGMod, and flex, but not the curses library. (The curses.h is required to build the library itself, however). "glka" also provides support for displaying Blorb images. It requires zlib, libpng, and the independant jpeg group's software. glkDOS/Unix: (glku) There has been some desire expressed to have the suite of advanced glkDOS features available on unix systems. In response, I have retroported glkDOS back to its origins. This mode is experimental, and should be treated with care. And a menu-driven system exists to pick-and-choose glk features and build glkDOS accordingly. Some video cards may require VBE/AF drivers to run Alegro GlkDOS correctly. The free VBE/AF driver is available from the allegro homepage questions, comments, and suggestions should be mailed to L. Ross Raszewski, rraszews@acm.org Also included is a precompiled version of the GLKDos library. ----------------- GlkDOS: 0.9.2 -- a (formerly) brief users guide. ( Aside: This document contains some commentary. It's set off in little "aside" notations, and explains some of the reasoning behind what might be considered "strange" or "bad" decisions on my part. ) 1. Compiling glkdos [This section is largely superceded by the graphical configuration toy.] Compiling glkDOS is facilitated by the graphical configuration system. type "config" to start the system. You will be presented with a screen like this: GlkDOS Configuration Target CSCR module *default (glkt) curses alleg (glka) dos dos (glkd) allegro allegn (glkan) unix ncurses no_sound (glks) no_config (glkc) no_frills (glkn) unix (glku) custom (glk) Options [*] sound Write makefile and compile [*] config files [ ] graphics Use the up and down arrow keys to navigate, to switch between option groups, and to select an option. quits. a '*' indicates selected options. Certain option groups are incompatable, and will be "greyed out" (graphics is only available under allegro, for example. Likewise, sound is always included under allegro). Most importantly, the 'Options' and 'CSCR Module' selections are only available when 'custom' is selected. Once you've chosen the combination you want, selecting "write makefile and compile" builds the glk library. If you're building a "custom" library, the library is called "libglk.a", and the makefile "make.gll". Otherwise, the naming conventions below apply. Also, once a custom build has been made using the configurator, the makefile target 'make custom' becomes available, which builds the library according to whatever specifications were last used in the graphical tool. 1.1 Compiling the curses version of glkdos 1.1.1 Compiling the full suite of glkdos (curses library) features: (glkt) requires: DJGPP 2.7.2.1 GNU Make GNU flex PDCurses or compatable curses library Allegro game programming library JGMod module player library This distribution of GlkDOS defaults to this configuration. After unpacking the source, run "make" at your command prompt. Assuming all goes well, this should create libglkt.a, the GlkDOS library binary, and make.glk, the makefile definitions for using GlkDOS. NOTE:: You may need to set the makefile variable BASE_LIBS to the name of your curses library. For most standard DJGPP Curses installations, you will want: BASE_LIBS = -lcurso 1.1.2 Compiling glkdos without config file support: (glkc) requires: As in section 1.1, EXCEPT: GNU flex Make GlkDOS compile without config file support, build the library with the following command: make no_config This will build libglkc.a without config file support, and make.glc. It is not necessary to link the flex library when building Glk programs for this library. 1.1.3 Compiling glkdos without sound: (glks) requires: As in section 1.1, EXCEPT: Allegro game programming library JGMod module player library to build GlkDOS without sound support, use the following make command: make no_sound This will build libglks.a without sound support, and make.gls. It is not necessary to link the standard math library, allegro, or jgmod to build glk applications 1.1.4 Compiling with neither sound nor config files (glkn) make no_frills 1.2 Compiling the PC-BIOS accelerated version of glkDOS requires DJGPP 2.7.2.1 GNU Make GNU flex Allegro game programming library JGMod module player library type 'make dos' to build libglkd.a and make.gld This version of the library supports all the features of glkDOS classic. Targets are not provided for compiling the PC-BIOS versions with features omitted. Such functionality can be easily constructed by careful examination of the other makefile targets, or via the configuration toy. (Aside: why do this version at all? This version of glkDOS was designed for users without curses, who wanted a smaller binary, or who needed a (very) slightly faster glk. It adds several additional sub-features: screen redraws are synchronized to the monitor refresh the original screen state is restored on exit Also, this version is a stepping-stone toward a proposed dual-mode glkDOS ) 1.3 Compiling the allegro version of glkDOS 1.3.1 Compiling glkDOS/Allegro without image support (glkan) requires: DJGPP 2.7.2.1 GNU Make GNU flex Allegro game programming library JGMod module player library type make allegn This will build libglkan.a and make.glg. The allegro version of glkDOS supports sound and config files, but does not offer text-mode only output. The "glkan" version offers graphics windows, but only the rectangle drawing functions are available for such windows. (this is the "stripped down" version of glkDOS/Allegro, and is provided only because it is substantially smaller, and requires fewer outside libraries to compile) 1.3.2 Compiling glkDOS/Allegro with image support (glka) requires: As section 1.2.1, plus Zlib compression library The Independant Jpeg Group's jpeg library libpng png library type make alleg This will build libglka.a and make.gla. This allegro version additionally supports jpeg and png images. 1.4 Compiling glkDOS/Unix GlkDOS/Unix can only be compiled on a *nix machine. requires: gcc flex ncurses make 'make unix' will produce libglku.a and make.glu 1.5 To compile all the libraries at once: make all will build the following libraries: libglkt.a GlkDOS with sound and config file support libglks.a GlkDOS with config file support libglkc.a GlkDOS with sound support libglkn.a GlkDOS without config file or sound support libglka.a GlkDOS with allegro graphical output. libglkan.a GlkDOS/Allegro without jpeg or PNG support. libglkd.a GlkDOS with PC-BIOS acceleration and the following makefile supplements: make.glk for libglkt make.gls for libglks make.glc for libglkc make.gln for libglkn make.gla for libglka make.glg for libglkan make.gld for libglkd * make all will _not_ build GlkDOS/Unix, nor will it build the "custom" glk. 1.5 Other Makefile targets: target effect requires source_arc produces glktds.zip source archive zip archiver bin_arc produces glktdb.zip library archive zip archiver dist source_arc bin_arc zip archiver clean removes all intermediate files rm config produces config.exe to use the cdos CSCR module custom rebuilds the last "custom" library config's makefile.cst the "zip archiver" is any command line program which can generate zip files. the makefile variable "ZIP" holds the name of this archiver 2. compiling with glkdos 2.1 Implementation-dependant features. GlkDOS provides several platform-bound features which are not directly part of Glk. They involve additional code which should be added to a Glk program only when it is compiled under glkDOS. 2.1.1 file name base **This section is superceeded by the sglk control sglk_set_basename. glkdos_set_basename still works, but shoudl be considered "less portable" Since Glk does not know anything about the program which it is running, it is difficult to make prompted file names provide sensible defaults. Some platforms may have facilities which make it possible for glk to infer a something about what it is doing, but DOS does not. GlkDOS allows the author to specify the "base name" for default file names during library initialization. The function: glkdos_set_basename(char *str); sets the base of the prompted file names to str. (subsequent user input will change the default). This function should be called at the same time as the parsing of command line parameters (probably from glkunix_startup_code; see below), though it will still function if called later. If glkdos_set_basename is never called, the library will try its darndest to choose a sensible default (by extracting the base name of the executable). 2.1.2 glk startup code. GlkDOS uses the startup code identical to glkterm. The following is an extract from the glkterm documentation elaborating... (Unlike set_basename, these functions still use the "glkunix" prefix; this is in order to allow programs to use the same code between unix and DOS glks) --------------------- When you compile a Glk program and link it with GlkTerm, you must supply one more file: you must define a function called glkunix_startup_code(), and an array glkunix_arguments[]. These set up various Unix-specific options used by the Glk library. There is a sample "glkstart.c" file included in this package; you should modify it to your needs. The glkunix_arguments[] array is a list of command-line arguments that your program can accept. The library will sort these out of the command line and pass them on to your code. The array structure looks like this: typedef struct glkunix_argumentlist_struct { char *name; int argtype; char *desc; } glkunix_argumentlist_t; extern glkunix_argumentlist_t glkunix_arguments[]; In each entry, name is the option as it would appear on the command line (including the leading dash, if any.) The desc is a description of the argument; this is used when the library is printing a list of options. And argtype is one of the following constants: glkunix_arg_NoValue: The argument appears by itself. glkunix_arg_ValueFollows: The argument must be followed by another argument (the value). glkunix_arg_ValueCanFollow: The argument may be followed by a value, optionally. (If the next argument starts with a dash, it is taken to be a new argument, not the value of this one.) glkunix_arg_NumberValue: The argument must be followed by a number, which may be the next argument or part of this one. (That is, either "-width 20" or "-width20" will be accepted.) glkunix_arg_End: The glkunix_arguments[] array must be terminated with an entry containing this value. To accept arbitrary arguments which lack dashes, specify a name of "" and an argtype of glkunix_arg_ValueFollows. If you don't care about command-line arguments, you must still define an empty arguments list, as follows: glkunix_argumentlist_t glkunix_arguments[] = { { NULL, glkunix_arg_End, NULL } }; Here is a more complete sample list: glkunix_argumentlist_t glkunix_arguments[] = { { "", glkunix_arg_ValueFollows, "filename: The game file to load." }, { "-hum", glkunix_arg_ValueFollows, "-hum NUM: Hum some NUM." }, { "-bom", glkunix_arg_ValueCanFollow, "-bom [ NUM ]: Do a bom (on the NUM, if given)." }, { "-goo", glkunix_arg_NoValue, "-goo: Find goo." }, { "-wob", glkunix_arg_NumberValue, "-wob NUM: Wob NUM times." }, { NULL, glkunix_arg_End, NULL } }; This would match the arguments "thingfile -goo -wob8 -bom -hum song". After the library parses the command line, it does various occult rituals of initialization, and then calls glkunix_startup_code(). int glkunix_startup_code(glkunix_startup_t *data); This should return TRUE if everything initializes properly. If it returns FALSE, the library will shut down without ever calling your glk_main() function. The data structure looks like this: typedef struct glkunix_startup_struct { int argc; char **argv; } glkunix_startup_t; The fields are a standard Unix (argc, argv) list, which contain the arguments you requested from the command line. In deference to custom, argv[0] is always the program name. You can put other startup code in glkunix_startup_code(). This should generally be limited to finding and opening data files. There are a few Unix Glk library functions which are convenient for this purpose: strid_t glkunix_stream_open_pathname(char *pathname, glui32 textmode, glui32 rock); This opens an arbitrary file, in read-only mode. Note that this function is *only* available during glkunix_startup_code(). It is inherently non-portable; it should not and cannot be called from inside glk_main(). ----------------- 2.1.3 sglk sglk is a set of extensions to glk which are unique to this library. they take advantage of the platform to increase flexibility. These features are, of course, non-portable, and "should not be used". (Alternatively, if these features are found handy, they may be added to future glk versions, but that's up to Zarf) Other Glk porters are asked to be kind and consider implementing as many of these functions as is convenient. The header file for sglk is sglk.h. It defines the following functions: void sglk_set_style(strid_t str, glui32 fg, glui32 bg, glui32 attr); This function "tweaks" the appearance of the given stream. Its output will be set to the specified foreground and background colors (or as close as glkDOS can come to matching them). The special value SGLK_DEFAULT means "whatever color the current style is usually rendered in" attr is a bitmask specifying one or more of the following flags: SGLK_BOLD: Render in high-intensity SGLK_DIM: Render in low-intensity SGLK_ITAL: Ignored, for compatability with nitfol SGLK_FIXED: Ignored, for compatability with nitfol SGLK_REVERSE: reverse fg and bg (which may be default) The effects of sglk_set_style are cancelled by a call to glk_set_style or by the call sglk_set_style(str,SGLK_DEFAULT,SGLK_DEFAULT,0); The practical effect of using this is to set the current output style to a "new magic style" whose metrics are those of the previous style with the given "tweaks". glui32 sglk_color_distinguish(glui32 col1, glui32 col2) GlkDOS renders text in 4-bit color; 3 bits represent the presence of blue, green, and red, and the remaining bit specifies the intensity. the intense bit is set if the high-order bit is set for blue, red, or green in the glk color number, so 0x7f0000 is low-intensity red, and 0x000080 is bright blue. This function returns non-zero if the given colors render differently in 4-bit color. glui32 sglk_color_distinguish_graphics(glui32 c1, glui32 c2) GlkDOS/Allegro uses 16 bit color; Glk uses 24. This function returns nonzero if the two given colors are distinct within a graphics window. This function always returns false in non-graphical versions. void sglk_get_default_colors(glui32 *fg, glui32 *bg); This function gets the current default fore and background colors and stores them in the pointers provided. If the "normbg" option is selected, bg is set to the background color of style_Normal. If one or both pointers are NULL, that value is not stored. void *sglk_get_image(winid_t win, glsi32 x,glsi32 y, glui32 width,glui32 height); This function captures part of a graphics window, and returns an opaque reference to it. The image can be drawn again using the sglk versions of the glk graphics functions. void sglk_delete_image(void *b); This function destroys an image returned by sglk_get_image glui32 sglk_image_draw(winid_t win, void *b, glsi32 val1, glsi32 val2); glui32 sglk_image_draw_scaled(winid_t win, void *b, glsi32 val1, glsi32 val2, glui32 width, glui32 height); These functions are equivalent to their glk counterparts, but take opaque sglk-image objects instead of blorb image numbers. void sglk_set_basename(char *str) This function sets the "base" for automatically generated file names. (see section 2.1.1 for mre details) void sglk_request_abilities(glui32 a) This function should only be called early in the startup code. It announces which glk features the program wants. Although it currently does nothing, other glks might use this to determine which components to load/initialize (a future version of glkDOS might combine curses and allegro versions, and use this to determine which screen interface to use) a is a bitwise OR of the following flags: SGLK_GRAPHICS : the program wants graphics SGLK_SOUND : the program wants sound SGLK_MOUSE : the program wants the mouse A Z-machine or glulx interpreter might check the story file for use of sound and pictures, and set the abilites aprpriately, so that the application is run in text or graphics mode as is apropriate. 2.2 Linking the relevant files The makefile for glkDOS creates (in addition to the library) a corresponding make.gl[kcsna], which "describes" how to link a glk program to glklib. It provides the makefile variables GLK_LIB (which has the gcc command to link the GlkDOS library), and LINK_LIBS (which has the gcc commands to link the other needed libraries). The make.gl? also provides one further variable: GLKFILE, which is the full name of the glk library. If you want targets in your makefile to depend on the "freshness" of the glk library itself, you can use this variable to get at the apropos .a file. Essentially, compile your glk program, and link it with your startup code and the libraries. Included with this distribution is a generic makefile, makefile.gd, which will build simple glk programs using glkDOS make -f makefile.gd foo will build "foo" from "foo.c" using glkDOS. this makefile supports the following makefile variables: GLKDIR=. the directory containing the glk headers and library GLKMAKE=make.glk the make.gl? for the desired glkDOS version GLKSTART=glkstart.o the object file for the glkterm startup code PROGDEPS=%.o the dependant files for the target PROGTARGET=% the desired target 3. Using glkDOS based applications 3.1 The command line GlkDOS-built applications support the following arguments to the glk library: -width NUM: manual screen width (if not specified, will try to measure) -height NUM: manual screen height (ditto) Set screen dimentions (in characters) -ml BOOL: use message line (default 'yes') Display messages from the library in a separate line at the screen bottom. Disabling this gives you one extra line of screen, but may hide warning or error messages. -historylen NUM: length of command history (default 20) -revgrid BOOL: reverse text in grid (status) windows (default 'no') Inverts the normal color settings in textgrid windows -border BOOL: draw borders between windows (default 'no') Draws a visible border around windows -latin BOOL: assume latin1 codepage (default: 'no') Try to use latin1 encoding (only partially functional, due to DOS limitations that I haven't worked around yet) -normbg BOOL: match background to "normal" style (default: 'yes') Paint the background of the entire screen (particularly, after a screen clear) with the color of the normal style, rather than the default color -fg NUM: default foreground color (default: 7) -bg NUM: default background color (default: 1) default screen color -gl BOOL: show links in grid windows (default: 'no') -bl BOOL: show links in buffer windows (default: 'yes') GlkDOS indicates the presence of hyperlinks by printing an annotation [#] at the begining of each link. Since this may cause calculations in grid windows to be inaccurate, annotations are not shown for textgrid windows by default. These options alter the normal display of link annotations. -normal/emphasis/preform/header/subheader/alert/note/blockquote/user1/user2 NUM: individual style appearances (see config menu for defaults) set the attributes for a particular style. The number is calculated based on the style metrics, and is displayed by the config menu. -sound BOOL: play sound (default: 'yes') -more BOOL: display "[MORE]" pager (default: 'yes') -percent BOOL: display percentage pager (default: 'no') -fraction BOOL: display fractional pager (default: 'yes') GlkDOS offers three "pager" indicators, which appear in the message line when a scrollable window is not positioned at its bottom (ie, a full page of text has just been printed) Any combination of these pagers can be enabled at any time. more: the traditional [MORE] prompt fraction: shows the current window position as a fraction (last visible line/total lines) percent: shows the percentage of the buffer which is above the current window position -credits: display library credits -version: display Glk library version -help: display library options The following options have no meaning except in the allegro version of the library -db BOOL: reduce flicker via screen buffering (default: 'yes') GlkDOS can maintain a memory buffer to minimize the frequency of video-memory writes. Using this buffering will greatly reduce flicker, however it requires more memory at run-time and may result in a slight screen lag at high resolutions If a buffer cannot be created, glk will halt with an error message. Use this option to disable buffering (alternatively, reducing the virtual resolution may make double-buffering possible again). Since the virtual screen uses this buffer, disabling double buffering also disables the virtual screen. Glk will print a warning but will not halt if you try to set a virtual resolution while buffering is off. -res NUM: set resolution to NUM (default: 2) Sets the screen resolution. The available resolutions are: 1: 320x200 2: 640x480 3: 800x600 4: 1024x768 5: 1280x1024 If allegro cannot set the desired resolution, glk will terminate with an error message. This is the size of the "real" screen, and is independant of the virtual screen -vresx NUM: set virtual X-resolution to NUM (default: 0=use screen size) -vresy NUM: set virtual y-resolution to NUM (default: 0=use screen size) Sets the size of the virtual screen, in pixels. The default setting is for the virtual screen to use the same dimentions as the physical screen, but it may be set smaller or larger to any size, so long as sufficient memory is available for the virtual screen buffer. -font NUM: use font NUM from the font datafile (default: 0=use builtin font) Tells GLK to use the specified font from the font file. (use -fl to display a list of available fonts) The builtin font (0) is an 8x8 font, which resembles the PC bios font, and is always available. Other font availability depends on the supplied font datafile -cpl NUM: scale (non-builtin) font to NUM characters per line (default: 0=do not rescale) The fonts in the font datafile can be resized to accommodate the screen resolution. This may cause undesirable distortion of the font (fonts become blocky if scaled up, and lose clarity of scaled down), so a variety of fonts are provided whose unscaled size is appropriate to different ranges of resolutions. (Note: due to rounding, the font may not be scaled to exactly the desired characters per line -- Glk will scale the font as closely as possible) -fl: display a list of all available fonts -dvorak BOOL: Remap for dvorak keyboard (default: 'no') remap the keyboard for dvorak. This is not necessary on all dvorak keyboards. The curses version will perform mapping automatically on a correctly configured dvorak keyboard. ** This option is depreciated. Use the International Keyboard Support package avialable from the glkDOS distribution site. *** 3.2 The on-line configurator While running a glkDOS application, press Alt-F1 to bring up the runtime-configuration manager: GlkDOS Configuration > Message Line [YES] Reverse textgrid [NO] Pager [ MORE FRACTION ] Display window borders [NO] Show links in buffer windows Sound (if available) [ON] Forground Color [7] Background Color [1] Match background to style_Normal [YES] Set attributes for style: Normal [768] Default foreground color Default background color Force high intensity Force low intensity Reverse Lock attributes Apply these settings to all current windows Write these settings to file These options have roughly the same meanings as their counterparts on the command line options list. The arrow keys cycle between settable options, and pressing will toggle the setting of the selected value. The number printed beside a style name is used by GlkDOS as a descriptor for the current attributes of the style. This number can be entered on the command line or in a glkDOS config file to change the style's default appearance. 'Lock Attributes' toggles which attributes of the currently selected style are "locked". Locked attributes are not changed by stylehints set within a glk program. 'Apply these settings' makes changes in the editor apply to windows already on the screen. If you do not select this option, any changes you make will only be applied to windows created AFTER you leave the configuration manager. 'Write settings' saves the current glkDOS configuration to a config file (see below) Press 'q' or escape to leave the menu 3.3 glkDOS configuration files. If glkDOS is compiled with support for config files, then on startup, glkDOS programs will look for a configuration file. If the environment (or DJGPP.ENV) variable GLKCFG is set, glkDOS will try to open the file listed there. Otherwise, glkDOS will attempt to read from the file glk.cfg in the current working directory. (if the variable GLKDIR is set, it will then concatenate it to the beginning of the config file name and look for that file, so if GLKDIR="d:\djgpp\", and GLKCFG is unset, it will first try glk.cfg, then d:\djgpp\glk.cfg) A glk configuration file contains one or more of the following lines. If two settings conflict, the last occurance is used. These options override glkDOS defaults, and are overridden by command line options. Each setting corresponds to a glkDOS command line argument: WIDTH equivalent to -width HEIGHT equivalent to -height MESSAGELINE (on, off) equivalent to -ml HISTORY equivalent to -historylen REVERSE GRID equivalent to -revgrid yes NORMAL GRID equivalent to -revgrid no BORDER (off,on) equivalent to -border LATIN1 (off,on) equivalent to -latin NORMALIZE BACKGROUND equivalent to -normbg yes DEFAULT BACKGROUND equivalent to -normbg no FOREGROUND equivalent to -fg BACKGROUND equivalent to -bg SOUND (on,off) equivalent to -sound MORE (on,off) equivalent to -more FRACT (on,off) equivalent to -fraction PERCENT (on,off) equivalent to -percent RESOLUTION equivalent to -res VIRTUAL_WIDTH equivalent to -vresx VIRTUAL_HEIGHT equivalent to -vresy CPL equivalent to -cpl BUFFER (on,off) equivalent to -db GRIDLINK (on,off) equivalent to -gl BUFFERLINK (on,off) equivalent to -bl DVORAK (on, off) equivalent to -dvorak the following commands take as an argument the value given by the configuration manager for the corresponding style NORMAL equivalent to -(style name) EMPHASIS PREFORMATTED HEADER SUBHEADER ALERT NOTE BLOCKQUOTE USER1 USER2 LINK (LINK is not a real style; it is the font used when printing link annotations) Finally, the option 'BINDKEY' is specific to glkDOS config files. It allows you to override the default key bindings for glkDOS applications. Note that binding a key does NOT invalidate the current binding, but new bindings will "shadow" the original, overriding it in apropriate windows. BINDKEY keycode command keycode is a decimal (base 10) number corresponding to the key to be bound ( see cscr.h for the keycodes; printable characters correspond to their ascii values, control-letters correspond to their placement in the alphabet (so ^A has keycode 1, ^B is 2, etc).) and 'command' is one of the glkDOS internal command names (which can be revealed by toggling the 'reveal codes' option.) see next section. *** UNIX ONLY: whether or not extended keys will be honored correctly depends on your terminal settings and the key translator in cncurses.c (Aside: improvments to the cncurses, calleg, and cdos key translators are more than welcome ) You cannot rebind ^C (curses) or control-alt-end (allegro) 3.4 Special keys The following keys have special meaning in glkDOS: ALT-F1 bring up the configuration manager ALT-F2 Capture current screen to scrxxxxx.txt or scrxxxxx.bmp ALT-F3 Execute a named command Tab switch focus to the next window ^O Input key by keycode ^R Reveal codes ^L redraw the screen ^Z Shell to DOS (COMSPEC environment variable or command.com) ^C Terminate glkDOS (curses versions) Ctrl-alt-END Terminate glkDOS (allegro versions) Ctrl-Tab generate a hyperlink event (if one is pending) General keys for a text buffer window: ^Home Jump to the beginning of the buffer ^End Jump to the bottom of the buffer ^Up Scroll up one line ^Down Scroll down one line PageUp,^Y Scroll up one page PageDown,^V Scroll down one page Keys for line input in a buffer: Insert toggle overwrite mode Enter signal completion of input <- move the cursor back a character -> move the cursor forward a character Home,^A jump to the beginning of input End,^E jump to the end of input Backspace delete the character BEFORE the cursor Delete delete the character UNDER the cursor/delete to mark F5-F8 User macros ^F5-^F8 Set user macro to contents of copy buffer ^K (Kill-line) move all characters AFTER the cursor to copy buffer ^U (Undo-line) clear the input buffer ^Q (Quote-on) Set the mark ^Del,^W (Wipe) Move text up to the mark into the copy buffer + ^Ins,^S (Save) Copy text up to the mark into the copy buffer + Alt-Ins,^X (Xtract) Paste the contents of the copy buffer to the input *+ Up, ^P (Previous) recall the previous input buffer from history Down,^N (Next) recall the next input buffer from history (*) In the allegro version, Shift-Insert also performs this function (+) The PC-BIOS accelerated version does not honor alt-ins, ^ins or ^del ( Aside: if anyone can work out why, e-mail me! ) ** UNIX ONLY: The keys ^Q, ^S, and ^Z have special meaning in unix shells. ^ serves to set the mark in unix. Use ^Insert to copy text, and suspend/resume is handled by the shell. To send an keycode, it is necessary to press escape twice in rapid succession. To send ^Tab, press escape, then tab, in rapid succession Special commands have an internal name, which can be displayed by revealing the codes. The command names are: toggle_overwrite reveal_codes shell change_focus refresh setup screencap exec_command accept_key insert_key arbitrary_key accept_line move_left move_right begin_line end_line delete_backward delete_forward end_line undo_input kill_line scroll_to_top scroll_up scroll_to_bottom page_up page_down get_link accept history_prev history_next set_macro_[1-4] macro_[1-4] buffer_extract buffer_wipe buffer_save set_mark These values are (mostly) accepted by the 'Bindkey' config file option ( Aside: these keybindings do not apply in the setup menu or the file listbox. ) 3.5 Hyperlinks GlkDOS supports the GLK Hyperlink capability. When a link is started, GlkDOS prints an annotation in the output window giving the number of the link. Since this may generate unwanted noise in the output, the user can turn link annotation on or off at runtime. Link annotations are on by default in buffer windows, and off in grid windows. It is not recomended that links be turned on in grid windows, as this may disrupt the intended flow of text. To select a hyperlink, press control-tab. If any windows desire a hyperlink input, the glk messageline will display partial text of the last printed hyperlink. Pressing will cycle backwards through hyperlinks in the order they were issued, and pressing cycles forward. Pressing enter causes the currently displayed hyperlink to be executed. Press escape or 'q' to cancel the hyperlink input. 3.6 Screen capture GlkDOS offers the ability to dump the current screen to disk. Press Alt-F2 to make a screen capture. In curses versions of glkDOS, the screen dump is an ascii text file layed out to mimic the appearance of the screen (note that the effect of styled text will not be visible in the output file). The output file is placed in the current directory, and is named scrXXXXX.txt, where XXXXX is the first unused number (so the first screen capture made in a directory will be called scr00000.txt, the second scr00001.txt, and so on. glkDOS will not overwrite existing scrXXXXX.txt files. Up to 10000 screen capture files may be created in any directory). In the allegro version, the screen dump is a truecolor BMP file at the current virtual resolution. (note that this can be quite large; at 640x480, a screen capture is almost 1 megabyte) The output file will reflect the exact layout of the screen, including styles as they appeared when the capture was made. Files are named as in the curses version, except that the file extension is .bmp (Aside: Why BMP? Allegro does not provide native support for PNG or JPEG files. Of the formats which it DOES natively support (bmp, tga, and pcx), BMP is the best supported on modern systems. For the sake of speed and easy programming, BMP is therefore the format of GlkDOS/Allegro screen dumps. ) Screen capture is not available under allegro if buffering is turned off. You cannot capture the GlkDOS configuration screen or the file listbox. 3.7 Copy Buffer and user macros GlkDOS offers a 1024-character "copy buffer", which can be used to store a frequently used string of text. Text is inserted into the copy buffer using the "mark". The mark is set by pressing ^Q. When the mark is set, the following keys will copy all text between the cursor and the mark into the copy buffer: ^W, ^Del : MOVE text to copy buffer (Wipe/Cut) ^S, ^Ins : COPY text to the copy buffer (Save/Copy) When the mark is not set, text may be copied to the buffer using ^K, which is equivalent to the sequence ^Q^E^W ( Aside: The copy buffer only works for line input in a text buffer. It's implementationally complex. Patches are welcome. ) Additionally, when the mark is set, will delete all text between the cursor and the mark. To recall the text from the copy buffer, type ^X ( Aside: These keys differ slightly from the common key bindings. In most DOS/Win applications, the "CUI" keyset is used for text editing. However, some CUI keys (shift-insert and shifted-arrow keys) are not available using the curses library. The keys used here are closer to those used by GNU/Emacs. The most notable exception is that the mark is set by ^Q instead of control-space. This too is because curses won't return that character. The key ^S was chosen for "copy" due to its mnemonic value, and the slightly clumsier ^X was chosen for "extract (paste)", primarily because the three keys ^W, ^S and ^X form a line down a standard QWERTY keyboard ) GlkDOS also has 4 slots reserved for "user macros". Pressing ^F5-^F8 sets the corresponding macro key to the current contents of the copy buffer. Later, pressing the corresponding F-key will print out the macro. 3.8 DOS Shell GlkDOS can suspend its operation and enable a user DOS session. Pressing ^Z will invoke the command interpreter listed in the environment variable COMSPEC. If COMSPEC is unset, it executes "command", the default DOS interpreter. Type "exit" (or exit the shell as usual) to resume GLK. ( Aside: ^Z is the common unix keybinding for "suspend", which the DOS shell emulates as best it can ) Note that in allegro versions, there will be a noticable lag when entering or leaving a DOS shell as the video mode resets. Shelling to DOS while audio is playing may have undesirable effects, and is not recomended. 3.9 File naming convenions GlkDOS uses the following file extensions. Extensions marked with a (*) indicate that the extension is a default value, which may be overridden Extension Format Usage .TXT Text GlkDOS/Curses screen capture .TXT (*) Text ASCII datafile .BMP Windows BMP GlkDOS/Allegro screen capture .BLB (*) Blorb Blorb resource (+) .DAT Allegro grabber Font data .DAT (*) Binary Binary datafile .SAV (*) Binary Savefile .SCR (*) Text Transcript .REC (*) Text Command record .CFG (*++) GlkDOS config GlkDOS config file (+) Glk never actually refers to a blorb file by name. the BLB extension is listed here simply for completeness, as most glk applications will use this extension for blorb data. (++) While a config file may have any name, glkDOS always writes output config files to "glk.cfg" The following extensions are not used by glk per se, but are common in glk applications. They are included here to alert users that using these extensions might have the undesirable effect of overwriting important data. Extension Function .GAM TADS gamefile .HEX Hugo gamefile .DAT Z-code gamefile (infocom) .ZIP Z-code gamefile (late infocom) .Z[3,5,8] Z-code gamefile (inform) .ULX Glulx gamefile .INF Inform source .T Tads source .HUG Hugo Source .C C source .CC,.CPP C++ source .A,.LIB Compiled library 3.10 The File list box If a program prompts for a file name, you can either type in the name you want for the file, or select a file from the file list box. To access the file list box, press while at the file selection prompt. You will be presented with a list of available files and directories. ( Aside: Why doesn't the file list box just come up all the time? I don't really like file list boxes that much in console apps. If I know the file name, it's easier for me to just type it in. If I don't, then maybe I'll want the list box to look at. Whatever. ) The file list box has four fields which may be navigated. Pressing toggles which field is active (denoted by the location of the cursor) Files: This is a list of files in the current directory (which is displayed at the top of the screen). You can use the arrow keys to navigate the list. (home and end jump to the top and bottom). Typing a letter will take you to the next entry beginning with that letter. Pressing will copy the current selection to the File prompt and switch focus there. Numbers appear at the top and bottom of the display to indicate that unseen files exist outside the visible list area Directories: This is a list of directories. It behaves like the files list. Pressing enter will switch the current directory to the one selected. File: The currently selected file. You can edit this as normal. Pressing enter will accept the current value as input. Filter: This is a wildcard expression which specifies which files are to be listed in the file box. Pressing enter will refresh the directory listing based on the new value of this filter. Pressing escape cancels the file input. 4 Allegro Extended features 4.1 The Virtual Screen When buffering is turned on, Allegro GlkDOS writes its output to a "virtual screen" in memory. While the size of the physical screen is determined by the resolutions available on your video card, the virtual screen can be of any size (limited by memory, of course) By default, the virtual screen is matched to the size of the physical screen, but this can be overridden by the command line options -vresx and -vresy. If the virtual resolution is smaller than the physical resolution, only part of the physical screen will contain output. Contrarywise, if the virtual resolution is greater than the physical screen size, only part of the virtual screen is displayed. You can think of the physical screen as a "window" (in the non-computing sense) through which the virtual screen is viewed. For example, if the resolution is set to its default (640x480), and the virtual resolution is set to 800x600, the screen model would look like this: (apologies for the ascii art) +--------------+------+ | Physical | | | Screen | | | (viewable | | | window) | | +--------------+ | | Virtual Screen | | (Non-viewable) | +---------------------+ GLK will render the screen as if the resolution were actually 800x600. This might at first seem a little useless, but it is possible to scroll the virtual screen at run-time. To move the viewable area, use the numeric keypad: 1: scroll the viewable window to the far right 2: scroll the viewable window down 3: scroll the viewable window to the bottom 4: scroll the viewable window to the left 6: scroll the viewable window to the right 7: scroll the viewable window to the far left 8: scroll the viewable window up 9: scroll the viewable window to the top (These keys correspond to the layout fo the directional arrows on the numeric pad.) For virtual scrolling to work, Num-Lock must be turned _ON_ and Scroll-lock must be turned _OFF_ (if you use the numeric keypad frequently, press scroll-lock to disable virtual scrolling) (Aside: I know that these keys are inconvenient for laptop users. There were very few keys left. ) This mode can be especially helpfull when running GlkDOS applications on a machine with limited video resources; many programs will not display correctly on very small screens (inform compiled programs often display broken status lines and box quotes if the screen width is too small.) starting glkDOS with the options -res 1 -vresx 640 -vresy 480 will emulate the default screen settings as a virtual screen of 640x480 on a physical screen of 320x200. The virtual screen can also be used, say, to make decorative GLK windows invisible, by scrolling them outside the viewable region, or as a form of alternative paging, or to magnify glk's output (a 640x480 virtual screen with a 320x200 physical screen could be considered to be a 640x480 screen with a 320x200 "magnifying glass") 4.2 Font support 4.2.1 using fonts Allegro GlkDOS can use a number of fonts to improve the appearance of text in a Glk application. One font, the 8x8 "standard" font, is built into GlkDOS. This is the default font used by Glk, and emulates the PC bios font. Other fonts are available, and are provided in the font datafile. When GlkDOS starts, if an alternative font is requested, GlkDOS looks for the font datafile. If the environment (or DJGPP.ENV) variable GLKFONT is set, GlkDOS tries to load that file, otherwise it looks in the current directory for "font.dat". Failing that, if GLKDIR is set, it looks there for GLKFONT or font.dat. If no font file is found, glk will exit with an error message if an attempt is made to use a different font or display the font list. The command line option -fl will print out the list of fonts available. The font datafile can be modified without recompiling the library or GlkDOS-built programs. Alternative fonts each have their own size. Because of the Allegro font format, fonts will generally look best at their default size, however, since fonts vary in size, it may be desirable to rescale a font for a specifc video mode (the included courier 12pt font, for example, prints only 65 characters per line in 640x480, and thus may reveal limitations in some inform games). The -cpl option rescales a font so that it displays the specified number of characters per line on the virtual screen (Glk will try to scale the font as closely as it can to the specified size, but due to scaling issues, this may not be exactly the same size requested.) Note that scaling a font down loses data; it is very dificult to find a font which remains readable if it is scaled to fit 80 characters across a 320x200 screen. Likewise, scaling up may cause the font to become blocky, though for some fonts the effect is not profound. The font list contains a description of the point size at which the font was rendered, which may be helpful in deciding which font to use for a certain video mode (note that a large font tends to scale better both up and down than a small one). This should not be taken as an absolute indication of font size, however (for example, the font 6x13 12 pt. prints at 106 characters per line in 640x480, while 7x14 12 pt prints 80 characters per line. Monotype 12 pt prints only 65). 4.2.2 Font file format The font.dat file is in the allegro datafile format, which can easily be created using the utilities which come with the allegro library. The first entry in the data file is the font description, a text file which is printed in response to the -fl option. The first thing in this file MUST be the number of fonts in the datafile Individual fonts are created from PCX bitmaps. While these are technically proportional fonts, for Glk to work properly, every character in the file must have the same width. The exact specifications of the font data file are left to the allegro documentation. If every character in the font is not of the same width, GlkDOS scales the font characters to the width of the letter 'M'. This may produce unwanted distortion, so it is recomended that user hand-edit the font bitmap so that every character is the same width, by scaling or centering the character as looks best It is also possible to add an 8x8 or 8x16 font to the datafile, but this is not recomended, as attempting to scale such a font will cause Glk to fail. Future versions may add support for other font formats, but proportional font support is not a priority. ( Aside: I don't like proportional fonts. Which is not enough to keep me from implementing them. However, doing so would mean that a very large percentage of the GlkDOS code would no longer be portable between curses and allegro versions, which is. ) the font.dat file must be distributed with any program which uses GlkDOS/Allegro, or only the builtin font will be available. If you wish to distribute a modified font datafile, it is requested that you leave the standard fonts in their original order to minimize user confusion. Even better, if you design a new font that works with GlkDOS, send it to the author for inclusion in the main distribution. ( Aside: Unless it's broken, I'll do it. Promise. ) 4.3 Graphics GlkDOS/Allegro (glka) supports the full suite of graphics capabilities promised under, as well as the sglk graphical extensions. GlkDOS's graphics support has the following limitations: * Graphics window sizes are not exact. GlkDOS/Allegro will pad the size of a graphics window to the next even character-sized unit. This ensures that no "dead space" occurs in adjacent text windows. ( Aside: That's not the real reason the real reason is that the curses version of GlkDOS measures the screen in character-units rather than pixels. In order to use the same (tested, documented) code for both versions, I opted to pad the graphics window. ) You will always get _at least_ as much space as you request, if it's possible, but you will more often than not get slightly more space. The extra space is fully usable, and will be returned by reading the window's size attributes. Alternatively, you can always safely ignore this space and it will serve as a visible boundary to the window. * Margin-aligned images are not quite accurate. Text does not "flow around" margin aligned images quite the way it should; left-aligned images are rendered as inline-up at the beginning of a line of text. Right-aligned images appear at the right margin on a line of their own. ( Aside: Margin-aligning images is HARD. ) * window_flow_break is unimplemented. because of the way aligned images are shown, the newline which prefaces a margin aligned image will always cause the image to be alighed properly, so the cascade effect that the spec warns of cannot happen. * Transparency in PNG images is not supported. My PNG library doesn't handle it, so neither do I. 4.4 International Keyboard support Allegro will translate the keyboard for Non-QWERTY/US keyboards, with the help of the International Support Package available from the GlkDOS distribution site. It is necessary to alter the allegro config file to reflect the keybaord used, or Allegro will assume that the keyboard is a US/QWERTY. This package superceeds the now-obsolete -dvorak option. 5 Mouse Support GlkDOS should support any reasonable mouse with an allegro-compatable or INT33 driver (that is, a DOS mouse driver; if you can generally use your mouse in DOS, you can use it in GlkDOS) There are no options relevant to the mouse itself. A mouse pointer is displayed only when mouse input is pending in some window. The mouse is not supported in GlkDOS for Unix. The gestalt MouseInput selector will correctly identify whether or not the mouse is accessable. Mouse clicks *ONLY* trigger MouseInput events. They ARE NOT used for selecting Hyperlinks. Version History... ( Aside: I pretty much allocate a new version number whenever I feel like it. As of 0.9.1, even-middle-number versions specify developmental releases. Odd numbers specify "production" releases. The first number is the major- version number of the GLK it supports (so it'll become 1 whenever Glk itself does, or when I reach version 100, whichever comes first) The last digit is supposed to represent minor features or bug fixes, but I might shoehorn a few in order to make the major version numbers work out right. Also, I wasn't really keeping track of changes from version 6 back, so I pretty much just made up the numbers below that. version 0.1.1 was called "GlkTerm 0.7.2/DOS DJGPP port 0.1" ) 0.19.1: Mouse support & underlying cscr functionality 0.18.6: Reordered cscr modules for readability 0.18.5: Undocumented the obsolete -revquote option. 0.18.4: Fixed style_measure and style_distinguish to be window-specific 0.18.3: Revamped color support; the background of each window is now the glk background (style_Normal or the default) at the time of window creation. Thanks to Adam Cadre for getting this method instatutionalized as the de facto practice. 0.18.2: Curses module rewritten to not use curses's background mechanism This is a touch clumsier, but gets rid of its annoying habit of fiddling with the intensity bits on text that shouldn't be thusly adjusted. This does result in slightly eccentric coloration of the message line, but you can't have everything. 0.18.1: Updated the dispatch layer Added GLKFILE to the make.* 0.17.1: Added the custom makefile generator. 0.16.1: Upgraded to glk 0.6.1 SoundMusic and GraphicsTransparency gestalt selectors stylehint_Reverse 0.15.2: Added documentation to cscr Removed redundant cscr functions Optimized cdos a little more 0.15.1: Added customizable keybindings Added PC-BIOS accelerated version 0.14.3: Added dvorak support under allegro (kludgy) 0.14.2: Improved color mechanism 0.14.1: Provisional unix retroport 0.13.4: Added cncurses.c, unix/ncurses output api 0.13.3: removed cscr's dependancy on curses.h for keybindings. 0.13.2: Fixed a bug in echo_to_link that only manifests in linux 0.13.1: Graphics in textbuffer windows 0.12.5: New cscr naming conventions 0.12.4: Removed redundant cscr functions 0.12.3: improved listbox to process directories from the 'to' line Added scrolling markers to the listbox added autojump to the listbox 0.12.2: source code cleaning 0.12.1: File list box sglk extensions 0.11.1: Graphics Improved file naming conventions, glkdos_set_basename Simplified the color support mechanism by complicating cscr. Should perform slightly better. 0.10.7: Graphics windows 0.10.6: rewrote key handler, added arbitrary key and exec-command 0.10.5: Added user macros 0.10.4: More copy buffer keys 0.10.3: Shell to dos added 0.10.2: Added copy buffer 0.10.1: Added hyperlink support Source code restructuring Removed some unused code Added conversion of proportional fonts 0.9.2 : Added generic makefile 0.9.1 : Upgraded GlkDOS to glk 0.6.0 0.8.4 : Improved the version information, tidied up the makefile 0.8.3 : Added font support 0.8.2 : Fixed various color bugs 0.8.1 : Added Allegro graphics capability. Major source revision should increase portability (All screen output is now collected in a single file. Porters need only implement the declarations of cscr.h to change the output API. ccurses.c implements output via curses, and calleg.c implements it via allegro) 0.7.3 : Fixed a bug which prevented timer events from occuring correctly 0.7.2 : Fixed an oversight that made it impossible to compile glkdos without a modified libc (name collision between curses and conio) 0.7.1 : Fixed stylehint support to comply with glk specification Added configuration file support Added makefile options to build without sound 0.6.1 : Fixed a bug in the sound system 0.5.2 : Enhanced the runtime menu 0.5.1 : Added run-time configuration menu 0.4.1 : Added partial latin1 support 0.3.2 : Added jgmod sound support 0.3.1 : Added Allegro sound support 0.2.3 : Remapped special keys to DOS/Win conventions 0.2.2 : Added high-resolution timer 0.2.2 : Added color 0.1.1 : Initial release, essentially a straight port of glkterm