src/glk.c

   1 #include <gtk/gtk.h>
   2
   3 #include "glk.h"
   4 #include "abort.h"
   5 #include "chimara-glk.h"
   6 #include "chimara-glk-private.h"
   7
   8 ChimaraGlkPrivate *glk_data = NULL;
   9
  10 /**
  11  * glk_exit:
  12  *
  13  * If you want to shut down your program in the middle of your <function>
  14  * glk_main()</function> function, you can call glk_exit().
  15  *
  16  * This function does not return.
  17  *
  18  * If you print some text to a window and then shut down your program, you can
  19  * assume that the player will be able to read it. Most likely the Glk library
  20  * will give a <quote><computeroutput>Hit any key to
  21  * exit</computeroutput></quote> prompt. (There are other possiblities, however.
  22  * A terminal-window version of Glk might simply exit and leave the last screen
  23  * state visible in the terminal window.)
  24  *
  25  * <note><para>
  26  * You should only shut down your program with glk_exit() or by returning from
  27  * your <function>glk_main()</function> function. If you call the ANSI
  28  * <function>exit()</function> function, bad things may happen. Some versions of
  29  * the Glk library may be designed for multiple sessions, for example, and you
  30  * would be cutting off all the sessions instead of just yours. You would
  31  * probably also prevent final text from being visible to the player.
  32  * </para></note>
  33  * <note><title>Chimara</title>
  34  * <para>
  35  * If there are any windows open at the time glk_exit() is called, then Chimara
  36  * will leave them open. This way, the final text remains visible. Note that bad
  37  * things most definitely <emphasis>will</emphasis> happen if you use the ANSI
  38  * <function>exit()</function>.
  39  * </para></note>
  40  */
  41 void
  42 glk_exit(void)
  43 {
  44     g_signal_emit_by_name(glk_data->self, "stopped");
  45
  46         /* Stop any timers */
  47         glk_request_timer_events(0);
  48
  49     glk_data = NULL;
  50         g_thread_exit(NULL);
  51 }
  52
  53 /**
  54  * glk_tick:
  55  *
  56  * Carries out platform-dependent actions such as yielding time to the operating
  57  * system and checking for interrupts. glk_tick() should be called every so
  58  * often when there is a long interval between calls of glk_select() or
  59  * glk_select_poll(). This call is fast; in fact, on average, it does nothing at
  60  * all. So you can call it often.
  61  *
  62  * <note><para>
  63  *   In a virtual machine interpreter, once per opcode is appropriate. In a
  64  *   program with lots of computation, pick a comparable rate.
  65  * </para></note>
  66  *
  67  * glk_tick() does not try to update the screen, or check for player input, or
  68  * any other interface task. For that, you should call glk_select() or
  69  * glk_select_poll(). See <link linkend="chimara-Events">Events</link>.
  70  *
  71  * <note>
  72  *   <para>Captious critics have pointed out that in the sample program
  73  *   <filename>model.c</filename>, I do not call glk_tick() at all. This is
  74  *   because <filename>model.c</filename> has no heavy loops. It does a bit of
  75  *   work for each command, and then cycles back to the top of the event loop.
  76  *   The glk_select() call, of course, blocks waiting for input, so it does all
  77  *   the yielding and interrupt-checking one could imagine.
  78  *   </para>
  79  *   <para>Basically, you must ensure there's some fixed upper bound on the
  80  *   amount of computation that can occur before a glk_tick() (or glk_select())
  81  *   occurs. In a VM interpreter, where the VM code might contain an infinite
  82  *   loop, this is critical. In a C program, you can often eyeball it.
  83  *   </para>
  84  *   <para>But the next version of <filename>model.c</filename> will have a
  85  *   glk_tick() in the ornate printing loop of <function>verb_yada()</function>.
  86  *   Just to make the point.
  87  *   </para>
  88  * </note>
  89  */
  90 void
  91 glk_tick()
  92 {
  93         check_for_abort();
  94
  95         /* Do one iteration of the main loop if there are any events */
  96         gdk_threads_enter();
  97         if(gtk_events_pending())
  98                 gtk_main_iteration();
  99         gdk_threads_leave();
 100 }
 101