docs/reference/glk-other-events.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-Other-Events">
   6 <refmeta>
   7 <refentrytitle>Other Events</refentrytitle>
   8 <manvolnum>3</manvolnum>
   9 <refmiscinfo>CHIMARA Library</refmiscinfo>
  10 </refmeta>
  11 <refnamediv>
  12 <refname>Other Events</refname>
  13 <refpurpose>Events in future versions of Glk</refpurpose>
  14 </refnamediv>
  15 <refsect1>
  16 <para>
  17 There are currently no other event types defined by Glk. (The <quote>#evtype_None</quote> constant is a placeholder, and is never returned by glk_select().)
  18 </para>
  19 <para>
  20 It is possible that new event types will be defined in the future.
  21 </para>
  22 <note><para>For example, if video or animation capabilities are added to Glk, there would probably be some sort of completion event for them.
  23 </para></note>
  24 <note><para>
  25 This is also why you must put calls to glk_select() in loops. If you tried to read a character by simply writing
  26 <informalexample><programlisting>
  27 #glk_request_char_event(win);
  28 #glk_select(&amp;ev);
  29 </programlisting></informalexample>
  30 you might not get a CharInput event back. You could get some not-yet-defined event which happened to occur before the player hit a key. Or, for that matter, a window arrangement event.
  31 </para></note>
  32 <note><para>
  33 It is not generally necessary to put a call to glk_select_poll() in a loop. You usually call glk_select_poll() to update the display or test if an event is available, not to wait for a particular event. However, if you are using sound notification events, and several sounds are playing, it might be important to make sure you knew about all sounds completed at any particular time. You would do this with
  34 <informalexample><programlisting>
  35 #glk_select_poll(&amp;ev);
  36 while (ev.type != #evtype_None) {
  37     /* handle event */
  38     #glk_select_poll(&amp;ev);
  39 }
  40 </programlisting></informalexample>
  41 </para>
  42 <para>
  43 Once glk_select_poll() returns #evtype_None, you should not call it again immediately. Do some work first. If you want to wait for an event, use glk_select(), not a loop of glk_select_poll().
  44 </para></note>
  45 </refsect1>
  46 </refentry>