GSignal                package:RGtk2                R Documentation

_T_h_e _G_S_i_g_n_a_l _A_P_I

_D_e_s_c_r_i_p_t_i_o_n:

     The basic concept of the signal system is that of the emission of
     a signal.  Signals are introduced per-type and are identified
     through strings.  Signals introduced for a parent type are
     available in derived types as well,  so basically they are a
     per-type facility that is inherited.

_U_s_a_g_e:

     gSignalConnect(obj, signal, f, data = NULL, after = FALSE, user.data.first = FALSE)
     gSignalHandlerDisconnect(obj, id)
     gSignalHandlerBlock(obj, id)
     gSignalHandlerUnblock(obj, id)
     gSignalEmit(obj, signal, ..., detail = NULL)
     gSignalStopEmission(obj, signal, detail = NULL)
     gSignalGetInfo(sig)

_A_r_g_u_m_e_n_t_s:

     obj: The object that owns the signal

  signal: The detailed name of the signal

       f: The R function to connect as a callback

    data: Arbitrary "user data" that will be passed to the callback 'f'

   after: Whether 'f' will be called before or after the default
          handler

user.data.first: Whether the 'data' is the first or last argument to
          the callback

      id: The signal handler id obtained upon connection to the signal

     ...: Arguments to pass to the signal handlers

  detail: Optional separate argument for the _detail_ portion of the
          signal

     sig: A signal id provided by 'gObjectGetSignals'.

_D_e_t_a_i_l_s:

     A signal emission mainly involves invocation of a certain set of
     callbacks  in precisely defined manner. There are two main
     categories of such callbacks,  per-object ones and user provided
     ones. The per-object callbacks are most often  referred to as
     "object method handler" or "default (signal) handler",  while user
     provided callbacks are usually just called "signal handler".  The
     object method handler is provided at signal creation time (this
     most  frequently happens at the end of an object class' creation),
     while user  provided handlers are frequently connected and
     disconnected to/from a certain  signal on certain object
     instances.

     A signal emission consists of five stages, unless prematurely
     stopped: 

        1.  Invocation of the object method handler for
           'G_SIGNAL_RUN_FIRST' signals

        2.  Invocation of normal user-provided signal handlers ('after'
           flag 'FALSE')

        3.  Invocation of the object method handler for
           'G_SIGNAL_RUN_LAST' signals

        4.  Invocation of user provided signal handlers, connected with
           an 'after' flag of 'TRUE'

        5.  Invocation of the object method handler for
           'G_SIGNAL_RUN_CLEANUP' signals

     The user-provided signal handlers are called in the order they
     were connected in.  All handlers may prematurely stop a signal
     emission, and any number of handlers  may be connected,
     disconnected, blocked or unblocked during a signal emission. 
     There are certain criteria for skipping user handlers in stages 2
     and 4 of a  signal emission. First, user handlers may be blocked,
     blocked handlers are  omitted during callback invocation, to
     return from the "blocked" state,  a handler has to get unblocked
     exactly the same amount of times it has been  blocked before.
     Second, upon emission of a 'G_SIGNAL_DETAILED' signal,  an
     additional "detail" argument passed in to 'gSignalEmit' has to
     match  the detail argument of the signal handler currently subject
     to invocation.  Specification of no detail argument for signal
     handlers (omission of the detail  part of the signal specification
     upon connection) serves as a wildcard and  matches any detail
     argument passed in to emission.

     Most of the time, the RGtk2 user will be connecting to signals
     using  'gSignalConnect'. This attaches an R function (and,
     optionally, some  arbitrary "user data") to a specific 'GObject'
     as a listener to the  named signal. 

     'gSignalHandlerBlock' and 'gSignalHandlerUnblock' provide
     facilities  for (temporarily) blocking and unblocking the calling
     of an R function in response to some signal.  To permanately
     disconnect the handler from the object and signal, use 
     'gSignalHandlerDisconnect'. 

     A signal may be manually emitted with 'gSignalEmit'. The emission
     of a signal may be killed prematurely with 'gSignalStopEmission'.

     Detailed information about a signal may be introspected with
     'gSignalGetInfo' using ids obtained with 'gObjectGetSignals'.

_V_a_l_u_e:

     'gSignalConnect' returns a numeric id for the signal handler. It
     is used for  blocking and disconnecting the handler.

     'gSignalGetInfo' returns detailed information about a signal. The
     returned list  contains the following elements: 

returnType: The return 'GType' id of the signal

  signal: The signal id

parameters: A list of 'GType' ids for the parameters

objectType: The 'GType' id owning the signal

runFlags: The flags determining behavior of the signal, see reference

_A_u_t_h_o_r(_s):

     Adapted from GSignal documentation by Michael Lawrence

_R_e_f_e_r_e_n_c_e_s:

     <URL:
     http://developer.gnome.org/doc/API/2.0/gobject/gobject-Signals.html>

_S_e_e _A_l_s_o:

     'GObject'

