definition module Gtk.Signal

/**
 * This module provides functionality for Gtk signals.
 */

from System._Pointer import :: Pointer

from Gdk.Events import :: GdkEvent
from Gtk.State import :: GtkM, :: GtkState
from Gtk.Tune import class tune
from Gtk.Types import :: GtkPropagate, :: GtkTimeout
from Gtk.Widgets import class gtkWidget, :: GtkMenu

/**
 * 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

//* A number of basic signals. See the Gtk documentation for their usage.
:: GSignalHandler
	= ActivateHandler      !(GtkM ())
	| ChangedHandler       !(GtkM ())
	| ClickedHandler       !(GtkM ())
	| DeleteEventHandler   !(GdkEvent -> GtkM GtkPropagate)
	| DestroyHandler       !(GtkM ())
	| KeyPressHandler      !(GdkEvent -> GtkM GtkPropagate)
	| NextMatchHandler     !(GtkM ())
	| PopulatePopupHandler !(GtkMenu -> GtkM ())
	| PreviousMatchHandler !(GtkM ())
	| SearchChangedHandler !(GtkM ())
	| StopSearchHandler    !(GtkM ())

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_Void !(Pointer -> 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

//* Alternative for `installSignalHandler` for more readable code.
instance tune w GSignalHandler | gtkWidget w

/**
 * 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 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

/**
 * 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_void :: !Pointer !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

handleTimeout :: !Int -> Int