|Portability||portable (depends on GHC)|
Types and accessors to examine information in events.
- type EventM t a = ReaderT (Ptr t) IO a
- data EAny
- data EKey
- data EButton
- data EScroll
- data EMotion
- data EExpose
- data EVisibility
- data ECrossing
- data EFocus
- data EConfigure
- data EProperty
- data EProximity
- data EWindowState
- data EOwnerChange
- data EGrabBroken
- eventWindow :: EventM any DrawWindow
- eventSent :: EventM any Bool
- eventCoordinates :: HasCoordinates t => EventM t (Double, Double)
- eventRootCoordinates :: HasRootCoordinates t => EventM t (Double, Double)
- eventModifier :: HasModifier t => EventM t [Modifier]
- eventModifierAll :: HasModifier t => EventM t [Modifier]
- eventTime :: HasTime t => EventM t TimeStamp
- eventKeyVal :: EventM EKey KeyVal
- eventKeyName :: EventM EKey String
- eventHardwareKeycode :: EventM EKey KeyCode
- eventKeyboardGroup :: EventM EKey Word8
- data MouseButton
- eventButton :: EventM EButton MouseButton
- data Click
- eventClick :: EventM EButton Click
- data ScrollDirection
- eventScrollDirection :: EventM EScroll ScrollDirection
- eventIsHint :: EventM EMotion Bool
- eventRequestMotions :: EventM EMotion ()
- eventArea :: EventM EExpose Rectangle
- eventRegion :: EventM EExpose Region
- data VisibilityState
- eventVisibilityState :: EventM EVisibility VisibilityState
- data CrossingMode
- eventCrossingMode :: EventM ECrossing CrossingMode
- data NotifyType
- eventNotifyType :: EventM ECrossing NotifyType
- eventCrossingFocus :: EventM ECrossing Bool
- eventFocusIn :: EventM EFocus Bool
- eventPosition :: EventM EConfigure (Int, Int)
- eventSize :: EventM EConfigure (Int, Int)
- eventProperty :: EventM EProperty Atom
- data WindowState
- eventWindowStateChanged :: EventM EWindowState [WindowState]
- eventWindowState :: EventM EWindowState [WindowState]
- data OwnerChange
- eventChangeReason :: EventM EOwnerChange OwnerChange
- eventSelection :: EventM EOwnerChange SelectionTag
- eventSelectionTime :: EventM EOwnerChange TimeStamp
- eventKeyboardGrab :: EventM EGrabBroken Bool
- eventImplicit :: EventM EGrabBroken Bool
- eventGrabWindow :: EventM EGrabBroken (Maybe DrawWindow)
- data Modifier
- type TimeStamp = Word32
- currentTime :: TimeStamp
- tryEvent :: EventM any () -> EventM any Bool
- stopEvent :: EventM any ()
This modules provides a monad that encapsulates the information in an event.
The events a widget can receive are defined in
Graphics.UI.Gtk.Abstract.Widget. Every event carries additional
information which is accessible through functions in the
For instance, every event is associated with a
DrawWindow which is accessed using the
eventWindow accessor function. Other information is only available in
one specific event. For example, the
area that has to be redrawn, accessed by
eventArea is only available in
exposeEvent. Indeed, you can only
eventArea if the first type parameter of
EventM is the phantom
EExpose. (A phantom type is a type for which no values exist and
which is only used to enforce certain constraints on the usage of
functions such as
eventArea.) Some information is available in several
but not all events. In order to express these constraints the module
defines type classes whose names start with
Has... but which are not
exported, implying that no new instance can be created. (They could be
called phantom type classes.) For instance, the mouse pointer coordinates
can be retrieved using the function
eventCoordinates which requires
that the first type parameter of
EventM is in the class
HasCoordinates. The module supplies instance of class
for the types
EScroll. Thus for
all events that require an
EventM action with one of the types above,
the accessor function
eventCoordinates may be used.
Note that an event handler must always returns
True if the event
was handled or
False if the event should be dealt with by another
event handler. For instance, a handler for a key press should return
False if the pressed key is not one of those that the widget reacts
to. In this case the event is passed to the parent widgets. This
ensures that pressing, say,
Alt-F opens the file menu even if the
current input focus is in a text entry widget. In order to facilitate
writing handlers that may abort handling an event, this module provides
tryEvent. This function catches pattern match exceptions
False. If the signal successfully runs to its end, it
True. A typical use is as follows:
widget `on` keyPressEvent $ tryEvent $ do [Control] <- eventModifier "Return" <- eventKeyName liftIO $ putStrLn "Ctrl-Return pressed"
The rationale is that the action will throw an exception if the
two event functions
eventKeyName return something
else than what is stated in
the pattern. When no exception is thrown, execution continues to
the last statement where the event is processed, here we merely
print a message. Note that the return
value of this statement must be
assumes that the
function handeled the event if no exception is thrown. A handler
tryEvent can also indicate that it cannot handle the
given event by calling
Finally, not that the
EventM monad wraps the
IO monad. As such
you can (and usually have to) use
liftIO to execute
Event monad and type tags
Accessor functions for event information
Query if this event was sent sent explicitly by the application (rather than being generated by human interaction).
(x,y) coordinates of the mouse.
(x,y) coordinates of the mouse relative to the
root (origin) of the screen.
Query the modifier keys that were depressed when the event happened.
Sticky modifiers such as CapsLock are omitted in the return value.
eventModifierAll your application requires all modifiers.
Query the modifier keys that were depressed when the event happened.
The result includes sticky modifiers such as CapsLock. Normally,
eventModifier is more appropriate in applications.
Type of mouse click
in which direction was scrolled?
Check if the motion event is only a hint rather than the full mouse movement information.
Request more motion notifies if this event is a motion notify hint event.
This action should be used instead of
drawWindowGetPointer to request
further motion notifies, because it also works for extension events where
motion notifies are provided for devices other than the core pointer.
Coordinate extraction, processing and requesting more motion events from a
motionNotifyEvent usually works like this:
on widget motionNotifyEvent $ do (x, y) <- eventCoordinates -- handle the x,y motion: ... -- finally, notify that we are ready to get more motion events: eventRequestMotions
Query a bounding box of the region that needs to be updated.
Query the region that needs to be updated. Removed in Gtk3.
Get the visibility status of a window.
How focus is crossing the widget.
Get the mode of the mouse cursor crossing a window.
Information on from what level of the widget hierarchy the mouse cursor came.
- The window is entered from an ancestor or left towards an ancestor.
- The pointer moves between an ancestor and an inferior of the window.
- The window is entered from an inferior or left towards an inferior.
- The window is entered from or left towards a window which is neither an ancestor nor an inferior.
- The pointer moves between two windows which are not ancestors of each other and the window is part of the ancestor chain between one of these windows and their least common ancestor.
- The level change does not fit into any of the other categories or could not be determined.
Get the notify type of the mouse cursor crossing a window.
Query if the window has the focus or is an inferior window.
Query if a window gained focus (
True) or lost the focus (
(x,y) position of the window within the parent window.
The state a
DrawWindow is in.
These are hints for the window manager that indicate what type of function the window has. The window manager can use this when determining decoration and behaviour of the window. The hint must be set before mapping the window.
See the extended window manager hints specification for more details about window types.
Query which window state bits have changed.
Query the time when the selection was taken over.
Check if a keyboard (
True) or a mouse pointer grap (
Get the new window that owns the grab or
Nothing if the window
is not part of this application.
Keyboard modifiers that are depressed when the user presses a key or a mouse button.
- This data type is used to build lists of modifers that were active during an event.
- The Apple key on Macintoshs is mapped to
Metakey (if available).
- Since Gtk 2.10, there are also
Metamodifiers which are simply generated from
Composemodifier keys, depending on the mapping used by the windowing system. Due to one key being mapped to e.g.
Meta, you shouldn't pattern match directly against a certain key but check whether a key is in the list using the
The time (in milliseconds) when an event happened. This is used mostly for ordering events and responses to events.
Represents the current time, and can be used anywhere a time is expected.
Execute an event handler and assume it handled the event unless it threw a pattern match exception or calls mzero (e.g. via guard).