All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class org.ifarchive.glk.Glk

java.lang.Object
   |
   +----org.ifarchive.glk.Glk

public class Glk

extends Object

gestalt_CharInput

Test if a character can be input in character input.

gestalt_CharOutput

Test if a character can be output.

gestalt_CharOutput_ApproxPrint

Character may not look right.

gestalt_CharOutput_CannotPrint

Character cannot be meaningfully printed.

gestalt_CharOutput_ExactPrint

Character will be printed exactly as defined.

gestalt_DrawImage

Test if images can be drawn in a particular window type.

gestalt_Graphics

Test if graphics functions are supported.

gestalt_GraphicsTransparency

Test if alpha channels are supported in images.

gestalt_HyperlinkInput

Test if a window type allows hyperlinks.

gestalt_Hyperlinks

Test if hyperlink functions are supported.

gestalt_LineInput

Test if a character can be input in line input.

gestalt_MouseInput

Test if mouse input is supported in a window type.

gestalt_Sound

Test if sound functions are supported.

gestalt_SoundMusic

Test if the library supports music sound resources.

gestalt_SoundNotify

Test if the library supports sound notification events.

gestalt_SoundVolume

Test if the volume can be set for sound channels.

gestalt_Timer

Test if timer events are supported.

gestalt_Version

Return the Glk version supported by the library.

keycode_Delete

This code is returned by the Delete and Backspace keys.

keycode_Down

This code is returned by the cursor down key.

keycode_End

This code is returned by the End key.

keycode_Escape

This code is returned by the Escape key.

keycode_Func1

This code is returned by the F1 key.

keycode_Func10

This code is returned by the F10 key.

keycode_Func11

This code is returned by the F11 key.

keycode_Func12

This code is returned by the F12 key.

keycode_Func2

This code is returned by the F2 key.

keycode_Func3

This code is returned by the F3 key.

keycode_Func4

This code is returned by the F4 key.

keycode_Func5

This code is returned by the F5 key.

keycode_Func6

This code is returned by the F6 key.

keycode_Func7

This code is returned by the F7 key.

keycode_Func8

This code is returned by the F8 key.

keycode_Func9

This code is returned by the F9 key.

keycode_Home

This code is returned by the Home key.

keycode_Left

This code is returned by the cursor left key.

keycode_MAXVAL

This is the number of keycode_* constants.

keycode_PageDown

This code is returned by the PageDown key.

keycode_PageUp

This code is returned by the PageUp key.

keycode_Return

This code is returned by the Enter / Return key.

keycode_Right

This code is returned by the cursor right key.

keycode_Tab

This code is returned by the Tab key.

keycode_Unknown

This code is returned if a key was pressed for which there is no Glk representation.

keycode_Up

This code is returned by the cursor up key.

charToLower(char)

Convert a character to lower case

charToUpper(char)

Convert a character to upper case

dispatchCall(int, Object[])

Dispatch interface.

dispatchCall(int, UniversalUnion[])

Dispatch interface (C-style version).

exit()

Terminate immediately.

gestalt(long)

Request information about the capabilities of the API.

gestalt(long, long)

Request information about the capabilities of the API.

gestalt(long, long, long[])

Request information about the capabilities of the API.

getStream()

Set the current output stream.

glkMain()

A default main() in case jniglk wasn't told what class to load

putBuffer(char[])

Write a character array to the currently selected stream.

putBuffer(char[], int, int)

Write part of a character array to the currently selected stream.

putChar(char)

Write a character to the currently selected stream.

putString(String)

Write a string to the currently selected stream.

requestTimerEvents(long)

Ask Glk to start sending timer events.

select(Event)

Wait for an event and return it.

selectPoll(Event)

Check for an internally spawned event.

setArrayRegistry(ArrayRegistry)

Set a retained array registry.

setHyperlink(int)

Set the current hyperlink value in the current output stream.

setInterruptHandler(InterruptListener)

Set an interrupt handler.

setStream(Stream)

Set the current output stream.

setStyle(int)

Set output style for the currently selected stream.

setWindow(Window)

Set the current stream to a window stream.

stringToLower(String)

Convert a string to lower case

stringToUpper(String)

Convert a string to upper case

styleDistinguish(Window, int, int)

Are two styles visually distinguishable?

styleHintClear(int, int, int)

Unset a stylehint for a window class.

styleHintSet(int, int, int, int)

Set a stylehint for a window class.

styleMeasure(Window, int, int, int[])

Test an attribute of a style in the given window.

tick()

Allow the underlying GLK library to yield if necessary.

 public static final int gestalt_Version

Return the Glk version supported by the library.

• Bits 31-16 = major version number
• Bits 15-8 = minor version number
• Bits 7-0 = revision number

 public static final int gestalt_CharInput

Test if a character can be input in character input.

Pass the character as the second parameter to the gestalt() call.

Returns 1 if the character can be input, 0 if not.

 public static final int gestalt_LineInput

Test if a character can be input in line input.

Pass the character as the second parameter to the gestalt() call.

Returns 1 if the character can be input, 0 if not.

 public static final int gestalt_CharOutput

Test if a character can be output.

Pass the character as the second parameter to the gestalt() call.

Pass an array with one entry to get the number of screen cells this character will take up when printed.

Returns one of gestalt_CharOutput_CannotPrint, gestalt_CharOutput_ApproxPrint, gestalt_CharOutput_ExactPrint

 public static final int gestalt_CharOutput_CannotPrint

Character cannot be meaningfully printed.

See Also:

gestalt_CharOutput

 public static final int gestalt_CharOutput_ApproxPrint

Character may not look right. For example, "ae" may be used for the one-character "ae" ligature, or "e" for an accented "e".

See Also:

gestalt_CharOutput

 public static final int gestalt_CharOutput_ExactPrint

Character will be printed exactly as defined.

See Also:

gestalt_CharOutput

 public static final int gestalt_MouseInput

Test if mouse input is supported in a window type.

Pass the window type as the second parameter to the gestalt() call.

Returns 1 if mouse input is possible, 0 if not.

 public static final int gestalt_Timer

Test if timer events are supported.

Returns 1 if they are, 0 if not.

 public static final int gestalt_Graphics

Test if graphics functions are supported.

Returns 1 if they are, 0 if not.

 public static final int gestalt_DrawImage

Test if images can be drawn in a particular window type.

Pass the window type as the second parameter to the gestalt() call.

Returns 1 if the window supports images, 0 if not.

 public static final int gestalt_Sound

Test if sound functions are supported.

Returns 1 if they are, 0 if not.

 public static final int gestalt_SoundVolume

Test if the volume can be set for sound channels.

Returns 1 if it can, 0 if not.

 public static final int gestalt_SoundNotify

Test if the library supports sound notification events.

Returns 1 if it does, 0 if not.

 public static final int gestalt_Hyperlinks

Test if hyperlink functions are supported.

Returns 1 if they are, 0 if not.

 public static final int gestalt_HyperlinkInput

Test if a window type allows hyperlinks.

Pass the window type as the second parameter to the gestalt() call.

Returns 1 if the window allows hyperlinks, 0 if not.

 public static final int gestalt_SoundMusic

Test if the library supports music sound resources.

Returns 1 if it does, 0 if not.

 public static final int gestalt_GraphicsTransparency

Test if alpha channels are supported in images.

Returns 1 if they are, 0 if not.

 public static final int keycode_Unknown

This code is returned if a key was pressed for which there is no Glk representation.

 public static final int keycode_Left

This code is returned by the cursor left key.

 public static final int keycode_Right

This code is returned by the cursor right key.

 public static final int keycode_Up

This code is returned by the cursor up key.

 public static final int keycode_Down

This code is returned by the cursor down key.

 public static final int keycode_Return

This code is returned by the Enter / Return key.

 public static final int keycode_Delete

This code is returned by the Delete and Backspace keys.

 public static final int keycode_Escape

This code is returned by the Escape key.

 public static final int keycode_Tab

This code is returned by the Tab key.

 public static final int keycode_PageUp

This code is returned by the PageUp key.

 public static final int keycode_PageDown

This code is returned by the PageDown key.

 public static final int keycode_Home

This code is returned by the Home key.

 public static final int keycode_End

This code is returned by the End key.

 public static final int keycode_Func1

This code is returned by the F1 key.

 public static final int keycode_Func2

This code is returned by the F2 key.

 public static final int keycode_Func3

This code is returned by the F3 key.

 public static final int keycode_Func4

This code is returned by the F4 key.

 public static final int keycode_Func5

This code is returned by the F5 key.

 public static final int keycode_Func6

This code is returned by the F6 key.

 public static final int keycode_Func7

This code is returned by the F7 key.

 public static final int keycode_Func8

This code is returned by the F8 key.

 public static final int keycode_Func9

This code is returned by the F9 key.

 public static final int keycode_Func10

This code is returned by the F10 key.

 public static final int keycode_Func11

This code is returned by the F11 key.

 public static final int keycode_Func12

This code is returned by the F12 key.

 public static final int keycode_MAXVAL

This is the number of keycode_* constants.

 public static void glkMain()

A default main() in case jniglk wasn't told what class to load

 public static void exit()

Terminate immediately. This function does not return.

 public static void setInterruptHandler(InterruptListener i)

Set an interrupt handler.

Most platforms have some provision for interrupting a program -- command-period on the Macintosh, control-C in Unix, possibly a window manager menu item, or other possibilities. This can happen at any time, including while execution is nested inside one of your own functions, or inside a Glk library function.

If you need to clean up critical resources, you can specify an interrupt handler class - one that implements the InterruptListener interface.

Initially there is no interrupt handler. You can reset to not having any by calling setInterruptHandler(null).

If you call glk_set_interrupt_handler() with a new handler function while an older one is set, the new one replaces the old one. Glk does not try to queue interrupt handlers.

Parameters:

i - The interface that will be called if the process is interrupted.

See Also:

InterruptListener

 public static void tick()

Allow the underlying GLK library to yield if necessary.

Many platforms have some annoying thing that has to be done every so often, or the gnurrs come from the voodvork out and eat your computer.

Well, not really. But you should call glk_tick() every so often, just in case. It may be necessary to yield time to other applications in a cooperative-multitasking OS, or to check for player interrupts in an infinite loop.

This call is fast; in fact, on average, it does nothing at all. So you can call it often.

 public static long gestalt(long sel)

Request information about the capabilities of the API.

This is exactly the same as the two-parameter version of gestalt(), except that the second parameter is always 0.

Parameters:

sel - The capability you are asking about

Returns:

Information on the requested capability, or 0 if no information is available.

See Also:

gestalt

 public static long gestalt(long sel,
                            long param)

Request information about the capabilities of the API.

Parameters:

sel - The capability you are asking about

value - Additional information on the parameter.

Returns:

Information on the requested capability, or 0 if no information is available.

 public static long gestalt(long sel,
                            long param,
                            long arr[])

Request information about the capabilities of the API.

Parameters:

sel - The capability you are asking about

value - Additional information on the parameter.

arr - More values to pass if required.

Returns:

Information on the requested capability, or 0 if no information is available.

 public static char charToLower(char c)

Convert a character to lower case

Parameters:

c - The character to convert

Returns:

The lowercase version, or (if c is not uppercase) c

 public static char charToUpper(char c)

Convert a character to upper case

Parameters:

c - The character to convert

Returns:

The uppercase version, or (if c is not lowercase) c

 public static String stringToLower(String s)

Convert a string to lower case

Parameters:

s - The string to convert

Returns:

The string with any uppercase characters converted to lower

 public static String stringToUpper(String s)

Convert a string to upper case

Parameters:

s - The string to convert

Returns:

The string with any lowercase characters converted to upper

 public static void select(Event e)

Wait for an event and return it.

Parameters:

e - An Event which will be populated when this function returns

 public static void selectPoll(Event e)

Check for an internally spawned event.

The first question you now ask is, what is an internally-spawned event? selectPoll() does *not* check for or return evtype_CharInput, evtype_LineInput, or evtype_MouseInput events. It is intended for you to test conditions which may have occurred while you are computing, and not interfacing with the player. For example, time may pass during slow computations; you can use selectPoll() to see if a evtype_Timer event has occured.

At the moment, glk_select_poll() checks for evtype_Timer, and possibly evtype_Arrange and evtype_SoundNotify events.

Parameters:

e - An Event which will be populated when this function returns

 public static void requestTimerEvents(long millisecs)

Ask Glk to start sending timer events. Timer events will be sent repeatedly until you call this method with millisecs = 0. Timer events can be missed if other events also arrive.

Parameters:

millisecs - Time spent between each event, 0 to cancel events.

 public static void setStream(Stream s)

Set the current output stream.

This doesn't gain you as much in Java as it does in C, because there are no global functions, so the difference in typing is between Glk.putChar() and myStream.putChar() as opposed to glk_put_char(c) and glk_put_char_stream(my_stream, c)

Parameters:

s - The stream to be used as the default for output. It can be null.

 public static Stream getStream()

Set the current output stream.

Returns:

The current output stream, or null if there is none.

See Also:

setStream

 public static void setWindow(Window w)

Set the current stream to a window stream. This is exactly identical to setStream(w.getStream()).

Parameters:

w - The window whose stream will be used.

See Also:

setStream

 public static void putChar(char c)

Write a character to the currently selected stream.

Parameters:

c - The character to write

See Also:

setStream, putChar

 public static void putString(String s)

Write a string to the currently selected stream.

Parameters:

s - The string to write

See Also:

setStream, putString

 public static void putBuffer(char c[])

Write a character array to the currently selected stream.

Parameters:

c - The character array to write

See Also:

setWindow, putBuffer

 public static void putBuffer(char c[],
                              int first,
                              int len)

Write part of a character array to the currently selected stream.

Parameters:

c - The character array to write

first - The first element to write

len - The number of elements to write

See Also:

setWindow, putBuffer

 public static void setStyle(int style)

Set output style for the currently selected stream.

Parameters:

style - The style to select

See Also:

setWindow, setStyle

 public static void styleHintSet(int wintype,
                                 int styl,
                                 int hint,
                                 int val)

Set a stylehint for a window class.

Parameters:

wintype - The type of window to set the hint for, or Window.wintype_AllTypes

style - The style to set (Stream.style_*)

hint - The stylehint selector (Stream.stylehint_*)

val - The new value of the hint.

 public static void styleHintClear(int wintype,
                                   int styl,
                                   int hint)

Unset a stylehint for a window class.

Parameters:

wintype - The type of window to set the hint for, or Window.wintype_AllTypes

style - The style to set (Stream.style_*)

hint - The stylehint selector (Stream.stylehint_*)

 public static boolean styleDistinguish(Window w,
                                        int styl1,
                                        int styl2)

Are two styles visually distinguishable?

Parameters:

w - The window in which to check

styl1 - The first style (Stream.style_*)

styl2 - The second style (Stream.style_*)

Returns:

true if the two styles can be distinguished, otherwise false.

 public static boolean styleMeasure(Window w,
                                    int styl,
                                    int hint,
                                    int result[])

Test an attribute of a style in the given window.

Parameters:

w - The window in which to check.

styl - The style to test (Stream.style_*).

hint - The hint to try and read (Stream.stylehint_*)

Returns:

true if the attribute could be determined, otherwise false.

 public static void dispatchCall(int func,
                                 Object args[])

Dispatch interface.

In Java, the normal dispatch interface is a bit different from the one that the C library provides. Each argument corresponds exactly to one entry in the args[] array. Argument encoding works like this:

• Basic types (integers, characters) are passed in as instances of the Java wrapper classes (Integer, Character etc.)
• Opaque objects are passed in as-is.
• To pass NULL to a reference argument, pass null.
• To pass an actual reference to a reference argument, pass a Reference object whose target is the current value. For example, to pass in a reference to a window, use:

        args[n] = new Reference(theWindow);
   

  A pass-out reference (one that will be filled in by the library) can be done like this:

        args[n] = new Reference(null);
   

• Arrays are passed in as the array itself - eg:

        byte array[] = new byte[64];
        args[n] = array;
   

• A reference to a structure is passed in a Reference to an array of Objects, one for each field. For example:

   	Object[] structure = new Object[2];
  	structure[0] = mainWindow;
  	structure[1] = new Integer(3);
   	args[0] = new Reference(structure);
   

Here are two examples: calling glk_select():

 
	Event e = new Event();
	Object args[] = new Object[1];
	args[0] = new Reference(null);
 	Glk.dispatchCall(0x00C0, args);
	Object out[] = (Object[])( ((Reference)args[0]).target );
	ev.type   = (Number)(out[0]).intVal();
	ev.window = (Window)(out[1]);
	ev.val1   = (Number)(out[2]).longVal();
	ev.val2   = (Number)(out[3]).longVal();
 

and calling glk_put_buffer_stream:

	byte buf[64];
	...populate buf...
 	Object args[] = new Object[2];
	args[0] = myStream;
 	args[1] = buf;
	Glk.dispatchCall(0x0085, args);
 

An important note: Any Reference argument passed into a function won't necessarily come back referring to the same object. For example, if you did this for glk_select():

 
	Event e = new Event();
 	Object in[] = new Object[4];
	Object args[] = new Object[1];
	args[0] = new Reference(in);
 	Glk.dispatchCall(0x00C0, args);
	Object out[] = (Object[])( ((Reference)args[0]).target );
 

then the array in[] would not be the same as the array out[], and it would be out[] that was populated.

Parameters:

func - The Glk function ID

args - The argument list, in Java form.

 public static void dispatchCall(int func,
                                 UniversalUnion uargs[])

Dispatch interface (C-style version).

This version of the Dispatch interface does no marshalling, so your calling code will have to do all the setting up of UniversalUnions (1 or 2 per reference, 1 or 3 per array, etc.)

The UniversalUnion documentation contains some examples of how to do this for various different types.

Parameters:

func - ID of Glk function to call.

uargs - Marshalled arguments.

See Also:

dispatchCall, UniversalUnion

 public static void setHyperlink(int linkval)

Set the current hyperlink value in the current output stream. A link value is any non-zero integer; zero indicates no link. Subsequent text output is considered to make up the body of the link, which continues until the link value is changed (or set to zero).

Parameters:

linkval - The link value, 0 for no hyperlink.

 public static void setArrayRegistry(ArrayRegistry r)

Set a retained array registry. It will be called when Glk retains or releases arrays.

Parameters:

r - An instance of your array registry.

All Packages  Class Hierarchy  This Package  Previous  Next  Index