gtk.texi

gtk是linux一款强大的夸平台的图形化开发工具

  GdkEvent event;
  gint return_val;
  @dots{}
  gtk_signal_emit (some_object,
                   gtk_signal_lookup ("event",
                     GTK_OBJECT_TYPE (some_object)),
                   &event, &return_val);
@end example

Notice that the @code{widget} argument is implicit in that the first
argument to every signal is a type derived from @code{GtkObject}. The
@var{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 @code{gtk_signal_lookup} call is
normally avoided by using the @code{gtk_signal_emit_by_name} function
instead. @code{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 @code{gtk_signal_lookup}.
@end deftypefun

@deftypefun gint gtk_signal_emit_by_name (GtkObject *@var{object}, gchar *@var{name}, @dots{})
Similar to @code{gtk_signal_emit} except that the signal is referenced
by @var{name} instead of by its integer identifier.
@end deftypefun

@deftypefun void gtk_signal_emit_stop (GtkObject *@var{object}, gint @var{signal_type})
Stop the emission of the signal @var{signal_type} on
@var{object}. @var{signal_type} is the integer identifier for the signal
and can be determined using the function
@code{gtk_signal_lookup}. Alternatively, the function
@code{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.
@end deftypefun

@deftypefun void gtk_signal_emit_stop_by_name (GtkObject *@var{object}, gchar *@var{name})
Similar to @code{gtk_signal_emit_stop} except that the signal is
referenced by @var{name} instead of by its integer identifier.
@end deftypefun

@deftypefun gint gtk_signal_connect (GtkObject *@var{object}, gchar *@var{name}, GtkSignalFunc @var{func}, gpointer @var{func_data})
Connects a signal handling function to a signal emitting
object. @var{func} is connected to the signal @var{name} emitted by
@var{object}. The arguments and returns type of @var{func} should match
the arguments and return type of the signal @var{name}. However,
@var{func} may take the extra argument of @var{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).

@code{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.
@end deftypefun

@deftypefun gint gtk_signal_connect_after (GtkObject *@var{object}, gchar *@var{name}, GtkSignalFunc @var{func}, gpointer @var{func_data})
Similar to @code{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 @code{gtk_signal_connect}, @code{gtk_signal_connect_after} returns
an integer identifier which can be used to refer to the connection.
@end deftypefun

@deftypefun gint gtk_signal_connect_object (GtkObject *@var{object}, gchar *@var{name}, GtkSignalFunc @var{func}, GtkObject *@var{slot_object})
Connects @var{func} to the signal @var{name} emitted by
@var{object}. Similar to @code{gtk_signal_connect} with the difference
that @var{slot_object} is passed as the first parameter to @var{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.
@end deftypefun

@deftypefun gint gtk_signal_connect_object_after (GtkObject *@var{object}, gchar *@var{name}, GtkSignalFunc @var{func}, GtkObject *@var{slot_object})
Similar to @code{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.
@end deftypefun

@deftypefun gint gtk_signal_connect_interp (GtkObject *@var{object}, gchar *@var{name}, GtkCallbackMarshal @var{func}, gpointer @var{data}, GtkDestroyNotify @var{destroy_func}, gint @var{after})
@end deftypefun

@deftypefun void gtk_signal_disconnect (GtkObject *@var{object}, gint @var{id})
Disconnects a signal handler from an object. The signal handler is
identified by the integer @var{id} which is returned by the
@code{gtk_signal_connect*} family of functions.
@end deftypefun

@deftypefun void gtk_signal_disconnect_by_data (GtkObject *@var{object}, gpointer @var{data})
Disconnects a signal handler from an object. The signal handler is
identified by the @var{data} argument specified as the @var{func_data}
argument to the @code{gtk_signal_connect*} family of functions. For the
@code{gtk_signal_connect_object*} functions, @var{data} refers to the
@var{slot_object}.

@strong{Note:} This will remove all signal handlers connected to
@var{object} which were connected using @var{data} as their
@var{func_data} argument. Multiple signal handlers may be disconnected
with this call.
@end deftypefun

@deftypefun void gtk_signal_handler_block (GtkObject *@var{object}, gint @var{id})
Blocks calling of a signal handler during signal emission. The signal
handler is identified by the integer @var{id} which is returned by the
@code{gtk_signal_connect*} family of functions. If the signal is already
blocked no change is made.
@end deftypefun

@deftypefun void gtk_signal_handler_block_by_data (GtkObject *@var{object}, gint @var{data})
Blocks calling of a signal handler during signal emission. The signal
handler is identified by the @var{data} argument specified as the
@var{func_data} argument to the @code{gtk_signal_connect*} family of
functions. For the @code{gtk_signal_connect_object*} functions,
@var{data} refers to the @var{slot_object}. If the signal is already
blocked no change is made.

@strong{Note:} This will block all signal handlers connected to
@var{object} which were connected using @var{data} as their
@var{func_data} argument. Multiple signal handlers may be blocked
with this call.
@end deftypefun

@deftypefun void gtk_signal_handler_unblock (GtkObject *@var{object}, gint @var{id})
Unblocks calling of a signal handler during signal emission. The signal
handler is identified by the integer @var{id} which is returned by the
@code{gtk_signal_connect*} family of functions. If the signal is already
unblocked no change is made.
@end deftypefun

@deftypefun void gtk_signal_handler_unblock_by_data (GtkObject *@var{object}, gint @var{data})
Unblocks calling of a signal handler during signal emission. The signal
handler is identified by the @var{data} argument specified as the
@var{func_data} argument to the @code{gtk_signal_connect*} family of
functions. For the @code{gtk_signal_connect_object*} functions,
@var{data} refers to the @var{slot_object}. If the signal is already
unblocked no change is made.

@strong{Note:} This will unblock all signal handlers connected to
@var{object} which were connected using @var{data} as their
@var{func_data} argument. Multiple signal handlers may be unblocked
with this call.
@end deftypefun

@deftypefun void gtk_signal_handlers_destroy (GtkObject *@var{object})
Destroy all of the signal handlers connected to @var{object}. There
should normally never be reason to call this function as it is called
automatically when @var{object} is destroyed.
@end deftypefun

@deftypefun void gtk_signal_default_marshaller (GtkObject *@var{object}, GtkSignalFunc @var{func}, gpointer @var{func_data}, GtkSignalParam *@var{params})
@code{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:

@example
  (* std_signal) (gpointer std_arg);
@end example

@code{gtk_signal_default_marshaller} is a signal marshaller which
marshals arguments for a signal of that form.
@end deftypefun

@deftypefun void gtk_signal_set_funcs (GtkSignalMarshal @var{marshal_func}, GtkSignalDestroy @var{destroy_fun})
@end deftypefun


@node Widgets, Other Objects, Signals, Top
@comment node-name, next, previous, up
@chapter Widget Overview
@cindex Widgets


Widgets are the general term used to describe user interface objects. A
widget defines a class interface that all user interface objects conform
to. This interface allows a uniform method for dealing with operations
common to all objects such as hiding and showing, size requisition and
allocation and events.

The common interface that widgets must adhere to is described by the
GtkWidget and GtkWidgetClass structure. For the purposes of using GTK
these structures can be considered read-only and, for the most part,
opaque.

All widget creation routines in GTK return pointers to GtkWidget
structures. In reality, all widget creation routines create structures
that can be viewed as equivalent to the GtkWidget structure, but often
have contain additional information. @xref{Object Implementation}.

The widgets available for use are implemented in a hierarchy. Several
widgets exist solely as common bases for more specific widgets. For
example, it is not possible to create a ruler widget itself, but the
ruler widget provides a base and functionality common to the horizontal
and vertical rulers.

The available widgets (in alphabetical order):

@menu
* GtkAlignment::                The alignment widget.
* GtkArrow::                    The arrow widget.
* GtkAspectFrame::              The aspect frame widget.
* GtkBin::                      The bin widget.
* GtkBox::                      The box widget.
* GtkButtonBox::                The button box widget.
* GtkButton::                   The button widget.
* GtkCheckButton::              The check button widget.
* GtkCheckMenuItem::            The check menu item widget.
* GtkCList::                    The compound list widget.
* GtkColorSelection::           The color selector widget.
* GtkCombo::                    The combo box widget.
* GtkContainer::                The container widget.
* GtkCTree::                    The multi-column tree widget.
* GtkCurve::                    The curve widget.
* GtkGammaCurve::               The gamma curve widget.
* GtkDialog::                   The dialog widget.
* GtkDrawingArea::              The drawing area widget.
* GtkEntry::                    The entry widget.
* GtkEventBox::                 The event box widget.
* GtkFileSelection::            The file selection dialog widget.
* GtkFixed::                    The fixed widget.
* GtkFrame::                    The frame widget.
* GtkGamma::                    The gamma widget.
* GtkHBox::                     The horizontal box widget.
* GtkHButtonBox::               The horizontal button box widget.
* GtkHPaned::                   The horizontal paned widget.
* GtkHRuler::                   The horizontal ruler widget.
* GtkHScale::                   The horizontal scale widget.
* GtkHScrollbar::               The horizontal scrollbar widget.
* GtkHSeparator::               The horizontal separator widget.
* GtkImage::                    The image widget.
* GtkInputDialog::              The input dialog widget.
* GtkItem::                     The item widget.
* GtkLabel::                    The label widget.
* GtkList::                     The list widget.
* GtkListItem::                 The list item widget.
* GtkMenu::                     The menu widget.
* GtkMenuBar::                  The menu bar widget.
* GtkMenuItem::                 The menu item widget.
* GtkMenuShell::                The menu shell widget.
* GtkMisc::                     The misc widget.
* GtkNotebook::                 The notebook widget.
* GtkOptionMenu::               The option menu widget.
* GtkPaned::                    The paned widget.
* GtkPixmap::                   The pixmap widget.
* GtkPreview::                  The preview widget.
* GtkProgressBar::              The progress bar widget.
* GtkRadioButton::              The radio button widget.
* GtkRadioMenuItem::            The radio menu item widget.
* GtkRange::                    The range widget.
* GtkRuler::                    The ruler widget.
* GtkScale::                    The scale widget.
* GtkScrollbar::                The scrollbar widget.
* GtkScrolledWindow::           The scrolled window widget.
* GtkSeparator::                The separator widget.
* GtkStatusbar::                The statusbar widget.
* GtkTable::                    The table widget.
* GtkText::                     The text widget.
* GtkToggleButton::             The toggle button widget.
* GtkToolbar::                  The tool bar widget.
* GtkTooltips::                 The tool tips widget.
* GtkTree::                     The tree widget.
* GtkTreeItem::                 The tree item widget.
* GtkVBox::                     The vertical box widget.
* GtkVButtonBox::               The vertical button box widget.
* GtkViewport::                 The viewport widget.
* GtkVPaned::                   The vertical paned widget.
* GtkVRuler::                   The vertical ruler widget.
* GtkVScale::                   The vertical scale widget.
* GtkVScrollbar::               The vertical scrollbar widget.
* GtkVSeparator::               The vertical separator widget.
* GtkWidget::                   The base widget type.
* GtkWindow::                   The window widget.
@end menu

@node GtkAlignment, GtkArrow, Widgets, Widgets
@comment node-name, next, previous, up
@section The alignment widget


@subsection Description

The alignment widget is a container (@pxref{GtkContainer}) derived from
the bin widget (@pxref{GtkBin}). Its entire purpose is to give the
programmer flexibility in how the child it manages is positioned when a
window is resized.

Normally, a widget is allocated at least as much size as it
requests. (@pxref{GtkContainer} for a discussion of geometry
management). When a widget is allocated more size than it requests there
is a question of how the widget should expand. By convention, most GTK
widgets expand to fill their allocated space. Sometimes this behavior is
not desired. The alignment widget allows the programmer to specify how a