Maintainer | gtk2hs-users\@lists.sourceforge.net |
---|---|
Stability | provisional |
Portability | portable (depends on GHC) |
Safe Haskell | None |
Language | Haskell98 |
Types and accessors to examine information in events.
Synopsis
- class HasCoordinates a
- class HasRootCoordinates a
- class HasModifier a
- class HasTime a
- type EventM t = ReaderT (Ptr t) IO
- 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]
- eventModifierMouse :: HasModifier t => EventM t [Modifier]
- eventTime :: HasTime t => EventM t TimeStamp
- eventKeyVal :: EventM EKey KeyVal
- eventKeyName :: EventM EKey DefaultGlibString
- 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 ()
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
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 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.
Classes
class HasCoordinates a Source #
Instances
HasCoordinates ECrossing Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasCoordinates EMotion Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasCoordinates EScroll Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasCoordinates EButton Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM |
class HasRootCoordinates a Source #
Instances
HasRootCoordinates ECrossing Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasRootCoordinates EMotion Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasRootCoordinates EScroll Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasRootCoordinates EButton Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM |
class HasModifier a Source #
Instances
HasModifier ECrossing Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasModifier EMotion Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasModifier EScroll Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasModifier EButton Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasModifier EKey Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM |
Instances
HasTime EOwnerChange Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasTime EProximity Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasTime EProperty Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasTime ECrossing Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasTime EMotion Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasTime EScroll Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasTime EButton Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasTime EKey Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM |
Event monad and type tags
A tag for key events.
Instances
HasTime EKey Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasModifier EKey Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM |
A tag for Button events.
Instances
HasTime EButton Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasModifier EButton Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasRootCoordinates EButton Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasCoordinates EButton Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM |
A tag for Scroll events.
Instances
HasTime EScroll Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasModifier EScroll Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasRootCoordinates EScroll Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasCoordinates EScroll Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM |
A tag for Motion events.
Instances
HasTime EMotion Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasModifier EMotion Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasRootCoordinates EMotion Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasCoordinates EMotion Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM |
data EVisibility Source #
A tag for Visibility events.
A tag for Crossing events.
Instances
HasTime ECrossing Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasModifier ECrossing Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasRootCoordinates ECrossing Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM | |
HasCoordinates ECrossing Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM |
data EConfigure Source #
A tag for Configure events.
A tag for Property events.
Instances
HasTime EProperty Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM |
data EProximity Source #
A tag for Proximity events.
Instances
HasTime EProximity Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM |
data EWindowState Source #
A tag for WindowState event.
data EOwnerChange Source #
A tag for OwnerChange events.
Instances
HasTime EOwnerChange Source # | |
Defined in Graphics.UI.Gtk.Gdk.EventM |
data EGrabBroken Source #
A tag for GrabBroken events.
Accessor functions for event information
eventWindow :: EventM any DrawWindow Source #
Retrieve the DrawWindow
that this
event relates to.
eventSent :: EventM any Bool Source #
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) Source #
Retrieve the (x,y)
coordinates of the mouse.
eventRootCoordinates :: HasRootCoordinates t => EventM t (Double, Double) Source #
Retrieve the (x,y)
coordinates of the mouse relative to the
root (origin) of the screen.
eventModifier :: HasModifier t => EventM t [Modifier] Source #
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.
Use eventModifierMouse
if you just need the mouse buttons.
eventModifierAll :: HasModifier t => EventM t [Modifier] Source #
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.
eventModifierMouse :: HasModifier t => EventM t [Modifier] Source #
Query the mouse buttons that were depressed when the event happened.
eventKeyName :: EventM EKey DefaultGlibString Source #
The key value as a string. See KeyVal
.
data MouseButton Source #
Mouse buttons.
Instances
Enum MouseButton Source # | |
Defined in Graphics.UI.Gtk.General.Enums succ :: MouseButton -> MouseButton # pred :: MouseButton -> MouseButton # toEnum :: Int -> MouseButton # fromEnum :: MouseButton -> Int # enumFrom :: MouseButton -> [MouseButton] # enumFromThen :: MouseButton -> MouseButton -> [MouseButton] # enumFromTo :: MouseButton -> MouseButton -> [MouseButton] # enumFromThenTo :: MouseButton -> MouseButton -> MouseButton -> [MouseButton] # | |
Eq MouseButton Source # | |
Defined in Graphics.UI.Gtk.General.Enums (==) :: MouseButton -> MouseButton -> Bool # (/=) :: MouseButton -> MouseButton -> Bool # | |
Show MouseButton Source # | |
Defined in Graphics.UI.Gtk.General.Enums showsPrec :: Int -> MouseButton -> ShowS # show :: MouseButton -> String # showList :: [MouseButton] -> ShowS # |
eventButton :: EventM EButton MouseButton Source #
Query the mouse buttons.
Type of mouse click
data ScrollDirection Source #
in which direction was scrolled?
Instances
Enum ScrollDirection Source # | |
Defined in Graphics.UI.Gtk.Gdk.Enums succ :: ScrollDirection -> ScrollDirection # pred :: ScrollDirection -> ScrollDirection # toEnum :: Int -> ScrollDirection # fromEnum :: ScrollDirection -> Int # enumFrom :: ScrollDirection -> [ScrollDirection] # enumFromThen :: ScrollDirection -> ScrollDirection -> [ScrollDirection] # enumFromTo :: ScrollDirection -> ScrollDirection -> [ScrollDirection] # enumFromThenTo :: ScrollDirection -> ScrollDirection -> ScrollDirection -> [ScrollDirection] # | |
Eq ScrollDirection Source # | |
Defined in Graphics.UI.Gtk.Gdk.Enums (==) :: ScrollDirection -> ScrollDirection -> Bool # (/=) :: ScrollDirection -> ScrollDirection -> Bool # | |
Show ScrollDirection Source # | |
Defined in Graphics.UI.Gtk.Gdk.Enums showsPrec :: Int -> ScrollDirection -> ShowS # show :: ScrollDirection -> String # showList :: [ScrollDirection] -> ShowS # |
eventScrollDirection :: EventM EScroll ScrollDirection Source #
Query the direction of scrolling.
eventIsHint :: EventM EMotion Bool Source #
Check if the motion event is only a hint rather than the full mouse movement information.
eventRequestMotions :: EventM EMotion () Source #
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
eventArea :: EventM EExpose Rectangle Source #
Query a bounding box of the region that needs to be updated.
eventRegion :: EventM EExpose Region Source #
Query the region that needs to be updated. Removed in Gtk3.
data VisibilityState Source #
Instances
Enum VisibilityState Source # | |
Defined in Graphics.UI.Gtk.Gdk.Enums succ :: VisibilityState -> VisibilityState # pred :: VisibilityState -> VisibilityState # toEnum :: Int -> VisibilityState # fromEnum :: VisibilityState -> Int # enumFrom :: VisibilityState -> [VisibilityState] # enumFromThen :: VisibilityState -> VisibilityState -> [VisibilityState] # enumFromTo :: VisibilityState -> VisibilityState -> [VisibilityState] # enumFromThenTo :: VisibilityState -> VisibilityState -> VisibilityState -> [VisibilityState] # | |
Eq VisibilityState Source # | |
Defined in Graphics.UI.Gtk.Gdk.Enums (==) :: VisibilityState -> VisibilityState -> Bool # (/=) :: VisibilityState -> VisibilityState -> Bool # | |
Show VisibilityState Source # | |
Defined in Graphics.UI.Gtk.Gdk.Enums showsPrec :: Int -> VisibilityState -> ShowS # show :: VisibilityState -> String # showList :: [VisibilityState] -> ShowS # |
eventVisibilityState :: EventM EVisibility VisibilityState Source #
Get the visibility status of a window.
data CrossingMode Source #
How focus is crossing the widget.
Instances
Enum CrossingMode Source # | |
Defined in Graphics.UI.Gtk.Gdk.Enums succ :: CrossingMode -> CrossingMode # pred :: CrossingMode -> CrossingMode # toEnum :: Int -> CrossingMode # fromEnum :: CrossingMode -> Int # enumFrom :: CrossingMode -> [CrossingMode] # enumFromThen :: CrossingMode -> CrossingMode -> [CrossingMode] # enumFromTo :: CrossingMode -> CrossingMode -> [CrossingMode] # enumFromThenTo :: CrossingMode -> CrossingMode -> CrossingMode -> [CrossingMode] # | |
Eq CrossingMode Source # | |
Defined in Graphics.UI.Gtk.Gdk.Enums (==) :: CrossingMode -> CrossingMode -> Bool # (/=) :: CrossingMode -> CrossingMode -> Bool # | |
Show CrossingMode Source # | |
Defined in Graphics.UI.Gtk.Gdk.Enums showsPrec :: Int -> CrossingMode -> ShowS # show :: CrossingMode -> String # showList :: [CrossingMode] -> ShowS # |
eventCrossingMode :: EventM ECrossing CrossingMode Source #
Get the mode of the mouse cursor crossing a window.
data NotifyType Source #
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.
Instances
Enum NotifyType Source # | |
Defined in Graphics.UI.Gtk.Gdk.Enums succ :: NotifyType -> NotifyType # pred :: NotifyType -> NotifyType # toEnum :: Int -> NotifyType # fromEnum :: NotifyType -> Int # enumFrom :: NotifyType -> [NotifyType] # enumFromThen :: NotifyType -> NotifyType -> [NotifyType] # enumFromTo :: NotifyType -> NotifyType -> [NotifyType] # enumFromThenTo :: NotifyType -> NotifyType -> NotifyType -> [NotifyType] # | |
Eq NotifyType Source # | |
Defined in Graphics.UI.Gtk.Gdk.Enums (==) :: NotifyType -> NotifyType -> Bool # (/=) :: NotifyType -> NotifyType -> Bool # | |
Show NotifyType Source # | |
Defined in Graphics.UI.Gtk.Gdk.Enums showsPrec :: Int -> NotifyType -> ShowS # show :: NotifyType -> String # showList :: [NotifyType] -> ShowS # |
eventNotifyType :: EventM ECrossing NotifyType Source #
Get the notify type of the mouse cursor crossing a window.
eventCrossingFocus :: EventM ECrossing Bool Source #
Query if the window has the focus or is an inferior window.
eventFocusIn :: EventM EFocus Bool Source #
Query if a window gained focus (True
) or lost the focus (False
).
eventPosition :: EventM EConfigure (Int, Int) Source #
Get the (x,y)
position of the window within the parent window.
data WindowState Source #
The state a DrawWindow
is in.
WindowStateWithdrawn | |
WindowStateIconified | |
WindowStateMaximized | |
WindowStateSticky | |
WindowStateFullscreen | |
WindowStateAbove | |
WindowStateBelow |
Instances
eventWindowStateChanged :: EventM EWindowState [WindowState] Source #
Query which window state bits have changed.
eventWindowState :: EventM EWindowState [WindowState] Source #
Query the new window state.
data OwnerChange Source #
Instances
Enum OwnerChange Source # | |
Defined in Graphics.UI.Gtk.Gdk.Enums succ :: OwnerChange -> OwnerChange # pred :: OwnerChange -> OwnerChange # toEnum :: Int -> OwnerChange # fromEnum :: OwnerChange -> Int # enumFrom :: OwnerChange -> [OwnerChange] # enumFromThen :: OwnerChange -> OwnerChange -> [OwnerChange] # enumFromTo :: OwnerChange -> OwnerChange -> [OwnerChange] # enumFromThenTo :: OwnerChange -> OwnerChange -> OwnerChange -> [OwnerChange] # | |
Eq OwnerChange Source # | |
Defined in Graphics.UI.Gtk.Gdk.Enums (==) :: OwnerChange -> OwnerChange -> Bool # (/=) :: OwnerChange -> OwnerChange -> Bool # | |
Show OwnerChange Source # | |
Defined in Graphics.UI.Gtk.Gdk.Enums showsPrec :: Int -> OwnerChange -> ShowS # show :: OwnerChange -> String # showList :: [OwnerChange] -> ShowS # |
eventChangeReason :: EventM EOwnerChange OwnerChange Source #
Query why a seleciton changed its owner.
eventSelection :: EventM EOwnerChange SelectionTag Source #
Query what selection changed its owner.
eventSelectionTime :: EventM EOwnerChange TimeStamp Source #
Query the time when the selection was taken over.
eventKeyboardGrab :: EventM EGrabBroken Bool Source #
Check if a keyboard (True
) or a mouse pointer grap (False
) was
broken.
eventImplicit :: EventM EGrabBroken Bool Source #
Check if a grab was broken implicitly.
eventGrabWindow :: EventM EGrabBroken (Maybe DrawWindow) Source #
Get the new window that owns the grab or Nothing
if the window
is not part of this application.
Auxilliary Definitions
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 theMeta
key (if available). - Since Gtk 2.10, there are also
Super
,Hyper
andMeta
modifiers which are simply generated fromAlt
..Compose
modifier keys, depending on the mapping used by the windowing system. Due to one key being mapped to e.g.Alt2
andMeta
, you shouldn't pattern match directly against a certain key but check whether a key is in the list using theelem
function, say.
Shift | |
Lock | |
Control | |
Alt | |
Alt2 | |
Alt3 | |
Alt4 | |
Alt5 | |
Button1 | |
Button2 | |
Button3 | |
Button4 | |
Button5 | |
Super | |
Hyper | |
Meta | |
Release | |
ModifierMask |
Instances
Bounded Modifier Source # | |
Enum Modifier Source # | |
Defined in Graphics.UI.Gtk.Gdk.Enums | |
Eq Modifier Source # | |
Show Modifier Source # | |
Flags Modifier Source # | |
Defined in Graphics.UI.Gtk.Gdk.Enums |
type TimeStamp = Word32 Source #
The time (in milliseconds) when an event happened. This is used mostly for ordering events and responses to events.
currentTime :: TimeStamp Source #
Represents the current time, and can be used anywhere a time is expected.