gstreamer/docs/pwg/building-props.xml

170 lines
5.5 KiB
XML
Raw Normal View History

<!-- ############ chapter ############# -->
2012-09-27 12:42:07 +00:00
<chapter id="chapter-building-args" xreflabel="Adding Properties">
<title>Adding Properties</title>
<para>
The primary and most important way of controlling how an element behaves,
is through GObject properties. GObject properties are defined in the
<function>_class_init ()</function> function. The element optionally
implements a <function>_get_property ()</function> and a
<function>_set_property ()</function> function. These functions will be
notified if an application changes or requests the value of a property,
and can then fill in the value or take action required for that property
to change value internally.
</para>
2012-09-27 12:42:07 +00:00
<para>
You probably also want to keep an instance variable around
with the currently configured value of the property that you use in the
get and set functions.
Note that <classname>GObject</classname> will not automatically set your
instance variable to the default value, you will have to do that in the
<function>_init ()</function> function of your element.
</para>
<programlisting><!-- example-begin properties.c a --><!--
#include "filter.h"
2012-09-28 11:24:52 +00:00
G_DEFINE_TYPE (GstMyFilter, gst_my_filter, GST_TYPE_ELEMENT);
static void
2012-09-28 11:24:52 +00:00
gst_my_filter_class_init (gpointer klass)
{
}
static void
gst_my_filter_init (GstMyFilter * filter)
{
}
--><!-- example-end properties.c a -->
<!-- example-begin properties.c b -->
/* properties */
enum {
2012-09-27 12:42:07 +00:00
PROP_0,
PROP_SILENT
/* FILL ME */
};
static void gst_my_filter_set_property (GObject *object,
guint prop_id,
const GValue *value,
GParamSpec *pspec);
static void gst_my_filter_get_property (GObject *object,
guint prop_id,
GValue *value,
GParamSpec *pspec);
static void
gst_my_filter_class_init (GstMyFilterClass *klass)
{
GObjectClass *object_class = G_OBJECT_CLASS (klass);
2012-09-27 12:42:07 +00:00
/* define virtual function pointers */
object_class->set_property = gst_my_filter_set_property;
object_class->get_property = gst_my_filter_get_property;
/* define properties */
2012-09-27 12:42:07 +00:00
g_object_class_install_property (object_class, PROP_SILENT,
g_param_spec_boolean ("silent", "Silent",
"Whether to be very verbose or not",
Define G_PARAM_STATIC_STRINGS if it's undefined (GLib < 2.13.0) and use it everywhere for GParamSpecs that use static... Original commit message from CVS: * docs/pwg/advanced-dparams.xml: * docs/pwg/building-props.xml: * docs/pwg/other-source.xml: * gst/glib-compat.h: * gst/gstbin.c: (gst_bin_class_init): * gst/gstclock.c: (gst_clock_class_init): * gst/gstindex.c: (gst_index_class_init): * gst/gstobject.c: (gst_object_class_init): * gst/gstpad.c: (gst_pad_class_init): * gst/gstpipeline.c: (gst_pipeline_class_init): * libs/gst/base/gstbasesink.c: (gst_base_sink_class_init): * libs/gst/base/gstbasesrc.c: (gst_base_src_class_init): * libs/gst/base/gstbasetransform.c: (gst_base_transform_class_init): * libs/gst/base/gstdataqueue.c: (gst_data_queue_class_init): * libs/gst/check/gstcheck.c: (_gst_check_fault_handler_restore), (_gst_check_fault_handler_sighandler), (_gst_check_fault_handler_setup), (gst_check_init): * libs/gst/controller/gstcontroller.c: (_gst_controller_class_init): * libs/gst/controller/gstlfocontrolsource.c: (gst_lfo_control_source_class_init): * libs/gst/net/gstnetclientclock.c: (gst_net_client_clock_class_init): * libs/gst/net/gstnettimeprovider.c: (gst_net_time_provider_class_init): * plugins/elements/gstcapsfilter.c: (gst_capsfilter_class_init): * plugins/elements/gstfakesink.c: (gst_fake_sink_class_init): * plugins/elements/gstfakesrc.c: (gst_fake_src_class_init): * plugins/elements/gstfdsink.c: (gst_fd_sink_class_init): * plugins/elements/gstfdsrc.c: (gst_fd_src_class_init): * plugins/elements/gstfilesink.c: (gst_file_sink_class_init): * plugins/elements/gstfilesrc.c: (gst_file_src_class_init): * plugins/elements/gstidentity.c: (gst_identity_class_init): * plugins/elements/gstmultiqueue.c: (gst_multi_queue_class_init): * plugins/elements/gstqueue.c: (gst_queue_class_init): * plugins/elements/gsttee.c: (gst_tee_class_init): * plugins/elements/gsttypefindelement.c: (gst_type_find_element_class_init): * plugins/indexers/gstfileindex.c: (gst_file_index_class_init): Define G_PARAM_STATIC_STRINGS if it's undefined (GLib < 2.13.0) and use it everywhere for GParamSpecs that use static strings (i.e. all). This gives us less memory usage, fewer allocations and thus less memory defragmentation. Fixes bug #523806.
2008-03-22 14:56:17 +00:00
FALSE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
}
static void
gst_my_filter_set_property (GObject *object,
guint prop_id,
const GValue *value,
GParamSpec *pspec)
{
GstMyFilter *filter = GST_MY_FILTER (object);
switch (prop_id) {
2012-09-27 12:42:07 +00:00
case PROP_SILENT:
filter->silent = g_value_get_boolean (value);
g_print ("Silent argument was changed to %s\n",
filter->silent ? "true" : "false");
break;
default:
G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
break;
}
}
static void
gst_my_filter_get_property (GObject *object,
guint prop_id,
GValue *value,
GParamSpec *pspec)
{
GstMyFilter *filter = GST_MY_FILTER (object);
switch (prop_id) {
2012-09-27 12:42:07 +00:00
case PROP_SILENT:
g_value_set_boolean (value, filter->silent);
break;
default:
G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
break;
}
}
<!-- example-end properties.c b -->
<!-- example-begin properties.c c --><!--
#include "register.func"
--><!-- example-end properties.c c --></programlisting>
<para>
2012-09-27 12:42:07 +00:00
The above is a very simple example of how properties are used. Graphical
applications will use these properties and will display a
user-controllable widget with which these properties can be changed.
This means that - for the property to be as user-friendly
as possible - you should be as exact as possible in the definition of the
property. Not only in defining ranges in between which valid properties
can be located (for integers, floats, etc.), but also in using very
descriptive (better yet: internationalized) strings in the definition of
the property, and if possible using enums and flags instead of integers.
The GObject documentation describes these in a very complete way, but
below, we'll give a short example of where this is useful. Note that using
integers here would probably completely confuse the user, because they
make no sense in this context. The example is stolen from videotestsrc.
</para>
<programlisting>
typedef enum {
GST_VIDEOTESTSRC_SMPTE,
GST_VIDEOTESTSRC_SNOW,
GST_VIDEOTESTSRC_BLACK
} GstVideotestsrcPattern;
[..]
#define GST_TYPE_VIDEOTESTSRC_PATTERN (gst_videotestsrc_pattern_get_type ())
static GType
gst_videotestsrc_pattern_get_type (void)
{
static GType videotestsrc_pattern_type = 0;
if (!videotestsrc_pattern_type) {
static GEnumValue pattern_types[] = {
{ GST_VIDEOTESTSRC_SMPTE, "SMPTE 100% color bars", "smpte" },
{ GST_VIDEOTESTSRC_SNOW, "Random (television snow)", "snow" },
{ GST_VIDEOTESTSRC_BLACK, "0% Black", "black" },
{ 0, NULL, NULL },
};
videotestsrc_pattern_type =
g_enum_register_static ("GstVideotestsrcPattern",
pattern_types);
}
return videotestsrc_pattern_type;
}
[..]
static void
gst_videotestsrc_class_init (GstvideotestsrcClass *klass)
{
[..]
2012-09-27 12:42:07 +00:00
g_object_class_install_property (G_OBJECT_CLASS (klass), PROP_PATTERN,
g_param_spec_enum ("pattern", "Pattern",
"Type of test pattern to generate",
2012-09-27 12:42:07 +00:00
GST_TYPE_VIDEOTESTSRC_PATTERN, GST_VIDEOTESTSRC_SMPTE,
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
[..]
}
</programlisting>
</chapter>