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.
- 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.
Event monad and type tags
data EVisibility Source
A tag for Visibility events.
data EConfigure Source
A tag for Configure events.
data EProximity Source
A tag for Proximity events.
data EWindowState Source
A tag for WindowState event.
data EOwnerChange Source
A tag for OwnerChange events.
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
.
eventHardwareKeycode :: EventM EKey KeyCode Source
The hardware key code.
eventKeyboardGroup :: EventM EKey Word8 Source
The keyboard group.
data MouseButton Source
Mouse buttons.
eventButton :: EventM EButton MouseButton Source
Query the mouse buttons.
Type of mouse click
data ScrollDirection Source
in which direction was scrolled?
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
eventVisibilityState :: EventM EVisibility VisibilityState Source
Get the visibility status of a window.
data CrossingMode Source
How focus is crossing the widget.
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.
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 |
Bounded WindowState Source | |
Enum WindowState Source | 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. |
Eq WindowState Source | |
Show WindowState Source | |
Flags WindowState Source |
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
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.
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.