<!-- manual page source format generated by PolyglotMan v3.2, --> <!-- available at http://polyglotman.sourceforge.net/ --> <html> <head> <title>VIPS_OBJECT(3) manual page</title> </head> <body bgcolor='white'> <a href='#toc'>Table of Contents</a><p> <h2><a name='sect0' href='#toc0'>Name</a></h2> 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 <h2><a name='sect1' href='#toc1'>Synopsis</a></h2> #include <vips/vips.h> <p> /* Flags we associate with each argument. <br> */<br> <br> typedef enum _VipsArgumentFlags { <br> VIPS_ARGUMENT_NONE = 0,<br> <p> /* Must be set in the constructor.<br> <br> */<br> <br> VIPS_ARGUMENT_REQUIRED = 1,<br> <p> /* Can only be set in the constructor.<br> <br> */<br> <br> VIPS_ARGUMENT_CONSTRUCT = 2,<br> <p> /* Can only be set once.<br> <br> */<br> <br> VIPS_ARGUMENT_SET_ONCE = 4,<br> <p> /* Have input & output flags. Both set is an error; neither set <br> <br> * is OK.<br> <br> */<br> <p> /* Is an input argument (one we depend on) ... if it’s a gobject, we <br> <br> * should ref it. In our _dispose(), we should unref it.<br> <br> */<br> <br> VIPS_ARGUMENT_INPUT = 8,<br> <p> /* Is an output argument (one that depends on us) ... if it’s a<br> <br> * gobject, we should ref ourselves. We watch "destroy" on the<br> <br> * argument: if it goes, we unref ourselves. If we dispose, we<br> <br> * disconnect the signal.<br> <br> */<br> <br> VIPS_ARGUMENT_OUTPUT = 16<br> <br> } VipsArgumentFlags; <p> /* Useful flag combinations. User-visible ones are: <p> VIPS_ARGUMENT_REQURED_INPUT <tt> </tt> <tt> </tt> Eg. the "left" argument for add <p> VIPS_ARGUMENT_OPTIONAL_INPUT <tt> </tt> <tt> </tt> Eg. the "caption" for an object <p> VIPS_ARGUMENT_REQURED_OUTPUT <tt> </tt> <tt> </tt> Eg. the "result" <p>of an add operation <p> VIPS_ARGUMENT_OPTIONAL_OUTPUT <tt> </tt> <tt> </tt> Eg. the "width" of an <p>image <p> Other combinations are used internally, eg. supplying the cast-table <br> <br> for an arithmetic operation<br> <p> */<br> <p> #define VIPS_ARGUMENT_REQUIRED_INPUT eg. supplying the cast-table <br> (VIPS_ARGUMENT_INPUT | VIPS_ARGUMENT_REQUIRED | <br> <br> VIPS_ARGUMENT_CONSTRUCT | VIPS_ARGUMENT_SET_ONCE)<br> <p> #define VIPS_ARGUMENT_OPTIONAL_INPUT <br> (VIPS_ARGUMENT_INPUT | <br> <br> VIPS_ARGUMENT_CONSTRUCT | VIPS_ARGUMENT_SET_ONCE)<br> <p> #define VIPS_ARGUMENT_REQUIRED_OUTPUT <br> (VIPS_ARGUMENT_OUTPUT | VIPS_ARGUMENT_REQUIRED | <br> <br> VIPS_ARGUMENT_SET_ONCE)<br> <p> #define VIPS_ARGUMENT_OPTIONAL_OUTPUT <br> (VIPS_ARGUMENT_OUTPUT | <br> <br> VIPS_ARGUMENT_SET_ONCE)<br> <p> /* Keep one of these for every argument. <br> */<br> <br> typedef struct _VipsArgument { <br> GParamSpec *pspec;<tt> </tt> <tt> </tt> /* pspec for this argument */<br> <p> /* More stuff, see below */<br> <br> } VipsArgument; <p> typedef void *(*VipsArgumentMapFn)( VipsObject *, GParamSpec *, <br> VipsArgumentClass *, VipsArgumentInstance *, void *a, void *b );<br> <br> void *vips_argument_map( VipsObject *object, <br> VipsArgumentMapFn fn, void *a, void *b );<br> <p> struct _VipsObject { <br> GObject parent_object;<br> <p> }; <p> struct _VipsObjectClass { <br> GObjectClass parent_class;<br> <p> /* Build the object ... all argument properties have been set,<br> <br> * now build the thing.<br> <br> */<br> <br> int (*build)( VipsObject *object );<br> <p> /* Try to print something about the class, handy for help displays.<br> <br> */<br> <br> void (*print_class)( struct _VipsObjectClass *, VipsBuf * );<br> <p> /* Try to print something about the object, handy for debugging.<br> <br> */<br> <br> void (*print)( VipsObject *, VipsBuf * );<br> <p> /* Class nickname, eg. "VipsInterpolateBicubic" has "bicubic" as a<br> <br> * nickname. Not internationalised. <br> <br> */<br> <br> const char *nickname;<br> <p> /* Class description. Used for help messages, so internationalised.<br> <br> */<br> <br> const char *description;<br> <p> }; <p> void vips_object_set_property( GObject *gobject, <br> guint property_id, const GValue *value, GParamSpec *pspec );<br> <br> void vips_object_get_property( GObject *gobject, <br> guint property_id, GValue *value, GParamSpec *pspec );<br> <p> int vips_object_build( VipsObject *object ); <br> void vips_object_print_class( VipsObjectClass *klass ); <br> void vips_object_print( VipsObject *object ); <p> void vips_object_class_install_argument( VipsObjectClass *, <br> GParamSpec *pspec, VipsArgumentFlags flags, guint offset );<br> <p> typedef void *(*VipsObjectSetArguments)( VipsObject *, <br> void *, void * );<br> <br> VipsObject *vips_object_new( GType type, <br> VipsObjectSetArguments set, void *a, void *b );<br> <p> VipsObject *vips_object_new_from_string( const char *base, <br> const char *str );<br> <br> void vips_object_to_string( VipsObject *object, VipsBuf *buf ); <p> <h2><a name='sect2' href='#toc2'>Description</a></h2> <b>VipsObject</b> is the base class for VIPS. It provides some common features, like class nicknames, and implements an extension to <b>GObject</b> for properties to let them be used more like function arguments. <p> <b>VipsObject</b> 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> <b>VipsInterpolate</b> and <b>VipsFormat.</b> Hopefully the next version will be more fleshed out. <p> <b>VipsObject</b> adds two properties: <b>nickname</b> and <b>description.</b> They are actually class properties, but are available as instance properties too for convenience. <p> <b>nickname</b> is the non-internationalised nickname of the class and is used to simplify lookup. For example, the <b>VipsInterpolateBicubic</b> class has the nickname "bicubic". <p> <b>description</b> is the internationalised short description of the class. For example, the <b>VipsInterpolateBicubic</b> class might have the description "bicubic interpolation (Catmull-Rom)". <p> Like the rest of VIPS, <b>VipsObject</b> 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. <p> To enforce these rules, VIPS extends the standard <b>GObject</b> property system and adds a new phase to object creation. <p> In class_init, after creating a property, you make it into an argument by adding a call to <a href='vips_object_class_install_argument.3.html'><b>vips_object_class_install_argument(3)</a> . </b> 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: <p> pspec = g_param_spec_string( "description",<br> _( "Description" ),<br> _( "Class description" ),<br> "",<br> (GParamFlags) G_PARAM_READWRITE );<br> g_object_class_install_property( gobject_class,<br> PROP_DESCRIPTION, pspec );<br> vips_object_class_install_argument( object_class, pspec,<br> VIPS_ARGUMENT_SET_ONCE,<br> G_STRUCT_OFFSET( VipsObject, description ) );<br> <p> After <a href='g_object_new.3.html'><b>g_object_new(3)</b></a> you can continue to set arguments. After you have set all the ones you want to set, call <a href='vips_object_build.3.html'><b>vips_object_build(3)</b></a> to check that required arguments have been set, no arguments have been set many times, and so on. <p> Once a <b>VipsObject</b> has been built, you can no longer set arguments, but you can read them. <p> Use <a href='vips_argument_map.3.html'><b>vips_argument_map(3)</b></a> 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. <p> <a href='vips_object_set_property.3.html'><b>vips_object_set_property(3)</b></a> and <a href='vips_object_get_property.3.html'><b>vips_object_get_property(3)</b></a> are used in subclasses of <b>VipsObject</b> to get and set object arguments. You don’t need to implement your own get/set methods. <p> <a href='vips_object_new.3.html'><b>vips_object_new(3)</b></a> is a convenience function which encapsulates the new/set/build sequence outlined above. <p> <a href='vips_object_new_from_string.3.html'><b>vips_object_new_from_string(3)</b></a> 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. <p> <a href='vips_object_to_string.3.html'><b>vips_object_to_string(3)</b></a> is the exact inverse: it prints the string that would construct an object. <p> <h2><a name='sect3' href='#toc3'>Return Value</a></h2> Unless otherwise noted, functions return 0 success and -1 on error. <h2><a name='sect4' href='#toc4'>See Also</a></h2> <a href='VipsFormat.3.html'>VipsFormat(3)</a> , <a href='VipsInterpolate.3.html'>VipsInterpolate(3)</a> , <a href='vips_type_find.3.html'>vips_type_find(3)</a> . <h2><a name='sect5' href='#toc5'>Author</a></h2> John Cupitt <p> <hr><p> <a name='toc'><b>Table of Contents</b></a><p> <ul> <li><a name='toc0' href='#sect0'>Name</a></li> <li><a name='toc1' href='#sect1'>Synopsis</a></li> <li><a name='toc2' href='#sect2'>Description</a></li> <li><a name='toc3' href='#sect3'>Return Value</a></li> <li><a name='toc4' href='#sect4'>See Also</a></li> <li><a name='toc5' href='#sect5'>Author</a></li> </ul> </body> </html>