|
|
|
xmlroff Reference Manual | |
|---|
The public header files for Formatting Objects are autogenerated and, therefore, have a consistent structure. The header files for the few that are not autogenerated also follow this structure.
This example uses the header for the fo:root formatting object, largely because fo:root only has one property: media-usage.
In the example, 'Root' and 'ROOT' are part of the formatting object name, not some feature of the GObject object system.
All formatting object GObjects are subclasses of the FoFo GObject class.
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.
/* Fo * fo-root.h: Root formatting object * * Copyright (C) 2001 Sun Microsystems * * $Id: fo-h-file.xml,v 1.1 2006/03/14 19:42:57 tonygraham Exp $ * * See Copying for the status of this software. */
Identifies the formatting object and states the copyright owner.
#ifndef FO_ROOT_H #define FO_ROOT_H
#ifndef and #define so the header file is not included multiple times.
#include <fo-utils.h> #include <fo-property.h>
#includes for other header files.
G_BEGIN_DECLS
GLib macro that, for a C++ compiler, expands into something useful for C++.
Every GObject has these.
typedef struct _FoRoot FoRoot; typedef struct _FoRootClass FoRootClass;
Typedefs for the object instance and object class.
The _FoRoot and _FoRootClass structures are defined in fo-root-private.h.
The effect is that the internals of the FoRoot and FoRootClass are not publicly visible.
Every GObject has these.
#define FO_TYPE_ROOT (fo_root_get_type ())
Shorthand for the function that returns the object's GType. The GType identifies the object type.
#define FO_ROOT(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), FO_TYPE_ROOT, FoRoot))
Macro for casting an object to the required type with a bit of checking that the object can be cast to the required type.
Will generate a warning message if the cast is not allowed.
#define FO_ROOT_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), FO_TYPE_ROOT, FoRootClass))
Macro for getting the named class structure. 'klass' is the class structure itself or the class structure of a subclass of the class. The macros use 'klass' instead of 'class' because 'class' is a C++ keyword.
#define FO_IS_ROOT(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), FO_TYPE_ROOT))
Macro for determining if 'object' is an instance of the specified class.
This macro type is frequently used in assertions.
#define FO_IS_ROOT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), FO_TYPE_ROOT))
Macro for determining if 'klass' is a class structure of the specified type.
#define FO_ROOT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), FO_TYPE_ROOT, FoRootClass))
Macro for getting the class structure for an instance of the specified type.
Will generate a warning message if the instance is not of the specified class or of a subclass of the specified class.
GType fo_root_get_type (void) G_GNUC_CONST;
Gets the GType for the object type.
FoFo *fo_root_new (void);
Gets a new instance of the object type.
All _new() functions for formatting objects return objects cast to FoFo. Since the functions that manipulate formatting object objects operate on FoFo objects, this avoids having to cast the specific object type to FoFo on every one of those function calls.
A formatting object may have hand-generated functions that do not just get and set property values. fo:root, however, does not have any.
By a happy coincidence, the XSL properties of a formatting object are expressed as GObject properties of the GObject for the formatting object.
Every property of every formatting object has _get() and _set() functions:
FoProperty * fo_root_get_media_usage (FoFo *fo_fo);
void fo_root_set_media_usage (FoFo *fo_fo,
FoProperty *new_media_usage);
The properties are registered with the GObject system as G_PARAM_READABLE, so property values can also be accessed using g_object_get_property().
The property values are not writeable, so they cannot be set using g_object_set_property().