DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

(gtk.info) Signals

Info Catalog (gtk.info) Objects (gtk.info) Top (gtk.info) Widgets
 
 Signals Overview
 ****************
 
    Signals are GTK's method for objects to perform callbacks. A signal
 is an event which occurs upon an object. The programmer can connect to a
 signal of an object which involves specifying a function to be called
 when that signal is emitted in the specified object.
 
    When a signal is emitted, both the class function associated with the
 signal (when it was defined) and all signal handlers installed for that
 signal on the particular object emitting the signal are called. The
 widget programmer can specify whether the class function is to be called
 before after or both before and after the signal handlers installed by
 the widget user. The widget user can, however, specify that their signal
 handler is to be run after the class function (using the "_after"
 signal connection routines). Any signal handling function can emit the
 same signal on the same object while it is running causing that signal
 emission to either restart or to run recursively. Additionally, signal
 emission can be terminated prematurely. While both such abilities are
 rarely used, they do allow for greater flexibility in regards to
 signals. For instance, a programmer can attach to the key press event
 signal and intercept all tab key presses from a widget. This particular
 example is used in the file selection dialog to implement tab completion
 of filenames and prevent the entry widget from inserting the tab into
 its buffer.
 
    Signals are selected using either an integer identifier or a
 character string name. It is convention to name the signal the same as
 the class function which is associated with it. There are two versions
 of most of the signal functions, one which takes an integer identifier
 and one which takes a character string name for the signal.
 
  - Function: gint gtk_signal_new (gchar *NAME, GtkSignalRunType
           RUN_TYPE, gint OBJECT_TYPE, gint FUNCTION_OFFSET,
           GtkSignalMarshaller MARSHALLER, GtkParamType RETURN_VAL, gint
           NPARAMS, ...)
      Create a new signal and give it the character string identifier
      NAME. NAME needs to be unique in the context of OBJECT_TYPE's
      branch of the class hierarchy. That is, OBJECT_TYPE cannot create
      a signal type with the same name as a signal type created by one
      of its parent types.
 
      RUN_TYPE specifies whether the class function should be run before
      (`GTK_RUN_FIRST'), after (`GTK_RUN_LAST') or both before and after
      normal signal handlers (`GTK_RUN_BOTH'). Additionally, the
      `GTK_RUN_NO_RECURSE' value can be or'ed with any of those values to
      specify that the signal should not be recursive. By default,
      emitting the same signal on the same widget will cause the signal
      to be emitted twice. However, if the `GTK_RUN_NO_RECURSE' flag is
      specified, emitting the same signal on the same widget will cause
      the current signal emission to be restarted. This allows the
      widget programmer to specify the semantics of signal emission on a
      per signal basis. (The `GTK_RUN_NO_RECURSE' flag is used by the
      GtkAdjustment widget).
 
      The FUNCTION_OFFSET is the byte offset from the start of the class
      structure to the class function field within the class structure.
      The easiest means to compute this offset is by using the
      `GTK_SIGNAL_OFFSET' macro which takes the class structure type as
      the first argument and the field as the second argument. For
      example, `GTK_SIGNAL_OFFSET (GtkObjectClass, destroy)' will give
      the offset of the `destroy' class function within the
      `GtkObjectClass'. Note: An offset is specified instead of an
      absolute location since there will be multiple instances of a class
      structure being referenced. (The `GtkWidgetClass' structure "is a"
      `GtkObjectClass' structure, etc.)
 
      The MARSHALLER function is used to invoke a signal handler. Since
      signal handlers may take different parameters and return values
      and a general mechanism for invoking them is not apparent, the
      approach of making the signal creator responsible for invoking the
      signal handler was taken. (FIXME: unfinished).
 
      The RETURN_VAL and NPARAMS and the remaining arguments specify the
      return value and the arguments to the signal handler respectively.
      Note: There is an implicit first argument to every signal handler
      which is the widget the signal has been emitted from. The variable
      argument list (...) specifies the types of the arguments. These
      can be one of `GTK_PARAM_CHAR', `GTK_PARAM_SHORT',
      `GTK_PARAM_INT', `GTK_PARAM_LONG', `GTK_PARAM_POINTER' or
      `GTK_PARAM_FUNCTION'. It is undefined to specify `GTK_PARAM_NONE'
      as an argument type, however it is OK to use `GTK_PARAM_NONE' for
      RETURN_VAL. (This corresponds to returning a `void').
 
      `gtk_signal_new' returns the integer identifier of the newly
      created signal. Signal identifiers start numbering at 1 and
      increase upwards. A value of -1 will be returned if an error
      occurs.
 
         A
      normal user of GTK will never needed to invoke this function.
 
  - Function: gint gtk_signal_lookup (gchar *NAME, gint OBJECT_TYPE)
      Returns the integer identifier for the signal referenced by NAME
      and OBJECT_TYPE. If OBJECT_TYPE does not define the signal NAME,
      then the signal is looked for in OBJECT_TYPE's parent type
      recursively.
 
  - Function: gchar* gtk_signal_name (gint SIGNAL_NUM)
 
  - Function: gint gtk_signal_emit (GtkObject *OBJECT, gint SIGNAL_TYPE,
           ...)
      Emit the signal specified by the integer identifier SIGNAL_TYPE
      from OBJECT. If an error occurs, `gtk_signal_emit' will return
      `FALSE' and will return `TRUE' on success. The signal definition
      determines the parameters passed in the variable argument list
      (`...'). For example, if the signal is defined as:
 
             gint (* event) (GtkWidget *widget, GdkEvent *event);
 
      Then a call to emit the "event" signal would look like:
 
             GdkEvent event;
             gint return_val;
             ...
             gtk_signal_emit (some_object,
                              gtk_signal_lookup ("event",
                                GTK_OBJECT_TYPE (some_object)),
                              &event, &return_val);
 
      Notice that the `widget' argument is implicit in that the first
      argument to every signal is a type derived from `GtkObject'. The
      RETURN_VAL argument is actually a pointer to the return value type
      since the signal mechanism needs to be able to place the return
      value in an actual location. And lastly, the `gtk_signal_lookup'
      call is normally avoided by using the `gtk_signal_emit_by_name'
      function instead. `gtk_signal_emit' is normally used internally by
      widgets which know the signal identifier (since they defined the
      signal) and can therefore side-step the cost of calling
      `gtk_signal_lookup'.
 
  - Function: gint gtk_signal_emit_by_name (GtkObject *OBJECT, gchar
           *NAME, ...)
      Similar to `gtk_signal_emit' except that the signal is referenced
      by NAME instead of by its integer identifier.
 
  - Function: void gtk_signal_emit_stop (GtkObject *OBJECT, gint
           SIGNAL_TYPE)
      Stop the emission of the signal SIGNAL_TYPE on OBJECT. SIGNAL_TYPE
      is the integer identifier for the signal and can be determined
      using the function `gtk_signal_lookup'. Alternatively, the function
      `gtk_signal_emit_stop_by_name' can be used to refer to the signal
      by name. Attempting to stop the emission of a signal that isn't
      being emitted does nothing.
 
  - Function: void gtk_signal_emit_stop_by_name (GtkObject *OBJECT,
           gchar *NAME)
      Similar to `gtk_signal_emit_stop' except that the signal is
      referenced by NAME instead of by its integer identifier.
 
  - Function: gint gtk_signal_connect (GtkObject *OBJECT, gchar *NAME,
           GtkSignalFunc FUNC, gpointer FUNC_DATA)
      Connects a signal handling function to a signal emitting object.
      FUNC is connected to the signal NAME emitted by OBJECT. The
      arguments and returns type of FUNC should match the arguments and
      return type of the signal NAME. However, FUNC may take the extra
      argument of FUNC_DATA. Due to the C calling convention it is OK to
      ignore the extra argument. (It is OK to ignore all the arguments
      in fact).
 
      `gtk_signal_connect' returns an integer identifier for the
      connection which can be used to refer to it in the future.
      Specifically it is useful for removing the connection and/or
      blocking it from being used.
 
  - Function: gint gtk_signal_connect_after (GtkObject *OBJECT, gchar
           *NAME, GtkSignalFunc FUNC, gpointer FUNC_DATA)
      Similar to `gtk_signal_connect' except the signal handler is
      connected in the "after" slot. This allows a signal handler to be
      guaranteed to run after other signal handlers connected to the same
      signal on the same object and after the class function associated
      with the signal.
 
      Like `gtk_signal_connect', `gtk_signal_connect_after' returns an
      integer identifier which can be used to refer to the connection.
 
  - Function: gint gtk_signal_connect_object (GtkObject *OBJECT, gchar
           *NAME, GtkSignalFunc FUNC, GtkObject *SLOT_OBJECT)
      Connects FUNC to the signal NAME emitted by OBJECT. Similar to
      `gtk_signal_connect' with the difference that SLOT_OBJECT is
      passed as the first parameter to FUNC instead of the signal
      emitting object. This can be useful for connecting a signal
      emitted by one object to a signal in another object. A common
      usage is to connect the "destroy" signal of dialog to the "clicked"
      signal emitted by a "close" button in the dialog. That is, the
      "clicked" signal emitted by the button will caused the "destroy"
      signal to be emitted for the dialog. This is also the "right" way
      to handle closing of a dialog since the "destroy" signal will be
      sent if the dialog is deleted using a window manager function and
      this enables the two methods of closing the window to be handled
      by the same mechanism. Returns an integer identifier which can be
      used to refer to the connection.
 
  - Function: gint gtk_signal_connect_object_after (GtkObject *OBJECT,
           gchar *NAME, GtkSignalFunc FUNC, GtkObject *SLOT_OBJECT)
      Similar to `gtk_signal_connect_object' except the signal handler is
      connected in the "after" slot. This allows a signal handler to be
      guaranteed to run after other signal handlers connected to the same
      signal on the same object and after the class function associated
      with the signal. Returns an integer identifier which can be used
      to refer to the connection.
 
  - Function: gint gtk_signal_connect_interp (GtkObject *OBJECT, gchar
           *NAME, GtkCallbackMarshal FUNC, gpointer DATA,
           GtkDestroyNotify DESTROY_FUNC, gint AFTER)
 
  - Function: void gtk_signal_disconnect (GtkObject *OBJECT, gint ID)
      Disconnects a signal handler from an object. The signal handler is
      identified by the integer ID which is returned by the
      `gtk_signal_connect*' family of functions.
 
  - Function: void gtk_signal_disconnect_by_data (GtkObject *OBJECT,
           gpointer DATA)
      Disconnects a signal handler from an object. The signal handler is
      identified by the DATA argument specified as the FUNC_DATA
      argument to the `gtk_signal_connect*' family of functions. For the
      `gtk_signal_connect_object*' functions, DATA refers to the
      SLOT_OBJECT.
 
        
      Multiple signal handlers may be disconnected with this call.
 
  - Function: void gtk_signal_handler_block (GtkObject *OBJECT, gint ID)
      Blocks calling of a signal handler during signal emission. The
      signal handler is identified by the integer ID which is returned
      by the `gtk_signal_connect*' family of functions. If the signal is
      already blocked no change is made.
 
  - Function: void gtk_signal_handler_block_by_data (GtkObject *OBJECT,
           gint DATA)
      Blocks calling of a signal handler during signal emission. The
      signal handler is identified by the DATA argument specified as the
      FUNC_DATA argument to the `gtk_signal_connect*' family of
      functions. For the `gtk_signal_connect_object*' functions, DATA
      refers to the SLOT_OBJECT. If the signal is already blocked no
      change is made.
 
        
      Multiple signal handlers may be blocked with this call.
 
  - Function: void gtk_signal_handler_unblock (GtkObject *OBJECT, gint
           ID)
      Unblocks calling of a signal handler during signal emission. The
      signal handler is identified by the integer ID which is returned
      by the `gtk_signal_connect*' family of functions. If the signal is
      already unblocked no change is made.
 
  - Function: void gtk_signal_handler_unblock_by_data (GtkObject
           *OBJECT, gint DATA)
      Unblocks calling of a signal handler during signal emission. The
      signal handler is identified by the DATA argument specified as the
      FUNC_DATA argument to the `gtk_signal_connect*' family of
      functions. For the `gtk_signal_connect_object*' functions, DATA
      refers to the SLOT_OBJECT. If the signal is already unblocked no
      change is made.
 
        
      Multiple signal handlers may be unblocked with this call.
 
  - Function: void gtk_signal_handlers_destroy (GtkObject *OBJECT)
      Destroy all of the signal handlers connected to OBJECT. There
      should normally never be reason to call this function as it is
      called automatically when OBJECT is destroyed.
 
  - Function: void gtk_signal_default_marshaller (GtkObject *OBJECT,
           GtkSignalFunc FUNC, gpointer FUNC_DATA, GtkSignalParam
           *PARAMS)
      `gtk_signal_new' requires a callback in order to actually call a
      signal handler for a particular signal. The vast majority of
      signals are of the particular form:
 
             (* std_signal) (gpointer std_arg);
 
      `gtk_signal_default_marshaller' is a signal marshaller which
      marshals arguments for a signal of that form.
 
  - Function: void gtk_signal_set_funcs (GtkSignalMarshal MARSHAL_FUNC,
           GtkSignalDestroy DESTROY_FUN)
 
Info Catalog (gtk.info) Objects (gtk.info) Top (gtk.info) Widgets
automatically generated byinfo2html