mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-12 11:26:39 +00:00
153 lines
4.8 KiB
Markdown
153 lines
4.8 KiB
Markdown
---
|
|
title: Adding Properties
|
|
...
|
|
|
|
# Adding Properties
|
|
|
|
The primary and most important way of controlling how an element
|
|
behaves, is through GObject properties. GObject properties are defined
|
|
in the `_class_init ()` function. The element optionally implements a
|
|
`_get_property ()` and a `_set_property ()` 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.
|
|
|
|
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 `GObject` will not automatically set your
|
|
instance variable to the default value, you will have to do that in the
|
|
`_init ()` function of your element.
|
|
|
|
``` c
|
|
|
|
/* properties */
|
|
enum {
|
|
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);
|
|
|
|
/* define virtual function pointers */
|
|
object_class->set_property = gst_my_filter_set_property;
|
|
object_class->get_property = gst_my_filter_get_property;
|
|
|
|
/* define properties */
|
|
g_object_class_install_property (object_class, PROP_SILENT,
|
|
g_param_spec_boolean ("silent", "Silent",
|
|
"Whether to be very verbose or not",
|
|
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) {
|
|
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) {
|
|
case PROP_SILENT:
|
|
g_value_set_boolean (value, filter->silent);
|
|
break;
|
|
default:
|
|
G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
|
|
break;
|
|
}
|
|
}
|
|
```
|
|
|
|
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.
|
|
|
|
``` c
|
|
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)
|
|
{
|
|
[..]
|
|
g_object_class_install_property (G_OBJECT_CLASS (klass), PROP_PATTERN,
|
|
g_param_spec_enum ("pattern", "Pattern",
|
|
"Type of test pattern to generate",
|
|
GST_TYPE_VIDEOTESTSRC_PATTERN, GST_VIDEOTESTSRC_SMPTE,
|
|
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
|
|
[..]
|
|
}
|
|
|
|
```
|