Portability	portable (depends on GHC)
Stability	provisional
Maintainer	gtk2hs-users\@lists.sourceforge.net
Safe Haskell	None

Graphics.UI.Gtk.Gdk.EventM

Contents

Detail
Event monad and type tags
Accessor functions for event information
Auxilliary Definitions

Description

Types and accessors to examine information in events.

Synopsis

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

type EventM t a = ReaderT (Ptr t) IO aSource

A monad providing access to data in an event.

data EAny Source

A tag for events that do not carry any event-specific information.

data EKey Source

A tag for key events.

data EButton Source

A tag for Button events.

data EScroll Source

A tag for Scroll events.

data EMotion Source

A tag for Motion events.

data EExpose Source

A tag for Expose events.

data EVisibility Source

A tag for Visibility events.

data ECrossing Source

A tag for Crossing events.

data EFocus Source

A tag for Focus events.

data EConfigure Source

A tag for Configure events.

data EProperty Source

A tag for Property 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.

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.

eventTime :: HasTime t => EventM t TimeStamp Source

Query the time when the event occurred.

eventKeyVal :: EventM EKey KeyVal Source

The key value. See KeyVal.

eventKeyName :: EventM EKey String 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

Constructors

LeftButton
MiddleButton
RightButton
OtherButton Int

Instances

Enum MouseButton
Eq MouseButton
Show MouseButton

eventButton :: EventM EButton MouseButton Source

Query the mouse buttons.

data Click Source

Type of mouse click

Constructors

SingleClick
DoubleClick
TripleClick
ReleaseClick

Instances

Enum Click
Eq Click
Show Click

eventClick :: EventM EButton Click Source

data ScrollDirection Source

in which direction was scrolled?

Constructors

ScrollUp
ScrollDown
ScrollLeft
ScrollRight

Instances

Enum ScrollDirection
Eq ScrollDirection
Show ScrollDirection

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.

data VisibilityState Source

Constructors

VisibilityUnobscured
VisibilityPartialObscured
VisibilityFullyObscured

Instances

Enum VisibilityState
Eq VisibilityState
Show VisibilityState

eventVisibilityState :: EventM EVisibility VisibilityState Source

Get the visibility status of a window.

data CrossingMode Source

How focus is crossing the widget.

Constructors

CrossingNormal
CrossingGrab
CrossingUngrab
CrossingGtkGrab
CrossingGtkUngrab
CrossingStateChanged

Instances

Enum CrossingMode
Eq CrossingMode
Show CrossingMode

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.

Constructors

NotifyAncestor
NotifyVirtual
NotifyInferior
NotifyNonlinear
NotifyNonlinearVirtual
NotifyUnknown

Instances

Enum NotifyType	Determine if child widget may be overdrawn.
Eq NotifyType
Show NotifyType

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.

eventSize :: EventM EConfigure (Int, Int)Source

Get the new size of the window as (width,height).

eventProperty :: EventM EProperty Atom Source

data WindowState Source

The state a DrawWindow is in.

Constructors

WindowStateWithdrawn
WindowStateIconified
WindowStateMaximized
WindowStateSticky
WindowStateFullscreen
WindowStateAbove
WindowStateBelow

Instances

Bounded WindowState
Enum WindowState	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
Show WindowState
Flags WindowState

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

Constructors

OwnerChangeNewOwner
OwnerChangeDestroy
OwnerChangeClose

Instances

Enum OwnerChange
Eq OwnerChange
Show OwnerChange

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

data Modifier Source

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 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.

tryEvent :: EventM any () -> EventM any Bool Source

Execute an event handler and assume it handled the event unless it threw a pattern match exception or calls mzero (e.g. via guard).

stopEvent :: EventM any ()Source

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.)