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.
  28
  29 If your Lisp supports multithreading, it starts the main loop in background thread (if it had not been started) and immediately returns. If your Lisp does not support multithreading, the main loop is started and waits for it to complete.
  30
  31 Calls to @ref{ensure-gtk-main} must be paired by calls to @ref{leave-gtk-main}. When the @ref{leave-gtk-main} is called the same number of time as @ref{ensure-gtk-main} is called then the main loop quits (e.g., main loops are nested).
  32
  33 It is also useful to call @ref{join-gtk-main} after @ref{ensure-gtk-main} to wait for main loop to quit.
  34
  35 @RFunction leave-gtk-main
  36 @lisp
  37 (leave-gtk-main)
  38 @end lisp
  39 This function terminates the gtk main loop.
  40
  41 Calls to @ref{ensure-gtk-main} must be paired by calls to @ref{leave-gtk-main}. When the @ref{leave-gtk-main} is called the same number of time as @ref{ensure-gtk-main} is called then the main loop quits (e.g., main loops are nested).
  42
  43
  44 @RFunction join-gtk-main
  45 @lisp
  46 (join-gtk-thread)
  47 @end lisp
  48 This function waits for the background thread that runs the Gtk+ main loop to quit. See @ref{ensure-gtk-main}.
  49
  50 @RFunction gtk-main-iteration
  51 @lisp
  52 (gtk-main-iteration) @result{} boolean
  53 @end lisp
  54 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.
  55
  56 Returns a boolean that is true if @ref{gtk-main-quit} has been called for the innermost mainloop.
  57
  58 @RFunction gtk-main-iteration-do
  59 @lisp
  60 (gtk-main-iteration-do blocking) @result{} boolean
  61 @end lisp
  62
  63 @table @var
  64 @item @var{blocking}
  65 True if you want Gtk+ to block if no events are pending
  66 @end table
  67
  68 Runs a single iteration of the mainloop. If no events are available either return or block dependent on the value of @var{blocking}.
  69
  70 Returns a boolean that is true if @ref{gtk-main-quit} has been called for the innermost mainloop.
  71
  72
  73 @RFunction gtk-events-pending
  74 @lisp
  75 (gtk-events-pending) @result{} boolean
  76 @end lisp
  77 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.
  78
  79 @RFunction gtk-main-add-timeout
  80 @lisp
  81 (gtk-main-add-timeout milliseconds function &key (priority +g-priority-default+)) @result{} source-id
  82 @end lisp
  83
  84 @table @var
  85 @item @var{milliseconds}
  86 An integer specifying the time between calls to the function, in milliseconds (1/1000ths of a second.)
  87 @item @var{function}
  88 The function to call periodically. This function accepts zero arguments and returns a boolean.
  89 @item @var{priority}
  90 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+}.
  91 @item @var{source-id}
  92 An integer identifier of GLib event source.
  93 @end table
  94
  95 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}.
  96 @RMacro within-main-loop
  97 @lisp
  98 (within-main-loop &body body)
  99 @end lisp
 100 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.
 101
 102 Returns immediately. If the main loop was not started, uses @ref{ensure-gtk-main} to start it.
 103
 104 @RMacro within-main-loop-and-wait
 105 @lisp
 106 (within-main-loop-and-wait &body body) @result{} results
 107 @end lisp
 108 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.
 109
 110 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.
 111
 112 If the main loop was not started, uses @ref{ensure-gtk-main} to start it.
 113
 114 @RFunction call-from-gtk-main-loop
 115 @lisp
 116 (call-from-gtk-main-loop function &key (priority +g-priority-default-idle+))
 117 @end lisp
 118
 119 @table @var
 120 @item @var{function}
 121 The function to be called. Accepts zero arguments.
 122 @item @var{priority}
 123 An integer specifying the priority of the call.
 124 @end table
 125
 126 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.
 127
 128 If the main loop was not started, uses @ref{ensure-gtk-main} to start it.
 129
 130 @RFunction call-within-main-loop-and-wait
 131 @lisp
 132 (call-from-gtk-main-loop-and-wait function)
 133 @end lisp
 134
 135 @table @var
 136 @item @var{function}
 137 The function to be called. Accepts zero arguments and returns zero, one or more values.
 138 @end table
 139
 140 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.
 141
 142 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.
 143
 144 If the main loop was not started, uses @ref{ensure-gtk-main} to start it.
 145
 146 @RCondition gtk-call-aborted
 147
 148 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.
 149
 150 @RFunction gtk-call-aborted-condition
 151
 152 Returns the error that caused call to aborted.
 153
 154 @RFunction grab-add
 155
 156 Undocumented yet