1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
%gtkdocentities;
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>&package_name; Reference Manual</title>
<releaseinfo>
For &package_string;.
The latest version of this documentation can be found on-line at
<ulink role="online-location" url="https://developer.xfce.org/&package_name;/index.html">https://developer.xfce.org/&package_name;/</ulink>.
</releaseinfo>
<copyright>
<year>@COPYRIGHT_YEAR@</year>
<holder>The Xfce development team</holder>
</copyright>
</bookinfo>
<part id="libxfce4panel-fundamentals">
<title>Fundamentals</title>
<xi:include href="xml/config.xml"/>
<xi:include href="xml/enums.xml"/>
</part>
<part id="libxfce4panel-plugins">
<title>Panel Plugins</title>
<sect1 id="libxfce4panel-register">
<title>Register plugins with the panel</title>
<para>Since 4.8 there are various ways to register a plugin with the panel. Which option you
choose depends on a couple of things: is the plugin compiled as a module or as an
executable and do you want to write a plugin as a GObject.</para>
<sect2>
<title>Internal or external</title>
<para>In 4.6 you had to choose to compile a plugin as an executable to run it external (with
the appropriate macro to register external plugins) and the same for internal plugins that
were compiled as modules. This worked quite good, but had a couple of disadvantages:</para>
<itemizedlist>
<listitem>
<para>To switch between internal and external you needed to change the build system and
registration macros, so this was not very flexible.</para>
</listitem>
<listitem>
<para>When changes were made in the registration macros (esp the ones for external plugins)
a plugin had to recompile. Also each plugin copied the same piece of code.</para>
</listitem>
<listitem>
<para>Improvements in the panel communication (D-Bus) and transparant backgrounds where
either avoided or hard to implement.</para>
</listitem>
</itemizedlist>
<para>To work around those disadvantages Xfce Panel 4.8 introduced a new way to run plugins
that are compiled as modules in a separate process: a plugin wrapper. The plugin wrapper is started
by the panel for each external plugin and embeds the plugin module. It provides the communication
between the panel and the module using D-Bus and still has the big advantage of the 'old' exectuable
external plugin: if it crashes it won't crash the panel.</para>
<para>Whether a plugin is started internal or external is defined by the boolean in the
<varname>X-XFCE-Internal</varname> key in the plugins desktop file. No need to change the macros
and the registration macro code can be kept to an absolute minimum.</para>
<para>This does not mean the 4.6 executable plugins are not supported anymore. However if you write
a new plugin or your plugin depends on libxfce4panel 4.8, it is recommended to switch to the new
registration functions and compile your plugin as a module. To make this move obvious the old
macros are all marked as deprecated in this API reference.</para>
</sect2>
<sect2>
<title>GObject plugins</title>
<para>To handle the difference in 4.6 between internal and external plugins, the plugin API contained
3 different types. There were two objects <structname>XfceInternalPanelPlugin</structname> and
<structname>XfceExternalPanelPlugin</structname> based on a different parents (resp.
<structname>GtkEventBox</structname> and <structname>GtkPlug</structname>) that both implemented the
<structname>XfcePanelPlugin</structname> interface.</para>
<para>Because internal and external is handled by the wrapper in 4.8, <structname>XfcePanelPlugin</structname>
is now a single object with <structname>GtkEventBox</structname> as parent. Apart from the fact that
this reduced a lot of code in libxfce4panel, it also has the advantage that it is easier to write
plugins as GObject with <varname>XFCE_TYPE_PANEL_PLUGIN</varname> as parent type. This brings a couple
of new advantages compared to plugins with register functions:</para>
<itemizedlist>
<listitem>
<para>You can easily cast your plugin to an <structname>XfcePanelPlugin</structname>, so
no need for custom structures. You also get all the GOBject features like type checking.</para>
</listitem>
</itemizedlist>
<para>Downside is that you have to register all other types you create inside your plugin and that it
could be a bit difficult (when running internal) with special libraries. To work around the latter
you can make your plugin resident.</para>
<para>All the plugins shipped with the panel are written as GObjects, so you can find enough examples
in the <filename>plugins/</filename> folder.</para>
</sect2>
</sect1>
<xi:include href="xml/xfce-panel-plugin.xml"/>
<xi:include href="xml/register-plugins.xml"/>
<xi:include href="xml/register-gobject-plugins.xml"/>
</part>
<part id="libxfce4panel-widgets">
<title>Additional Widgets</title>
<para>This section describes the additional widgets provided by the <application>xfce4-panel</application> library.</para>
<xi:include href="xml/xfce-arrow-button.xml"/>
<xi:include href="xml/xfce-panel-image.xml"/>
</part>
<part id="libxfce4panel-miscelleanous">
<title>Miscelleanous</title>
<xi:include href="xml/convenience.xml"/>
<xi:include href="xml/macros.xml"/>
</part>
<index id="api-index-full">
<title>Index of all symbols</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-deprecated">
<title>Index of deprecated symbols</title>
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-4-22">
<title>Index of new symbols in 4.22</title>
<xi:include href="xml/api-index-4.21.0.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-4-20">
<title>Index of new symbols in 4.20</title>
<xi:include href="xml/api-index-4.19.6.xml"><xi:fallback /></xi:include>
<xi:include href="xml/api-index-4.19.0.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-4-18">
<title>Index of new symbols in 4.18</title>
<xi:include href="xml/api-index-4.17.4.xml"><xi:fallback /></xi:include>
<xi:include href="xml/api-index-4.17.2.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-4-14">
<title>Index of new symbols in 4.14</title>
<xi:include href="xml/api-index-4.14.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-4-10">
<title>Index of new symbols in 4.10</title>
<xi:include href="xml/api-index-4.10.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-4-8">
<title>Index of new symbols in 4.8</title>
<xi:include href="xml/api-index-4.8.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-4-6">
<title>Index of new symbols in 4.6</title>
<xi:include href="xml/api-index-4.6.xml"><xi:fallback /></xi:include>
</index>
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</book>
<!--
vi:set ts=2 sw=2 et ai:
-->
|
