| gtk-0.11.2: Binding to the Gtk+ graphical user interface library. | Contents | Index
Graphics.UI.Gtk.Gdk.EventM |
Portability | portable (depends on GHC)
Stability | provisional
Maintainer | gtk2hs-users\@lists.sourceforge.net
Contents
Detail Event monad and type tags Accessor functions for event information Auxilliary Definitions
Description
Types and accessors to examine information in events.
Synopsis
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 Word16
eventKeyboardGroup :: EventM EKey Word8
data MouseButton
= LeftButton
| MiddleButton
| RightButton
| OtherButton Int
eventButton :: EventM EButton MouseButton
data Click
= SingleClick
| DoubleClick
| TripleClick
| ReleaseClick
eventClick :: EventM EButton Click
data ScrollDirection
= ScrollUp
| ScrollDown
| ScrollLeft
| ScrollRight
eventScrollDirection :: EventM EScroll ScrollDirection
eventIsHint :: EventM EMotion Bool
eventArea :: EventM EExpose Rectangle
eventRegion :: EventM EExpose Region
data VisibilityState
= VisibilityUnobscured
| VisibilityPartialObscured
| VisibilityFullyObscured
eventVisibilityState :: EventM EVisibility VisibilityState
data CrossingMode
= CrossingNormal
| CrossingGrab
| CrossingUngrab
| CrossingGtkGrab
| CrossingGtkUngrab
| CrossingStateChanged
eventCrossingMode :: EventM ECrossing CrossingMode
data NotifyType
= NotifyAncestor
| NotifyVirtual
| NotifyInferior
| NotifyNonlinear
| NotifyNonlinearVirtual
| NotifyUnknown
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
= WindowStateWithdrawn
| WindowStateIconified
| WindowStateMaximized
| WindowStateSticky
| WindowStateFullscreen
| WindowStateAbove
| WindowStateBelow
eventWindowStateChanged :: EventM EWindowState [WindowState]
eventWindowState :: EventM EWindowState [WindowState]
data OwnerChange
= OwnerChangeNewOwner
| OwnerChangeDestroy
| OwnerChangeClose
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
= Shift
| Lock
| Control
| Alt
| Alt2
| Alt3
| Alt4
| Alt5
| Button1
| Button2
| Button3
| Button4
| Button5
| Super
| Hyper
| Meta
| Release
| ModifierMask
type TimeStamp = Word32
currentTime :: TimeStamp
tryEvent :: EventM any () -> EventM any Bool
stopEvent :: EventM any ()
Detail
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 `EventM` monad. For instance, every event is associated with a Graphics.UI.Gtk.Gdk.DrawWindow.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 the Graphics.UI.Gtk.Abstract.Widget.exposeEvent. Indeed, you can only call `eventArea` if the first type parameter of `EventM` is the phantom type `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 `HasCoordinates` for the types `EButton`, `ECrossing`, `EMotion` and `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 the function `tryEvent`. This function catches pattern match exceptions and returns `False`. If the signal successfully runs to its end, it returns `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 `eventModifier` and `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 `()` since `tryEvent` always assumes that the function handeled the event if no exception is thrown. A handler wrapped by `tryEvent` can also indicate that it cannot handle the given event by calling `stopEvent`. Finally, not that the `EventM` monad wraps the `IO` monad. As such you can (and usually have to) use `liftIO` to execute `IO` functions.
Event monad and type tags
type EventM t a = ReaderT (Ptr t) IO a
A monad providing access to data in an event.
data EAny
A tag for events that do not carry any event-specific information.
data EKey
A tag for key events.
Instances
HasTime EKey |
HasModifier EKey |
data EButton
A tag for Button events.
Instances
HasTime EButton |
HasModifier EButton |
HasRootCoordinates EButton |
HasCoordinates EButton |
data EScroll
A tag for Scroll events.
Instances
HasTime EScroll |
HasModifier EScroll |
HasRootCoordinates EScroll |
HasCoordinates EScroll |
data EMotion
A tag for Motion events.
Instances
HasTime EMotion |
HasModifier EMotion |
HasRootCoordinates EMotion |
HasCoordinates EMotion |
data EExpose
A tag for Expose events.
data EVisibility
A tag for Visibility events.
data ECrossing
A tag for Crossing events.
Instances
HasTime ECrossing |
HasModifier ECrossing |
HasRootCoordinates ECrossing |
HasCoordinates ECrossing |
data EFocus
A tag for Focus events.
data EConfigure
A tag for Configure events.
data EProperty
A tag for Property events.
Instances
HasTime EProperty |
data EProximity
A tag for Proximity events.
Instances
HasTime EProximity |
data EWindowState
A tag for WindowState event.
data EOwnerChange
A tag for OwnerChange events.
Instances
HasTime EOwnerChange |
data EGrabBroken
A tag for GrabBroken events.
Accessor functions for event information
eventWindow :: EventM any DrawWindow
Retrieve the Graphics.UI.Gtk.Gdk.DrawWindow.DrawWindow that this event relates to.
eventSent :: EventM any Bool
Query if this event was sent sent explicitly by the application (rather than being generated by human interaction).
eventCoordinates :: HasCoordinates t => EventM t (Double, Double)
Retrieve the `(x,y)` coordinates of the mouse.
eventRootCoordinates :: HasRootCoordinates t => EventM t (Double, Double)
Retrieve the `(x,y)` coordinates of the mouse relative to the root (origin) of the screen.
eventModifier :: HasModifier t => EventM t [Modifier]
Query the modifier keys that were depressed when the event happened. Sticky modifiers such as CapsLock are omitted in the return value. Use `eventModifierAll` your application requires all modifiers.
eventModifierAll :: HasModifier t => EventM t [Modifier]
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.
eventTime :: HasTime t => EventM t TimeStamp
Query the time when the event occurred.
eventKeyVal :: EventM EKey KeyVal
The key value. See `KeyVal`.
eventKeyName :: EventM EKey String
The key value as a string. See `KeyVal`.
eventHardwareKeycode :: EventM EKey Word16
The hardware key code.
eventKeyboardGroup :: EventM EKey Word8
The keyboard group.
data MouseButton
Constructors
LeftButton |
MiddleButton |
RightButton |
OtherButton Int |
Instances
Enum MouseButton |
Eq MouseButton |
Show MouseButton |
eventButton :: EventM EButton MouseButton
Query the mouse buttons.
data Click
Type of mouse click
Constructors
SingleClick |
DoubleClick |
TripleClick |
ReleaseClick |
Instances
Enum Click |
Eq Click |
Show Click |
eventClick :: EventM EButton Click
data ScrollDirection
in which direction was scrolled?
Constructors
ScrollUp |
ScrollDown |
ScrollLeft |
ScrollRight |
Instances
Enum ScrollDirection |
Eq ScrollDirection |
Show ScrollDirection |
eventScrollDirection :: EventM EScroll ScrollDirection
Query the direction of scrolling.
eventIsHint :: EventM EMotion Bool
Check if the motion event is only a hint rather than the full mouse movement information.
eventArea :: EventM EExpose Rectangle
Query a bounding box of the region that needs to be updated.
eventRegion :: EventM EExpose Region
Query the region that needs to be updated.
data VisibilityState
Constructors
VisibilityUnobscured |
VisibilityPartialObscured |
VisibilityFullyObscured |
Instances
Enum VisibilityState |
Eq VisibilityState |
Show VisibilityState |
eventVisibilityState :: EventM EVisibility VisibilityState
Get the visibility status of a window.
data CrossingMode
How focus is crossing the widget.
Constructors
CrossingNormal |
CrossingGrab |
CrossingUngrab |
CrossingGtkGrab |
CrossingGtkUngrab |
CrossingStateChanged |
Instances
Enum CrossingMode |
Eq CrossingMode |
Show CrossingMode |
eventCrossingMode :: EventM ECrossing CrossingMode
Get the mode of the mouse cursor crossing a window.
data NotifyType
Information on from what level of the widget hierarchy the mouse cursor came. `NotifyAncestor` The window is entered from an ancestor or left towards an ancestor. `NotifyVirtual` The pointer moves between an ancestor and an inferior of the window. `NotifyInferior` The window is entered from an inferior or left towards an inferior. `NotifyNonlinear` The window is entered from or left towards a window which is neither an ancestor nor an inferior. `NotifyNonlinearVirtual` 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. `NotifyUnknown` The level change does not fit into any of the other categories or could not be determined.
Constructors
NotifyAncestor |
NotifyVirtual |
NotifyInferior |
NotifyNonlinear |
NotifyNonlinearVirtual |
NotifyUnknown |
Instances
Enum NotifyType |
Eq NotifyType |
Show NotifyType |
eventNotifyType :: EventM ECrossing NotifyType
Get the notify type of the mouse cursor crossing a window.
eventCrossingFocus :: EventM ECrossing Bool
Query if the window has the focus or is an inferior window.
eventFocusIn :: EventM EFocus Bool
Query if a window gained focus (`True`) or lost the focus (`False`).
eventPosition :: EventM EConfigure (Int, Int)
Get the `(x,y)` position of the window within the parent window.
eventSize :: EventM EConfigure (Int, Int)
Get the new size of the window as `(width,height)`.
eventProperty :: EventM EProperty Atom
data WindowState
The state a `DrawWindow` is in.
Constructors
WindowStateWithdrawn |
WindowStateIconified |
WindowStateMaximized |
WindowStateSticky |
WindowStateFullscreen |
WindowStateAbove |
WindowStateBelow |
Instances
Bounded WindowState |
Enum WindowState |
Eq WindowState |
Show WindowState |
Flags WindowState |
eventWindowStateChanged :: EventM EWindowState [WindowState]
Query which window state bits have changed.
eventWindowState :: EventM EWindowState [WindowState]
Query the new window state.
data OwnerChange
Constructors
OwnerChangeNewOwner |
OwnerChangeDestroy |
OwnerChangeClose |
Instances
Enum OwnerChange |
Eq OwnerChange |
Show OwnerChange |
eventChangeReason :: EventM EOwnerChange OwnerChange
Query why a seleciton changed its owner.
eventSelection :: EventM EOwnerChange SelectionTag
Query what selection changed its owner.
eventSelectionTime :: EventM EOwnerChange TimeStamp
Query the time when the selection was taken over.
eventKeyboardGrab :: EventM EGrabBroken Bool
Check if a keyboard (`True`) or a mouse pointer grap (`False`) was broken.
eventImplicit :: EventM EGrabBroken Bool
Check if a grab was broken implicitly.
eventGrabWindow :: EventM EGrabBroken (Maybe DrawWindow)
Get the new window that owns the grab or `Nothing` if the window is not part of this application.
Auxilliary Definitions
data Modifier
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 `Alt2` and the `Meta` key (if available). Since Gtk 2.10, there are also `Super`, `Hyper` and `Meta` modifiers which are simply generated from `Alt` .. Compose modifier keys, depending on the mapping used by the windowing system. Due to one key being mapped to e.g. `Alt2` and `Meta`, you shouldn't pattern match directly against a certain key but check whether a key is in the list using the `elem` function, say.
Constructors
Shift |
Lock |
Control |
Alt |
Alt2 |
Alt3 |
Alt4 |
Alt5 |
Button1 |
Button2 |
Button3 |
Button4 |
Button5 |
Super |
Hyper |
Meta |
Release |
ModifierMask |
Instances
Bounded Modifier |
Enum Modifier |
Eq Modifier |
Show Modifier |
Flags Modifier |
type TimeStamp = Word32
The time (in milliseconds) when an event happened. This is used mostly for ordering events and responses to events.
currentTime :: TimeStamp
Represents the current time, and can be used anywhere a time is expected.
tryEvent :: EventM any () -> EventM any Bool
Execute an event handler and assume it handled the event unless it threw a pattern match exception.
stopEvent :: EventM any ()
Explicitly stop the handling of an event. This function should only be called inside a handler that is wrapped with `tryEvent`. (It merely throws a bogus pattern matching error which `tryEvent` interprets as if the handler does not handle the event.)
Produced by Haddock version 2.7.2