1 <!-- ############ chapter ############# -->
3 <chapter id="chapter-building-args" xreflabel="Adding Arguments">
4 <title>Adding Arguments</title>
6 The primary and most important way of controlling how an element behaves,
7 is through GObject properties. GObject properties are defined in the
8 <function>_class_init ()</function> function. The element optionally
9 implements a <function>_get_property ()</function> and a
10 <function>_set_property ()</function> function. These functions will be
11 notified if an application changes or requests the value of a property,
12 and can then fill in the value or take action required for that property
13 to change value internally.
23 static void gst_my_filter_set_property (GObject *object,
27 static void gst_my_filter_get_property (GObject *object,
33 gst_my_filter_class_init (GstMyFilterClass *klass)
35 GObjectClass *object_class = G_OBJECT_CLASS (klass);
37 /* define properties */
38 g_object_class_install_property (object_class, ARG_SILENT,
39 g_param_spec_boolean ("silent", "Silent",
40 "Whether to be very verbose or not",
41 FALSE, G_PARAM_READWRITE));
43 /* define virtual function pointers */
44 object_class->set_property = gst_my_filter_set_property;
45 object_class->get_property = gst_my_filter_get_property;
49 gst_my_filter_set_property (GObject *object,
54 GstMyFilter *filter = GST_MY_FILTER (object);
58 filter->silent = g_value_get_boolean (value);
59 g_print ("Silent argument was changed to %s\n",
60 filter->silent ? "true" : "false");
63 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
69 gst_my_filter_get_property (GObject *object,
74 GstMyFilter *filter = GST_MY_FILTER (object);
78 g_value_set_boolean (value, filter->silent);
81 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
87 The above is a very simple example of how arguments are used. Graphical
88 applications - for example GStreamer Editor - will use these properties
89 and will display a user-controlleable widget with which these properties
90 can be changed. This means that - for the property to be as user-friendly
91 as possible - you should be as exact as possible in the definition of the
92 property. Not only in defining ranges in between which valid properties
93 can be located (for integers, floats, etc.), but also in using very
94 descriptive (better yet: internationalized) strings in the definition of
95 the property, and if possible using enums and flags instead of integers.
96 The GObject documentation describes these in a very complete way, but
97 below, we'll give a short example of where this is useful. Note that using
98 integers here would probably completely confuse the user, because they
99 make no sense in this context. The example is stolen from videotestsrc.
103 GST_VIDEOTESTSRC_SMPTE,
104 GST_VIDEOTESTSRC_SNOW,
105 GST_VIDEOTESTSRC_BLACK
106 } GstVideotestsrcPattern;
110 #define GST_TYPE_VIDEOTESTSRC_PATTERN (gst_videotestsrc_pattern_get_type ())
112 gst_videotestsrc_pattern_get_type (void)
114 static GType videotestsrc_pattern_type = 0;
116 if (!videotestsrc_pattern_type) {
117 static GEnumValue pattern_types[] = {
118 { GST_VIDEOTESTSRC_SMPTE, "smpte", "SMPTE 100% color bars" },
119 { GST_VIDEOTESTSRC_SNOW, "snow", "Random (television snow)" },
120 { GST_VIDEOTESTSRC_BLACK, "black", "0% Black" },
124 videotestsrc_pattern_type =
125 g_enum_register_static ("GstVideotestsrcPattern",
129 return videotestsrc_pattern_type;
135 gst_videotestsrc_class_init (GstvideotestsrcClass *klass)
138 g_object_class_install_property (G_OBJECT_CLASS (klass), ARG_TYPE,
139 g_param_spec_enum ("pattern", "Pattern",
140 "Type of test pattern to generate",
141 GST_TYPE_VIDEOTESTSRC_PATTERN, 1, G_PARAM_READWRITE));