.TH VIPS_OBJECT 3 "28 March 2009"
.SH 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
.SH SYNOPSIS
#include <vips/vips.h>

/* Flags we associate with each argument.
.br
 */
.br
typedef enum _VipsArgumentFlags {
.br
  VIPS_ARGUMENT_NONE = 0,

  /* Must be set in the constructor.
.br
   */
.br
  VIPS_ARGUMENT_REQUIRED = 1,

  /* Can only be set in the constructor.
.br
   */
.br
  VIPS_ARGUMENT_CONSTRUCT = 2,

  /* Can only be set once.
.br
   */
.br
  VIPS_ARGUMENT_SET_ONCE = 4,

  /* Have input & output flags. Both set is an error; neither set 
.br
   * is OK.
.br
   */

  /* Is an input argument (one we depend on) ... if it's a gobject, we 
.br
   * should ref it. In our _dispose(), we should unref it.
.br
   */
.br
  VIPS_ARGUMENT_INPUT = 8,

  /* Is an output argument (one that depends on us) ... if it's a
.br
   * gobject, we should ref ourselves. We watch "destroy" on the
.br
   * argument: if it goes, we unref ourselves. If we dispose, we
.br
   * disconnect the signal.
.br
   */
.br
  VIPS_ARGUMENT_OUTPUT = 16
.br
} 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 
.br
   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.
.br
 */
.br
typedef struct _VipsArgument {
.br
  GParamSpec *pspec;	/* pspec for this argument */

  /* More stuff, see below */
.br
} VipsArgument;

typedef void *(*VipsArgumentMapFn)( VipsObject *, GParamSpec *,
.br
  VipsArgumentClass *, VipsArgumentInstance *, void *a, void *b );
.br
void *vips_argument_map( VipsObject *object, 
.br
  VipsArgumentMapFn fn, void *a, void *b );

struct _VipsObject {
.br
  GObject parent_object;

};

struct _VipsObjectClass {
.br
  GObjectClass parent_class;

  /* Build the object ... all argument properties have been set,
.br
   * now build the thing.
.br
   */
.br
  int (*build)( VipsObject *object );

  /* Try to print something about the class, handy for help displays.
.br
   */
.br
  void (*print_class)( struct _VipsObjectClass *, VipsBuf * );

  /* Try to print something about the object, handy for debugging.
.br
   */
.br
  void (*print)( VipsObject *, VipsBuf * );

  /* Class nickname, eg. "VipsInterpolateBicubic" has "bicubic" as a
.br
   * nickname. Not internationalised. 
.br
   */
.br
  const char *nickname;

  /* Class description. Used for help messages, so internationalised.
.br
   */
.br
  const char *description;

};

void vips_object_set_property( GObject *gobject, 
.br
  guint property_id, const GValue *value, GParamSpec *pspec );
.br
void vips_object_get_property( GObject *gobject, 
.br
  guint property_id, GValue *value, GParamSpec *pspec );

int vips_object_build( VipsObject *object );
.br
void vips_object_print_class( VipsObjectClass *klass );
.br
void vips_object_print( VipsObject *object );

void vips_object_class_install_argument( VipsObjectClass *,
.br
  GParamSpec *pspec, VipsArgumentFlags flags, guint offset );

typedef void *(*VipsObjectSetArguments)( VipsObject *, 
.br
  void *, void * );
.br
VipsObject *vips_object_new( GType type, 
.br
  VipsObjectSetArguments set, void *a, void *b );

VipsObject *vips_object_new_from_string( const char *base, 
.br
  const char *str );
.br
void vips_object_to_string( VipsObject *object, VipsBuf *buf );

.SH DESCRIPTION
.B VipsObject
is the base class for VIPS. It provides some common features, like class
nicknames, and implements an extension to 
.B GObject
for properties to let them be used more like function arguments.

.B 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
.B VipsObject:
.B VipsInterpolate
and
.B VipsFormat.
Hopefully the next version will be more fleshed out.

.B VipsObject
adds two properties: 
.B nickname
and
.B description.
They are actually class properties, but are available as instance properties
too for convenience.

.B nickname
is the non-internationalised nickname of the class and is used to simplify
lookup. For example, the
.B VipsInterpolateBicubic
class has the nickname "bicubic".

.B description
is the internationalised short description of the class.
For example, the
.B VipsInterpolateBicubic
class might have the description "bicubic interpolation (Catmull-Rom)".

Like the rest of VIPS, 
.B 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 
.B 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
.B 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
.B g_object_new(3)
you can continue to set arguments. After you have set all the ones you want to
set, call 
.B vips_object_build(3)
to check that required arguments have been set, no arguments have been set
many times, and so on.

Once a 
.B VipsObject
has been built, you can no longer set arguments, but you can read them.

Use
.B 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. 

.B vips_object_set_property(3)
and
.B vips_object_get_property(3)
are used in subclasses of
.B VipsObject
to get and set object arguments. You don't need to implement your own get/set
methods.

.B vips_object_new(3)
is a convenience function which encapsulates the new/set/build sequence 
outlined above.

.B 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.

.B vips_object_to_string(3)
is the exact inverse: it prints the string that would construct an object.

.SH RETURN VALUE
Unless otherwise noted, functions return 0 success and -1 on error.
.SH SEE ALSO
VipsFormat(3), VipsInterpolate(3),
vips_type_find(3).
.SH AUTHOR
John Cupitt