6.1 Gtk+ Main loop

Gtk+ is an event-driven toolkit and it naturally is built around the event dispatching loop. The Gtk+ Main loop is a GLib Main loop. This section describes Gtk+-specific usage of the main loop.

Gtk+ main loop is run in a background thread that is launched by ensure-gtk-main (however it is also possible to launch Gtk+ main loop with 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.

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:

• Use gdk_threads_enter, gdk_threads_leave. This is unsupported at this time on cl-gtk2.
• Use within-main-loop and related macros and functions.

     (gtk-main)

This function runs the main loop and returns when the main loop is terminated. (see gtk-main-quit and ensure-gtk-main)

     (gtk-main-quit)

This function causes the main loop to terminate and causes gtk-main to return.

     (ensure-gtk-main)

This function ensures that the Gtk+ main loop is started.

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.

Calls to ensure-gtk-main must be paired by calls to leave-gtk-main. When the leave-gtk-main is called the same number of time as ensure-gtk-main is called then the main loop quits (e.g., main loops are nested).

It is also useful to call join-gtk-main after ensure-gtk-main to wait for main loop to quit.

     (leave-gtk-main)

This function terminates the gtk main loop.

Calls to ensure-gtk-main must be paired by calls to leave-gtk-main. When the leave-gtk-main is called the same number of time as ensure-gtk-main is called then the main loop quits (e.g., main loops are nested).

     (join-gtk-thread)

This function waits for the background thread that runs the Gtk+ main loop to quit. See ensure-gtk-main.

     (gtk-main-iteration) => boolean

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 gtk-main-iteration-do or check if any events are pending with gtk-events-pending first.

Returns a boolean that is true if gtk-main-quit has been called for the innermost mainloop.

     (gtk-main-iteration-do blocking) => boolean

blocking

True if you want Gtk+ to block if no events are pending

Runs a single iteration of the mainloop. If no events are available either return or block dependent on the value of blocking.

Returns a boolean that is true if gtk-main-quit has been called for the innermost mainloop.

     (gtk-events-pending) => boolean

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.

     (gtk-main-add-timeout milliseconds function &key (priority +g-priority-default+)) => source-id

milliseconds

An integer specifying the time between calls to the function, in milliseconds (1/1000ths of a second.)

function

The function to call periodically. This function accepts zero arguments and returns a boolean.

priority

An integer specifying the priority of the timeout. Typically this will be in the range between +g-priority-default+ and +g-priority-high+.

source-id

An integer identifier of GLib event source.

Registers a function to be called periodically. The function will be called repeatedly after once per 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 source-id to g-source-remove.

     (within-main-loop &body body)

Schedules the body to be evaluated within the main loop. Expression inside body are run inside the main loop, so they can call any Gtk+ functions. This expression may be evaluated in any thread.

Returns immediately. If the main loop was not started, uses ensure-gtk-main to start it.

     (within-main-loop-and-wait &body body) => results

Schedules the body to be evaluated within the main loop. Expression inside body are run inside the main loop, so they can call any Gtk+ functions. This expression may be evaluated in any thread.

Returns the values produced by evaluating body. If the evaluation of body results in unhandled error, the gtk-call-aborted error condition is signaled.

If the main loop was not started, uses ensure-gtk-main to start it.

     (call-from-gtk-main-loop function &key (priority +g-priority-default-idle+))

function

The function to be called. Accepts zero arguments.

priority

An integer specifying the priority of the call.

Schedules the function to be called within the main loop. function is evaluated inside the main loop, so it can call any Gtk+ functions. This function may be called from any thread.

If the main loop was not started, uses ensure-gtk-main to start it.

     (call-from-gtk-main-loop-and-wait function)

function

The function to be called. Accepts zero arguments and returns zero, one or more values.

Schedules the function to be called within the main loop. function is evaluated inside the main loop, so it can call any Gtk+ functions. This function may be called from any thread.

Returns the values produced by calling function. If the evaluation of function results in unhandled error, the gtk-call-aborted error condition is signaled.

If the main loop was not started, uses ensure-gtk-main to start it.

A condition inheriting from error that is used to signal the fact that the evaluation of expression or function in main loop by within-main-loop, within-main-loop-and-wait, call-from-gtk-main-loop, call-within-main-loop-and-wait was interrupted by error.

Returns the error that caused call to aborted.

Undocumented yet