Class: Ruber::SettingsDialogManager

Class which takes care of automatically syncronize (some of) the options in an SettingsContainer with the widgets in the SettingsDialog.

In the following documentation, the widgets passed as argument to the constructor will be called upper level widgets, because they’re the topmost widgets this class is interested in. The term child widget will be used to refer to any widget which is child of an upper level widget, while the generic widget can refer to both. The upper level widget corresponding to a widget is the upper level widget the given widget is child of (or the widget itself if it already is an upper level widget)

To syncronize options and widgets contents, this class looks among the upper level widgets and their children for the widget which have an object_name of the form _group__option, that is: an underscore, a group name, two underscores, an option name (both the group and the option name can contain underscores. This is the reason for which two underscores are used to separate them). Such a widget is associated with the option with name name belonging to the group group.

Having a widget associated with an option means three things: 1. when the widget emits some signals (which mean that the settings have changed, the dialog’s Apply button is enabled) 2. when the dialog is displayed, the widget is updated so that it displays the value stored in the SettingsContainer 3. when the Apply or the OK button of the dialog is clicked, the option in the SettingsContainer is updated with the value of the widget.

For all this to happen, who writes the widget (or the upper level widget the widget is child of) must give it several custom properties (this can be done with the UI designer, if it is used to create the widget, or by hand). These properties are:

• signal: it’s a string containing the signal(s) on which the Apply button of the dialog will be enabled. If more than one signal should be used, you can specify them using a YAML array (that is, enclose them in square brackets and separate them with a comma followed by one space). If the widget has only a single signal with that name, you can omit the signal’s signature, otherwise you need to include it (for example, Qt::LineEdit has a single signall called textChanged, so you can simply use that instead of textChanged(QString). On the other hand, Qt::ComboBox has two signals called currentIndexChanged, so you must fully specify them: currentIndexChanged(QString) or currentIndexChanged(int)).
• read: is the method to use to sync the value in the widget with that in the SettingsContainer. The reason of the name “read” is that it is used to read the value from the container.
• store: is the method to use to sync the value in the SettingsContainer with that in the widget.
• access: a method name to derive the read and the store methods from. The store method has the same name as this property, while the read method has the same name with ending “?” and “!” removed and an ending “=” added.

In the documentation for this class, the term read method refers to the method specified in the read property or derived from the access property by adding the = to it. The term store method refers to the method specified in the store or access property.

If the read, store or access properties start with a $, they’ll be called on the upper level widget corresponding to the widget, instead than on the widget itself.

Not all of the above properties need to be specified. In particular, the access property can’t coexhist the read and the store properties. On the other hand, you can’t give only one of the read and store properties. If you omit the access, store and read property entierely, and the signal property only contains one signal, then an access property is automatically created using the name of the signal after having removed from its end the strings ‘Edited’, ‘Changed’, ‘Modified’, ‘_edited’, ‘_changed’, ‘_modified’ (for example, if the signal is ’textChanged(QString), then the access property will become text.

If the signal property hasn’t been specified, a default one will be used, depending on the class of the widgets. See the documentation for DEFAULT_PROPERTIES to see which signals will be used for which classes. If neither the access property nor the read and store properties have been given, a default access property will also be used. If the class of the widget is not included in DEFAULT_PROPERTIES, an exception will be raised.

A read method must accept one argument, which is the value of the option, and display it in the corresponding widget in whichever way is appropriate. A store method, instead, should take no arguments, retrieve the option value from the widget, again using the most appropriate way, and return it.

Often, the default access method is almost, but not completely, enough. For example, if the widget is a KDE::UrlRequester, but you want to store the option as a string, instead of using a KDE::Url, you’d need to create a method whose only task is to convert a KDE::Url to a string and vice versa. The same could happen with a symbol and a Qt::LineEdit. To avoid such a need, this class also performs automatic conversions, when reading or storing an option. It works this way: if the value to store in the SettingsContainer or in the widget are of a different class from the one previously contained there, the DEFAULT_CONVERSIONS hash is scanned for an entry corresponding to the two classes and, if found, the value returned by the corresponding Proc is stored instead of the original one.

===Example

Consider the following situation:

Options: OpenStruct.new({:name => :number, :group => :G1, :default => 4}):: this is an option which contains an integral value, with default 4 OpenStruct.new({:name => :path, :group => :G1, :default => ENV[[‘HOME’]]}):: this is an option which contains a string representing a path. The default value is the user’s home directory (contained in the environment variable HOME) OpenStruct.new({:name => :list, :group => :G2, :default => %w[a b c]}):: this is an option which contains an array of strings, with default value [‘a’, ‘b’, ‘c’].

Widgets:

There’s a single upper level widget, of class MyWidget, which contains a Qt::SpinBox, a KDE::UrlRequester and a Qt::LineEdit. The value displayed in the spin box should be associated to the :number option, while the url requester should be associated to the :path option. The line edit widget should be associated with the :list option, by splitting the text on commas.

We can make some observations:

• the spin box doesn’t need anything except having its name set to match the :number option: the default signal and access method provided by DEFAULT_PROPERTIES are perfectly adequate to this situation.
• the url requester doesn’t need any special settings, aside from the object name: the default signal and access method provided by DEFAULT_PROPERTIES are almost what we need and the only issue is that the methods take and return a KDE::Url instead of a string. But since the DEFAULT_CONVERSIONS contains conversion procs for this pair of classes, even this is handled automatically
• the line edit requires custom read and store methods (which can be specified with a signle access property), because there’s no default conversion from array to string and vice versa. The default signal, instead, is suitable for our needs, so we don’t need to specify one.

Here’s how the class MyWidget could be written (here, all widgets are created manually. In general, it’s more likely that you’d use the Qt Designer to create it. In that case, you can set the widgets’ properties using the designer itself). Note that in the constructor we make use of the block form of the widgets’ constructors, which evaluates the given block in the new widget’s context.

class MyWidget < Qt::Widget def initialize parent = nil super @spin_box = Qt::SpinBox.new{ self.object_name = ’_G1__number’} @url_req = KDE::UrlRequester.new= ’_G1__path’ @line_edit = Qt::LineEdit.new do self.object_name = ‘_G2__list’ set_property ‘access’, ‘$items’ end end

1. This is the store method for the list option. It takes the text in the line
2. edit and splits it on commas, returning the array def items @line_edit.text.split ‘,’ end

1. This is the read method for the list option. It takes the array containing
2. the value of the option (an array) as argument, then sets the text of the
3. line edit to the string obtained by calling join on the array def items= array @line_edit.text = array.join ‘,’ end

end