← Back to branch summary

~ubuntu-branches/ubuntu/trusty/libgnome/trusty-proposed

« back to all changes in this revision

Viewing changes to doc/reference/xml/gnome-triggers.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Bacher
  • Date: 2009-03-06 17:27:16 UTC
  • mfrom: (1.1.29 upstream)
  • Revision ID: james.westby@ubuntu.com-20090306172716-lnh6jr51eoy0x2qo
Tags: 2.25.1-0ubuntu1
* New upstream version
* debian/control.in:
  - set vcs location
* debian/watch:
  - track unstable series

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/reference/xml/gnome-triggers.xml
8
8
<refnamediv>
9
9
<refname>gnome-triggers</refname>
10
10
<refpurpose>Hierarchical signal mechanism for GNOME events.</refpurpose>
11
 
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
12
11
</refnamediv>
13
12
 
14
13
<refsynopsisdiv id="libgnome-gnome-triggers.synopsis" role="synopsis">
22
21
<link linkend="void">void</link>                (<link linkend="GnomeTriggerActionFunction">*GnomeTriggerActionFunction</link>)       (<link linkend="char">char</link> *msg,
23
22
                                                         <link linkend="char">char</link> *level,
24
23
                                                         <link linkend="char">char</link> *supinfo[]);
 
24
                    <link linkend="GnomeTrigger">GnomeTrigger</link>;
 
25
<link linkend="void">void</link>                <link linkend="gnome-triggers-add-trigger">gnome_triggers_add_trigger</link>          (<link linkend="GnomeTrigger">GnomeTrigger</link> *nt,
 
26
                                                         ...);
 
27
<link linkend="void">void</link>                <link linkend="gnome-triggers-vadd-trigger">gnome_triggers_vadd_trigger</link>         (<link linkend="GnomeTrigger">GnomeTrigger</link> *nt,
 
28
                                                         <link linkend="char">char</link> *supinfo[]);
 
29
<link linkend="void">void</link>                <link linkend="gnome-triggers-do">gnome_triggers_do</link>                   (const <link linkend="char">char</link> *msg,
 
30
                                                         const <link linkend="char">char</link> *level,
 
31
                                                         ...);
 
32
<link linkend="void">void</link>                <link linkend="gnome-triggers-vdo">gnome_triggers_vdo</link>                  (const <link linkend="char">char</link> *msg,
 
33
                                                         const <link linkend="char">char</link> *level,
 
34
                                                         const <link linkend="char">char</link> *supinfo[]);
25
35
</synopsis>
26
36
</refsynopsisdiv>
27
37
 
62
72
<title role="details.title">Details</title>
63
73
<refsect2 id="GnomeTriggerType" role="enum">
64
74
<title>enum GnomeTriggerType</title>
65
 
<indexterm zone="GnomeTriggerType"><primary>GnomeTriggerType</primary></indexterm><programlisting>typedef enum {
 
75
<indexterm zone="GnomeTriggerType"><primary sortas="GnomeTriggerType">GnomeTriggerType</primary></indexterm><programlisting>typedef enum {
66
76
        GTRIG_NONE,
67
77
        GTRIG_FUNCTION,
68
78
        GTRIG_COMMAND,
73
83
These are the different types of triggers that can be activated by an
74
84
application.
75
85
</para><variablelist role="enum">
76
 
<varlistentry id="GTRIG-NONE:CAPS" role="constant">
 
86
<varlistentry id="GTRIG-NONE--CAPS" role="constant">
77
87
<term><literal>GTRIG_NONE</literal></term>
78
88
<listitem><simpara>A null trigger type. Should never be used.
79
89
</simpara></listitem>
80
90
</varlistentry>
81
 
<varlistentry id="GTRIG-FUNCTION:CAPS" role="constant">
 
91
<varlistentry id="GTRIG-FUNCTION--CAPS" role="constant">
82
92
<term><literal>GTRIG_FUNCTION</literal></term>
83
93
<listitem><simpara>The trigger causes a function to be executed.
84
94
</simpara></listitem>
85
95
</varlistentry>
86
 
<varlistentry id="GTRIG-COMMAND:CAPS" role="constant">
 
96
<varlistentry id="GTRIG-COMMAND--CAPS" role="constant">
87
97
<term><literal>GTRIG_COMMAND</literal></term>
88
98
<listitem><simpara>The trigger causes a command to be executed (using <link linkend="execv"><function>execv()</function></link>).
89
99
</simpara></listitem>
90
100
</varlistentry>
91
 
<varlistentry id="GTRIG-MEDIAPLAY:CAPS" role="constant">
 
101
<varlistentry id="GTRIG-MEDIAPLAY--CAPS" role="constant">
92
102
<term><literal>GTRIG_MEDIAPLAY</literal></term>
93
103
<listitem><simpara>The trigger causes a sound to be played.
94
 
 
95
104
</simpara></listitem>
96
105
</varlistentry>
97
106
</variablelist></refsect2>
98
107
<refsect2 id="GnomeTriggerActionFunction" role="function">
99
108
<title>GnomeTriggerActionFunction ()</title>
100
 
<indexterm zone="GnomeTriggerActionFunction"><primary>GnomeTriggerActionFunction</primary></indexterm><programlisting><link linkend="void">void</link>                (*GnomeTriggerActionFunction)       (<link linkend="char">char</link> *msg,
 
109
<indexterm zone="GnomeTriggerActionFunction"><primary sortas="GnomeTriggerActionFunction">GnomeTriggerActionFunction</primary></indexterm><programlisting><link linkend="void">void</link>                (*GnomeTriggerActionFunction)       (<link linkend="char">char</link> *msg,
101
110
                                                         <link linkend="char">char</link> *level,
102
111
                                                         <link linkend="char">char</link> *supinfo[]);</programlisting>
103
112
<para>
104
 
The signature of a function that can used as a target for <link linkend="GTRIG-FUNCTION:CAPS"><type>GTRIG_FUNCTION</type></link>
 
113
The signature of a function that can used as a target for <link linkend="GTRIG-FUNCTION--CAPS"><type>GTRIG_FUNCTION</type></link>
105
114
types of <link linkend="GnomeTrigger"><type>GnomeTrigger</type></link> instances.
106
115
</para><variablelist role="params">
107
 
<varlistentry><term><parameter>msg</parameter>&nbsp;:</term>
 
116
<varlistentry><term><parameter>msg</parameter>&#160;:</term>
108
117
<listitem><simpara>The human-readable message that was passed to <link linkend="gnome-triggers-do"><function>gnome_triggers_do()</function></link>. May be
109
 
<link linkend="NULL:CAPS"><literal>NULL</literal></link>.
110
 
</simpara></listitem></varlistentry>
111
 
<varlistentry><term><parameter>level</parameter>&nbsp;:</term>
112
 
<listitem><simpara>The severity level of the event. May be <link linkend="NULL:CAPS"><literal>NULL</literal></link>.
113
 
</simpara></listitem></varlistentry>
114
 
<varlistentry><term><parameter>supinfo</parameter>&nbsp;:</term>
115
 
<listitem><simpara>The section in which the event belongs. This is a <link linkend="NULL:CAPS"><literal>NULL</literal></link> terminated
 
118
<link linkend="NULL--CAPS"><literal>NULL</literal></link>.
 
119
</simpara></listitem></varlistentry>
 
120
<varlistentry><term><parameter>level</parameter>&#160;:</term>
 
121
<listitem><simpara>The severity level of the event. May be <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
 
122
</simpara></listitem></varlistentry>
 
123
<varlistentry><term><parameter>supinfo</parameter>&#160;:</term>
 
124
<listitem><simpara>The section in which the event belongs. This is a <link linkend="NULL--CAPS"><literal>NULL</literal></link> terminated
116
125
array.
117
 
 
118
 
 
 
126
</simpara></listitem></varlistentry>
 
127
</variablelist></refsect2>
 
128
<refsect2 id="GnomeTrigger" role="struct">
 
129
<title>GnomeTrigger</title>
 
130
<indexterm zone="GnomeTrigger"><primary sortas="GnomeTrigger">GnomeTrigger</primary></indexterm><programlisting>typedef struct {
 
131
        GnomeTriggerType type;
 
132
        union {
 
133
                /*
 
134
                 * These will be passed the same info as
 
135
                 * gnome_triggers_do was given.
 
136
                 */
 
137
                GnomeTriggerActionFunction function;
 
138
                gchar *command;
 
139
                struct {
 
140
                        gchar *file;
 
141
                        int cache_id;
 
142
                } media;
 
143
        } u;
 
144
        gchar *level;
 
145
} GnomeTrigger;
 
146
</programlisting>
 
147
<para>
 
148
This structure stores the information about an action that is triggered for
 
149
a particular event. A filled in instance of this structure is passed to
 
150
<link linkend="gnome-triggers-add-trigger"><function>gnome_triggers_add_trigger()</function></link> and <link linkend="gnome-triggers-vadd-trigger"><function>gnome_triggers_vadd_trigger()</function></link>.
 
151
</para></refsect2>
 
152
<refsect2 id="gnome-triggers-add-trigger" role="function">
 
153
<title>gnome_triggers_add_trigger ()</title>
 
154
<indexterm zone="gnome-triggers-add-trigger"><primary sortas="gnome_triggers_add_trigger">gnome_triggers_add_trigger</primary></indexterm><programlisting><link linkend="void">void</link>                gnome_triggers_add_trigger          (<link linkend="GnomeTrigger">GnomeTrigger</link> *nt,
 
155
                                                         ...);</programlisting>
 
156
<para>
 
157
Adds a new <link linkend="GnomeTrigger"><type>GnomeTrigger</type></link> instance to the event hierarchy.</para>
 
158
<para>
 
159
</para><variablelist role="params">
 
160
<varlistentry><term><parameter>nt</parameter>&#160;:</term>
 
161
<listitem><simpara> Information on the new trigger to be added.
 
162
</simpara></listitem></varlistentry>
 
163
<varlistentry><term><parameter>...</parameter>&#160;:</term>
 
164
<listitem><simpara> The section to add the trigger under.
 
165
</simpara></listitem></varlistentry>
 
166
</variablelist></refsect2>
 
167
<refsect2 id="gnome-triggers-vadd-trigger" role="function">
 
168
<title>gnome_triggers_vadd_trigger ()</title>
 
169
<indexterm zone="gnome-triggers-vadd-trigger"><primary sortas="gnome_triggers_vadd_trigger">gnome_triggers_vadd_trigger</primary></indexterm><programlisting><link linkend="void">void</link>                gnome_triggers_vadd_trigger         (<link linkend="GnomeTrigger">GnomeTrigger</link> *nt,
 
170
                                                         <link linkend="char">char</link> *supinfo[]);</programlisting>
 
171
<para>
 
172
This does the same as <link linkend="gnome-triggers-add-trigger"><function>gnome_triggers_add_trigger()</function></link>, except the section is
 
173
stored in the <link linkend="NULL--CAPS"><literal>NULL</literal></link> terminated array <parameter>supinfo</parameter> instead of as a variable
 
174
length argument list.</para>
 
175
<para>
 
176
</para><variablelist role="params">
 
177
<varlistentry><term><parameter>nt</parameter>&#160;:</term>
 
178
<listitem><simpara> Information on the new trigger to be added.
 
179
</simpara></listitem></varlistentry>
 
180
<varlistentry><term><parameter>supinfo</parameter>&#160;:</term>
 
181
<listitem><simpara> The section to add the trigger under.
 
182
</simpara></listitem></varlistentry>
 
183
</variablelist></refsect2>
 
184
<refsect2 id="gnome-triggers-do" role="function">
 
185
<title>gnome_triggers_do ()</title>
 
186
<indexterm zone="gnome-triggers-do"><primary sortas="gnome_triggers_do">gnome_triggers_do</primary></indexterm><programlisting><link linkend="void">void</link>                gnome_triggers_do                   (const <link linkend="char">char</link> *msg,
 
187
                                                         const <link linkend="char">char</link> *level,
 
188
                                                         ...);</programlisting>
 
189
<para>
 
190
Notifies GNOME about an event happening, so that any appropriate handlers
 
191
can be run.</para>
 
192
<para>
 
193
</para><variablelist role="params">
 
194
<varlistentry><term><parameter>msg</parameter>&#160;:</term>
 
195
<listitem><simpara> The human-readable message describing the event (can be <link linkend="NULL--CAPS"><literal>NULL</literal></link>).
 
196
</simpara></listitem></varlistentry>
 
197
<varlistentry><term><parameter>level</parameter>&#160;:</term>
 
198
<listitem><simpara> The level of severity of the event, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
 
199
</simpara></listitem></varlistentry>
 
200
<varlistentry><term><parameter>...</parameter>&#160;:</term>
 
201
<listitem><simpara> The classification of the event.
 
202
</simpara></listitem></varlistentry>
 
203
</variablelist></refsect2>
 
204
<refsect2 id="gnome-triggers-vdo" role="function">
 
205
<title>gnome_triggers_vdo ()</title>
 
206
<indexterm zone="gnome-triggers-vdo"><primary sortas="gnome_triggers_vdo">gnome_triggers_vdo</primary></indexterm><programlisting><link linkend="void">void</link>                gnome_triggers_vdo                  (const <link linkend="char">char</link> *msg,
 
207
                                                         const <link linkend="char">char</link> *level,
 
208
                                                         const <link linkend="char">char</link> *supinfo[]);</programlisting>
 
209
<para>
 
210
Notifies GNOME about an event happening, so that any appropriate handlers
 
211
can be run. This does the same as <link linkend="gnome-trigger-do"><function>gnome_trigger_do()</function></link> except that it takes a
 
212
<link linkend="NULL--CAPS"><literal>NULL</literal></link> terminated array instead of a varargs list.</para>
 
213
<para>
 
214
</para><variablelist role="params">
 
215
<varlistentry><term><parameter>msg</parameter>&#160;:</term>
 
216
<listitem><simpara> The human-readable message describing the event (can be <link linkend="NULL--CAPS"><literal>NULL</literal></link>).
 
217
</simpara></listitem></varlistentry>
 
218
<varlistentry><term><parameter>level</parameter>&#160;:</term>
 
219
<listitem><simpara> The level of severity of the event, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
 
220
</simpara></listitem></varlistentry>
 
221
<varlistentry><term><parameter>supinfo</parameter>&#160;:</term>
 
222
<listitem><simpara> The classification of the event (<link linkend="NULL--CAPS"><literal>NULL</literal></link> terminated array).
119
223
</simpara></listitem></varlistentry>
120
224
</variablelist></refsect2>
121
225