Man Linux: Main Page and Category List

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)