gtkobject.html

该压缩包包含了GTK+的大量API函数

>Description</H3
><P
>GtkObject is the root of the gtk+ type hierarchy.  It serves
a similar roles as java's Object class.  It is used 
by the type-casting system to represent the base composite type.</P
><P
>Objects have <I
CLASS="WORDASWORD"
>arguments</I
> that are
name/typed-value pairs.  
They may be readable or writable (or both or neither).
The special handlers in every object are responsible for
setting and getting these parameters.
If the handler for a given argument <I
CLASS="EMPHASIS"
>must</I
>
be called before the object may be used, be sure the
GTK_ARG_CONSTRUCT or GTK_ARG_CONSTRUCT_ONLY flags
are set;  otherwise they are set only when the user does so.</P
><P
>Object also store a simpler association table, sometimes
called the object_data.  This is just an efficient mapping from
a fixed set of strings to a gpointer.  This can be used as
arbitrary extra members.  Notice that each new field name
allocates a new quark, so it is probably best only to use
this for fields with fixed names.</P
><P
>The primary difference between object_data and arguments is that
the object defines two functions which set and get each type of argument.
The object just has a table to store its object data in:  it does not
receive notice when data changes.</P
><P
>Objects are reference counted;  this means that we maintain
a count of how many references (usually in the form of a pointer)
are being held to this object.
To indicate that you reference an object, call <A
HREF="gtkobject.html#GTK-OBJECT-REF"
>gtk_object_ref</A
>().
The object will not be freed until everyone calls 
<A
HREF="gtkobject.html#GTK-OBJECT-UNREF"
>gtk_object_unref</A
>().</P
><P
>In order to reduce the chances of a memory leak, gtk+ defines
"floating objects".  All objects created with <A
HREF="gtkobject.html#GTK-OBJECT-NEW"
>gtk_object_new</A
>()
start out floating with a reference count of 1.
In order to reduce that initial reference count you should <A
HREF="gtkobject.html#GTK-OBJECT-SINK"
>gtk_object_sink</A
>()
them, but usually the parent widget you add the child to will
sink the object.  </P
><P
>So, because <A
HREF="gtkwidget.html#GTK-WIDGET-SET-PARENT"
>gtk_widget_set_parent</A
>() sinks the object from
<A
HREF="gtkcontainer.html#GTK-CONTAINER-ADD"
>gtk_container_add</A
>(), there are no memory leaks in this code:
<DIV
CLASS="INFORMALEXAMPLE"
><A
NAME="AEN33747"
></A
><P
></P
><TABLE
BORDER="0"
BGCOLOR="#D8F8D8"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>	button = gtk_button_new_with_label("Hi Mom!");
	gtk_container_add(GTK_CONTAINER(window), button);
	/* Button may not be used anymore since we don't retain a reference
	 * to it. */</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
>
Likewise, the following code attaches the same adjustment to two
ranges:
<DIV
CLASS="INFORMALEXAMPLE"
><A
NAME="AEN33749"
></A
><P
></P
><TABLE
BORDER="0"
BGCOLOR="#D8F8D8"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>	adjustment = (GtkAdjustment*) gtk_adjustment_new(0,10,0,0,0,0);
	gtk_range_set_adjustment(range1, adjustment);
	gtk_range_set_adjustment(range2, adjustment);</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
>
Note that we could put as many set_adjustments as we like:  cleanup is easy
because they all retain a reference but only one sinks the initial reference
count.  If it is possible for "range1" to stop retaining its reference
then we need to enclose the lines using "adjustment" with ref/unref
to guarantee the the object won't be deleted:
<DIV
CLASS="INFORMALEXAMPLE"
><A
NAME="AEN33751"
></A
><P
></P
><TABLE
BORDER="0"
BGCOLOR="#D8F8D8"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>	adjustment = (GtkAdjustment*) gtk_adjustment_new(0,10,0,0,0,0);
	gtk_object_ref(GTK_OBJECT(adjustment));
	gtk_range_set_adjustment(range1, adjustment);
	gtk_range_set_adjustment(range1, another_adjustment);
	/* With the initial reference, `adjustment' would have
	 * been deleted as `range1' lost its reference to it. */
	gtk_range_set_adjustment(range2, adjustment);
	gtk_object_unref(GTK_OBJECT(adjustment));</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
></P
><P
>Be careful with reference counting:  if two objects reference eachother
then they will always have at least reference count 1, even if
there are no other pointers to them.  This means that they
will never be freed.  More precisely, you must be certain that
your references <I
CLASS="EMPHASIS"
>never</I
> can form cycles.</P
><P
>If you find yourself forming cyclic references, perhaps you
can convert some of them to <I
CLASS="WORDASWORD"
>weak-references</I
>.
A weak-reference is one that holds a pointer to an object,
but doesn't increase the reference count.  To insure
the object is valid when the referer tries to use it,
the referer registers a callback that will be invoked
after the object has been destroyed (but before its memory is actually
deallocated).  This callback must prevent the weak-reference from
being used again.</P
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN33757"
></A
><H3
>Brief Glossary</H3
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>argument</DT
><DD
><P
>A typed-variable identified by ObjectType::argument_name.  It may be
readable, writable, both or none.  For example,
"GtkButton::label" is a read/write string-valued argument.</P
></DD
><DT
>constructed</DT
><DD
><P
></P
></DD
><DT
>destroyed</DT
><DD
><P
></P
></DD
><DT
>finalization</DT
><DD
><P
></P
></DD
><DT
>floating</DT
><DD
><P
></P
></DD
><DT
>object data</DT
><DD
><P
></P
></DD
><DT
>reference count</DT
><DD
><P
></P
></DD
><DT
>weak-reference</DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN33792"
></A
><H2
>Details</H2
><DIV
CLASS="REFSECT2"
><A
NAME="AEN33794"
></A
><H3
><A
NAME="GTKOBJECT-STRUCT"
></A
>struct GtkObject</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>struct GtkObject;</PRE
></TD
></TR
></TABLE
><P
>The object itself.  You should never use these members directly-
instead you the accessing macros.</P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN33799"
></A
><P
></P
><TABLE
BORDER="0"
WIDTH="100%"
BGCOLOR="#FFF0D0"
CELLSPACING="0"
CELLPADDING="4"
CLASS="CALSTABLE"
><TBODY
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN33804"
></A
><H3
><A
NAME="GTK-OBJECT-TYPE-CAPS"
></A
>GTK_OBJECT_TYPE()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define GTK_OBJECT_TYPE(obj)		  (GTK_OBJECT (obj)-&gt;klass-&gt;type)</PRE
></TD
></TR
></TABLE
><P
>Get the type of an object.</P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN33809"
></A
><P
></P
><TABLE
BORDER="0"
WIDTH="100%"
BGCOLOR="#FFD0D0"
CELLSPACING="0"
CELLPADDING="4"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>obj</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>the object whose type we wish to get.
&#13;</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN33818"
></A
><H3
><A
NAME="GTK-OBJECT-SIGNALS-CAPS"
></A
>GTK_OBJECT_SIGNALS()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define GTK_OBJECT_SIGNALS(obj)		  (GTK_OBJECT (obj)-&gt;klass-&gt;signals)</PRE
></TD
></TR
></TABLE
><P
>Get the array of signals defined for this object.</P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN33823"
></A
><P
></P
><TABLE
BORDER="0"
WIDTH="100%"
BGCOLOR="#FFD0D0"
CELLSPACING="0"
CELLPADDING="4"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>obj</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>the object to fetch the signals from.
&#13;</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN33832"
></A
><H3
><A
NAME="GTK-OBJECT-NSIGNALS-CAPS"
></A
>GTK_OBJECT_NSIGNALS()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define GTK_OBJECT_NSIGNALS(obj)	  (GTK_OBJECT (obj)-&gt;klass-&gt;nsignals)</PRE
></TD
></TR
></TABLE
><P
>Get the number of signals defined by this object.</P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN33837"
></A
><P
></P
><TABLE
BORDER="0"
WIDTH="100%"
BGCOLOR="#FFD0D0"
CELLSPACING="0"
CELLPADDING="4"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>obj</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>the object to query.
&#13;</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN33846"
></A
><H3
><A
NAME="GTKOBJECTFLAGS"
></A
>enum GtkObjectFlags</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>typedef enum
{
  GTK_DESTROYED		= 1 &lt;&lt; 0,
  GTK_FLOATING		= 1 &lt;&lt; 1,
  GTK_CONNECTED		= 1 &lt;&lt; 2,
  GTK_CONSTRUCTED	= 1 &lt;&lt; 3
} GtkObjectFlags;</PRE
></TD
></TR
></TABLE
><P
>Tells about the state of the object.</P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN33851"
></A
><P
></P
><TABLE
BORDER="0"
WIDTH="100%"
BGCOLOR="#F0F0D0"
CELLSPACING="0"
CELLPADDING="4"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>GTK_DESTROYED</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>the GtkObject has had gtk_object_destroyed() invoked on it
and is processing the shutdown callback.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>GTK_FLOATING</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>whether the object is orphaned.  Objects that take
strong hold of an object may <A
HREF="gtkobject.html#GTK-OBJECT-SINK"
>gtk_object_sink</A
>() it, after obtaining
there own references, if they believe they are nearly primary
ownership of the object.
GTK_CONNECTED: refers to whether are signals are connected to this
object.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>GTK_CONNECTED</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>&nbsp;</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>GTK_CONSTRUCTED</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>refers to whether the arguments for this object are
ready.&#13;</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN33874"
></A
><H3
><A
NAME="GTK-OBJECT-FLAGS-CAPS"
></A
>GTK_OBJECT_FLAGS()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define GTK_OBJECT_FLAGS(obj)		  (GTK_OBJECT (obj)-&gt;flags)</PRE
></TD
></TR
></TABLE
><P
>Get the <A
HREF="gtkobject.html#GTKOBJECTFLAGS"
>GtkObjectFlags</A
> for an object without directly
accessing its members.</P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN33880"
></A
><P
></P
><TABLE
BORDER="0"
WIDTH="100%"
BGCOLOR="#FFD0D0"
CELLSPACING="0"
CELLPADDING="4"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>obj</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>the object whose flags are returned.
&#13;</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN33889"
></A
><H3
><A
NAME="GTK-OBJECT-DESTROYED-CAPS"
></A
>GTK_OBJECT_DESTROYED()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define GTK_OBJECT_DESTROYED(obj)	  ((GTK_OBJECT_FLAGS (obj) &amp; GTK_DESTROYED) != 0)</PRE
></TD
></TR
></TABLE
><P
>Test whether a GtkObject has had gtk_object_destroyed() invoked on it.</P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN33895"
></A
><P
></P
><TABLE
BORDER="0"
WIDTH="100%"
BGCOLOR="#FFD0D0"
CELLSPACING="0"
CELLPADDING="4"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>obj</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>the object to examine.
&#13;</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN33904"
></A
><H3
><A
NAME="GTK-OBJECT-FLOATING-CAPS"
></A
>GTK_OBJECT_FLOATING()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define GTK_OBJECT_FLOATING(obj)	  ((GTK_OBJECT_FLAGS (obj) &amp; GTK_FLOATING) != 0)</PRE
></TD
></TR
></TABLE
><P
>When an object is created, it has an initial reference count
of 1 and is floating.  <I
CLASS="WORDASWORD"
>Sinking</I
> the object 
refers to decrementing that original reference count.</P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN33910"
></A
><P
></P
><TABLE
BORDER="0"
WIDTH="100%"
BGCOLOR="#FFD0D0"
CELLSPACING="0"
CELLPADDING="4"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>obj</I
></TT
>&nbsp;:</TD