<section id="fo-c-file">
<sectioninfo>
<title>Anatomy of a Formatting Object C source code file</title>
<subtitle>FO .c File</subtitle>
<abstract><para>Anatomy of a Formatting Object C source code file</para></abstract>
</sectioninfo>

<section id="fo-c-abbreviations">
<title>Abbreviations</title>

<para>Every formatting object has a source code file that contains the functions for initializing and finalizing the object class and object instances and for its methods.</para>

<para>This example uses the source code file for the fo:root formatting object, largely because fo:root only has one property: media-usage.</para>

<para>In the example, 'Root' and 'ROOT' are part of the formatting object name, not some feature of the GObject object system.</para>

<para>All formatting object GObjects are subclasses of the FoFo GObject class.</para>

<para>The document describes the conventions current at the time of this writing. Not only may the convention change in the future, some of the older source code files may not yet have been updated to match the current conventions.</para>

</section>
<section id="fo-c-initial-comment">
<title>Initial comment</title>

<para>See the description in FoHFile.</para>

<programlisting>/* Fo
 * fo-root.c: 'root' formatting object
 *
 * Copyright (C) 2001 Sun Microsystems
 *
 * $Id: fo-c-file.xml,v 1.3 2006/03/14 19:41:40 tonygraham Exp $
 *
 * See Copying for the status of this software.
 */</programlisting>

</section>

<section id="fo-c-includes">
<title>#includes</title>

<programlisting>#include "fo-root-private.h"</programlisting>

<para>The private header file for the formatting object GObject. See FoPrivateHFile.</para>

<programlisting>#include "fo-layout-master-set.h"
#include "fo-declarations.h"
#include "fo-page-sequence.h"</programlisting>

<para>Public header files for child formatting objects. Usually only needed for validating the content of instances of the current formatting object type. Some formatting objects do not include public header files of other formatting objects.</para>

<programlisting>#include "fo-property-media-usage.h"</programlisting>

<para>Public header file for every property of the formatting object type.</para>

</section>

<section id="fo-c-property-enumeration">
<title>Property enumeration</title>

<programlisting>enum {
  PROP_0,
  PROP_MEDIA_USAGE
};</programlisting>

<para>Enumeration of the formatting object properties. Used when registering and accessing the properties as GObject properties.</para>

</section>

<section id="fo-c-static-function-prototypes">
<title>Static function prototypes</title>

<programlisting>static void fo_root_class_init  (FoRootClass *klass);</programlisting>

<para>Function called when the GObject class is initialized.</para>

<programlisting>static void fo_root_get_property (GObject      *object,
                                  guint         prop_id,
                                  GValue       *value,
                                  GParamSpec   *pspec);
static void fo_root_set_property (GObject      *object,
                                  guint         prop_id,
                                  const GValue *value,
                                  GParamSpec   *pspec);</programlisting>

<para>Functions to get and set the GObject properties of the formatting object.</para>

<programlisting>static void fo_root_finalize    (GObject           *object);</programlisting>

<para>Function called when an instance of the GObject type is finalized, i.e., when it's killed.</para>

<programlisting>static gboolean fo_root_validate_content (FoFo    *fo,
                                          GError **error);</programlisting>

<para>Function for checking the content of the formatting object w.r.t. what's allowed by the XSL Recommendation.</para>

<programlisting>static void fo_root_validate (FoFo      *fo,
                              FoContext *current_context,
                              FoContext *parent_context,
                              GError   **error);</programlisting>

<para>Function for checking the internal consistency of the formatting object's properties and, in some cases, modifying the values of interdependent properties.</para>

<programlisting>static void fo_root_update_from_context (FoFo      *fo,
                                         FoContext *context);</programlisting>

<para>Function for updating the formatting object instance's properties from an FoContext.</para>

<programlisting>static void fo_root_debug_dump_properties (FoFo *fo,
                                           gint  depth);</programlisting>

<para>Used, fairly obviously, when debugging.</para>

<programlisting>static gpointer parent_class;</programlisting>

<para>GObject convention is to maintain a pointer to the parent
GObject class.</para>

</section>
<section id="fo-c-get-type">
<title>GObject _get_type() function</title>

<para>GObject conventions require a _get_type() function that registers the object type and returns its assigned GType value.</para>

<para>Registering a GObject type requires passing a filled-in GTypeInfo structure and the type of the parent class to a registration function. xmlroff uses g_type_register_static(), but there are others.</para>

<programlisting>/**
 * fo_root_get_type:
 * @void:
 *
 * Register the FoRoot object type.
 *
 * Return value: GType value of the FoRoot object type.
 **/
GType
fo_root_get_type (void)
{
  static GType object_type = 0;

  if (!object_type)
    {
      static const GTypeInfo object_info =
      {
        sizeof (FoRootClass),
        (GBaseInitFunc) NULL,
        (GBaseFinalizeFunc) NULL,
        (GClassInitFunc) fo_root_class_init,
        NULL,           /* class_finalize /
        NULL,           / class_data /
        sizeof (FoRoot),
        0,              / n_preallocs /
        NULL,           / instance_init /
        NULL            / value_table */
      };

      object_type = g_type_register_static (FO_TYPE_FO,
                                            "root",
                                            &amp;object_info, 0);
    }

  return object_type;
}</programlisting>

</section>
<section id="fo-c-gobject-init">
<title>GObject class initializer</title>

<para>GObject convention requires this function.</para>

<para>The _class_init() function sets the class methods and variables and installs the GObject properties of the class. Every formatting object property is installed as a corresponding read-only GObject property.</para>

<programlisting>/**
 * fo_root_class_init:
 * @klass: #FoRootClass object to initialise
 *
 * Implements #GClassInitFunc for #FoRootClass
 **/
void
fo_root_class_init (FoRootClass *klass)
{
  GObjectClass *object_class = G_OBJECT_CLASS (klass);
  FoFoClass *fofo_class = FO_FO_CLASS (klass);

  parent_class = g_type_class_peek_parent (klass);</programlisting>

<para>GObject convention does this. parent_class is used when finalizing this class.</para>

<programlisting>object_class->finalize = fo_root_finalize;</programlisting>

<para>Every GObject does this.</para>

<programlisting>  object_class->get_property = fo_root_get_property;
  object_class->set_property = fo_root_set_property;</programlisting>

<para>Functions of this property that are called when g_object_get_property() and g_object_set_property() access a property of instances of this class.</para>

<programlisting>  fofo_class->validate_content = fo_root_validate_content;
  fofo_class->validate2 = fo_root_validate;
  fofo_class->update_from_context = fo_root_update_from_context;
  fofo_class->debug_dump_properties = fo_root_debug_dump_properties;</programlisting>

<para>These are the FoFo-specific class methods that are overridden by subclasses of FoFo.</para>

<programlisting>  g_object_class_install_property
    (object_class,
     PROP_MEDIA_USAGE,
     g_param_spec_object ("media-usage",
                          _("Media Usage"),
                          _("Media Usage property"),
                          FO_TYPE_PROPERTY,
                          G_PARAM_READABLE));</programlisting>

<para>The famous declaration of the formatting object property as a GObject property.</para>

<para>The enumerated value PROP_MEDIA_USAGE was defined at the head of this file.</para>

<programlisting>}

GObject class finalizer</programlisting>

<para>GObject convention requires this.</para>

<para>Clean up after the last instance of the class is destroyed.</para>

<programlisting>/**
 * fo_root_finalize:
 * @object: #FoRoot object to finalize
 *
 * Implements #GObjectFinalizeFunc for #FoRoot
 **/
void
fo_root_finalize (GObject *object)
{
  FoRoot *fo_root;

  fo_root = FO_ROOT (object);

  G_OBJECT_CLASS (parent_class)->finalize (object);
}</programlisting>

<para>GObject _get_property() and _set_property()</para>

<para>GObject convention requires these.</para>

<para>This is the second place where the property enumeration is used.</para>

<programlisting>/**
 * fo_root_get_property:
 * @object:  #GObject whose property will be retreived
 * @prop_id: Property ID assigned when property registered
 * @value:   GValue to set with property value
 * @pspec:   Parameter specification for this property type
 *
 * Implements #GObjectGetPropertyFunc for #FoRoot
 **/
void
fo_root_get_property (GObject    *object,
                      guint       prop_id,
                      GValue     *value,
                      GParamSpec *pspec)
{
  FoFo *fo_fo;

  fo_fo = FO_FO (object);

  switch (prop_id)
    {
    case PROP_MEDIA_USAGE:
      g_value_set_object (value, G_OBJECT (fo_root_get_media_usage (fo_fo)));
      break;
    default:
      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
      break;
    }
}

/**
 * fo_root_set_property:
 * @object:  #GObject whose property will be set
 * @prop_id: Property ID assigned when property registered
 * @value:   New value for property
 * @pspec:   Parameter specification for this property type
 *
 * Implements #GObjectSetPropertyFunc for #FoRoot
 **/
void
fo_root_set_property (GObject      *object,
                      guint         prop_id,
                      const GValue *value,
                      GParamSpec   *pspec)
{
  FoFo *fo_fo;

  fo_fo = FO_FO (object);

  switch (prop_id)
    {
    case PROP_MEDIA_USAGE:
      fo_root_set_media_usage (fo_fo, g_value_get_object (value));
      break;
    default:
      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
      break;
    }
}</programlisting>

</section>
<section id="fo-c-gobject-new">
<title>GObject _new()</title>

<para>GObject convention requires this.</para>

<para>Creates a new object of the specified type.</para>

<programlisting>/**
 * fo_root_new:
 *
 * Creates a new #FoRoot initialized to default value.
 *
 * Return value: the new #FoRoot
 **/
FoFo*
fo_root_new (void)
{
  return FO_FO (g_object_new (fo_root_get_type (), NULL));
}</programlisting>

</section>
<section id="fo-c-validate-content">
<title>FoFo _validate_content()</title>

<para>This is xmlroff-specific. It is not autogenerated.</para>

<para>Validate the content -- the child FoFo nodes in the FO tree -- of the current FO against the content model defined in the XSL Recommendation (plus any extra conditions in the text of the Recommendation).</para>

<para>Some formatting object do not have this function: some of the common content model, such as for empty elements, are handled by common _validate_content() functions in fo-fo.c.</para>

<programlisting>/**
 * fo_root_validate_content:
 * @fo:    FoRoot object to validate
 * @error: GError indicating error condition, if any
 *
 * Validate the content model, i.e., the structure, of the object.
 * Return value matches GNodeTraverseFunc model: FALSE indicates
 * content model is correct, or TRUE indicates an error.  When used
 * with fo_node_traverse(), returning TRUE stops the traversal.
 *
 * Return value: FALSE if content model okay, TRUE if not
 **/
gboolean
fo_root_validate_content (FoFo    *fo,
                          GError **error)
{
  FoNode *child_node;
  GError *tmp_error;

  g_return_val_if_fail (fo != NULL, TRUE);
  g_return_val_if_fail (FO_IS_ROOT (fo), TRUE);
  g_return_val_if_fail (error == NULL || *error == NULL, TRUE);

  fo_fo_trim_whitespace_children (fo);

  child_node = fo_node_first_child (FO_NODE (fo));

  if (!FO_IS_LAYOUT_MASTER_SET (child_node))
    goto error;

  while (child_node)
    {
      FoNode *next_child = fo_node_next_sibling (child_node);

      if (FO_IS_LAYOUT_MASTER_SET (child_node))
        {
          if (FO_IS_DECLARATIONS (next_child) ||
              FO_IS_PAGE_SEQUENCE (next_child))
            {
              child_node = next_child;
            }
          else
            {
              goto error;
            }
        }
      else if (FO_IS_DECLARATIONS (child_node))
        {
          if (FO_IS_PAGE_SEQUENCE (next_child))
            {
              child_node = next_child;
            }
          else
            {
              goto error;
            }
        }
      else if (FO_IS_PAGE_SEQUENCE (child_node))
        {
          if (!next_child ||
              FO_IS_PAGE_SEQUENCE (next_child))
            {
              child_node = next_child;
            }
          else
            {
              goto error;
            }
        }
      else
        {
          goto error;
        }
    }

  return FALSE;

 error:
  tmp_error = g_error_new (FO_FO_ERROR,
                           FO_FO_ERROR_INVALID_CONTENT,
                           _(fo_fo_error_messages[FO_FO_ERROR_INVALID_CONTENT]),
                           fo_object_sprintf (fo));

  return fo_object_log_or_propagate_error (FO_OBJECT (fo),
                                           error,
                                           tmp_error);
}</programlisting>

</section>
<section id="fo-c-validate">
<title>FoFo _validate()</title>

<para>This is xmlroff-specific. It is autogenerated, but is commonly then modified by hand.</para>

<para>Resolve interrelated property values, if any; merge the current context -- i.e., the property values declared for this formatting object instance -- with the parent context -- i.e., the inherited and default property values; set the property values used by the current formatting object instance.</para>

<programlisting>/**
 * fo_root_validate:
 * @fo:              FoRoot object to validate
 * @current_context: FoContext associated with current object
 * @parent_context:  FoContext associated with parent FO
 * @error:           Information about any error that has occurred
 *
 * Validate and possibly update interrelated property values in
 * @current_context, then update @fo property values.  Set @error if
 * an error occurred.
 **/
void
fo_root_validate (FoFo      *fo,
                  FoContext *current_context,
                  FoContext *parent_context,
                  GError   **error)
{
  FoRoot *fo_root;

  g_return_if_fail (fo != NULL);
  g_return_if_fail (FO_IS_ROOT (fo));
  g_return_if_fail (FO_IS_CONTEXT (current_context));
  g_return_if_fail (FO_IS_CONTEXT (parent_context));
  g_return_if_fail (error == NULL || *error == NULL);

  fo_root = FO_ROOT (fo);

  fo_context_merge (current_context, parent_context);
  fo_fo_update_from_context (fo, current_context);
}</programlisting>

</section>
<section id="fo-c-update-from-context">
<title>FoFo _update_from_context()</title>

<para>This is xmlroff-specific.</para>

<para>Set the property values used by the current formatting object instance.</para>

<programlisting>/**
 * fo_root_update_from_context:
 * @fo:      The #FoFo object
 * @context: The #FoContext object from which to update the properties of @fo
 *
 * Sets the properties of @fo to the corresponding property values in @context
 **/
void
fo_root_update_from_context (FoFo *fo,
                             FoContext *context)
{
  g_return_if_fail (fo != NULL);
  g_return_if_fail (FO_IS_ROOT (fo));
  g_return_if_fail (context != NULL);
  g_return_if_fail (FO_IS_CONTEXT (context));

  fo_root_set_media_usage (fo,
                          fo_context_get_media_usage (context));
}</programlisting>

</section>
<section id="fo-c-debug-dump-properties">
<title>FoFo _debug_dump_properties()</title>

<para>This is xmlroff-specific.</para>

<para>Dump the value of each of the properties of the formatting object instance.</para>

<para>Common code in fo-fo.c handles the rest of dumping the particulars of the formatting object instance.</para>

<programlisting>/**
 * fo_root_debug_dump_properties:
 * @fo: The #FoFo object
 * @depth: Indent level to add to the output
 *
 * Calls #fo_object_debug_dump on each property of @fo then calls
 * debug_dump_properties method of parent class
 **/
void
fo_root_debug_dump_properties (FoFo *fo, gint depth)
{
  FoRoot *fo_root;

  g_return_if_fail (fo != NULL);
  g_return_if_fail (FO_IS_ROOT (fo));

  fo_root = FO_ROOT (fo);

  fo_object_debug_dump (fo_root->media_usage, depth);

  FO_FO_CLASS (parent_class)->debug_dump_properties (fo, depth + 1);
}</programlisting>

</section>
<section id="fo-c-gobject-get-set">
<title>GObject _get() and _set() for properties</title>

<para>These are not strictly required by GObject convention, since all
GObject properties are supposed to be accessible by
g_object_get_property() and/or g_object_set_property().</para>

<programlisting>/**
 * fo_root_get_media_usage:
 * @fo_fo: The @FoFo object
 *
 * Gets the "media-usage" property of @fo_fo
 *
 * Return value: The "media-usage" property value
**/
?FoProperty*
fo_root_get_media_usage (FoFo *fo_fo)
{
  FoRoot *fo_root = (FoRoot *) fo_fo;

  g_return_val_if_fail (fo_root != NULL, NULL);
  g_return_val_if_fail (FO_IS_ROOT (fo_root), NULL);

  return fo_root->media_usage;
}

/**
 * fo_root_set_media_usage:
 * @fo_fo: The #FoFo object
 * @new_media_usage: The new "media-usage" property value
 *
 * Sets the "media-usage" property of @fo_fo to @new_media_usage
 **/
void
fo_root_set_media_usage (FoFo *fo_fo,
                         ?FoProperty *new_media_usage)
{
  FoRoot *fo_root = (FoRoot *) fo_fo;

  g_return_if_fail (fo_root != NULL);
  g_return_if_fail (FO_IS_ROOT (fo_root));
  g_return_if_fail (FO_IS_PROPERTY_MEDIA_USAGE (new_media_usage));

  if (new_media_usage != NULL)
    {
      g_object_ref (new_media_usage);
    }
  if (fo_root->media_usage != NULL)
    {
      g_object_unref (fo_root->media_usage);
    }
  fo_root->media_usage = new_media_usage;
  /*g_object_notify (G_OBJECT (fo_root), "media-usage");*/</programlisting>

<para>The g_object_notify() call is present but commented out because,
if it is needed, it will be much easier to just uncomment it than add
it to every _set() function.</para>

<programlisting>}</programlisting>
</section>
</section>