← Back to branch summary

~ubuntu-branches/ubuntu/trusty/gstreamer1.0/trusty-proposed

« back to all changes in this revision

Viewing changes to docs/pwg/building-props.xml

  • Committer: Package Import Robot
  • Author(s): Sebastian Dröge
  • Date: 2012-10-08 09:59:20 UTC
  • mfrom: (1.1.7)
  • Revision ID: package-import@ubuntu.com-20121008095920-3k2vlenl0zf6lu7i
Tags: 1.0.1-1
* New upstream stable release:
  + debian/libgstreamer.symbols:
    - Add new symbols.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/pwg/building-props.xml
1
1
<!-- ############ chapter ############# -->
2
2
 
3
 
<chapter id="chapter-building-args" xreflabel="Adding Arguments">
4
 
  <title>Adding Arguments</title>
 
3
<chapter id="chapter-building-args" xreflabel="Adding Properties">
 
4
  <title>Adding Properties</title>
5
5
  <para>
6
6
    The primary and most important way of controlling how an element behaves,
7
7
    is through GObject properties. GObject properties are defined in the
12
12
    and can then fill in the value or take action required for that property
13
13
    to change value internally.
14
14
  </para>
 
15
  <para>
 
16
    You probably also want to keep an instance variable around
 
17
    with the currently configured value of the property that you use in the
 
18
    get and set functions. 
 
19
    Note that <classname>GObject</classname> will not automatically set your
 
20
    instance variable to the default value, you will have to do that in the
 
21
    <function>_init ()</function> function of your element.
 
22
  </para>
15
23
  <programlisting><!-- example-begin properties.c a --><!--
16
24
#include "filter.h"
17
 
GST_BOILERPLATE (GstMyFilter, gst_my_filter, GstElement, GST_TYPE_ELEMENT);
 
25
G_DEFINE_TYPE (GstMyFilter, gst_my_filter, GST_TYPE_ELEMENT);
18
26
static void
19
 
gst_my_filter_base_init (gpointer klass)
 
27
gst_my_filter_class_init (gpointer klass)
20
28
{
21
29
}
22
30
static void
27
35
<!-- example-begin properties.c b -->
28
36
/* properties */
29
37
enum {
30
 
  ARG_0,
31
 
  ARG_SILENT
 
38
  PROP_0,
 
39
  PROP_SILENT
32
40
  /* FILL ME */
33
41
};
34
42
 
46
54
{
47
55
  GObjectClass *object_class = G_OBJECT_CLASS (klass);
48
56
 
 
57
  /* define virtual function pointers */
 
58
  object_class->set_property = gst_my_filter_set_property;
 
59
  object_class->get_property = gst_my_filter_get_property;
 
60
 
49
61
  /* define properties */
50
 
  g_object_class_install_property (object_class, ARG_SILENT,
 
62
  g_object_class_install_property (object_class, PROP_SILENT,
51
63
    g_param_spec_boolean ("silent", "Silent",
52
64
                          "Whether to be very verbose or not",
53
65
                          FALSE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
54
 
 
55
 
  /* define virtual function pointers */
56
 
  object_class->set_property = gst_my_filter_set_property;
57
 
  object_class->get_property = gst_my_filter_get_property;
58
66
}
59
67
 
60
68
static void
66
74
  GstMyFilter *filter = GST_MY_FILTER (object);
67
75
 
68
76
  switch (prop_id) {
69
 
    case ARG_SILENT:
 
77
    case PROP_SILENT:
70
78
      filter->silent = g_value_get_boolean (value);
71
79
      g_print ("Silent argument was changed to %s\n",
72
80
               filter->silent ? "true" : "false");
86
94
  GstMyFilter *filter = GST_MY_FILTER (object);
87
95
                                                                                
88
96
  switch (prop_id) {
89
 
    case ARG_SILENT:
 
97
    case PROP_SILENT:
90
98
      g_value_set_boolean (value, filter->silent);
91
99
      break;
92
100
    default:
99
107
#include "register.func"
100
108
  --><!-- example-end properties.c c --></programlisting>
101
109
  <para>
102
 
    The above is a very simple example of how arguments are used. Graphical
103
 
    applications - for example GStreamer Editor - will use these properties
104
 
    and will display a user-controllable widget with which these properties
105
 
    can be changed. This means that - for the property to be as user-friendly
 
110
    The above is a very simple example of how properties are used. Graphical
 
111
    applications will use these properties and will display a
 
112
    user-controllable widget with which these properties can be changed.
 
113
    This means that - for the property to be as user-friendly
106
114
    as possible - you should be as exact as possible in the definition of the
107
115
    property. Not only in defining ranges in between which valid properties
108
116
    can be located (for integers, floats, etc.), but also in using very
150
158
gst_videotestsrc_class_init (GstvideotestsrcClass *klass)
151
159
{
152
160
[..]
153
 
  g_object_class_install_property (G_OBJECT_CLASS (klass), ARG_TYPE,
 
161
  g_object_class_install_property (G_OBJECT_CLASS (klass), PROP_PATTERN,
154
162
    g_param_spec_enum ("pattern", "Pattern",
155
163
                       "Type of test pattern to generate",
156
 
                       GST_TYPE_VIDEOTESTSRC_PATTERN, 1, G_PARAM_READWRITE |
157
 
                           G_PARAM_STATIC_STRINGS));
 
164
                       GST_TYPE_VIDEOTESTSRC_PATTERN, GST_VIDEOTESTSRC_SMPTE,
 
165
                       G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
158
166
[..]
159
167
}
160
168
  </programlisting>