[[Property:title|Interface for preferences]]
[[Property:weight|2]]
[[Property:uuid|6f4964b1-8cf6-d9d4-0778-94d8a3737cad]]
This document describes the use of graphical widgets to display and manipulate preferences.
The preference library contains a cluster called interface. This cluster provides some basic classes which can be used to graphically display and manipulate the PREFERENCE types used by the library. There are various widget classes which correspond to particular types of preferences and can be used to view and change the values of an associated preference. The table below illustrates which widgets are used to display each of the known preference types:
{| border="1"
|-
| '''Preference Type'''
| '''Associated Widget'''
|-
| INTEGER_PREFERENCE
| STRING_PREFERENCE_WIDGET
|-
| BOOLEAN_PREFERENCE
| BOOLEAN_PREFERENCE_WIDGET
|-
| STRING_PREFERENCE
| STRING_PREFERENCE_WIDGET
|-
| ARRAY_PREFERENCE
| STRING_PREFERENCE_WIDGET or CHOICE_PREFERENCE_WIDGET
|-
| COLOR_PREFERENCE
| COLOR_PREFERENCE_WIDGET
|-
| FONT_PREFERENCE
| FONT_PREFERENCE_WIDGET
|}
All of these widgets inherit the abstract base class PREFERENCE_WIDGET and implement the required deferred features therein. Each implementation implements handling of an EV_GRID_ITEM widget from EiffelVision2 for use in the EV_GRID control, which allows for viewing and editing of the underlying preference value. For example, BOOLEAN_PREFERENCE_WIDGET uses an EV_GRID_CHECKABLE_LABEL_ITEM to display the 'True' and 'False' properties of a BOOLEAN_PREFERENCE. Another example: CHOICE_PREFERENCE_WIDGET uses EV_GRID_CHOICE_ITEM, when the widget is loaded it displays the current value of the associated preference in the combo box. When the user changes the combo box value the preference value is changed also, and optionally saved.
Using these supplied widgets in your interface is simply a matter of creating the object and adding the change_item_widget to an instance of EV_GRID.
By default the library provides such a view, in the form of PREFERENCES_GRID_CONTROL, and for easier usage PREFERENCES_GRID_DIALOG, which is a dialog control that contains a grid PREFERENCES_GRID_CONTROL and has all the necessary logic to handle graphical manipulation of the preference types provided in the library.
The PREFERENCES_GRID_DIALOG is a EV_DIALOG with a navigable tree/grid for finding groups of related preferences (i.e. managers), and the various preferences as a row. It is a useful, general purpose interface for preference manipulation.
You have the possibility to view the preferences as a ''tree'', or a ''flat view''. In this ''flat view'', you can filter the preferences to find easily a preference.
As with preferences themselves you may create your own custom view if this dialog is not sufficient for your needs, and can use the code therein as a template for your own code. You can also use the PREFERENCES_GRID_CONTROL to embed the preferences grid control in your application interface.
Below is an image of the supplied window as it appears in the EiffelStudio preferences environment.
[[Image:preference-window]]
For an example of creating custom widget views for individual preferences, or a custom view for all preferences, please refer to the [[EiffelPreferences Sample|example]] in this documentation.