diff options
Diffstat (limited to 'src/Gtk/Signal.dcl')
| -rw-r--r-- | src/Gtk/Signal.dcl | 57 |
1 files changed, 48 insertions, 9 deletions
diff --git a/src/Gtk/Signal.dcl b/src/Gtk/Signal.dcl index fa9babf..85a780c 100644 --- a/src/Gtk/Signal.dcl +++ b/src/Gtk/Signal.dcl @@ -1,5 +1,9 @@ definition module Gtk.Signal +/** + * This module provides functionality for Gtk signals. + */ + from System._Pointer import :: Pointer from Gdk.Events import :: GdkEvent @@ -8,13 +12,19 @@ from Gtk.Tune import class tune from Gtk.Types import :: GtkPropagate, :: GtkTimeout from Gtk.Widgets import class gtkWidget +/** + * If more handlers are defined outside this module (and hence outside the + * `GSignalHandler` type), they must instantiate this class to be able to be + * installed on widgets. + */ class signalHandler h where + //* The name of the signal, e.g. `destroy` or `key-press-event`. signalName :: !h -> String + //* An internal representation of the handler. signalHandler :: !h -> SignalHandlerInternal -:: SignalHandler = E.h: SignalHandler h & signalHandler h - +//* A number of basic signals. See the Gtk documentation for their usage. :: GSignalHandler = ActivateHandler !(GtkM ()) | ChangedHandler !(GtkM ()) @@ -29,28 +39,57 @@ where instance signalHandler GSignalHandler +/** + * Inner representation of the various types of signal handlers that there are. + * This is only needed outside this module when adding more signals. + */ :: SignalHandlerInternal = SHI_Void !(GtkM ()) | SHI_Pointer_Bool !(Pointer -> GtkM Bool) | SHI_Int_Int_Bool !(Int Int -> GtkM Bool) | SHI_Int_Int_Pointer_Pointer_Bool !(Int Int Pointer Pointer -> GtkM Bool) +/** + * Install a signal handler on a widget. Often, the `tune` instance defined + * below leads to more readable code. + */ installSignalHandler :: !h !w -> GtkM w | signalHandler h & gtkWidget w -instance tune w SignalHandler | gtkWidget w +//* Alternative for `installSignalHandler` for more readable code. instance tune w GSignalHandler | gtkWidget w -saveState :: GtkM () -retrieveState :: GtkM GtkState +/** + * Run a function at a certain interval. The function will continue to run + * until it returns `False`. Note that Glib timeouts cannot be used for precise + * timing; see the documentation for more details: + * https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#g-timeout-add + */ +addTimeout :: !GtkTimeout !(GtkM Bool) -> GtkM () -//* Wrap functionality in `saveState` and `retrieveState` if it can be re-entrant. +/** + * Wrap functionality with `saveState` and `retrieveState`. This is needed if + * it can be re-entrant, for example when it can trigger signals. See the + * documentation on `saveState` for more details. + */ withPossibleCallback :: !(GtkM a) -> GtkM a -// Only for foreign export: +/** + * Some functions can lead to Gtk signals to be emitted. If these signals have + * handlers set up, the function is re-entrant (may return to Clean code). For + * this kind of functions, we need to save the `GtkM` state beforehand and + * retrieve it afterwards, because the signal handler may rely on that state + * and may modify it. `saveState` saves the state internally; `retrieveState` + * restores it. `withPossibleCallback` is a convenient wrapper combining both. + */ +saveState :: GtkM () + +//* Retrieve the state saved with `saveState`. +retrieveState :: GtkM GtkState + +// The functions below are only exported because they need a foreign export entry point: handleSignal_void :: !Pointer !Int -> Int handleSignal_pointer_bool :: !Pointer !Pointer !Int -> Int handleSignal_int_int_bool :: !Pointer !Int !Int !Int -> Int handleSignal_int_int_pointer_pointer_bool :: !Pointer !Int !Int !Pointer !Pointer !Int -> Int -addTimeout :: !GtkTimeout !(GtkM Bool) -> GtkM () -handleTimeout :: !Int -> Int // only for foreign export +handleTimeout :: !Int -> Int |