|
Graphics.UI.Gtk.Gdk.EventM | Portability | portable (depends on GHC) | Stability | provisional | Maintainer | gtk2hs-users\@lists.sourceforge.net |
|
|
|
|
|
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
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
|
|
|
A monad providing access to data in an event.
|
|
|
A tag for events that do not carry any event-specific information.
|
|
|
|
A tag for key events.
| Instances | |
|
|
|
A tag for Button events.
| Instances | |
|
|
|
A tag for Scroll events.
| Instances | |
|
|
|
A tag for Motion events.
| Instances | |
|
|
|
|
|
|
A tag for Visibility events.
|
|
|
|
A tag for Crossing events.
| Instances | |
|
|
|
|
|
|
A tag for Configure events.
|
|
|
|
A tag for Property events.
| Instances | |
|
|
|
A tag for Proximity events.
| Instances | |
|
|
|
A tag for WindowState event.
|
|
|
|
A tag for OwnerChange events.
| Instances | |
|
|
|
A tag for GrabBroken events.
|
|
|
Accessor functions for event information
|
|
|
Retrieve the Graphics.UI.Gtk.Gdk.DrawWindow.DrawWindow that this
event relates to.
|
|
|
Query if this event was sent sent explicitly by the application
(rather than being generated by human interaction).
|
|
|
Retrieve the (x,y) coordinates of the mouse.
|
|
|
Retrieve the (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.
Use 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.
|
|
|
Query the time when the event occurred.
|
|
|
The key value. See KeyVal.
|
|
|
The key value as a string. See KeyVal.
|
|
|
The hardware key code.
|
|
|
The keyboard group.
|
|
|
Constructors | LeftButton | | MiddleButton | | RightButton | | OtherButton Int | |
| Instances | |
|
|
|
Query the mouse buttons.
|
|
|
Type of mouse click
| Constructors | SingleClick | | DoubleClick | | TripleClick | | ReleaseClick | |
| Instances | |
|
|
|
|
|
in which direction was scrolled?
| Constructors | ScrollUp | | ScrollDown | | ScrollLeft | | ScrollRight | |
| Instances | |
|
|
|
Query the direction of scrolling.
|
|
|
Check if the motion event is only a hint rather than the full mouse
movement information.
|
|
|
Query a bounding box of the region that needs to be updated.
|
|
|
Query the region that needs to be updated.
|
|
|
Constructors | VisibilityUnobscured | | VisibilityPartialObscured | | VisibilityFullyObscured | |
| Instances | |
|
|
|
Get the visibility status of a window.
|
|
|
How focus is crossing the widget.
| Constructors | CrossingNormal | | CrossingGrab | | CrossingUngrab | | CrossingGtkGrab | | CrossingGtkUngrab | | CrossingStateChanged | |
| Instances | |
|
|
|
Get the mode of the mouse cursor crossing a window.
|
|
|
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 | |
|
|
|
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 (False).
|
|
|
Get the (x,y) position of the window within the parent window.
|
|
|
Get the new size of the window as (width,height).
|
|
|
|
|
The state a DrawWindow is in.
| Constructors | WindowStateWithdrawn | | WindowStateIconified | | WindowStateMaximized | | WindowStateSticky | | WindowStateFullscreen | | WindowStateAbove | | WindowStateBelow | |
| Instances | |
|
|
|
Query which window state bits have changed.
|
|
|
Query the new window state.
|
|
|
Constructors | OwnerChangeNewOwner | | OwnerChangeDestroy | | OwnerChangeClose | |
| Instances | |
|
|
|
Query why a seleciton changed its owner.
|
|
|
Query what selection changed its owner.
|
|
|
Query the time when the selection was taken over.
|
|
|
Check if a keyboard (True) or a mouse pointer grap (False) was
broken.
|
|
|
Check if a grab was broken implicitly.
|
|
|
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 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 | |
|
|
|
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.
|
|
|
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.6.1 |