INFGLK WRAPPER REFERENCE 8/03/00 Marnie Parker doeadeer3@aol.com Matches infglk 0.6.1 which matches Glk 0.6.1. **************************************************************************** Version 4.22 CONTENTS Notes on this file Constants summary Functions summary Last update: 8/11/01 **************************************************************************** NOTES: infglk 0.6.1 allows you to drop off trailing zero parameters to glk functions. Functions are in the same order as in the infglk.h include file and use the same naming conventions. 1 = True, 0 = False, GLK_NULL = 0 (a constant defined in infglk.h) INTERNAL = The word, internal, has been placed next to constants and functions which are really intended for glk interpreter programmers. The functions are run automatically by the interpreter when playing a game. They CAN be called by Inform programmers, but they do not need to be provided, and often calling them is not a good idea. PARAMETERS = As with all Inform functions/routines, the parameters used are all numbers. They are represented either by: an Inform object name, an Inform constant, an Inform variable, an Inform array, actual decimal number, actual hexadecimal number (preceeded by $). VARIABLE PARMETERS = Some functions return too much information for one result (functions can only return one result). These are passed an array that is then filled in with the pertinent information. VARIABLE POINTER PARAMETERS = Sometimes, these variables have a ptr suffix designating they are pointers. When you need a pointer passed, you pass an address. In Inform, arrays are equal to addresses. So the multipurpose array, gg_arguments, has been created in parserm.h for just this purpose. Where gg_arguments should be passed has been noted. Pointers (addresses) need to be incremented by WORDSIZE on successive calls to the same function. Upon return, you should immediately save gg_arguments' values in local or global variables as gg_arguments may be called again, whiping out returned values. Successive calls in same function: gg_arguments, gg_arguments+4, gg_arguments+8 or gg_arguments, gg_arguments+WORDSIZE, gg_arguments+(WORDSIZE*2) Example: glk_window_get_size(gg_mygraph_win, gg_arguments, gg_arguments+4); mygraph_width = gg_arguments-->0; mygraph_height = gg_arguments-->1; BUFFERS = Buffers are also passed as variable parameters to some glk functions. These should be author-created buffers. Where the Glulx Inform library uses the input buffer with a function has been noted. Author-created: Constant my_buffer_len 120; Array my_buffer->my_buffer_len; EVENTS = Events are stored in an array, gg_event, also created in parserm.h. Sometimes this array is also passed to a function -- where has been noted. Unlike gg_arguments, the event array is considered to have a "structure" because specific elements are for specific things. gg_event-->0 event type (defined as constants evtype_specific) gg_event-->1 window the event is associated with gg_event-->2 value = depends on usage gg_event-->3 value = depends on usage ROCK NUMBERS: (these rock numbers are "reserved" in parsem.h, for more explanation see: http://members.aol.com/doepage/glkdunces2.htm) Constant GG_MAINWIN_ROCK 201; Constant GG_STATUSWIN_ROCK 202; Constant GG_QUOTEWIN_ROCK 203; Constant GG_SAVESTR_ROCK 301; Constant GG_SCRIPTSTR_ROCK 302; Constant GG_COMMANDWSTR_ROCK 303; Constant GG_COMMANDRSTR_ROCK 304; Constant GG_SCRIPTFREF_ROCK 401; New glk objects should use: 210 + = Windows 310 + = Streams 410 + = File References DEFAULT WINDOWS: gg_mainwin = main text window (text buffer) gg_statuswin = status line window (text grid) gg_quotewin = quote box window (text buffer) DEFAULT STREAMS: gg_savestr = save game stream gg_scriptstr = transcript stream gg_commandstr = command stream for debugging (if debug on) DEFAULT FILE REFERENCE: gg_scriptfref = transcript file reference **************************************************************************** CONSTANTS Constant definitions are from infglk.h. Most are self-explanatory. For more explanation see web pages and function summaries. Note that glk is written in c, which defines NULL as 0, while Inform defines NULL as -1. So the constant GLK_NULL is used instead of NULL. In this infglk wrapper reference, return values of 0 and GLK_NULL are often used interchangeably. Constant GLK_NULL 0; Gestalt Testing Constants ------------------------------------------ Constant gestalt_Version 0; Constant gestalt_CharInput 1; Constant gestalt_LineInput 2; Constant gestalt_CharOutput 3; Constant gestalt_CharOutput_CannotPrint 0; Constant gestalt_CharOutput_ApproxPrint 1; Constant gestalt_CharOutput_ExactPrint 2; Constant gestalt_MouseInput 4; Constant gestalt_Timer 5; Constant gestalt_Graphics 6; Constant gestalt_DrawImage 7; Constant gestalt_Sound 8; Constant gestalt_SoundVolume 9; Constant gestalt_SoundNotify 10; Constant gestalt_Hyperlinks 11; Constant gestalt_HyperlinkInput 12; Constant gestalt_SoundMusic 13; Constant gestalt_GraphicsTransparency 14; Event Type Constants ------------------------------------------ Constant evtype_None 0; Constant evtype_Timer 1; Constant evtype_CharInput 2; Constant evtype_LineInput 3; Constant evtype_MouseInput 4; Constant evtype_Arrange 5; Constant evtype_Redraw 6; Constant evtype_SoundNotify 7; Constant evtype_Hyperlink 8; Keycode Constants ------------------------------------------ Constant keycode_Unknown $ffffffff; Constant keycode_Left $fffffffe; Constant keycode_Right $fffffffd; Constant keycode_Up $fffffffc; Constant keycode_Down $fffffffb; Constant keycode_Return $fffffffa; Constant keycode_Delete $fffffff9; Constant keycode_Escape $fffffff8; Constant keycode_Tab $fffffff7; Constant keycode_PageUp $fffffff6; Constant keycode_PageDown $fffffff5; Constant keycode_Home $fffffff4; Constant keycode_End $fffffff3; Constant keycode_Func1 $ffffffef; Constant keycode_Func2 $ffffffee; Constant keycode_Func3 $ffffffed; Constant keycode_Func4 $ffffffec; Constant keycode_Func5 $ffffffeb; Constant keycode_Func6 $ffffffea; Constant keycode_Func7 $ffffffe9; Constant keycode_Func8 $ffffffe8; Constant keycode_Func9 $ffffffe7; Constant keycode_Func10 $ffffffe6; Constant keycode_Func11 $ffffffe5; Constant keycode_Func12 $ffffffe4; Constant keycode_MAXVAL 28; Internal Style Constants ------------------------------------------ Constant style_Normal 0; Constant style_Emphasized 1; Constant style_Preformatted 2; Constant style_Header 3; Constant style_Subheader 4; Constant style_Alert 5; Constant style_Note 6; Constant style_BlockQuote 7; Constant style_Input 8; Constant style_User1 9; Constant style_User2 10; Constant style_NUMSTYLES 11; Internal Window Constants ------------------------------------------ Constant wintype_AllTypes 0; Constant wintype_Pair 1; Constant wintype_Blank 2; Constant wintype_TextBuffer 3; Constant wintype_TextGrid 4; Constant wintype_Graphics 5; Constant winmethod_Left $00; Constant winmethod_Right $01; Constant winmethod_Above $02; Constant winmethod_Below $03; Constant winmethod_DirMask $0f; Internal Constant winmethod_Fixed $10; Constant winmethod_Proportional $20; Constant winmethod_DivisionMask $f0; Internal File I/O Constants ------------------------------------------ Constant fileusage_Data $00; Constant fileusage_SavedGame $01; Constant fileusage_Transcript $02; Constant fileusage_InputRecord $03; Constant fileusage_TypeMask $0f; Constant fileusage_TextMode $100; Constant fileusage_BinaryMode $000; Constant filemode_Write $01; Constant filemode_Read $02; Constant filemode_ReadWrite $03; Constant filemode_WriteAppend $05; Constant seekmode_Start 0; Constant seekmode_Current 1; Constant seekmode_End 2; Style Hint Constants ------------------------------------------ Constant stylehint_Indentation 0; Constant stylehint_ParaIndentation 1; Constant stylehint_Justification 2; Constant stylehint_Size 3; Constant stylehint_Weight 4; Constant stylehint_Oblique 5; Constant stylehint_Proportional 6; Constant stylehint_TextColor 7; Constant stylehint_BackColor 8; Constant stylehint_ReverseColor 9; Constant stylehint_NUMHINTS 10; Internal Constant stylehint_just_LeftFlush 0; Constant stylehint_just_LeftRight 1; Constant stylehint_just_Centered 2; Constant stylehint_just_RightFlush 3; Graphic Image Constants ------------------------------------------ Constant imagealign_InlineUp $01; Constant imagealign_InlineDown $02; Constant imagealign_InlineCenter $03; Constant imagealign_MarginLeft $04; Constant imagealign_MarginRight $05; **************************************************************************** FUNCTIONS Functions appear in the same order as they appear in infglk.h. ORDER MAIN GESTALT UTILITY WINDOW STREAM STREAM / STYLE STREAM / STYLE HINT FILE REFERENCE EVENT IMAGE SOUND HYPERLINK ---------------------------------------------------------------------------- Main Internal glk_exit Purpose: Exits glk system Called by glk_main Parameters: None Returns: Does not return ---------------------------------------------------------------------------- Main Internal glk_set_interrupt_handler func Purpose: Sets glk's interrupt handler (hardware interrupts) Called by glk_main Parameters: func = pointer to/address of interrupt handler function which takes no argument and returns no result Returns: nothing ---------------------------------------------------------------------------- Main Internal glk_tick Purpose: Periodically checks platform operations Called by glk_main Parameters: none Returns: nothing ---------------------------------------------------------------------------- Gestalt glk_gestalt sel val Purpose: Determines a glk library's/interpreter's configuration Parameters: sel = capability being tested for uses constant gestalt_(specific) val = value (usually one of the constants, often wintype) Returns: value or 1 = true, 0 = false Testing: Version result = glk_gestalt(gestalt_Version, 0); returns a a 32 bit version number number: upper 16 bits stores the major version number, the next 8 bits the minor version number, the low eight bits even a more minor version number ($004E020B = 78.2.11) Graphics result = glk_gestalt(gestalt_Graphics, 0); returns 1 if the overall suite of graphic functions is available (glk_image_draw, etc.) result = glk_gestalt(gestalt_DrawImage, wintype); returns 1 if images can be drawn in window of given type result = glk_gestalt(gestalt_GraphicsTransparency, 0); returns 1 if transparent graphics are supported Sound result = glk_gestalt(gestalt_Sound, 0); returns 1 if overall suite of sound functions is available result = glk_gestalt(gestalt_SoundVolume, 0); returns 1 if the set volume function works result = glk_gestalt(gestalt_SoundNotify, 0); returns 1 if sound notification events are supported result = glk_gestalt(gestalt_SoundMusic, 0); returns 1 if capable of playing music sound resources (MOD) 0 if only sampled sounds can be played (AIFF) Mouse result = glk_gestalt(gestalt_MouseInput, wintype); returns 1 if window of a given type supports mouse input Hyperlinks result = glk_gestalt(gestalt_Hyperlinks, 0); returns 1 if overall suite of hyperlink functions is available result = glk_gestalt(gestalt_HyperlinkInput, wintype); returns 1 if window of a given type supports hyperlinks Timer result = glk_gestalt(gestalt_Timer, 0); returns 1 if glk timer events are supported ---------------------------------------------------------------------------- Gestalt glk_gestalt_ext sel val arr arrlen Purpose: Determines a glk library's/interpreter's configuration Can also be used to test whether a particular character is printable Parameters: sel = capability being tested for uses constant gestalt_(specific) val = value (character output - the character) arr = array (character output - the pointer / address to be filled in with number of glyphs, gg_arguments) arrlen = number of characters to be tested (usually 1) Returns: 1 = true, 0 = false Testing: Character Encoding Notes: Characters can be from 0-255. Values 32-126 are standard printable ASCII characters. 0-31 and 127-159 are control characters and have no printing equivalent. When printing text to a text window or stream, glk can print any printable Latin-1 characters in 32-126, 160-255, and the newline character (linefeed, Control-J and decimal 10). result = glk_gestalt_ext(gestalt_CharOutput, ch, gg_arguments, 1); returns: gestalt_CharOutput_CannotPrint = cannot be meaningfully printed gestalt_CharOutput_ExactPrint = will be printed exactly gestalt_CharOutput_ApproxPrint = will print some approximation glyphs = gg_arguments-->0; number of glyphs that will be used to represent the character ---------------------------------------------------------------------------- Utility glk_char_to_lower ch Purpose: Converts character to lowercase Parameters: ch = character Returns: ch = character ---------------------------------------------------------------------------- Utility glk_char_to_upper ch Purpose: Converts character to upper case Parameters: ch = character Returns: ch = character --------------------------------------------------------------------------------------------- Window glk_window_get_root Purpose: Gets the root of the window tree (topmost window) Parameters: none Returns: root window GLK_NULL = none Example: root = glk_window_get_root(); ---------------------------------------------------------------------------- Window glk_window_open split method size wintype rock Purpose: Opens a new window Parameters: split = window to split method = splitting + sizing method above/below or left/right and fixed or proportional uses constant winmethod_(specific) size = height for above/below split or width for left/right split wintype = text buffer/text grid/graphic uses constant wintype_(specific) rock = unique id number for window Returns: window GLK_NULL = open not successful Examples: opening a proportional text buffer window - size is the percentage of gg_mainwin to use (since split is above, size is proportional height, number of lines of text down) gg_mytext_win = glk_window_open(gg_mainwin, winmethod_Above+winmethod_Proportinal, 30, wintype_TextBuffer, 210); opening a fixed-width graphics window (size is height in number of pixels) gg_mygraph_win = glk_window_open(gg_mainwin, winmethod_Above+winmethod_Fixed, 200, wintype_Graphics, 210); ---------------------------------------------------------------------------- Window glk_window_close win result Purpose: Closes given window Parameters: win = window result = pointer/address to be filled in with output character count (gg_arguments) GLK_NULL = character count not wanted Returns: 1 = success, 0 = failure Example: result = glk_window_close(gg_mytext_win, gg_arguments); char_count = gg_arguments-->0; ---------------------------------------------------------------------------- Window glk_window_get_size win widthptr heightptr Purpose: Gets size of given window Parameters: win = window widthptr = pointer/address to be filled with width heightptr = pointer/address to be filled with height (gg_arguments) Returns: 1 = success, 0 = failure Example: result = glk_window_get_size(gg_mygraph_win, gg_arguments, gg_arguments+WORDSIZE); graph_width = arguments-->0; graph_height = arguments-->1; ---------------------------------------------------------------------------- Window glk_window_set_arrangement win method size keywin Purpose: Changes configuration of given window Parameters: win = window method = splitting + sizing method above/below or left/right and fixed or proportional uses constant winmethod_(specific) size = height for above/below split or width for left/right split keywin = the first window in a split pair, GLK_NULL = leave key window unchanged Returns: 1 = success, 0 = failure Example: result = glk_window_set_arrangement(gg_mygraph_win, winmethod_Below+winmethod_Fixed, 200, 0); ---------------------------------------------------------------------------- Window glk_window_get_arrangement win methodptr sizeptr keywinptr Purpose: Gets arrangement of given window Parameters: win = window methodptr = pointer/address to be filled with method sizeptr = pointer/address to be filled with size keywinptr = pointer/address to be filled with keywin (gg_arguments) Returns: 1 = success, 0 = failure Example: result = glk_window_get_arrangement(gg_mygraph_win, gg_arguments, gg_arguments+WORDSIZE, gg_arguments+(WORDSIZE*2)) graph_method = gg_arguments-->0; graph_size = gg_arguments-->1; graph_keywin = gg_argumetns-->2; ---------------------------------------------------------------------------- Window glk_window_iterate win rockptr Purpose: Loops through open windows (class membership) Parameters: win = GLK_NULL = returns first window object win = returns next window object after this one rockptr = pointer/address to be filled in with each window rock number (gg_arguments) GLK_NULL = don't want rock numbers Returns: window GLK_NULL = when reaches end Example: obj = glk_window_iterate(GLK_NULL, GLK_NULL); while (obj) { ! do something with window obj obj = glk_window_iterate(obj, GLK_NULL); } ---------------------------------------------------------------------------- Window glk_window_get_rock win Purpose: Gets rock number of given window Parameters: win = window Returns: rock number GLK_NULL = failure Example: graph_rock = glk_window_get_rock(gg_mygraph_win); ---------------------------------------------------------------------------- Window glk_window_get_type win Purpose: Gets type of given window Parameters: win = window Returns: wintype GLK_NULL = failure Example: graph_type = glk_window_get_type(gg_mygraph_win); ---------------------------------------------------------------------------- Window glk_window_get_parent win Purpose: Gets parent of given window Parameters: win = window Returns: window GLK_NULL = window is the root window Example: graph_parent = glk_window_get_parent(gg_mygraph_win); ---------------------------------------------------------------------------- Window glk_window_get_sibling win Purpose: Gets sibling of given window Parameters: win = window Returns: window GLK_NULL = no sibling Example: graph_sib = glk_window_get_sibling(gg_mygraph_win); ---------------------------------------------------------------------------- Window glk_window_clear win Purpose: Erases given window Text buffer = may delete all text in window or print blank lines, etc. Text grid = fills all grid boxes with blanks and positions cursor to 0,0 Graphics = clears window to current background color Parameters: win = window Returns: 1 = success, 0 = failure Example: result = glk_window_clear(gg_mygraph_win); ---------------------------------------------------------------------------- Window Cursor glk_window_move_cursor win xpos ypos Purpose: Positions cursor in given window Parameters: win = window xpos = vertical position ypos = horizontal position 0, 0 is upper left Returns: 1 = success, 0 = failure Example: result = glk_window_move_cursor(gg_mytext_win, 0, 0); ---------------------------------------------------------------------------- Window glk_window_get_stream win Purpose: Gets stream associated with given window Parameters: win = window Returns: stream GLK_NULL = failure Example: gg_mytext_str = glk_window_get_stream(gg_mytext_win); ---------------------------------------------------------------------------- Window glk_window_set_echo_stream win str Purpose: Echos given window's stream Duplicates window's stream, everything directed to it is replicated in the echo stream Echoing is one-way, may print text directly to echo stream and it will go wherever the stream is bound, but does not back up into window Stream may be of any type, even another window's stream Parameters: win = window str = stream GLK_NULL = stop echoing Returns: 1 = success, 0 = failure Example: result = glk_window_set_echo_stream(gg_mainwin, gg_myecho_str); ---------------------------------------------------------------------------- Window glk_window_get_echo_stream win Purpose: Gets the echo stream of given window Initially given window has no echo stream, so may return GLK_NULL Parameters: win = window Returns: stream GLK_NULL = echo stream doesn't exist Example: gg_myecho_str = glk_window_get_echo_stream(gg_mainwin); ---------------------------------------------------------------------------- Window glk_set_window win Purpose: Sets the current stream to given window's stream, exactly equivalent to glk_stream_set_current (switches to given window) Subsequent printing is directed to current window Parameters: win = window Returns: 1 = success, 0 = failure Example: result = glk_set_window(gg_mytext_win); ---------------------------------------------------------------------------- Stream glk_stream_open_file fileref fmode rock Purpose: Opens a new stream which reads/writes to a disk file Parameters: fileref = file reference fmode = read/write file mode write/read/read write/write append uses constant filemode_(specific) Read - file must exist, for other modes an empty file is created if none exist Write - if file exists, truncated down to 0 WriteAppend - read/write mark set to end of file rock = unique id number Returns: stream GLK_NULL = failure Examples: gg_mywrite_str = glk_stream_open_file(gg_mywrite_ref, filemode_Write, 310); gg_myread_str = glk_stream_open_file(gg_myread_ref, filemode_Read, 311); ---------------------------------------------------------------------------- Stream glk_stream_open_memory buf buflen fmode rock Purpose: Opens a new stream which reads/writes into a space in memory Parameters: buf = buffer array where output will be read/written to buflen = length of buffer outputting - if more than buflen characters are written to the stream, the excess will be thrown away so not to overwrite buffer inputting - if more than buflen characters are read from the stream, stream will start returning -1 (end of file) fmode = MUST be read/write/read write uses constant fmode_(specific) rock = unique id number Returns: stream GLK_NULL = failure Example: gg_mybufferout_str = glk_stream_open_memory(my_buffer, my_buffer_len, filemode_Write, 312); gg_mybufferin_str = glk_stream_open_memory(my_buffer, my_buffer_len, filemode_Read, 313); ---------------------------------------------------------------------------- Stream glk_stream_close str result Purpose: Closes given stream Parameters: str = stream result = pointer to a "structure" that stores the final character counts (gg_arguments, just gg_argument is passed, not gg_arguments+4) gg_arguments-->0 = read count gg_arguments-->1 = write count) GLK_NULL = character count not wanted Returns: 1 = success, 0 = failure if stream is current output stream, stream is set to GLK_NULL Example: result = glk_stream_close(gg_mytext_str, gg_arguments); read_count = gg_arguments-->0; write_count = gg_arguments-->1; ---------------------------------------------------------------------------- Stream glk_stream_iterate str rockptr Purpose: Loops through open streams (class membership) Parameters: str = GLK_NULL = returns first stream object str = returns next stream object after this one rockptr = pointer/address to be filled in with each stream rock number (gg_arguments) GLK_NULL = don't want rock numbers Returns: stream GLK_NULL = when reaches end Example: obj = glk_stream_iterate(GLK_NULL, GLK_NULL); while (obj) { ! do something with stream obj obj = glk_stream_iterate(obj, GLK_NULL); } ---------------------------------------------------------------------------- Stream glk_stream_get_rock str Purpose: Gets the rock number of given stream Parameters: str = stream Returns: rock number GLK_NULL = failure Example: str_rock = glk_stream_get_rock(gg_mywrite_str); ---------------------------------------------------------------------------- Stream glk_stream_set_position str pos seekmode Purpose: Sets position of read/write mark in given stream Parameters: str = stream pos = position determined by seekmode Start = pos number of characters after beginning of file Current = pos number of characters after current pos End = pos number of characters after end of file Binary files = pos is exact, corresponds to the number of characters read/written Text files = can vary, because of linefeed conversions and character sets, so safest to only to move mark to beginning/end or position found by get_position seekmode = start/current/end uses constant seekmode_(specific) Returns: 1 = success, 0 = failure Example: result = glk_stream_set_position(gg_mywrite_str, 0, seekmode_Start); ---------------------------------------------------------------------------- Stream glk_stream_get_position str Purpose: Gets current position of read/write mark in given stream Parameters: str = stream Returns: position of mark Memory/Binary = exact number of bytes read/written from beginning of stream Text = ambigious, can only be sure pos increases after read/writes Example: curr_pos = glk_stream_get_position(gg_mywrite_str); ---------------------------------------------------------------------------- Stream glk_stream_set_current str Purpose: Sets current stream to given stream, must be an output stream (switches to given stream) Parameters: str = stream Returns: 1 = success GLK_NULL = current stream set to nothing Example: result = glk_stream_set_current(gg_mywrite_str); ---------------------------------------------------------------------------- Stream glk_stream_get_current Purpose: Gets the current stream Parameters: none Returns: stream GLK_NULL = none Example: curr_str = glk_stream_get_current(); ---------------------------------------------------------------------------- Stream glk_put_char ch Purpose: Prints one character to current stream Parameters: ch = character Returns: 1 = success, 0 = failure Example: result = glk_put_char('A'); ---------------------------------------------------------------------------- Stream glk_put_char_stream str ch Purpose: Prints one character to given stream Parameters: str = stream ch = character Returns: 1 = success, 0 = failure Example: result = glk_put_char_stream(gg_mywrite_str, 'A'); ---------------------------------------------------------------------------- Stream glk_put_string s Purpose: Prints NULL terminated string to current stream Parameters: s = string Returns: 1 = success, 0 = failure Example: result = glk_put_string("Hello."); ---------------------------------------------------------------------------- Stream glk_put_string_stream str s Purpose: Prints NULL terminated string to given stream Parameters: str = stream s = string Returns: 1 = success, 0 = failure Example: result = glk_put_string_stream(gg_mywrite_str, "Hello."); ---------------------------------------------------------------------------- Stream glk_put_buffer buf len Purpose: Prints block of characters to current stream, equivalent to: for (i = 0: i < len: i++) print (char) buf->(i); Parameters: buf = buffer array len = length of block to print Returns: 1 = success, 0 = failure Example: result = glk_but_buffer(my_buffer, my_buffer_len); ---------------------------------------------------------------------------- Stream glk_put_buffer_stream str buf len Purpose: Prints block of characters to given stream, equivalent to: for (i = 0: i < len: i++) print (char) buf->(i); Parameters: str = stream buf = buffer array len = length of block to print Returns: 1 = success, 0 = failure result = glk_put_buffer_stream(gg_mywrite_str, my_buffer, my_buffer_len); ---------------------------------------------------------------------------- Stream Style glk_set_style styl Purpose: Sets given text style Parameters: styl = style to be set uses constant style_(specific) Returns: 1 = success, 0 = failure Example: result = glk_set_style_stream(style_Emphasized); ---------------------------------------------------------------------------- Stream Style glk_set_style_stream str styl Purpose: Sets given text style for given stream Parameters: styl = style to be set uses constant style_(specific) Returns: 1 = success, 0 = failure Example: result = glk_set_style_stream(gg_mywrite_str, style_Emphasized); ---------------------------------------------------------------------------- Stream glk_get_char_stream str Purpose: Reads one character from given stream Parameters: str = stream Returns: character = 0 - 255 may use constant keycode_(specific) Example: ch = glk_get_char(gg_myread_str); ---------------------------------------------------------------------------- Stream glk_get_line_stream str buf len Purpose: Reads characters from given stream until len-1 or a newline has been reached Puts terminating NULL, '\0', in buffer Parameters: str = stream buf = butter array len = number of characters to read Returns: number of characters actually read, including the new line if there is one, but not the NULL Example: char_count = glk_get_line(gg_myread_str, my_buffer+WORDSIZE, my_buffer_len); Note: glk_get_line_stream doesn't set aside the first four bytes of the passed array for the length, which is why the address must be juggled. The Glulx Inform library sometimes also uses this function with the input buffer. Also see notes for glk_request_line_event. ---------------------------------------------------------------------------- glk_get_buffer_stream str buf len Stream Purpose: Reads len number of characters from given stream into a buffer, unless end of stream is reached first No terminal NULL is placed in buffer Parameters: str = stream buf = buffer array len = number of characters to read Returns: number of characters actually read Example: char_count = glk_get_buffer_stream(gg_mywrite_str, my_buffer, my_buffer_len); ---------------------------------------------------------------------------- Stream Style Hint glk_stylehint_set wintype styl hint val Purpose: Suggests the given style hint for given style category Only affects windows created subsequently Parameters: wintype = type of window uses constant wintype_(specific) may use constant wintype_AllTypes styl = style category suggesting hint for uses constant style_(specific) hint = style hint uses constant stylehint_(specific) val = value of specific hint Varies depending on style hint set Indentation/ParaIndentation = metric amount of indentation Justification, which justification used = just_LeftFlush, just_LeftRight, etc. Size = metric size of font Weight = 1 = heavy font 0 = normal weight -1 = lightweight Oblique = 1 = italic 0 = normal angle Proportional = 1 = proportional 0 = fixed width TextColor = decimal/hexadecimal number of color Background = decimal/hexadecimal number of color ReverseColor = 1 if colors are reversed 0 if normal Returns: 1 = success, 0 = failure Examples: suggesting normal text use white text on a black background glk_stylehint_set(wintype_TextBuffer, style_Normal, stylehint_BackColor, $000000); glk_stylehint_set(wintype_TextBuffer, style_Normal, stylehint_TextColor, $ffffff); suggesting note text use a proportional font with left justification glk_stylehint_set(wintype_TextBuffer, style_Note, stylehint_Proportional, 0); glk_stylehint_set(wintype_TextBuffer, style_Note, stylehint_just_FlushLeft, 0); ---------------------------------------------------------------------------- Stream Style Hint glk_stylehint_clear wintype styl hint Purpose: Clears the given style hint from given style category Parameters: wintype = type of window uses constant wintype_(specific) may use constant wintype_AllTypes styl = style category clearing style hint from uses constant style_(specific) hint = style hint uses constant stylehint_(specific) Returns: 1 = success, 0 = failure Examples: result = glk_stylehint_clear(wintype_TextBuffer, style_Note, stylehint_Proportional); result = glk_stylehint_clear(wintype_TextBuffer, style_Note, stylehint_just_FlushLeft); ---------------------------------------------------------------------------- Stream Style Hint glk_style_distinguish win styl1 styl2 Purpose: Sees if two styles are visually distinguisable in given window Parameters: win = window styl1 = style category uses constant style_(specific) styl2 = style attribute (hint) uses constant style_(specific) Returns: 1 = true, 0 = false Example: result = glk_style_distinguish(gg_mytext_win, style_Normal, style_Emphasized); ---------------------------------------------------------------------------- Stream Style Hint glk_style_measure win styl hint result Purpose: Determines attributes of given style in given window Parameters: win = window styl = category uses constant style_(specific) hint = style attribute (hint) uses constant stylehint_(specific) result = pointer/address to be filled in with result (gg_arguments) Varies depending on style hint tested Indentation/ParaIndentation = metric amount of indentation Justification, which justification used = just_LeftFlush, just_LeftRight, etc. Size = metric size of font Weight = 1 = heavy font 0 = normal weight -1 = lightweight Oblique = 1 = italic 0 = normal angle Proportional = 1 = proportional 0 = fixed width TextColor = decimal/hexadecimal number of color Background = decimal/hexadecimal number of color ReverseColor = 1 if colors are reversed 0 if normal Returns: 1 = success, 0 = failure Example: result = glk_style_measure(gg_mytext_win, style_Normal, stylehint_Oblique, gg_arguments); normal_oblique = gg_arguments-->0; ---------------------------------------------------------------------------- File Reference glk_fileref_create_temp usage rock Purpose: Creates a new temporary file, file must not already exist May be deleted automatically upon exit or game end Parameters: usage = data usage + format usage data/saved game/transcript/input record and text mode/binary mode uses constant fileusage_(specific) rock = unique id number Returns: file reference GLK_NULL = failure Example: gg_mytemp_fref = glk_fileref_create_temp(fileusage_Data + fileusage_TextMode, 413); ---------------------------------------------------------------------------- File Reference glk_fileref_create_by_name usage name rock Purpose: Creates file with the given name Parameters: usage = data usage + format usage data/saved game/transcript/input record and text mode/binary mode uses constant fileusage_(specific) name = due to platform differences, safest to stick to eight letters (in caps), suffix based on usage will be added by the interpreter rock = unique id number Returns: file reference GLK_NULL = failure Examples: gg_mywrite_fref = glk_fileref_create_by_name(fileusage_Data + fileusage_BinaryMode, "TEST", 410); ---------------------------------------------------------------------------- File Reference glk_fileref_create_by_prompt usage fmode rock Purpose: Creates a file by asking player to provide the name, either entered or selected from a platform-dependent file navigator Parameters: usage = data usage + format usage data/saved game/transcript/input record and text mode/binary mode uses constant fileusage_(specific) fmode = read & write file mode write/read/read write/write append uses constant filemode_(specific) rock = unique id number Returns: file reference GLK_NULL = failure Examples: gg_mywrite_fref = glk_fileref_create_by_prompt(fileusage_Data + fileusage_BinaryMode, filemode_Write, 410); gg_myread_fref = glk_fileref_create_by_prompt(fileusage_Data + fileusage_BinaryMode, filemode_Read, 411); ---------------------------------------------------------------------------- File Reference glk_fileref_create_from_fileref usage fref rock Purpose: Copies existing file reference, but changes the usage - original file is not modified Parameters: usage = data usage + format usage data/saved game/transcript/input record and text mode/binary mode uses constant fileusage_(specific) fref = file reference rock = unique id number Returns: file reference GLK_NULL = failure Example: gg_mytrans_fref = glk_fileref_from_fileref(fileusage_Transcript + fileusage_BinaryMode, gg_myread_fref, 414); ---------------------------------------------------------------------------- File Reference glk_fileref_destroy fref Purpose: Destroys given file reference (destroys the file reference object, not the disk file) File references are used to open files, not for accessing the file stream, so it's legal to destroy a file reference while the file is still open Parameters: fref = file reference Returns: 1 = success, 0 = failure Example: result = glk_fileref_destroy(gg_mywrite_fref); ---------------------------------------------------------------------------- File Reference glk_fileref_iterate fref rockptr Purpose: Loops through existing file references (class membership) Parameters: fref = GLK_NULL = returns first file reference object fref = returns next file reference object after this one rockptr = pointer/address to be filled in with each fref rock number (gg_arguments) GLK_NULL = don't want rock numbers Returns: file reference GLK_NULL = when reaches end Example: obj = glk_fileref_iterate(GLK_NULL, GLK_NULL); while (obj) { ! do something with fref obj obj = glk_fileref_iterate(obj, GLK_NULL); } ---------------------------------------------------------------------------- File Reference glk_fileref_get_rock fref Purpose: Gets the rock number of given file reference Parameters: fref = file reference Returns: rock number GLK_NULL = failure Example: fref_rock = glk_fileref_get_rock(gg_mywrite_ref); ---------------------------------------------------------------------------- File Reference glk_fileref_delete_file fref Purpose: Actually deletes given disk file Parameters: fref = file reference Returns: 1 = success, 0 = failure Exmample: result = glk_fileref_delete_file(gg_mywrite_fref); ---------------------------------------------------------------------------- File Reference glk_fileref_does_file_exist fref Purpose: Tests to see given file already exists Parameters: fref = file reference Returns: 1 = true, 0 = false Example: result = glk_fileref_does_file_exist(gg_myread_fref); ---------------------------------------------------------------------------- Event Internal glk_select event Purpose: All user interface is done through glk_select - glk_main calls glk_select and it waits for an event, then returns it in a structure Halts game until event arrives Inform programmers should use HandleGlkEvent Parameters: event = pointer to/address of structure to be filled in with event information (gg_event) Returns: 1 = success, 0 = failure ---------------------------------------------------------------------------- Event Internal glk_select_poll event Purpose: Polls (finds) if any events are pending, (mainly used by interpreter programmers, not recommended it be called often) Inform programmers should probably limit their usage to polling for timer events when a lot of other things are also going on Parameters: event = pointer to/address of structure to be filled in with event information (gg_event) Returns: 1 = success, 0 = failure ---------------------------------------------------------------------------- Event Timer glk_request_timer_events millisecs Purpose: Requests timed events Unlike input events, timer events can be tested with glk_select_poll or glk_select Parameters: millisecs = milliseconds Returns: 1 = success, 0 = failure Example: result = glk_request_timer_events(300); ---------------------------------------------------------------------------- Event Line Input Internal glk_request_line_event win buf maxlen initlen Purpose: Reguests line input in given window (used by Glulx Inform's normal I/O) Parameters: win = window buf = buffer array maxlen = maximum length of line in bytes initlen = nonzero = first initlen of buffer will be entered as pre-existing input, as if the player entered it themselves Returns: 1 = success, 0 = failure Example: puts line in author-created buffer result = glk_request_line_event(gg_mytext_win, my_buffer, my_buffer_len, GLK_NULL); Notes: The Glulx Inform library already uses glk_request_line_event with the input buffer. So if a game author used initlen to enter a command into the input buffer as if the player typed it, there could be a conflict. And if initlen is used with an author-created buffer, there will be no effect. So Zarf (Andrew Plotin) recommends that the game author (always) use this code in HandleGlkEvent to achieve the same result. Entering command into the input buffer as if player typed it: newcmd = "command"; cmdlen = PrintAnyToArray(abortes+WORDSIZE, INPUT_BUFFER_LEN-WORDSIZE,newcmd); abortres-->0 = cmdlen; return 2; PrintAnyToArray doesn't set aside the first four bytes for the length of the buffer, which is why the address must be juggled. Also in parserm.h, INPUT_BUFFER_LEN is declared, for various reasons, as one more than the buffer's actual length, so that address must be juggled as well. PrintAnyToArry will return the exact byte length, so it can be used to find the length of anything, including functions. ---------------------------------------------------------------------------- Event Character Input glk_request_char_event win Purpose: Requests character input in given window Parameters: win = window Returns: 1 = success, 0 = failure Example: result = glk_request_char_event(gg_mytext_win); ---------------------------------------------------------------------------- Event Mouse Input glk_request_mouse_event win Purpose: Requests mouse input in given window Parameters: win = window Returns: 1 = success, 0 = failure Example: result = glk_request_mouse_event(gg_mygraph_win); ---------------------------------------------------------------------------- Event Line Input glk_cancel_line_event win event Purpose: Cancels line input request in given window It is legal to cancel a line input request in the given window when one isn't pending Parameters: win = window event = event type = will be filled in as if player had hit enter and the input composed so far stored in the input buffer, when canceling this is not necessary uses constant evtype_(specific) GLK_NULL = event type not wanted Returns: 1 = success, 0 = failure Example: result = glk_request_line_event(gg_mytext_win, GLK_NULL); Note: Canceling a line event is best done in HandleGlkEvent anyway, and it automatically retrieves the event type. ---------------------------------------------------------------------------- Event Character Input glk_cancel_char_event win Purpose: Cancels character input request in given window It is legal to cancel a character input request in the given window when one isn't pending Parameters: win = window Returns: 1 = success, 0 = failure Example: result = glk_cancel_char_event(gg_mytext_win); ---------------------------------------------------------------------------- Event Mouse Input glk_cancel_mouse_event win Purpose: Cancels mouse input request in given window It is legal to cancel a mouse input request in the given window when one isn't pending Parameters: win = window Returns: 1 = success, 0 = failure Example: result = glk_cancel_mouse_event(gg_mygraph_win); ---------------------------------------------------------------------------- Image glk_image_draw win image val1 val2 Purpose: Draws given image in given window Parameters: win = window image = image val1 = graphic window = x coordinate text buffer window = image alignment uses constant imagealign_(specific) val2 = graphic window = y coordinate text buffer window = 0 Returns: 1 = success, 0 = failure Example: result = glk_image_draw(gg_mygraph_win, mess_pic, 0, 0); ---------------------------------------------------------------------------- Image glk_image_draw_scaled win image val1 val2 width height Purpose: Draws given image to scale in given window Parameters: win = window image = image val1 = graphic window = x coordinate text buffer window = image alignment uses constant imagealign_(specific) val2 = graphic window = y coordinate text buffer window = 0 width = height of image height = height of image Returns: 1 = success, 0 = failure Example: result = glk_image_draw_scaled(gg_mygraph_win, mess_pic, 0, 0, 200, 200); ---------------------------------------------------------------------------- Image glk_image_get_info image widthptr heightptr Purpose: Gets information about given image Parameters: image = image widthptr = pointer/address to be filled in with width heightptr = pointer/address to be filled in with height (gg_arguments) Returns: 1 = success, 0 = failure Example: result = glk_image_get_info(mess_pic, gg_arguments, gg_arguments+WORDSIZE); mess_width = gg_arguments-->0; mess_height = gg_arguments-->1; Note: Although infglk does not show this function's width and height having pointer suffixes, they are pointers (see glk specs). ---------------------------------------------------------------------------- Image Text Buffer Window glk_window_flow_break win Purpose: Puts next line of text below a margin-aligned image, works out number of new lines it would take (based on the current font) to put text below image Essentially puts an invisible marker into the text Parameters: win = window Returns: 1 = success, 0 = failure ---------------------------------------------------------------------------- Image Graphic Window glk_window_erase_rect win left top width height Purpose: Erases a rectangular area of given graphic window (clears to current background color) Parameters: win = window left = left side of rectangle top = top of rectangle width = width of rectangle height = height of rectangle Returns: 1 = success, 0 = failure Example: result = glk_window_erase_rect(gg_mygraph_win, 0, 5, 50, 50); ---------------------------------------------------------------------------- Image Graphic Window glk_window_fill_rect win color left top width height Purpose: Fills a rectangular area of given graphic window with a color Parameters: win = window color = decimal/hexadecimal number of color left = left side of rectangle top = top of rectangle width = width of rectangle height = height of rectangle Returns: 1 = success, 0 = failure Example: result = glk_window_fill_rect(gg_mygraph_win, $ff0000, 0, 5, 50, 50); ---------------------------------------------------------------------------- Image Graphic Window glk_window_set_background_color win color Purpose: Sets background color of given window Only affects subsequent clears and resizes Parameters: win = window color = decimal/hexadecimal number of color Returns: 1 = success, 0 = failure Example: result = glk_window_set_background_color(gg_mygraph_win, $C0C0C0) ---------------------------------------------------------------------------- Sound glk_schannel_create rock Purpose: Creates a sound channel Parameters: rock = unique id number for channel Returns: sound channel GLK_NULL = failure Example: result = glk_schannel_create(510); ---------------------------------------------------------------------------- Sound glk_schannel_destroy chan Purpose: Destroys given sound channel Parameters: chan = channel Returns: 1 = success, 0 = failure Example: result = glk_schannel_destroy(gg_mychan); ---------------------------------------------------------------------------- Sound glk_schannel_iterate chan rockptr Purpose: Loops through open channels (class membership) Parameters: chan = GLK_NULL = returns first channel object chan = returns next channel object after this one rockptr = pointer/address to be filled in with each sound channel rock number (gg_arguments) GLK_NULL = don't want rock numbers Returns: sound channel GLK_NULL = when reaches end Example: obj = glk_schannel_iterate(GLK_NULL, GLK_NULL); while (obj) { ! do something with sound channel obj obj = glk_schannel_iterate(obj, GLK_NULL); } ---------------------------------------------------------------------------- Sound glk_schannel_get_rock chan Purpose: Gets rock number of given sound channel Parameters: chan = channel Returns: rock number GLK_NULL = failure Example: chan_rock = glk_schannel_get_rock(gg_mychan); ---------------------------------------------------------------------------- Sound glk_schannel_play chan snd Purpose: Starts a given sound playing in given channel Parameters: chan = channel snd = sound Returns: 1 = success, 0 = failure Example: result = glk_schannel_play(gg_mychan, babble_snd); ---------------------------------------------------------------------------- Sound Event glk_schannel_play_ext chan snd repeats notify Purpose: Starts given sound playing in given channel with repeats Parameters: chan = channel snd = sound repeats = number of times to repeat -1 = played forever 0 = not played at all notify = nonzero to request a sound notification event, when sound finishes playing Returns: 1 = success, 0 = failure Example: result = glk_schannel_play_ext(gg_mychan, babble_snd, 2, 1); ---------------------------------------------------------------------------- Sound glk_schannel_stop chan Purpose: Stops given sound channel playing Parameters: chan = channel Returns: 1 = success, 0 = failure Example: result = glk_schannel_stop(gg_mychan); ---------------------------------------------------------------------------- Sound glk_schannel_set_volume chan vol Purpose: Sets volume of given sound channel Takes effect immediately Parameters: chan = channel vol = decimal/hexadecimal number of volume starts at full volume 65536 ($10000) three quarters volume = 49152 ($C000) half volume = 32768 ($8000) Returns: 1 = success, 0 = failure Example: result = glk_schannel_set_volume(gg_mychan, $C000); ---------------------------------------------------------------------------- Sound glk_sound_load_hint snd flag Purpose: Hints if a specific sound should be loaded Parameters: snd = sound flag = 1 = true, 0 = false Returns: 1 = success, 0 = failure Example: result = glk_sound_load_hint(babble_snd, 1); ---------------------------------------------------------------------------- Hyperlink glk_set_hyperlink linkval Purpose: Turns hyperlinking on/off in current window Parameters: linkval = value = if nonzero, subsequent text is a hyperlinked (usually underlined), each hyperlink should have a unique number 0 = turns hyperlinking off Returns: 1 = success, 0 = failure Example: glk_set_hyperlink(1); print "This is a test."; glk_set_hyperlink(0); ---------------------------------------------------------------------------- Hyperlink glk_set_hyperlink_stream str linkval Purpose: Turns hyperlinking on/off for given stream Parameters: str = stream linkval = value = if nonzero, subsequent text is a hyperlinked (usually underlined), each hyperlink should have a unique number 0 = turns hyperlinking off Returns: 1 = success, 0 = failure Example: glk_set_hyperlink_stream(gg_mywrite_str, 1); print "This is a test."; glk_set_hyperlink_stream(gg_mywrite_str, 0); ---------------------------------------------------------------------------- Hyperlink Event glk_request_hyperlink_event win Purpose: Requests hyperlink input in given window Parameters: win = window Returns: 1 = success, 0 = failure Example: result = glk_request_hyperlink(gg_mytext_win); ---------------------------------------------------------------------------- Hyperlink Event glk_cancel_hyperlink_event win Purpose: Cancels hyperlink input request in given window It is legal to cancel a hyperlink selection request in the given window when one isn't pending Parameters: win = window Returns: 1 = success, 0 = failure Example: result = glk_cancel_hyperlink(gg_mytext_win); ----------------------------------------------------------------------------