mirror of
https://github.com/Ryujinx/GtkSharp.git
synced 2024-12-26 10:25:28 +00:00
d33dd8a15f
* gconf, sample/gconf: Added. * glue/combo.c: This was never added, add it now. * configure.in, makefile, sample/Makefile.in: Build new gconf bindings if gnome is enabled. svn path=/trunk/gtk-sharp/; revision=8389
208 lines
9.6 KiB
HTML
208 lines
9.6 KiB
HTML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
<head>
|
|
<title>Using GConf#</title>
|
|
</head>
|
|
<body>
|
|
<p align="center">
|
|
<font size="+3">Using GConf#</font></p>
|
|
<h1>Introduction</h1>
|
|
<p>Using GConf directly from an application is often inconvenient.
|
|
Because the configuration key system effectively represents a
|
|
string-based API, accessing GConf values leaves your application
|
|
open to runtime errors from a single typo. Even if you store your
|
|
keys in constants (as is recommended), you still wind up maintaining
|
|
two lists of keys: one in the schema, and one in your app.</p>
|
|
<p>Another problem is that the GConf value types are very limited:
|
|
string, float, int, bool, and list. When storing common value types
|
|
such as colors or enumerations, one has to serialize these values
|
|
to and from strings.</p>
|
|
<p>Finally, providing graphical dialogs for your settings can be a very
|
|
tedious process. For each config element exposed in your UI, you have
|
|
to manually hook up the "changed" signal on the UI to a custom handler
|
|
setting the GConf value. Inversely, one must initially populate the
|
|
dialog based on previously-set GConf values. Complicating all of this
|
|
is the GNOME HIG, which specifies that all preference dialogs be
|
|
instant-apply if possible.</p>
|
|
<p>GConf# addresses these issues with two new utilities: SchemaGen, and
|
|
the GConf.PropertyEditors library.</p>
|
|
|
|
<h1>SchemaGen</h1>
|
|
<p>SchemaGen is a new tool which generates a custom API for the settings
|
|
in a gconf schema file. Given a schema, it generates two classes,
|
|
<b>Settings</b> and <b>SettingKeys</b>. <b>Settings</b> provides static
|
|
properties for each specified gconf setting. These properties map
|
|
directly to the values in the gconf database. <b>Settings</b> also
|
|
specifies static events for each setting indicating when the setting
|
|
has changed, and a generic Changed event which notifies when any
|
|
of your settings have changed. Finally, for every property in
|
|
<b>Settings</b>, SchemaGen creates a read-only property of the same
|
|
name in <b>SettingKeys</b> specifying the GConf key used to access
|
|
this property. <b>SettingKeys</b> is not needed if you are only using
|
|
the <b>Settings</b> class, but it is very useful when attaching
|
|
PropertyEditors, or when accessing GConf directly.</p>
|
|
<p>SchemaGen also provides for limited marshalling to and from the
|
|
GConf value types. It currently defines marshallers for
|
|
System.Drawing.Color and for enumerations. This is done by specifying
|
|
a <b>cstype</b> directive in the GConf schema.</p>
|
|
<h2>Example</h2>
|
|
<p>First, we need to write a GConf schema specifying our settings.</p>
|
|
<pre>
|
|
<gconfschema>
|
|
<schemalist>
|
|
<schema>
|
|
<key>/schemas/apps/gconfsharp/sample_app/toolbar_alignment</key>
|
|
<applyto>/apps/gconfsharp/sample_app/toolbar_alignment</applyto>
|
|
<owner>sample_app</owner>
|
|
<b> <type>string</type></b>
|
|
<b> <cstype class="Sample.Alignment">enum</cstype></b>
|
|
<locale name="C">
|
|
<short>Toolbar alignment</short>
|
|
<long>Where the toolbar should be. Can be one of Top, Bottom, Left, Rigt.</long>
|
|
</locale>
|
|
<default>Top</default>
|
|
</schema>
|
|
<schema>
|
|
<key>/schemas/apps/gconfsharp/sample_app/text_color</key>
|
|
<applyto>/apps/gconfsharp/sample_app/text_color</applyto>
|
|
<owner>sample_app</owner>
|
|
<b> <type>string</type></b>
|
|
<b> <cstype>color</cstype></b>
|
|
<locale name="C">
|
|
<short>Text color</short>
|
|
<long>Text color</long>
|
|
</locale>
|
|
<default>#000000</default>
|
|
</schema>
|
|
<schema>
|
|
<key>/schemas/apps/gconfsharp/sample_app/enable_text_color</key>
|
|
<applyto>/apps/gconfsharp/sample_app/enable_text_color</applyto>
|
|
<owner>sample_app</owner>
|
|
<type>bool</type>
|
|
<locale name="C">
|
|
<short>Show colored text</short>
|
|
<long>Show colored text</long>
|
|
</locale>
|
|
<default>#000000</default>
|
|
</schema>
|
|
</schemalist>
|
|
</gconfschemafile>
|
|
</pre>
|
|
<p>Note how we specify both the cstype and type for the enum and color.
|
|
This is because GConf doesn't know anything about cstype.</p>
|
|
<p>We save this to sample.schema, and install it with the command:</p>
|
|
<pre>env GCONF_CONFIG_SOURCE="" gconftool-2 --makefile-install-rule sample.schema</pre>
|
|
<p>GConf generates a warning because it doesn't recognize cstype, but
|
|
it is nothing to worry about.</p>
|
|
<p>We're now ready to run SchemaGen. Installing the schema before running
|
|
SchemaGen is not required, but you should make sure to install it before
|
|
running your application, because GConf# will throw an exception if
|
|
GConf can't find your settings.</p>
|
|
<p>SchemaGen's full executable name is <b>gconfsharp-schemagen</b>. It
|
|
takes a namespace and the schema filename as parameters, and outputs
|
|
to the console. Here is the command used to generate Settings.cs for
|
|
sample.schema:</p>
|
|
<pre>gconfsharp-schemagen Sample sample.schema > Settings.cs</pre>
|
|
<p>Now we're ready to write a small program using our new settings.</p>
|
|
<pre>
|
|
namespace Sample
|
|
{
|
|
using System;
|
|
using System.Drawing;
|
|
|
|
public enum Alignment
|
|
{
|
|
Top,
|
|
Bottom,
|
|
Left,
|
|
Right
|
|
}
|
|
|
|
class X
|
|
{
|
|
public static void Main (string args[])
|
|
{
|
|
Alignment align = Settings.ToolbarAlignment;
|
|
Console.WriteLine ("Alignment is: {0}", align);
|
|
Settings.ToolbarAlignment = Left;
|
|
Console.WriteLine ("Color is: {0}", Settings.TextColor);
|
|
Console.WriteLine ("Color is enabled: {0}", Settings.TextEnableColor);
|
|
}
|
|
}
|
|
}
|
|
</pre>
|
|
<p>As you can see, our GConf settings are now nicely encapsulated, and
|
|
are as easy to access as any other .NET properties.</p>
|
|
<h1>Property Editors</h1>
|
|
<p>Property Editors are objects which act as intermediaries between
|
|
GConf and Gtk+ widgets. They are analoguous to the Controller of the MVC
|
|
design pattern. Property editors do two things:
|
|
<ul>
|
|
<li>They listen to GConf notifications, and update the widget
|
|
to reflect any changes in a GConf setting.
|
|
<li>They connect to the various "changed" signals on a widget,
|
|
and update GConf to reflect the widget's current state.</li>
|
|
</ul>
|
|
This means that the widget and GConf are always in sync, no matter
|
|
if the value is set through Gtk+ or through GConf. GConf# defines a
|
|
number of Property Editors which correspond to common widget/setting
|
|
combinations -- for example, a CheckButton representing a boolean
|
|
setting.
|
|
</p>
|
|
<p>GConf# also provides a utility class called <b>EditorShell</b>.
|
|
EditorShell exposes a simple API to automatically construct
|
|
PropertyEditors for a Glade UI.</p>
|
|
<p>As a historical note, and in the interests of giving credit where
|
|
credit is due, it should be noted that GConf Property Editors are
|
|
not unique to GConf#. They were originally conceived and implemented
|
|
by Bradford Hovinen for use in the GNOME Control Center. Although
|
|
the APIs are somewhat similar, the original version was written in
|
|
C and was limited to internal use in the Control Center.</p>
|
|
<h2>Example</h2>
|
|
<p>For this example we'll assume you have written a Glade UI for
|
|
the settings in the previous example. It employs three elements:
|
|
an option menu named "toolbar_menu", a checkbox named "enable_check",
|
|
and a color picker named "colorpicker". Given our Glade.XML object,
|
|
all we have to do is set up the EditorShell.</p>
|
|
<pre>
|
|
Glade.XML gxml = <i>...</i>
|
|
GConf.PropertyEditors.EditorShell shell = new GConf.PropertyEditors.EditorShell (gxml);
|
|
|
|
shell.Add (SettingKeys.ToolbarAlignment, "toolbar_menu", typeof (Sample.Alignment));
|
|
shell.Add (SettingKeys.EnableTextColor, "enable_check");
|
|
shell.Add (SettingKeys.TextColor, "colorpicker");
|
|
</pre>
|
|
<p>That's all that is needed to implement the preferences dialog. Note
|
|
how we didn't have to specify what type of property editor to use.
|
|
The EditorShell uses introspection to create the correct Property
|
|
Editor for all the types of widgets it knows about. Also note that
|
|
because ToolbarAlignment is an enum, we had to pass its type in so that
|
|
the Property Editor can store its value correctly. By default,
|
|
Property Editors assume that the order of elements in an OptionMenu
|
|
(or RadioButton) correspond to the order of values in an enum. If
|
|
this is not the case, you can pass in an additional parameter to
|
|
Add: an array of integers, each array element being the integer
|
|
representation of an enum value. This array represents the order of
|
|
values in your GUI element.
|
|
</p>
|
|
<p>Now, a really good preference dialog would "ghost out" the
|
|
color picker if the "Enable text color" option is disabled. This
|
|
requires a small addition to our previous code:</p>
|
|
<pre>
|
|
shell.AddGuard (SettingKeys.EnableTextColor, "color_box");
|
|
</pre>
|
|
<p>Again, for the purposes of the example, "color_box" is the name of the
|
|
HBox containing the label and color picker corresponding to TextColor.</p>
|
|
<h1></h1>
|
|
<p>
|
|
<font size=-1>
|
|
<i>Last updated: October 19th, 2002 <br />
|
|
Rachel Hestilow <a href="mailto:hestilow@ximian.com">(hestilow@ximian.com)</a></i>
|
|
</font>
|
|
</p>
|
|
</body>
|
|
</html>
|