NAME
VipsObject, vips_object_build, vips_object_print_class,
vips_object_print, vips_object_class_install_argument,
vips_argument_map, vips_object_set_property, vips_object_get_property,
vips_object_new, vips_object_new_from_string, vips_object_to_string -
VIPS base class
SYNOPSIS
#include <vips/vips.h>
/* Flags we associate with each argument.
*/
typedef enum _VipsArgumentFlags {
VIPS_ARGUMENT_NONE = 0,
/* Must be set in the constructor.
*/
VIPS_ARGUMENT_REQUIRED = 1,
/* Can only be set in the constructor.
*/
VIPS_ARGUMENT_CONSTRUCT = 2,
/* Can only be set once.
*/
VIPS_ARGUMENT_SET_ONCE = 4,
/* Have input & output flags. Both set is an error; neither set
* is OK.
*/
/* Is an input argument (one we depend on) ... if it’s a gobject, we
* should ref it. In our _dispose(), we should unref it.
*/
VIPS_ARGUMENT_INPUT = 8,
/* Is an output argument (one that depends on us) ... if it’s a
* gobject, we should ref ourselves. We watch "destroy" on the
* argument: if it goes, we unref ourselves. If we dispose, we
* disconnect the signal.
*/
VIPS_ARGUMENT_OUTPUT = 16
} VipsArgumentFlags;
/* Useful flag combinations. User-visible ones are:
VIPS_ARGUMENT_REQURED_INPUT Eg. the "left" argument for add
VIPS_ARGUMENT_OPTIONAL_INPUT Eg. the "caption" for an object
VIPS_ARGUMENT_REQURED_OUTPUT Eg. the "result" of an add operation
VIPS_ARGUMENT_OPTIONAL_OUTPUT Eg. the "width" of an image
Other combinations are used internally, eg. supplying the cast-table
for an arithmetic operation
*/
#define VIPS_ARGUMENT_REQUIRED_INPUT .br
(VIPS_ARGUMENT_INPUT | VIPS_ARGUMENT_REQUIRED | .br
VIPS_ARGUMENT_CONSTRUCT | VIPS_ARGUMENT_SET_ONCE)
#define VIPS_ARGUMENT_OPTIONAL_INPUT .br
(VIPS_ARGUMENT_INPUT | .br
VIPS_ARGUMENT_CONSTRUCT | VIPS_ARGUMENT_SET_ONCE)
#define VIPS_ARGUMENT_REQUIRED_OUTPUT .br
(VIPS_ARGUMENT_OUTPUT | VIPS_ARGUMENT_REQUIRED | .br
VIPS_ARGUMENT_SET_ONCE)
#define VIPS_ARGUMENT_OPTIONAL_OUTPUT .br
(VIPS_ARGUMENT_OUTPUT | .br
VIPS_ARGUMENT_SET_ONCE)
/* Keep one of these for every argument.
*/
typedef struct _VipsArgument {
GParamSpec *pspec; /* pspec for this argument */
/* More stuff, see below */
} VipsArgument;
typedef void *(*VipsArgumentMapFn)( VipsObject *, GParamSpec *,
VipsArgumentClass *, VipsArgumentInstance *, void *a, void *b );
void *vips_argument_map( VipsObject *object,
VipsArgumentMapFn fn, void *a, void *b );
struct _VipsObject {
GObject parent_object;
};
struct _VipsObjectClass {
GObjectClass parent_class;
/* Build the object ... all argument properties have been set,
* now build the thing.
*/
int (*build)( VipsObject *object );
/* Try to print something about the class, handy for help displays.
*/
void (*print_class)( struct _VipsObjectClass *, VipsBuf * );
/* Try to print something about the object, handy for debugging.
*/
void (*print)( VipsObject *, VipsBuf * );
/* Class nickname, eg. "VipsInterpolateBicubic" has "bicubic" as a
* nickname. Not internationalised.
*/
const char *nickname;
/* Class description. Used for help messages, so internationalised.
*/
const char *description;
};
void vips_object_set_property( GObject *gobject,
guint property_id, const GValue *value, GParamSpec *pspec );
void vips_object_get_property( GObject *gobject,
guint property_id, GValue *value, GParamSpec *pspec );
int vips_object_build( VipsObject *object );
void vips_object_print_class( VipsObjectClass *klass );
void vips_object_print( VipsObject *object );
void vips_object_class_install_argument( VipsObjectClass *,
GParamSpec *pspec, VipsArgumentFlags flags, guint offset );
typedef void *(*VipsObjectSetArguments)( VipsObject *,
void *, void * );
VipsObject *vips_object_new( GType type,
VipsObjectSetArguments set, void *a, void *b );
VipsObject *vips_object_new_from_string( const char *base,
const char *str );
void vips_object_to_string( VipsObject *object, VipsBuf *buf );
DESCRIPTION
VipsObject is the base class for VIPS. It provides some common
features, like class nicknames, and implements an extension to GObject
for properties to let them be used more like function arguments.
VipsObject is still being developed, so this documentation only covers
enough of the interface to let you use the classes that have been built
on top of VipsObject: VipsInterpolate and VipsFormat. Hopefully the
next version will be more fleshed out.
VipsObject adds two properties: nickname and description. They are
actually class properties, but are available as instance properties too
for convenience.
nickname is the non-internationalised nickname of the class and is used
to simplify lookup. For example, the VipsInterpolateBicubic class has
the nickname "bicubic".
description is the internationalised short description of the class.
For example, the VipsInterpolateBicubic class might have the
description "bicubic interpolation (Catmull-Rom)".
Like the rest of VIPS, VipsObject is a functional type. You can set
properties during object construction, but not after that point. You
may read properties at any time after construction, but not before.
To enforce these rules, VIPS extends the standard GObject property
system and adds a new phase to object creation.
In class_init, after creating a property, you make it into an argument
by adding a call to vips_object_class_install_argument(3). This takes
a set of flags, used to tell VIPS what sort of argument this is, and an
offset for the data value in the class instance. For example:
pspec = g_param_spec_string( "description",
_( "Description" ),
_( "Class description" ),
"",
(GParamFlags) G_PARAM_READWRITE );
g_object_class_install_property( gobject_class,
PROP_DESCRIPTION, pspec );
vips_object_class_install_argument( object_class, pspec,
VIPS_ARGUMENT_SET_ONCE,
G_STRUCT_OFFSET( VipsObject, description ) );
After g_object_new(3) you can continue to set arguments. After you have
set all the ones you want to set, call vips_object_build(3) to check
that required arguments have been set, no arguments have been set many
times, and so on.
Once a VipsObject has been built, you can no longer set arguments, but
you can read them.
Use vips_argument_map(3) to iterate over the arguments for an object in
the correct order. You can use this to discover the arguments any class
takes at runtime.
vips_object_set_property(3) and vips_object_get_property(3) are used in
subclasses of VipsObject to get and set object arguments. You don’t
need to implement your own get/set methods.
vips_object_new(3) is a convenience function which encapsulates the
new/set/build sequence outlined above.
vips_object_new_from_string(3) is a convenience function which builds
an object from a set of arguments encoded as a string. It used used by
the VIPS command-line program to generate operation arguments.
vips_object_to_string(3) is the exact inverse: it prints the string
that would construct an object.
RETURN VALUE
Unless otherwise noted, functions return 0 success and -1 on error.
SEE ALSO
VipsFormat(3), VipsInterpolate(3), vips_type_find(3).
AUTHOR
John Cupitt
28 March 2009 VIPS_OBJECT(3)