Graphics.UI.Gtk.General.General

library initialization, main event loop, and events

Initialisation

initGUI :: IO [String]

Initialize the GUI.

This must be called before any other function in the Gtk2Hs library.

This function initializes the GUI toolkit and parses all Gtk specific arguments. The remaining arguments are returned. If the initialization of the toolkit fails for whatever reason, an exception is thrown.

• Throws: error "Cannot initialize GUI."
• If you want to use Gtk2Hs and in a multi-threaded application then it is your obligation to ensure that all calls to Gtk+ happen in a single OS thread. If you want to make calls to Gtk2Hs functions from a Haskell thread other than the one that calls this functions and mainGUI then you will have to 'post' your GUI actions to the main GUI thread. You can do this using postGUISync or postGUIAsync. See also threadsEnter.

Support for OS threads

unsafeInitGUIForThreadedRTS :: IO [String]

postGUISync :: IO a -> IO a

Post an action to be run in the main GUI thread.

The current thread blocks until the action completes and the result is returned.

postGUIAsync :: IO () -> IO ()

Post an action to be run in the main GUI thread.

The current thread continues and does not wait for the result of the action.

threadsEnter :: IO ()

Acquire the global Gtk lock.

• During normal operation, this lock is held by the thread from which all interaction with Gtk is performed. When calling mainGUI, the thread will release this global lock before it waits for user interaction. During this time it is, in principle, possible to use a different OS thread (any other Haskell thread that is bound to the Gtk OS thread will be blocked anyway) to interact with Gtk by explicitly acquiring the lock, calling Gtk functions and releasing the lock. However, the Gtk functions that are called from this different thread may not trigger any calls to the OS since this will lead to a crash on Windows (the Win32 API can only be used from a single thread). Since it is very hard to tell which function only interacts on Gtk data structures and which function call actual OS functions, it is best not to use this feature at all. A better way to perform updates in the background is to spawn a Haskell thread and to perform the update to Gtk widgets using postGUIAsync or postGUISync. These will execute their arguments from the main loop, that is, from the OS thread of Gtk, thereby ensuring that any Gtk and OS function can be called.

threadsLeave :: IO ()

Release the global Gtk lock.

• The use of this function is not recommended. See threadsEnter.

Main event loop

mainGUI :: IO ()

Run the Gtk+ main event loop.

mainQuit :: IO ()

Exit the main event loop.

Less commonly used event loop functions

eventsPending :: IO Int

Inquire the number of events pending on the event queue

mainLevel :: IO Int

Inquire the main loop level.

• Callbacks that take more time to process can call mainIteration to keep the GUI responsive. Each time the main loop is restarted this way, the main loop counter is increased. This function returns this counter.

mainIteration :: IO Bool

Process an event, block if necessary.

• Returns True if mainQuit was called while processing the event.

mainIterationDo :: Bool -> IO Bool

Process a single event.

• Called with True, this function behaves as mainIteration in that it waits until an event is available for processing. It will return immediately, if passed False.
• Returns True if the mainQuit was called while processing the event.

mainDoEvent :: EventM t ()

Processes a single GDK event. This is public only to allow filtering of events between GDK and GTK+. You will not usually need to call this function directly.

While you should not call this function directly, you might want to know how exactly events are handled. So here is what this function does with the event:

1. Compress enter/leave notify events. If the event passed build an enter/leave pair together with the next event (peeked from GDK) both events are thrown away. This is to avoid a backlog of (de-)highlighting widgets crossed by the pointer.
2. Find the widget which got the event. If the widget can't be determined the event is thrown away unless it belongs to a INCR transaction. In that case it is passed to selectionIncrEvent.
3. Then the event is passed on a stack so you can query the currently handled event with getCurrentEvent.
4. The event is sent to a widget. If a grab is active all events for widgets that are not in the contained in the grab widget are sent to the latter with a few exceptions:

• Deletion and destruction events are still sent to the event widget for obvious reasons.
• Events which directly relate to the visual representation of the event widget.
• Leave events are delivered to the event widget if there was an enter event delivered to it before without the paired leave event.
• Drag events are not redirected because it is unclear what the semantics of that would be.

Another point of interest might be that all key events are first passed through the key snooper functions if there are any. Read the description of keySnooperInstall if you need this feature.

1. After finishing the delivery the event is popped from the event stack.

Call when mainloop is left

quitAddDestroy

Arguments

:: ObjectClass obj

=> Int

mainLevel Level of the mainloop which shall trigger the destruction.

-> obj

object Object to be destroyed.

-> IO ()

Trigger destruction of object in case the mainloop at level mainLevel is quit.

Removed in Gtk3.

quitAdd

Arguments

:: Int

mainLevel Level at which termination the function shall be called. You can pass 0 here to have the function run at the current mainloop.

-> IO Bool

function The function to call. This should return False to be removed from the list of quit handlers. Otherwise the function might be called again.

-> IO Int

returns A handle for this quit handler (you need this for quitRemove)

Registers a function to be called when an instance of the mainloop is left.

Removed in Gtk3.

quitRemove

Arguments

:: Int

quitHandlerId Identifier for the handler returned when installing it.

-> IO ()

Removes a quit handler by its identifier.

Removed in Gtk3.

Grab widgets

grabAdd :: WidgetClass wd => wd -> IO ()

add a grab widget

grabGetCurrent :: IO (Maybe Widget)

inquire current grab widget

grabRemove :: WidgetClass w => w -> IO ()

remove a grab widget

Timeout and idle callbacks

type Priority = Int

Priorities for installing callbacks.

priorityLow :: Int

priorityDefaultIdle :: Int

priorityHighIdle :: Int

priorityDefault :: Int

priorityHigh :: Int

timeoutAdd :: IO Bool -> Int -> IO HandlerId

Sets a function to be called at regular intervals, with the default priority priorityDefault. The function is called repeatedly until it returns False, after which point the timeout function will not be called again. The first call to the function will be at the end of the first interval.

Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given interval (it does not try to 'catch up' time lost in delays).

This function differs from timeoutAdd in that the action will be executed within the global Gtk+ lock. It is therefore possible to call Gtk+ functions from the action.

timeoutAddFull :: IO Bool -> Priority -> Int -> IO HandlerId

Sets a function to be called at regular intervals, with the given priority. The function is called repeatedly until it returns False, after which point the timeout function will not be called again. The first call to the function will be at the end of the first interval.

Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given interval (it does not try to 'catch up' time lost in delays).

This function differs from timeoutAddFull in that the action will be executed within the global Gtk+ lock. It is therefore possible to call Gtk+ functions from the action.

timeoutRemove :: HandlerId -> IO ()

Remove a previously added timeout handler by its HandlerId.

idleAdd :: IO Bool -> Priority -> IO HandlerId

Add a callback that is called whenever the system is idle.

• A priority can be specified via an integer. This should usually be priorityDefaultIdle.
• If the function returns False it will be removed.

This function differs from idleAdd in that the action will be executed within the global Gtk+ lock. It is therefore possible to call Gtk+ functions from the action.

idleRemove :: HandlerId -> IO ()

Remove a previously added idle handler by its HandlerId.

inputAdd

Arguments

:: FD

a file descriptor

-> [IOCondition]

the condition to watch for

-> Priority

the priority of the event source

-> IO Bool

the function to call when the condition is satisfied. The function should return False if the event source should be removed.

-> IO HandlerId

the event source id

Adds the file descriptor into the main event loop with the given priority.

This function differs from inputAdd in that the action will be executed within the global Gtk+ lock. It is therefore possible to call Gtk+ functions from the action.

inputRemove :: HandlerId -> IO ()

data IOCondition :: *

Flags representing a condition to watch for on a file descriptor.

IOIn

There is data to read.

IOOut

Data can be written (without blocking).

IOPri

There is urgent data to read.

IOErr

Error condition.

IOHup

Hung up (the connection has been broken, usually for pipes and sockets).

IOInvalid

Invalid request. The file descriptor is not open.

Constructors

IOIn

IOOut

IOPri

IOErr

IOHup

IOInvalid

Instances

Bounded IOCondition

Enum IOCondition

Eq IOCondition

Flags IOCondition

type HandlerId = CUInt

type FD = Int