Portability | portable (depends on GHC) |
---|---|
Stability | provisional |
Maintainer | gtk2hs-users@lists.sourceforge.net |
library initialization, main event loop, and events
- initGUI :: IO [String]
- unsafeInitGUIForThreadedRTS :: IO [String]
- postGUISync :: IO a -> IO a
- postGUIAsync :: IO () -> IO ()
- threadsEnter :: IO ()
- threadsLeave :: IO ()
- mainGUI :: IO ()
- mainQuit :: IO ()
- eventsPending :: IO Int
- mainLevel :: IO Int
- mainIteration :: IO Bool
- mainIterationDo :: Bool -> IO Bool
- grabAdd :: WidgetClass wd => wd -> IO ()
- grabGetCurrent :: IO (Maybe Widget)
- grabRemove :: WidgetClass w => w -> IO ()
- type Priority = Int
- priorityLow :: Int
- priorityDefaultIdle :: Int
- priorityHighIdle :: Int
- priorityDefault :: Int
- priorityHigh :: Int
- timeoutAdd :: IO Bool -> Int -> IO HandlerId
- timeoutAddFull :: IO Bool -> Priority -> Int -> IO HandlerId
- timeoutRemove :: HandlerId -> IO ()
- idleAdd :: IO Bool -> Priority -> IO HandlerId
- idleRemove :: HandlerId -> IO ()
- inputAdd :: FD -> [IOCondition] -> Priority -> IO Bool -> IO HandlerId
- inputRemove :: HandlerId -> IO ()
- data IOCondition
- type HandlerId = CUInt
Initialisation
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 on 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 usingpostGUISync
orpostGUIAsync
. See alsothreadsEnter
.
Support for OS threads
postGUISync :: IO a -> IO aSource
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 ()Source
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.
Acquired 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 usingpostGUIAsync
orpostGUISync
. 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.
Release the global Gtk lock.
- The use of this function is not recommended. See
threadsEnter
.
Main event loop
Less commonly used event loop functions
Inquire the number of events pending on the event queue
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 BoolSource
Process an event, block if necessary.
- Returns
True
ifmainQuit
was called while processing the event.
mainIterationDo :: Bool -> IO BoolSource
Process a single event.
- Called with
True
, this function behaves asmainIteration
in that it waits until an event is available for processing. It will return immediately, if passedFalse
. - Returns
True
if themainQuit
was called while processing the event.
Grab widgets
grabAdd :: WidgetClass wd => wd -> IO ()Source
add a grab widget
grabGetCurrent :: IO (Maybe Widget)Source
inquire current grab widget
grabRemove :: WidgetClass w => w -> IO ()Source
remove a grab widget
Timeout and idle callbacks
priorityLow :: 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).
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).
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.
idleRemove :: HandlerId -> IO ()
Remove a previously added idle handler by its HandlerId
.
:: 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.
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.