doc/gtk.ref.texi

   1 @menu
   2 * Gtk+ Main loop::
   3 @end menu
   4
   5 All symbols of Gtk+ binding in cl-gtk2 reside in @code{gtk} package.
   6
   7 @node Gtk+ Main loop
   8 @chapter Gtk+ Main loop
   9
  10 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.
  11
  12 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.
  13
  14 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:
  15 @itemize
  16 @item Use @code{gdk_threads_enter}, @code{gdk_threads_leave}. This is unsupported at this time on cl-gtk2.
  17 @item Use @ref{within-main-loop} and related macros and functions.
  18 @end itemize
  19
  20 @RFunction gtk-main
  21 @lisp
  22 (gtk-main)
  23 @end lisp
  24 This function runs the main loop and returns when the main loop is terminated. (see @ref{gtk-main-quit} and @ref{ensure-gtk-main})
  25
  26 @RFunction gtk-main-quit
  27 @lisp
  28 (gtk-main-quit)
  29 @end lisp
  30 This function causes the main loop to terminate and causes @ref{gtk-main} to return.
  31
  32 @RFunction ensure-gtk-main
  33 @lisp
  34 (ensure-gtk-main)
  35 @end lisp
  36 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.
  37
  38 @RFunction join-main-thread
  39 @lisp
  40 (join-main-thread)
  41 @end lisp
  42 This function waits for the background thread that runs the Gtk+ main loop to quit.
  43
  44 @RFunction gtk-main-iteration
  45 @lisp
  46 (gtk-main-iteration) @result{} boolean
  47 @end lisp
  48 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.
  49
  50 Returns a boolean that is true if @ref{gtk-main-quit} has been called for the innermost mainloop.
  51
  52 @RFunction gtk-main-iteration-do
  53 @lisp
  54 (gtk-main-iteration-do blocking) @result{} boolean
  55 @end lisp
  56
  57 @table @var
  58 @item @var{blocking}
  59 True if you want Gtk+ to block if no events are pending
  60 @end table
  61
  62 Runs a single iteration of the mainloop. If no events are available either return or block dependent on the value of @var{blocking}.
  63
  64 Returns a boolean that is true if @ref{gtk-main-quit} has been called for the innermost mainloop.
  65
  66
  67 @RFunction gtk-events-pending
  68 @lisp
  69 (gtk-events-pending) @result{} boolean
  70 @end lisp
  71 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.
  72
  73 @RFunction gtk-main-add-timeout
  74 @lisp
  75 (gtk-main-add-timeout milliseconds function &key (priority +g-priority-default+)) @result{} source-id
  76 @end lisp
  77
  78 @table @var
  79 @item @var{milliseconds}
  80 An integer specifying the time between calls to the function, in milliseconds (1/1000ths of a second.)
  81 @item @var{function}
  82 The function to call periodically. This function accepts zero arguments and returns a boolean.
  83 @item @var{priority}
  84 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+}.
  85 @item @var{source-id}
  86 An integer identifier of GLib event source.
  87 @end table
  88
  89 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}.
  90 @RMacro within-main-loop
  91 @lisp
  92 (within-main-loop &body body)
  93 @end lisp
  94 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.
  95
  96 Returns immediately. If the main loop was not started, uses @ref{ensure-gtk-main} to start it.
  97
  98 @RMacro within-main-loop-and-wait
  99 @lisp
 100 (within-main-loop-and-wait &body body) @result{} results
 101 @end lisp
 102 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.
 103
 104 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.
 105
 106 If the main loop was not started, uses @ref{ensure-gtk-main} to start it.
 107
 108 @RFunction call-from-gtk-main-loop
 109 @lisp
 110 (call-from-gtk-main-loop function &key (priority +g-priority-default-idle+))
 111 @end lisp
 112
 113 @table @var
 114 @item @var{function}
 115 The function to be called. Accepts zero arguments.
 116 @item @var{priority}
 117 An integer specifying the priority of the call.
 118 @end table
 119
 120 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.
 121
 122 If the main loop was not started, uses @ref{ensure-gtk-main} to start it.
 123
 124 @RFunction call-within-main-loop-and-wait
 125 @lisp
 126 (call-from-gtk-main-loop-and-wait function)
 127 @end lisp
 128
 129 @table @var
 130 @item @var{function}
 131 The function to be called. Accepts zero arguments and returns zero, one or more values.
 132 @end table
 133
 134 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.
 135
 136 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.
 137
 138 If the main loop was not started, uses @ref{ensure-gtk-main} to start it.
 139
 140 @RCondition gtk-call-aborted
 141
 142 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.
 143
 144 @RFunction gtk-call-aborted-condition
 145
 146 Returns the error that caused call to aborted.