docs/reference/glk-windows.sgml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
   4 <!ENTITY version SYSTEM "version.xml">
   5 ]>
   6 <refentry id="chimara-Windows">
   7 <refmeta>
   8 <refentrytitle>Windows</refentrytitle>
   9 <manvolnum>3</manvolnum>
  10 <refmiscinfo>CHIMARA Library</refmiscinfo>
  11 </refmeta>
  12 <refnamediv>
  13 <refname>Windows</refname>
  14 <refpurpose>Introduction to Glk windows</refpurpose>
  15 </refnamediv>
  16 <refsect1>
  17 <title>Description</title>
  18 <para>
  19 On most platforms, the program/library combination will appear to the player in a window &mdash; either a window which covers the entire screen, or one which shares screen space with other windows in a multi-programming environment. Obviously your program does not have worry about the details of this. The Glk screen space is a rectangle, which you can divide into panels for various purposes. It is these panels which I will refer to as <quote>windows</quote> hereafter.
  20 </para>
  21 <para>
  22 You refer to a window using an opaque C structure pointer. See <link linkend="chimara-Opaque-Objects">Opaque Objects</link>.
  23 </para>
  24 <para>
  25 A window has a type. Currently there are four window types:
  26 <variablelist>
  27 <varlistentry>
  28         <term>Text buffer windows</term>
  29         <listitem><para>
  30         A stream of text.
  31         </para>
  32         <note><para>The <quote>story window</quote> of an Infocom game.
  33         </para></note>
  34         <para>
  35         You can only print at the end of the stream, and input a line of text at the end of the stream.
  36         </para></listitem>
  37 </varlistentry>
  38 <varlistentry>
  39         <term>Text grid windows</term>
  40         <listitem><para>
  41         A grid of characters in a fixed-width font.
  42         </para>
  43         <note><para>The <quote>status window</quote> of an Infocom game.
  44         </para></note>
  45         <para>
  46         You can print anywhere in the grid.
  47         </para></listitem>
  48 </varlistentry>
  49 <varlistentry>
  50         <term>Graphics windows</term>
  51         <listitem><para>
  52         A grid of colored pixels. Graphics windows do not support text input or output, but there are image commands to draw in them.
  53         </para>
  54         <note><para>This is an optional capability; not all Glk libraries support graphics. See <link linkend="chimara-Testing-for-Graphics-Capabilities">Testing for Graphics Capabilities</link>.
  55         </para></note></listitem>
  56 </varlistentry>
  57 <varlistentry>
  58         <term>Blank windows</term>
  59         <listitem><para>A blank window. Blank windows support neither input nor output.
  60         </para>
  61         <note><para>They exist mostly to be an example of a <quote>generic</quote> window. You are unlikely to want to use them.
  62         </para></note></listitem>
  63 </varlistentry>
  64 </variablelist>
  65 </para>
  66 <para>
  67 As Glk is an expanding system, more window types may be added in the future. Therefore, it is important to remember that not all window types will necessarily be available under all Glk libraries.
  68 </para>
  69 <para>
  70 There is one other special type of window, the pair window. Pair windows are created by Glk as part of the system of window arrangement. You cannot create them yourself. See <link linkend="wintype-Pair">Pair Windows</link>.
  71 </para>
  72 <para>
  73 Every window has a rock. This is a value you provide when the window is created; you can use it however you want. See <link linkend="chimara-Rocks">Rocks</link>.
  74 </para>
  75 <para>
  76 When Glk starts up, there are no windows.
  77 </para>
  78 <note><para>
  79 When I say there are no windows, I mean there are no Glk windows. In a multiprogramming environment, such as X or MacOS, there may be an application window visible; this is the screen space that will contain all the Glk windows that you create. But at first, this screen space is empty and unused.
  80 </para></note>
  81 <para>
  82 Without a window, you cannot do any kind of input or output; so the first thing you'll want to do is create one. See <link linkend="chimara-Window-Opening-Closing-and-Constraints">Window Opening, Closing, and Constraints</link>.
  83 </para>
  84 <para>
  85 You can create as many windows as you want, of any types. You control their arrangement and sizes through a fairly flexible system of calls. See <link linkend="chimara-Window-Arrangement">Window Arrangement</link>.
  86 </para>
  87 <para>
  88 You can close any windows you want. You can even close all the windows, which returns you to the original startup state.
  89 </para>
  90 <para>
  91 You can request input from any or all windows. Input can be mouse input (on platforms which support a mouse), single-character input, or input of an entire line of text. It is legal to request input from several windows at the same time. The library will have some interface mechanism for the player to control which window he is typing in.
  92 </para>
  93 </refsect1>
  94 </refentry>