blob: 4125f91e4e3ff4abdc8e0f4cf255ec6d5c656480 (
plain)
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
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
<refentry id="widgetclasses" revision="8 Feb 2006">
<refmeta>
<refentrytitle>Widget Class Definitions</refentrytitle>
<refmiscinfo>Glade UI</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Widget Classes</refname>
<refpurpose>
Adding support for custom widgets
</refpurpose>
</refnamediv>
<refsect1>
<title>Forward</title>
<para>
#GladeWidgetClass stuctures are added to a global pool using the `glade-widget-class' tag
and then later added to the palette through the `glade-widget-group' section; class-wide
parameters can be set on non-instantiatable classes; for example, parameters for
#GtkBox are valid for #GtkHBox and #GtkVBox.
</para>
<para>
Note that there are alot of features to support alot of special-cases from
toolkits; but assuming that a widget is completely configurable via properties
and does not implement any special container relationships (which we will
explain in further detail later on) the catalog entry should really just be
a one liner like this:
<programlisting>
<![CDATA[<glade-widget-class name="GtkLabel" get-type-function="gtk_label_get_type" generic-name="label" title="Label"/>]]></programlisting>
</para>
<para>
To delve further into details; the complex layout looks like this:
<programlisting>
<![CDATA[<glade-widget-class name="GtkLabel" get-type-function="gtk_label_get_type" generic-name="label" title="Label">
... widget class support functions go here
<properties>
... property definitions go here
</properties>
<children>
... child specific parameters go here
</children>
</glade-widget-class>]]></programlisting>
</para>
</refsect1>
<refsect1>
<title>Widget Class Parameters</title>
<variablelist>
<varlistentry>
<term>name</term>
<listitem>
<para>
The 'name' property is the class name of the widget; unless the 'get-type-function'
property is present, this will essentially be used to instantiate the actual class
by deriving 'gtk_label_get_type' from 'GtkLabel' and searching for 'gtk_label_get_type'
in the support library.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>get-type-function</term>
<listitem>
<para>
The 'get-type-function' property is used to explicitly specify the name of the
function used to get the type of the widget. It is optional, but if it is not
present, the 'name' property will be used to guess the name of the function,
a process that could lead to unexpected results.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>generic-name</term>
<listitem>
<para>
The 'generic-name' is used to generate a default name for instances of the
widget in the UI editor. It is also used in conjunction with the 'icon-prefix'
to form an icon name for the widget.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>icon-name</term>
<listitem>
<para>
The 'icon-name' property is used to explicitly set an icon name for this widget.
These icon names are looked up in the current icon theme to retrieve an icon for
the widget.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>title</term>
<listitem>
<para>
The'title' property is used to display the name of the class in the palette and widget
tree and will be translated before use in the interface.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>toplevel</term>
<listitem>
<para>
The'toplevel' property is used to know whether this widget class is toplevel or not
in Glade context.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>post-create-function</term>
<listitem>
<para>
The 'post-create-function' tag is a #GladePostCreateFunc support function that
gets called whenever a widget of 'this class' (or a widget derived from 'this class'
that didn't provide its own post-create-function) is instantiated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>launch-editor-function</term>
<listitem>
<para>
The 'launch-editor-function' tag is a #GladeEditorLaunchFunc support function used to
launch a custom editor for this class; a good example for this is the #GtkMenuBar
which needs a special editor in order to be easier to use.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>get-internal-child-function</term>
<listitem>
<para>
The 'get-internal-child-function' tag is a #GladeGetInternalFunc support function
used to retrieve an internal child of a composite object (like a button in a
filechooser or something); support for internal children must also be added to
your application via libglade.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Icons</title>
<para>The Glade palette and other components use icons to represent the various widget classes.
It is a good idea to provide icons for your widget classes, as this
enhances the user interface.</para>
<para>Glade uses the GTK+ GtkIconTheme facility to provide icons for widget classes. Any icon
available in the current icon theme can be used as an icon for a widget class.</para>
<para>By default, an icon name of the format "widget-CATALOG_NAME-GENERIC_NAME"
is assigned to every widget class. CATALOG_NAME is the value of catalog name attribute, and GENERIC_NAME is
the value of an widget class's generic name attribute.</para>
<para>To explicity set an icon name for a widget class, the "icon-name" attribute of the "glade-widget-class"
element can be specified. This will override the default icon name assigned to the widget class.</para>
<para>Icon files can be installed under any system icon theme folder, but we recommend
that you install them in glade's private icon theme folder:</para>
<programlisting>pkg-config --variable=pixmapdir gladeui-1.0</programlisting>
</refsect1>
<refsect1>
<title>Grouping widget classes in the catalog</title>
<para>
The widgets are groups in different groups in the Glade UI. Those groups
are defined in the catalog file as follows:
<programlisting>
<![CDATA[
<glade-widget-group name="my-widgets" title="My widgets">
<glade-widget-class-ref name="MyFirstWidget"/>
<glade-widget-class-ref name="MysecondWidget"/>
...
</glade-widget-group>]]></programlisting>
The file should contain one or more widget groups.
</para>
</refsect1>
</refentry>
|
