docs/reference/glk-main-function.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 ]>
   5 <refentry id="chimara-Your-Programs-Main-Function">
   6 <refmeta>
   7 <refentrytitle>Your Program's Main Function</refentrytitle>
   8 <manvolnum>3</manvolnum>
   9 <refmiscinfo>CHIMARA Library</refmiscinfo>
  10 </refmeta>
  11 <refnamediv>
  12 <refname>Your Program's Main Function</refname>
  13 <refpurpose>How Glk starts your program</refpurpose>
  14 </refnamediv>
  15 <refsect1>
  16 <title>Description</title>
  17 <para>
  18 The top level of the program &mdash; the <function>main()</function> function in C, for example &mdash; belongs to Glk.
  19 </para>
  20 <note><para>
  21 This means that Glk isn't really a library. In a sense, you are writing a library, which is linked into Glk. This is bizarre to think about, so forget it.
  22 </para></note>
  23 <note><title>Chimara</title>
  24 <para>
  25 In Chimara, the arrangement is even more bizarre. Chimara <emphasis>is</emphasis> a library, and it runs your Glk program from within a GTK+ graphical application (the <quote>host program</quote>). Chimara treats your program as a plugin, or shared library, and it executes your program in its own thread, displaying windows and output in the GTK+ program.
  26 </para>
  27 <para>
  28 This makes absolutely no difference to you, the Glk <emphasis>programmer</emphasis>; if your program works correctly with a <quote>regular</quote> Glk library, it will also work properly with Chimara. The only difference is in compiling your Glk program.
  29 </para></note>
  30 <para>
  31 You define a function called glk_main(), which the library calls to begin running your program. glk_main() should run until your program is finished, and then return.
  32 </para>
  33 <para>
  34 Glk does all its user-interface work in a function called glk_select(). This function waits for an event &mdash; typically the player's input &mdash; and returns an structure representing that event. This means that your program must have an event loop. In the very simplest case, you could write
  35 </para>
  36 <informalexample>
  37 <programlisting>
  38 void glk_main()
  39 {
  40     #event_t ev;
  41     while (1) {
  42         #glk_select(&amp;ev);
  43         switch (ev.type) {
  44             default:
  45                 /* do nothing */
  46                 break;
  47         }
  48     }
  49 }
  50 </programlisting>
  51 </informalexample>
  52 <para>
  53 This is a legal Glk-compatible program. As you might expect, it doesn't do anything. The player will see an empty window, which he can only stare at, or destroy in a platform-defined standard manner.
  54 </para>
  55 <note><para>
  56 <keycombo action="simul"><keycap function="command">Command</keycap><keycap>period</keycap></keycombo> on the Macintosh; a <guimenuitem>kill-window</guimenuitem> menu option in an X window manager; <keycombo action="simul"><keycap function="control">control</keycap><keycap>C</keycap></keycombo> in a curses terminal window.
  57 </para></note>
  58 <note><title>Chimara</title>
  59 <para>
  60 In Chimara, there is no standard way; the program will stop when the host program calls chimara_glk_stop(). The host program might have a <quote>Stop</quote> button which does this, for example, but it will also generally happen when the #ChimaraGlk widget is destroyed or when the host program ends.
  61 </para></note>
  62 <note><para>
  63 However, this program does not spin wildly and burn CPU time. The glk_select() function waits for an event it can return. Since it only returns events which you have requested, it will wait forever, and grant CPU time to other processes if that's meaningful on the player's machine.
  64 </para></note>
  65 <note><para>
  66 Actually, there are some events which are always reported. More may be defined in future versions of the Glk API. This is why the default response to an event is to do nothing. If you don't recognize the event, ignore it.
  67 </para></note>
  68 </refsect1>
  69 </refentry>