[[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 <eiffel>interface</eiffel>. This cluster provides some basic classes which can be used to graphically display and manipulate the <eiffel>PREFERENCE</eiffel> 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''' 
|- 
| <eiffel>INTEGER_PREFERENCE</eiffel>
| <eiffel>STRING_PREFERENCE_WIDGET</eiffel>
|- 
| <eiffel>BOOLEAN_PREFERENCE</eiffel>
| <eiffel>BOOLEAN_PREFERENCE_WIDGET</eiffel>
|- 
| <eiffel>STRING_PREFERENCE</eiffel>
| <eiffel>STRING_PREFERENCE_WIDGET</eiffel>
|- 
| <eiffel>ARRAY_PREFERENCE</eiffel>
| <eiffel>STRING_PREFERENCE_WIDGET</eiffel> or <eiffel>CHOICE_PREFERENCE_WIDGET</eiffel>
|- 
| <eiffel>COLOR_PREFERENCE</eiffel>
| <eiffel>COLOR_PREFERENCE_WIDGET</eiffel>
|- 
| <eiffel>FONT_PREFERENCE</eiffel>
| <eiffel>FONT_PREFERENCE_WIDGET</eiffel>
|}


All of these widgets inherit the abstract base class <eiffel>PREFERENCE_WIDGET</eiffel> and implement the required deferred features therein. Each implementation implements handling of an <eiffel>EV_GRID_ITEM</eiffel> widget from EiffelVision2 for use in the <eiffel>EV_GRID</eiffel> control, which allows for viewing and editing of the underlying preference value. For example, <eiffel>BOOLEAN_PREFERENCE_WIDGET</eiffel> uses an <eiffel>EV_GRID_CHECKABLE_LABEL_ITEM</eiffel> to display the 'True' and 'False' properties of a <eiffel>BOOLEAN_PREFERENCE</eiffel>. Another example: <eiffel>CHOICE_PREFERENCE_WIDGET</eiffel> uses <eiffel>EV_GRID_CHOICE_ITEM</eiffel>, 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 <eiffel>change_item_widget</eiffel> to an instance of <eiffel>EV_GRID</eiffel>.

By default the library provides such a view, in the form of <eiffel>PREFERENCES_GRID_CONTROL</eiffel>, and for easier usage <eiffel>PREFERENCES_GRID_DIALOG</eiffel>, which is a dialog control that contains a grid <eiffel>PREFERENCES_GRID_CONTROL</eiffel> and has all the necessary logic to handle graphical manipulation of the preference types provided in the library.

The <eiffel>PREFERENCES_GRID_DIALOG</eiffel>  is a <eiffel>EV_DIALOG</eiffel> 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 <eiffel>PREFERENCES_GRID_CONTROL</eiffel> 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.




