hc-objectargs.html

gtk_text program sample&eg

              shorthand for <span class="STRUCTNAME">
              (GTK_ARG_READABLE | GTK_ARG_WRITABLE)</span>.&#13;
            </p>
          </li>
        </ul>
        <p>
          There are some limitations on which flags can be used.
        </p>
        <ul>
          <li>
            <p>
              All arguments must be either readable or
              writable.&#13;
            </p>
          </li>
          <li>
            <p>
              <span class="STRUCTNAME">GTK_ARG_CONSTRUCT</span>
              arguments must be both readable and writable.&#13;
            </p>
          </li>
          <li>
            <p>
              <span class="STRUCTNAME">
              GTK_ARG_CONSTRUCT_ONLY</span> arguments must be
              writable.&#13;
            </p>
          </li>
          <li>
            <p>
              <span class="STRUCTNAME">GTK_ARG_CHILD_ARG</span>
              should not be used outside of container-style object
              implementations; it is used internally by the <span
              class="STRUCTNAME">GtkContainer</span> child argument
              functions.&#13;
            </p>
          </li>
        </ul>
        <p>
          The fourth and final argument to <tt class="FUNCTION">
          gtk_object_add_arg_type()</tt> is an argument ID to be
          used by the object subclass to identify this argument.
          This can be any integer except <span class="STRUCTNAME">
          0</span>, but it is customary to use a private
          enumeration in the object implementation's <tt class= 
          "APPLICATION">.c</tt> file. <span class="STRUCTNAME">
          GtkObject</span> has two class functions any subclass
          with arguments must implement: one to get arguments
          specific to the subclass, and one to set them. These
          functions are passed the argument ID, so they know which
          argument to get or set. Argument IDs reduce the need for
          string comparisons, increasing the efficiency of argument
          manipulation.
        </p>
        <p>
          For example, <tt class="CLASSNAME">GtkContainer</tt>
          defines these functions:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
 
static void gtk_container_get_arg(GtkObject* object,
                                  GtkArg* arg,
                                  guint arg_id);
static void gtk_container_set_arg(GtkObject* object,
                                  GtkArg* arg,
                                  guint arg_id);&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          It uses this enumeration to create its argument IDs:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;enum {
  ARG_0,              /* Skip 0, an invalid argument ID */
  ARG_BORDER_WIDTH,
  ARG_RESIZE_MODE,
  ARG_CHILD
};&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          It registers its arguments in <tt class="FUNCTION">
          gtk_container_class_init()</tt> as follows:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;  gtk_object_add_arg_type("GtkContainer::border_width",
                          GTK_TYPE_ULONG, 
                          GTK_ARG_READWRITE, 
                          ARG_BORDER_WIDTH);
  gtk_object_add_arg_type("GtkContainer::resize_mode", 
                          GTK_TYPE_RESIZE_MODE, 
                          GTK_ARG_READWRITE, 
                          ARG_RESIZE_MODE);
  gtk_object_add_arg_type("GtkContainer::child", 
                          GTK_TYPE_WIDGET, 
                          GTK_ARG_WRITABLE, 
                          ARG_CHILD);&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          <tt class="FUNCTION">gtk_container_set_arg()</tt> and <tt
          class="FUNCTION">gtk_container_get_arg()</tt> are
          installed in the class struct:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;  object_class-&gt;get_arg = gtk_container_get_arg;
  object_class-&gt;set_arg = gtk_container_set_arg;&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          <tt class="FUNCTION">gtk_container_set_arg()</tt> and <tt
          class="FUNCTION">gtk_container_get_arg()</tt> are then
          implemented like this:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;static void
gtk_container_set_arg (GtkObject    *object,
                       GtkArg       *arg,
                       guint         arg_id)
{
  GtkContainer *container;

  container = GTK_CONTAINER (object);

  switch (arg_id)
    {
    case ARG_BORDER_WIDTH:
      gtk_container_set_border_width (container, GTK_VALUE_ULONG (*arg));
      break;
    case ARG_RESIZE_MODE:
      gtk_container_set_resize_mode (container, GTK_VALUE_ENUM (*arg));
      break;
    case ARG_CHILD:
      gtk_container_add (container, GTK_WIDGET (GTK_VALUE_OBJECT (*arg)));
      break;
    default:
      break;
    }
}

static void
gtk_container_get_arg (GtkObject    *object,
                       GtkArg       *arg,
                       guint         arg_id)
{
  GtkContainer *container;

  container = GTK_CONTAINER (object);
  
  switch (arg_id)
    {
    case ARG_BORDER_WIDTH:
      GTK_VALUE_ULONG (*arg) = container-&gt;border_width;
      break;
    case ARG_RESIZE_MODE:
      GTK_VALUE_ENUM (*arg) = container-&gt;resize_mode;
      break;
    default:
      arg-&gt;type = GTK_TYPE_INVALID;
      break;
    }
}    &#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          Notice that the type must be set to <span class= 
          "STRUCTNAME">GTK_TYPE_INVALID</span> if your subclass
          doesn't understand the argument ID. This is used as an
          error indicator; users who call <tt class="FUNCTION">
          gtk_object_getv()</tt> will check for it.
        </p>
        <p>
          If you flip back to page XXXX and have another look at
          the <tt class="CLASSNAME">GtkButton</tt> class
          initialization function, you should now understand what
          is going on with respect to object arguments.
        </p>
      </div>
      <div class="SECT2">
        <h2 class="SECT2">
          <a name="Z108">Discovering the Available Object
          Arguments</a>
        </h2>
        <p>
          You can easily find out at runtime what arguments a given
          <span class="STRUCTNAME">GtkObject</span> understands,
          using the <tt class="FUNCTION">
          gtk_object_query_args()</tt>. Here is a nifty piece of
          code which prints out the arguments for the entire class
          hierarchy of a given <span class="STRUCTNAME">
          GtkObject</span>:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;void
print_arguments(GtkObject* object)
{
  GtkType type;

  type = GTK_OBJECT_TYPE(object);

  do {
    GtkArg* args;
    guint32* flags;
    guint n_args;
    guint i;

    args = gtk_object_query_args(type,
                                 &amp;flags, 
                                 &amp;n_args);
  
    printf("Displaying arguments for object type `%s'\n",
           gtk_type_name(type));

    i = 0;
    while (i &lt; n_args)
      {
        printf(" - Argument %u is called `%s' and has type `%s'\n",
               i, 
               args[i].name, 
               gtk_type_name(args[i].type));
      
        ++i;
      }

    g_free(args);
    g_free(flags);

    type = gtk_type_parent(type);
  } 
  while (type != GTK_TYPE_INVALID);
}&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          Notice that a type's parent type can be obtained using
          the <tt class="FUNCTION">gtk_type_parent()</tt> function,
          and that you can extract the <span class="STRUCTNAME">
          GtkType</span> tag from a <span class="STRUCTNAME">
          GtkObject</span> using the <tt class="FUNCTION">
          GTK_OBJECT_TYPE()</tt> macro. <tt class="FUNCTION">
          GTK_OBJECT_TYPE()</tt> is defined as follows:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;#define GTK_OBJECT_TYPE(obj) (GTK_OBJECT (obj)-&gt;klass-&gt;type)&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          An object's type is stored in its class structure, and a
          pointer to an object's class structure is stored in each
          instance of the object. (The class structure pointer is
          called <span class="STRUCTNAME">klass</span> rather than
          <span class="STRUCTNAME">class</span> to avoid confusing
          C++ compilers.)
        </p>
        <p>
          <a href="hc-objectargs.html#FL-OBJARGS">Figure 3</a>
          summarizes the functions for reading, writing, and
          querying object arguments.
        </p>
        <div class="FIGURE">
          <a name="FL-OBJARGS"></a>
          <div class="FUNCSYNOPSIS">
            <a name="FL-OBJARGS.SYNOPSIS"></a>
            <table border="0" bgcolor="#E0E0E0" width="100%">
              <tr>
                <td>
<pre class="FUNCSYNOPSISINFO">
#include &lt;gtk/gtkobject.h&gt;
</pre>
                </td>
              </tr>
            </table>
            <p>
              <code><code class="FUNCDEF">void <tt class=
              "FUNCTION">gtk_object_getv</tt></code>(GtkObject* <tt
              class="PARAMETER"><i>object</i></tt>, guint <tt
              class="PARAMETER"><i>n_args</i></tt>, GtkArg* <tt
              class="PARAMETER"><i>args</i></tt>);</code>
            </p>
            <p>
              <code><code class="FUNCDEF">void <tt class=
              "FUNCTION">gtk_object_set</tt></code>(GtkObject* <tt
              class="PARAMETER"><i>object</i></tt>, const gchar*
              <tt class="PARAMETER"><i>first_arg_name</i></tt>, <tt
              class="PARAMETER"><i>...</i></tt>);</code>
            </p>
            <p>
              <code><code class="FUNCDEF">void <tt class=
              "FUNCTION">gtk_object_setv</tt></code>(GtkObjec* <tt
              class="PARAMETER"><i>object</i></tt>, guint <tt
              class="PARAMETER"><i>n_args</i></tt>, GtkArg* <tt
              class="PARAMETER"><i>args</i></tt>);</code>
            </p>
            <p>
              <code><code class="FUNCDEF">void <tt class=
              "FUNCTION">gtk_object_add_arg_type</tt></code>(const
              gchar* <tt class="PARAMETER"><i>arg_name</i></tt>,
              GtkType <tt class="PARAMETER"><i>arg_type</i></tt>,
              guint <tt class="PARAMETER"><i>arg_flags</i></tt>,
              guint <tt class="PARAMETER"><i>
              arg_id</i></tt>);</code>
            </p>
            <p>
              <code><code class="FUNCDEF">GtkArg* <tt class= 
              "FUNCTION">gtk_object_query_args</tt></code>(GtkType
              <tt class="PARAMETER"><i>class_type</i></tt>,
              guint32** <tt class="PARAMETER"><i>
              arg_flags</i></tt>, guint* <tt class="PARAMETER"><i>
              n_args</i></tt>);</code>
            </p>
          </div>
          <p>
            <b>Figure 3. Manipulating Object Arguments</b>
          </p>
        </div>
      </div>
    </div>
    <div class="NAVFOOTER">
      <br>
      <br>
      <table width="100%" border="0" bgcolor="#ffffff" cellpadding= 
      "1" cellspacing="0">
        <tr>
          <td width="25%" bgcolor="#ffffff" align="left">
            <a href="sec-gtkarg.html"><font color="#0000ff" size=
            "2"><b>&lt;&lt;&lt; Previous</b></font></a>
          </td>
          <td width="25%" colspan="2" bgcolor="#ffffff" align= 
          "center">
            <font color="#0000ff" size="2"><b><a href="ggad.html">
            <font color="#0000ff" size="2"><b>
            Home</b></font></a></b></font>
          </td>
          <td width="25%" bgcolor="#ffffff" align="right">
            <a href="z109.html"><font color="#0000ff" size="2"><b>
            Next &gt;&gt;&gt;</b></font></a>
          </td>
        </tr>
        <tr>
          <td colspan="2" align="left">
            <font color="#000000" size="2"><b><span class= 
            "STRUCTNAME">GtkArg</span> and the Type
            System</b></font>
          </td>
          <td colspan="2" align="right">
            <font color="#000000" size="2"><b>Signals</b></font>
          </td>
        </tr>
      </table>
    </div>
  </body>
</html>