Commit fca3fb58 authored by Stefan Kost's avatar Stefan Kost

Migrating docs.

	* docs/reference/gobject/tmpl/param_value_types.sgml:
	* gobject/gboxed.c:
	* gobject/gboxed.h:
	* gobject/genums.c:
	* gobject/genums.h:
	* gobject/gobject.c:
	* gobject/gobject.h:
	* gobject/gparam.c:
	* gobject/gparam.h:
	* gobject/gparamspecs.c:
	* gobject/gparamspecs.h:
	* gobject/gvaluetypes.c:
	* gobject/gvaluetypes.h:
	  Migrating docs.


svn path=/trunk/; revision=7081
parent fedbbf5d
2008-06-22 Stefan Kost <ensonic@users.sf.net>
* docs/reference/gobject/tmpl/param_value_types.sgml:
* gobject/gboxed.c:
* gobject/gboxed.h:
* gobject/genums.c:
* gobject/genums.h:
* gobject/gobject.c:
* gobject/gobject.h:
* gobject/gparam.c:
* gobject/gparam.h:
* gobject/gparamspecs.c:
* gobject/gparamspecs.h:
* gobject/gvaluetypes.c:
* gobject/gvaluetypes.h:
Migrating docs.
2008-06-21 Stefan Kost <ensonic@users.sf.net>
* docs/reference/gobject/tmpl/objects.sgml:
......
This diff is collapsed.
......@@ -532,6 +532,14 @@ g_boxed_free (GType boxed_type,
}
}
/**
* g_value_get_boxed:
* @value: a valid #GValue of %G_TYPE_BOXED derived type
*
* Get the contents of a %G_TYPE_BOXED derived #GValue.
*
* Returns: boxed contents of @value
*/
gpointer
g_value_get_boxed (const GValue *value)
{
......@@ -541,6 +549,16 @@ g_value_get_boxed (const GValue *value)
return value->data[0].v_pointer;
}
/**
* g_value_dup_boxed:
* @value: a valid #GValue of %G_TYPE_BOXED derived type
*
* Get the contents of a %G_TYPE_BOXED derived #GValue.
* Upon getting, the boxed value is duplicated and needs to be
* later freed with g_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value), return_value);
*
* Returns: boxed contents of @value
*/
gpointer
g_value_dup_boxed (const GValue *value)
{
......@@ -593,6 +611,13 @@ value_set_boxed_internal (GValue *value,
}
}
/**
* g_value_set_boxed:
* @value: a valid #GValue of %G_TYPE_BOXED derived type
* @v_boxed: boxed value to be set
*
* Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed.
*/
void
g_value_set_boxed (GValue *value,
gconstpointer boxed)
......@@ -603,6 +628,15 @@ g_value_set_boxed (GValue *value,
value_set_boxed_internal (value, boxed, TRUE, TRUE);
}
/**
* g_value_set_static_boxed:
* @value: a valid #GValue of %G_TYPE_BOXED derived type
* @v_boxed: static boxed value to be set
*
* Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed.
* The boxed value is assumed to be static, and is thus not duplicated
* when setting the #GValue.
*/
void
g_value_set_static_boxed (GValue *value,
gconstpointer boxed)
......@@ -613,6 +647,15 @@ g_value_set_static_boxed (GValue *value,
value_set_boxed_internal (value, boxed, FALSE, FALSE);
}
/**
* g_value_set_boxed_take_ownership:
* @value: a valid #GValue of %G_TYPE_BOXED derived type
* @v_boxed: duplicated unowned boxed value to be set
*
* This is an internal function introduced mainly for C marshallers.
*
* Deprecated: 2.4: Use g_value_take_boxed() instead.
*/
void
g_value_set_boxed_take_ownership (GValue *value,
gconstpointer boxed)
......@@ -620,6 +663,17 @@ g_value_set_boxed_take_ownership (GValue *value,
g_value_take_boxed (value, boxed);
}
/**
* g_value_take_boxed:
* @value: a valid #GValue of %G_TYPE_BOXED derived type
* @v_boxed: duplicated unowned boxed value to be set
*
* Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed and
* takes over the ownership of the callers reference to @v_boxed;
* the caller doesn't have to unref it any more.
*
* Since: 2.4
*/
void
g_value_take_boxed (GValue *value,
gconstpointer boxed)
......
......@@ -29,6 +29,14 @@ G_BEGIN_DECLS
/* --- type macros --- */
#define G_TYPE_IS_BOXED(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_BOXED)
/**
* G_VALUE_HOLDS_BOXED:
* @value: a valid #GValue structure
*
* Checks whether the given #GValue can hold values derived from type %G_TYPE_BOXED.
*
* Returns: %TRUE on success.
*/
#define G_VALUE_HOLDS_BOXED(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_BOXED))
......
......@@ -546,6 +546,13 @@ g_flags_get_first_value (GFlagsClass *flags_class,
return NULL;
}
/**
* g_value_set_enum:
* @value: a valid #GValue whose type is derived from %G_TYPE_ENUM
* @v_enum: enum value to be set
*
* Set the contents of a %G_TYPE_ENUM #GValue to @v_enum.
*/
void
g_value_set_enum (GValue *value,
gint v_enum)
......@@ -555,6 +562,14 @@ g_value_set_enum (GValue *value,
value->data[0].v_long = v_enum;
}
/**
* g_value_get_enum:
* @value: a valid #GValue whose type is derived from %G_TYPE_ENUM
*
* Get the contents of a %G_TYPE_ENUM #GValue.
*
* Returns: enum contents of @value
*/
gint
g_value_get_enum (const GValue *value)
{
......@@ -563,6 +578,13 @@ g_value_get_enum (const GValue *value)
return value->data[0].v_long;
}
/**
* g_value_set_flags:
* @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS
* @v_flags: flags value to be set
*
* Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags.
*/
void
g_value_set_flags (GValue *value,
guint v_flags)
......@@ -572,6 +594,14 @@ g_value_set_flags (GValue *value,
value->data[0].v_ulong = v_flags;
}
/**
* g_value_get_flags:
* @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS
*
* Get the contents of a %G_TYPE_FLAGS #GValue.
*
* Returns: flags contents of @value
*/
guint
g_value_get_flags (const GValue *value)
{
......
......@@ -116,7 +116,23 @@ G_BEGIN_DECLS
#define G_FLAGS_CLASS_TYPE_NAME(class) (g_type_name (G_FLAGS_CLASS_TYPE (class)))
/**
* G_VALUE_HOLDS_ENUM:
* @value: a valid #GValue structure
*
* Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM.
*
* Returns: %TRUE on success.
*/
#define G_VALUE_HOLDS_ENUM(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_ENUM))
/**
* G_VALUE_HOLDS_FLAGS:
* @value: a valid #GValue structure
*
* Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS.
*
* Returns: %TRUE on success.
*/
#define G_VALUE_HOLDS_FLAGS(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_FLAGS))
......
......@@ -2718,6 +2718,24 @@ g_value_object_lcopy_value (const GValue *value,
return NULL;
}
/**
* g_value_set_object:
* @value: a valid #GValue of %G_TYPE_OBJECT derived type
* @v_object: object value to be set
*
* Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object.
*
* g_value_set_object() increases the reference count of @v_object
* (the #GValue holds a reference to @v_object).
* If you do not wish to increase the reference count of the object
* (i.e. you wish to pass your current reference to the #GValue because you no
* longer need it),
* use g_value_take_object() instead.
*
* It is important that your #GValue holds a reference to @v_object (either its
* own, or one it has taken) to ensure that the object won't be destroyed while
* the #GValue still exists).
*/
void
g_value_set_object (GValue *value,
gpointer v_object)
......@@ -2743,6 +2761,15 @@ g_value_set_object (GValue *value,
g_object_unref (old);
}
/**
* g_value_set_object_take_ownership:
* @value: a valid #GValue of %G_TYPE_OBJECT derived type
* @v_object: object value to be set
*
* This is an internal function introduced mainly for C marshallers.
*
* Deprecated: 2.4: Use g_value_take_object() instead.
*/
void
g_value_set_object_take_ownership (GValue *value,
gpointer v_object)
......@@ -2750,6 +2777,21 @@ g_value_set_object_take_ownership (GValue *value,
g_value_take_object (value, v_object);
}
/**
* g_value_take_object:
* @value: a valid #GValue of %G_TYPE_OBJECT derived type
* @v_object: object value to be set
*
* Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object
* and takes over the ownership of the callers reference to @v_object;
* the caller doesn't have to unref it any more (i.e. the reference
* count of the object is not increased).
*
* If you want the #GValue to hold its own reference to @v_object, use
* g_value_set_object() instead.
*
* Since: 2.4
*/
void
g_value_take_object (GValue *value,
gpointer v_object)
......@@ -2771,6 +2813,14 @@ g_value_take_object (GValue *value,
}
}
/**
* g_value_get_object:
* @value: a valid #GValue of %G_TYPE_OBJECT derived type
*
* Get the contents of a %G_TYPE_OBJECT derived #GValue.
*
* Returns: object contents of @value
*/
gpointer
g_value_get_object (const GValue *value)
{
......@@ -2779,6 +2829,14 @@ g_value_get_object (const GValue *value)
return value->data[0].v_pointer;
}
/**
* g_value_dup_object:
* @value: a valid #GValue whose type is derived from %G_TYPE_OBJECT
*
* Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing its reference count.
*
* Returns: object content of @value, should be unreferenced when no longer needed.
*/
gpointer
g_value_dup_object (const GValue *value)
{
......
......@@ -119,6 +119,14 @@ G_BEGIN_DECLS
* should not be freed.
*/
#define G_OBJECT_CLASS_NAME(class) (g_type_name (G_OBJECT_CLASS_TYPE (class)))
/**
* G_VALUE_HOLDS_OBJECT:
* @value: a valid #GValue structure
*
* Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT.
*
* Returns: %TRUE on success.
*/
#define G_VALUE_HOLDS_OBJECT(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_OBJECT))
/* --- type macros --- */
......
......@@ -1386,6 +1386,13 @@ g_param_type_register_static (const gchar *name,
return g_type_register_static (G_TYPE_PARAM, name, &info, 0);
}
/**
* g_value_set_param:
* @value: a valid #GValue of type %G_TYPE_PARAM
* @param: the #GParamSpec to be set
*
* Set the contents of a %G_TYPE_PARAM #GValue to @param.
*/
void
g_value_set_param (GValue *value,
GParamSpec *param)
......@@ -1401,6 +1408,15 @@ g_value_set_param (GValue *value,
g_param_spec_ref (value->data[0].v_pointer);
}
/**
* g_value_set_param_take_ownership:
* @value: a valid #GValue of type %G_TYPE_PARAM
* @param: the #GParamSpec to be set
*
* This is an internal function introduced mainly for C marshallers.
*
* Deprecated: 2.4: Use g_value_take_param() instead.
*/
void
g_value_set_param_take_ownership (GValue *value,
GParamSpec *param)
......@@ -1408,6 +1424,17 @@ g_value_set_param_take_ownership (GValue *value,
g_value_take_param (value, param);
}
/**
* g_value_take_param:
* @value: a valid #GValue of type %G_TYPE_PARAM
* @param: the #GParamSpec to be set
*
* Sets the contents of a %G_TYPE_PARAM #GValue to @param and
* takes over the ownership of the callers reference to @param;
* the caller doesn't have to unref it any more.
*
* Since: 2.4
*/
void
g_value_take_param (GValue *value,
GParamSpec *param)
......@@ -1421,6 +1448,14 @@ g_value_take_param (GValue *value,
value->data[0].v_pointer = param; /* we take over the reference count */
}
/**
* g_value_get_param:
* @value: a valid #GValue whose type is derived from %G_TYPE_PARAM
*
* Get the contents of a %G_TYPE_PARAM #GValue.
*
* Returns: #GParamSpec content of @value
*/
GParamSpec*
g_value_get_param (const GValue *value)
{
......@@ -1429,6 +1464,14 @@ g_value_get_param (const GValue *value)
return value->data[0].v_pointer;
}
/**
* g_value_dup_param:
* @value: a valid #GValue whose type is derived from %G_TYPE_PARAM
*
* Get the contents of a %G_TYPE_PARAM #GValue, increasing its reference count.
*
* Returns: #GParamSpec content of @value, should be unreferenced when no longer needed.
*/
GParamSpec*
g_value_dup_param (const GValue *value)
{
......
......@@ -99,6 +99,14 @@ G_BEGIN_DECLS
* Retrieves the #GType to initialize a #GValue for this parameter.
*/
#define G_PARAM_SPEC_VALUE_TYPE(pspec) (G_PARAM_SPEC (pspec)->value_type)
/**
* G_VALUE_HOLDS_PARAM:
* @value: a valid #GValue structure
*
* Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM.
*
* Returns: %TRUE on success.
*/
#define G_VALUE_HOLDS_PARAM(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_PARAM))
......
......@@ -16,7 +16,23 @@
* Free Software Foundation, Inc., 59 Temple Place, Suite 330,
* Boston, MA 02111-1307, USA.
*/
/**
* SECTION:param_value_types
* @Short_description: Standard Parameter and Value Types
* @See_also:#GParamSpec, #GValue, g_object_class_install_property().
* @Title: Parameters and Values
*
* #GValue provides an abstract container structure which can be copied,
* transformed and compared while holding a value of any (derived) type, which
* is registered as a #GType with a #GTypeValueTable in its #GTypeInfo structure.
* Parameter specifications for most value types can be created as
* #GParamSpec derived instances, to implement e.g. #GObject properties which
* operate on #GValue containers.
*
* Parameter names need to start with a letter (a-z or A-Z). Subsequent
* characters can be letters, numbers or a '-'.
* All other characters are replaced by a '-' during construction.
*/
/*
* MT safe
*/
......@@ -1493,6 +1509,20 @@ g_param_spec_types_init (void)
/* --- GParamSpec initialization --- */
/**
* g_param_spec_char:
* @name: canonical name of the property specified
* @nick: nick name for the property specified
* @blurb: description of the property specified
* @minimum: minimum value for the property specified
* @maximum: maximum value for the property specified
* @default_value: default value for the property specified
* @flags: flags for the property specified
*
* Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property.
*
* Returns: a newly created parameter specification
*/
GParamSpec*
g_param_spec_char (const gchar *name,
const gchar *nick,
......@@ -1519,6 +1549,20 @@ g_param_spec_char (const gchar *name,
return G_PARAM_SPEC (cspec);
}
/**
* g_param_spec_uchar:
* @name: canonical name of the property specified
* @nick: nick name for the property specified
* @blurb: description of the property specified
* @minimum: minimum value for the property specified
* @maximum: maximum value for the property specified
* @default_value: default value for the property specified
* @flags: flags for the property specified
*
* Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property.
*
* Returns: a newly created parameter specification
*/
GParamSpec*
g_param_spec_uchar (const gchar *name,
const gchar *nick,
......@@ -1545,6 +1589,21 @@ g_param_spec_uchar (const gchar *name,
return G_PARAM_SPEC (uspec);
}
/**
* g_param_spec_boolean:
* @name: canonical name of the property specified
* @nick: nick name for the property specified
* @blurb: description of the property specified
* @default_value: default value for the property specified
* @flags: flags for the property specified
*
* Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN
* property.
*
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
*/
GParamSpec*
g_param_spec_boolean (const gchar *name,
const gchar *nick,
......@@ -1567,6 +1626,22 @@ g_param_spec_boolean (const gchar *name,
return G_PARAM_SPEC (bspec);
}
/**
* g_param_spec_int:
* @name: canonical name of the property specified
* @nick: nick name for the property specified
* @blurb: description of the property specified
* @minimum: minimum value for the property specified
* @maximum: maximum value for the property specified
* @default_value: default value for the property specified
* @flags: flags for the property specified
*
* Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property.
*
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
*/
GParamSpec*
g_param_spec_int (const gchar *name,
const gchar *nick,
......@@ -1593,6 +1668,22 @@ g_param_spec_int (const gchar *name,
return G_PARAM_SPEC (ispec);
}
/**
* g_param_spec_uint:
* @name: canonical name of the property specified
* @nick: nick name for the property specified
* @blurb: description of the property specified
* @minimum: minimum value for the property specified
* @maximum: maximum value for the property specified
* @default_value: default value for the property specified
* @flags: flags for the property specified
*
* Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property.
*
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
*/
GParamSpec*
g_param_spec_uint (const gchar *name,
const gchar *nick,
......@@ -1619,6 +1710,22 @@ g_param_spec_uint (const gchar *name,
return G_PARAM_SPEC (uspec);
}
/**
* g_param_spec_long:
* @name: canonical name of the property specified
* @nick: nick name for the property specified
* @blurb: description of the property specified
* @minimum: minimum value for the property specified
* @maximum: maximum value for the property specified
* @default_value: default value for the property specified
* @flags: flags for the property specified
*
* Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property.
*
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
*/
GParamSpec*
g_param_spec_long (const gchar *name,
const gchar *nick,
......@@ -1645,6 +1752,22 @@ g_param_spec_long (const gchar *name,
return G_PARAM_SPEC (lspec);
}
/**
* g_param_spec_ulong:
* @name: canonical name of the property specified
* @nick: nick name for the property specified
* @blurb: description of the property specified
* @minimum: minimum value for the property specified
* @maximum: maximum value for the property specified
* @default_value: default value for the property specified
* @flags: flags for the property specified
*
* Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG property.
*
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
*/
GParamSpec*
g_param_spec_ulong (const gchar *name,
const gchar *nick,
......@@ -1671,6 +1794,22 @@ g_param_spec_ulong (const gchar *name,
return G_PARAM_SPEC (uspec);
}
/**
* g_param_spec_int64:
* @name: canonical name of the property specified
* @nick: nick name for the property specified
* @blurb: description of the property specified
* @minimum: minimum value for the property specified
* @maximum: maximum value for the property specified
* @default_value: default value for the property specified
* @flags: flags for the property specified
*
* Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property.
*
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
*/
GParamSpec*
g_param_spec_int64 (const gchar *name,
const gchar *nick,
......@@ -1697,6 +1836,23 @@ g_param_spec_int64 (const gchar *name,
return G_PARAM_SPEC (lspec);
}
/**
* g_param_spec_uint64:
* @name: canonical name of the property specified
* @nick: nick name for the property specified
* @blurb: description of the property specified
* @minimum: minimum value for the property specified
* @maximum: maximum value for the property specified
* @default_value: default value for the property specified
* @flags: flags for the property specified
*
* Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64
* property.
*
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
*/
GParamSpec*
g_param_spec_uint64 (const gchar *name,
const gchar *nick,
......@@ -1723,6 +1879,22 @@ g_param_spec_uint64 (const gchar *name,
return G_PARAM_SPEC (uspec);
}
/**
* g_param_spec_unichar:
* @name: canonical name of the property specified
* @nick: nick name for the property specified
* @blurb: description of the property specified
* @default_value: default value for the property specified
* @flags: flags for the property specified
*
* Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT
* property. #GValue structures for this property can be accessed with
* g_value_set_uint() and g_value_get_uint().
*
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
*/
GParamSpec*
g_param_spec_unichar (const gchar *name,
const gchar *nick,
......@@ -1743,6 +1915,22 @@ g_param_spec_unichar (const gchar *name,
return G_PARAM_SPEC (uspec);
}
/**
* g_param_spec_enum:
* @name: canonical name of the property specified
* @nick: nick name for the property specified
* @blurb: description of the property specified
* @enum_type: a #GType derived from %G_TYPE_ENUM
* @default_value: default value for the property specified
* @flags: flags for the property specified
*
* Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM
* property.
*
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
*/
GParamSpec*
g_param_spec_enum (const gchar *name,
const gchar *nick,
......@@ -1773,6 +1961,22 @@ g_param_spec_enum (const gchar *name,
return G_PARAM_SPEC (espec);
}
/**
* g_param_spec_flags:
* @name: canonical name of the property specified
* @nick: nick name for the property specified
* @blurb: description of the property specified
* @flags_type: a #GType derived from %G_TYPE_FLAGS
* @default_value: default value for the property specified
* @flags: flags for the property specified
*
* Creates a new #GParamSpecFlags instance specifying a %G_TYPE_FLAGS
* property.
*
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
*/
GParamSpec*
g_param_spec_flags (const gchar *name,
const gchar *nick,
......@@ -1803,6 +2007,22 @@ g_param_spec_flags (const gchar *name,
return G_PARAM_SPEC (fspec);
}
/**
* g_param_spec_float:
* @name: canonical name of the property specified
* @nick: nick name for the property specified
* @blurb: description of the property specified
* @minimum: minimum value for the property specified
* @maximum: maximum value for the property specified
* @default_value: default value for the property specified
* @flags: flags for the property specified
*
* Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property.
*
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
*/
GParamSpec*
g_param_spec_float (const gchar *name,
const gchar *nick,
......@@ -1829,6 +2049,23 @@ g_param_spec_float (const gchar *name,
return G_PARAM_SPEC (fspec);
}
/**
* g_param_spec_double:
* @name: canonical name of the property specified
* @nick: nick name for the property specified
* @blurb: description of the property specified
* @minimum: minimum value for the property specified
* @maximum: maximum value for the property specified
* @default_value: default value for the property specified
* @flags: flags for the property specified
*
* Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE
* property.
*
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
*/
GParamSpec*
g_param_spec_double (const gchar *name,
const gchar *nick,
......@@ -1855,6 +2092,20 @@ g_param_spec_double (const gchar *name,
return G_PARAM_SPEC (dspec);
}
/**
* g_param_spec_string:
* @name: canonical name of the property specified
* @nick: nick name for the property specified
* @blurb: description of the property specified
* @default_value: default value for the property specified