gimbal_property.h File Reference

Go to the source code of this file.

Data Structures
struct	GblPropertyClass
struct	GblProperty

Macros
#define	GBL_GENERIC_PROPERTY_TYPE
Type System
UUID and Cast Operators
#define	GBL_PROPERTY_TYPE
#define	GBL_PROPERTY(self)
#define	GBL_PROPERTY_CLASS(klass)
#define	GBL_PROPERTY_GET_CLASS(self)
Helper DSL
Helper macros for declaration and registration
#define	GBL_PROPERTIES(object, ...)
#define	GBL_PROPERTIES_REGISTER(...)

Typedefs
typedef GblBool(*	GblPropertyIterFn) (const GblProperty *pProp, void *pClosure)
typedef GblEnum	GBL_PROPERTY_FLAG

Enumerations
enum	GBL_PROPERTY_FLAG

Functions
GblType	GblProperty_type (void)
Management
Routines for installing and uninstalling properties.
GBL_RESULT	GblProperty_install (GblType objType, GblProperty *pProp)
GblBool	GblProperty_uninstall (GblType objType, const char *pName)
GblBool	GblProperty_uninstallQuark (GblType objType, GblQuark name)
GblBool	GblProperty_uninstallAll (GblType objType)
Info
Querying for miscellaneous property info.
size_t	GblProperty_totalCount (void)
size_t	GblProperty_count (GblType objectType)
GblFlags	GblProperty_combinedFlags (GblType objectType)
Querying
Routines for looking up installed properties.
const GblProperty *	GblProperty_find (GblType objectType, const char *pName)
const GblProperty *	GblProperty_findQuark (GblType objectType, GblQuark name)
Iterating
Routines for iterating over installed properties.
const GblProperty *	GblProperty_next (GblType objectType, const GblProperty *pPrev, GblFlags mask)
GblBool	GblProperty_foreach (GblType objectType, GBL_PROPERTY_FLAG flags, GblPropertyIterFn pFnIt, void *pClosure)
Initializing
Routines for creating and constructing new properties.
GblProperty *	GblProperty_create (GblType derivedType, const char *pName, size_t id, GblFlags flags, size_t optionalArgCount,...)
GblProperty *	GblProperty_createVaList (GblType derivedType, const char *pName, size_t id, GblFlags flags, size_t optionalArgCount, va_list *pList)
GBL_RESULT	GblProperty_construct (GblProperty *pSelf, GblType derivedType, const char *pName, size_t id, GblFlags flags, size_t optionalArgCount,...)
GBL_RESULT	GblProperty_constructVaList (GblProperty *pSelf, GblType derivedType, const char *pName, size_t id, GblFlags flags, size_t optionalArgCount, va_list *pList)
GBL_RESULT	GblProperty_createOrConstruct (GblProperty **ppSelf, GblType derivedType, const char *pName, size_t id, GblFlags flags, size_t optionalArgCount,...)
Accessors
Routines for accessing internal property data.
GblType	GblProperty_objectType (const GblProperty *pSelf)
const char *	GblProperty_name (const GblProperty *pSelf)
Methods
Routines for calling class methods on properties.
GBL_RESULT	GblProperty_defaultValue (const GblProperty *pSelf, GblVariant *pValue)
GblBool	GblProperty_checkValue (const GblProperty *pSelf, const GblVariant *pValue)
GBL_RESULT	GblProperty_validateValue (const GblProperty *pSelf, GblVariant *pValue)
int	GblProperty_compareValues (const GblProperty *pSelf, const GblVariant *pV1, const GblVariant *pV2)

Detailed Description

GblProperty instance, DSL, and management API.

This file contains the type declarations and methods for GblProperty, the root property instance from which all other properties are derived.

Properties are string-keyed values of any data type which can be added to a GblObject.

Author

2023, 2025 Falco Girgis

Copyright

MIT License

Definition in file gimbal_property.h.

Macro Definition Documentation

GBL_PROPERTY_TYPE

#define GBL_PROPERTY_TYPE

Type UUID for GblProperty.

Definition at line 24 of file gimbal_property.h.

GBL_PROPERTY

#define GBL_PROPERTY

(

self

)

Casts a GblInstance to GblProperty.

Definition at line 25 of file gimbal_property.h.

GBL_PROPERTY_CLASS

#define GBL_PROPERTY_CLASS

(

klass

)

Casts a GblClass to GblPropertyClass.

Definition at line 26 of file gimbal_property.h.

GBL_PROPERTY_GET_CLASS

#define GBL_PROPERTY_GET_CLASS

(

self

)

Gets a GblPropertyClass from GblInstance.

Definition at line 27 of file gimbal_property.h.

GBL_GENERIC_PROPERTY_TYPE

#define GBL_GENERIC_PROPERTY_TYPE

Alternate type identifier for GblProperty.

Definition at line 31 of file gimbal_property.h.

GBL_PROPERTIES

#define GBL_PROPERTIES	(		object,
			... )

Declares a list of properties for the given object/instance structure.

Definition at line 38 of file gimbal_property.h.

GBL_PROPERTIES_REGISTER

#define GBL_PROPERTIES_REGISTER

(

...

)

Registers the list of properties which were declared with GBL_PROPERTIES()

Definition at line 40 of file gimbal_property.h.

Typedef Documentation

GblPropertyIterFn

typedef GblBool(* GblPropertyIterFn) (const GblProperty *pProp, void *pClosure)

Function signature used as an iterator with GblProperty_foreach(), returns GBL_FALSE when iteration should cease.

Definition at line 50 of file gimbal_property.h.

GBL_PROPERTY_FLAG

typedef GblEnum GBL_PROPERTY_FLAG

Definition at line 55 of file gimbal_property.h.

Enumeration Type Documentation

GBL_PROPERTY_FLAG

enum GBL_PROPERTY_FLAG

Flags used to denote property attributes.

Enumerator
GBL_PROPERTY_FLAG_CONSTRUCT	Property must be given to the constructor.
GBL_PROPERTY_FLAG_READ	Property value can be read.
GBL_PROPERTY_FLAG_WRITE	Property value can be modified.
GBL_PROPERTY_FLAG_IN	Property assumes ownership of data when writing.
GBL_PROPERTY_FLAG_OUT	Property releases ownership of data when reading.
GBL_PROPERTY_FLAG_SAVE	Property is serialized when saving.
GBL_PROPERTY_FLAG_LOAD	Property is deserialized when loading.
GBL_PROPERTY_FLAG_ABSTRACT	Property must be implemented by deriving type.
GBL_PROPERTY_FLAG_OVERRIDE	Property overrides an existing property.
GBL_PROPERTY_FLAG_READ_WRITE	Property is both readable and writable.
GBL_PROPERTY_FLAG_SAVE_LOAD	Property is both savable and loadable.
GBL_PROPERTY_FLAG_ALL	Mask for all property flags combined.

Definition at line 55 of file gimbal_property.h.

                                    {
    GBL_PROPERTY_FLAG_CONSTRUCT  = 0x001, //!< Property must be given to the constructor.
    GBL_PROPERTY_FLAG_READ       = 0x002, //!< Property value can be read.
    GBL_PROPERTY_FLAG_WRITE      = 0x004, //!< Property value can be modified.
    GBL_PROPERTY_FLAG_IN         = 0x008, //!< Property assumes ownership of data when writing.
    GBL_PROPERTY_FLAG_OUT        = 0x010, //!< Property releases ownership of data when reading.
    GBL_PROPERTY_FLAG_SAVE       = 0x020, //!< Property is serialized when saving.
    GBL_PROPERTY_FLAG_LOAD       = 0x040, //!< Property is deserialized when loading.
    GBL_PROPERTY_FLAG_ABSTRACT   = 0x080, //!< Property must be implemented by deriving type.
    GBL_PROPERTY_FLAG_OVERRIDE   = 0x100, //!< Property overrides an existing property.
    GBL_PROPERTY_FLAG_READ_WRITE = 0x006, //!< Property is both readable and writable.
    GBL_PROPERTY_FLAG_SAVE_LOAD  = 0x060, //!< Property is both savable and loadable.
    GBL_PROPERTY_FLAG_ALL        = 0xfff  //!< Mask for all property flags combined.
};

Function Documentation

GblProperty_type()

GblType GblProperty_type

(

void

)

Returns the UUID associated with the GblProperty type, registering it if it hasn't been already.

GblProperty_install()

GBL_RESULT GblProperty_install	(	GblType	objType,
		GblProperty *	pProp )

Installs the given property onto the given type (which must be GblObject compatible).

GblProperty_uninstall()

GblBool GblProperty_uninstall	(	GblType	objType,
		const char *	pName )

Uninstalls the property with the given name from the given object type.

GblProperty_uninstallQuark()

GblBool GblProperty_uninstallQuark	(	GblType	objType,
		GblQuark	name )

Uninstalls the property with the given name quark from the given object type.

GblProperty_uninstallAll()

GblBool GblProperty_uninstallAll

(

GblType

objType

)

Uninstalls all properties which were previously installed onto the given object type.

GblProperty_totalCount()

size_t GblProperty_totalCount

(

void

)

Returns the total number of properties which have been registered onto any GblType.

GblProperty_count()

size_t GblProperty_count

(

GblType

objectType

)

Returns the number of properties which were explicitly registered to the given type (not including inherited properties).

GblProperty_combinedFlags()

GblFlags GblProperty_combinedFlags

(

GblType

objectType

)

Returns the combined, bitwise OR'd flags from all properties registered onto the given type.

GblProperty_find()

const GblProperty * GblProperty_find	(	GblType	objectType,
		const char *	pName )

Looks up the given property by string name which was previously installed onto the given GblObject type.

GblProperty_findQuark()

const GblProperty * GblProperty_findQuark	(	GblType	objectType,
		GblQuark	name )

Looks up the given property by GblQuark name which was previously installed onto the given GblObject type.

GblProperty_next()

const GblProperty * GblProperty_next	(	GblType	objectType,
		const GblProperty *	pPrev,
		GblFlags	mask )

Returns the next property installed onto the given type, given the current property (or NULL for the first) and the flag mask for which properties to include.

GblProperty_foreach()

GblBool GblProperty_foreach	(	GblType	objectType,
		GBL_PROPERTY_FLAG	flags,
		GblPropertyIterFn	pFnIt,
		void *	pClosure )

Iterates over the properties installed onto the given type containing any of the given flags, calling the given callback, which gets passed back an optional closure. Returns false if the callback returns false to end iteration.

GblProperty_create()

GblProperty * GblProperty_create	(	GblType	derivedType,
		const char *	pName,
		size_t	id,
		GblFlags	flags,
		size_t	optionalArgCount,
			... )

Creates a new property on the heap with the given type, name, id, flags, and any optional arguments handled by its optional argument initializer.

GblProperty_createVaList()

GblProperty * GblProperty_createVaList	(	GblType	derivedType,
		const char *	pName,
		size_t	id,
		GblFlags	flags,
		size_t	optionalArgCount,
		va_list *	pList )

Equivalent to GblProperty_create(), except taking a va_list rather than variadic argument list.

GblProperty_construct()

GBL_RESULT GblProperty_construct	(	GblProperty *	pSelf,
		GblType	derivedType,
		const char *	pName,
		size_t	id,
		GblFlags	flags,
		size_t	optionalArgCount,
			... )

Constructs a preallocated property with the given type, name, id, flags, and any optional arguments handled by its optional argument initializer.

GblProperty_constructVaList()

GBL_RESULT GblProperty_constructVaList	(	GblProperty *	pSelf,
		GblType	derivedType,
		const char *	pName,
		size_t	id,
		GblFlags	flags,
		size_t	optionalArgCount,
		va_list *	pList )

Equivalent to GblProperty_construct(), except taking a va_list rather than variadic argument list.

GblProperty_createOrConstruct()

GBL_RESULT GblProperty_createOrConstruct	(	GblProperty **	ppSelf,
		GblType	derivedType,
		const char *	pName,
		size_t	id,
		GblFlags	flags,
		size_t	optionalArgCount,
			... )

Either calls GblProperty_create() or GblProperty_construct() based on whether ppSelf points to an existing property or not. If not, it will point to a newly created property, upon success, after the function returns.

GblProperty_objectType()

GblType GblProperty_objectType

(

const GblProperty *

pSelf

)

Returns the UUID of the type associated with the given property.

GblProperty_name()

const char * GblProperty_name

(

const GblProperty *

pSelf

)

Returns the string name of the given property.

GblProperty_defaultValue()

GBL_RESULT GblProperty_defaultValue	(	const GblProperty *	pSelf,
		GblVariant *	pValue )

Sets the given variant to contain the default value of the given property, calling GblPropertyClass::pFnDefaultValue().

GblProperty_checkValue()

GblBool GblProperty_checkValue	(	const GblProperty *	pSelf,
		const GblVariant *	pValue )

Checks whether the value contained by the given variant is valid for the given property, calling GblPropertyClass::pFnCeckValue().

GblProperty_validateValue()

GBL_RESULT GblProperty_validateValue	(	const GblProperty *	pSelf,
		GblVariant *	pValue )

Modifies the value contained within the given variant to be a valid value, if possible, calling GblPropertyClass::pFnValidateValue().

GblProperty_compareValues()

int GblProperty_compareValues	(	const GblProperty *	pSelf,
		const GblVariant *	pV1,
		const GblVariant *	pV2 )

Compares the values contained by the given variants, based on the rules of the given property, calling GblPropertyClass::pFnCompareValues().