doc/gtk.main_loop.texi

   1 Gtk+ is an event-driven toolkit and it naturally is built around the event dispatching loop. The Gtk+ Main loop is a @ref{GLib Main loop}. This section describes Gtk+-specific usage of the main loop.
   2
   3 Gtk+ main loop is run in a background thread that is launched by @ref{ensure-gtk-main} (however it is also possible to launch Gtk+ main loop with @ref{gtk-main} that does not spawn threads). This allows interactive development: while the Gtk+ thread is blocked by waiting for events or processing them, REPL thread is alive.
   4
   5 Gtk+ is not thread-safe, but thread-aware. This means that any access to Gtk+ from the thread different from the thread running the main loop must be explicitly synchronized with Gtk+. There are two ways to call Gtk+ from another thread:
   6 @itemize
   7 @item Use @code{gdk_threads_enter}, @code{gdk_threads_leave}. This is unsupported at this time on cl-gtk2.
   8 @item Use @ref{within-main-loop} and related macros and functions.
   9 @end itemize
  10
  11 @RFunction gtk-main
  12 @lisp
  13 (gtk-main)
  14 @end lisp
  15 This function runs the main loop and returns when the main loop is terminated. (see @ref{gtk-main-quit} and @ref{ensure-gtk-main})
  16
  17 @RFunction gtk-main-quit
  18 @lisp
  19 (gtk-main-quit)
  20 @end lisp
  21 This function causes the main loop to terminate and causes @ref{gtk-main} to return.
  22
  23 @RFunction ensure-gtk-main
  24 @lisp
  25 (ensure-gtk-main)
  26 @end lisp
  27 This function ensures that the Gtk+ main loop is started in background thread. If the loop has not been started or if had been terminated, restarts the background thread.
  28
  29 @RFunction join-main-thread
  30 @lisp
  31 (join-main-thread)
  32 @end lisp
  33 This function waits for the background thread that runs the Gtk+ main loop to quit.
  34
  35 @RFunction gtk-main-iteration
  36 @lisp
  37 (gtk-main-iteration) @result{} boolean
  38 @end lisp
  39 Runs a single iteration of the mainloop. If no events are waiting to be processed Gtk+ will block until the next event is noticed. If you don't want to block look at @ref{gtk-main-iteration-do} or check if any events are pending with @ref{gtk-events-pending} first.
  40
  41 Returns a boolean that is true if @ref{gtk-main-quit} has been called for the innermost mainloop.
  42
  43 @RFunction gtk-main-iteration-do
  44 @lisp
  45 (gtk-main-iteration-do blocking) @result{} boolean
  46 @end lisp
  47
  48 @table @var
  49 @item @var{blocking}
  50 True if you want Gtk+ to block if no events are pending
  51 @end table
  52
  53 Runs a single iteration of the mainloop. If no events are available either return or block dependent on the value of @var{blocking}.
  54
  55 Returns a boolean that is true if @ref{gtk-main-quit} has been called for the innermost mainloop.
  56
  57
  58 @RFunction gtk-events-pending
  59 @lisp
  60 (gtk-events-pending) @result{} boolean
  61 @end lisp
  62 Checks if any events are pending. This can be used to update the GUI and invoke timeouts etc. while doing some time intensive computation. Note that this is not the best way to have a responsive GUI - it is usually better to do work in background thread.
  63
  64 @RFunction gtk-main-add-timeout
  65 @lisp
  66 (gtk-main-add-timeout milliseconds function &key (priority +g-priority-default+)) @result{} source-id
  67 @end lisp
  68
  69 @table @var
  70 @item @var{milliseconds}
  71 An integer specifying the time between calls to the function, in milliseconds (1/1000ths of a second.)
  72 @item @var{function}
  73 The function to call periodically. This function accepts zero arguments and returns a boolean.
  74 @item @var{priority}
  75 An integer specifying the priority of the timeout. Typically this will be in the range between @ref{+g-priority-default+} and @ref{+g-priority-high+}.
  76 @item @var{source-id}
  77 An integer identifier of GLib event source.
  78 @end table
  79
  80 Registers a @var{function} to be called periodically. The function will be called repeatedly after once per @var{milliseconds} until it returns False at which point the timeout is destroyed and will not be called again. Timeout can also be removed by passing @var{source-id} to @ref{g-source-remove}.
  81 @RMacro within-main-loop
  82 @lisp
  83 (within-main-loop &body body)
  84 @end lisp
  85 Schedules the @var{body} to be evaluated within the main loop. Expression inside @var{body} are run inside the main loop, so they can call any Gtk+ functions. This expression may be evaluated in any thread.
  86
  87 Returns immediately. If the main loop was not started, uses @ref{ensure-gtk-main} to start it.
  88
  89 @RMacro within-main-loop-and-wait
  90 @lisp
  91 (within-main-loop-and-wait &body body) @result{} results
  92 @end lisp
  93 Schedules the @var{body} to be evaluated within the main loop. Expression inside @var{body} are run inside the main loop, so they can call any Gtk+ functions. This expression may be evaluated in any thread.
  94
  95 Returns the values produced by evaluating @var{body}. If the evaluation of @var{body} results in unhandled error, the @ref{gtk-call-aborted} error condition is signaled.
  96
  97 If the main loop was not started, uses @ref{ensure-gtk-main} to start it.
  98
  99 @RFunction call-from-gtk-main-loop
 100 @lisp
 101 (call-from-gtk-main-loop function &key (priority +g-priority-default-idle+))
 102 @end lisp
 103
 104 @table @var
 105 @item @var{function}
 106 The function to be called. Accepts zero arguments.
 107 @item @var{priority}
 108 An integer specifying the priority of the call.
 109 @end table
 110
 111 Schedules the @var{function} to be called within the main loop. @var{function} is evaluated inside the main loop, so it can call any Gtk+ functions. This function may be called from any thread.
 112
 113 If the main loop was not started, uses @ref{ensure-gtk-main} to start it.
 114
 115 @RFunction call-within-main-loop-and-wait
 116 @lisp
 117 (call-from-gtk-main-loop-and-wait function)
 118 @end lisp
 119
 120 @table @var
 121 @item @var{function}
 122 The function to be called. Accepts zero arguments and returns zero, one or more values.
 123 @end table
 124
 125 Schedules the @var{function} to be called within the main loop. @var{function} is evaluated inside the main loop, so it can call any Gtk+ functions. This function may be called from any thread.
 126
 127 Returns the values produced by calling @var{function}. If the evaluation of @var{function} results in unhandled error, the @ref{gtk-call-aborted} error condition is signaled.
 128
 129 If the main loop was not started, uses @ref{ensure-gtk-main} to start it.
 130
 131 @RCondition gtk-call-aborted
 132
 133 A condition inheriting from @code{error} that is used to signal the fact that the evaluation of expression or function in main loop by @ref{within-main-loop}, @ref{within-main-loop-and-wait}, @ref{call-from-gtk-main-loop}, @ref{call-within-main-loop-and-wait} was interrupted by error.
 134
 135 @RFunction gtk-call-aborted-condition
 136
 137 Returns the error that caused call to aborted.