\section{Prefs}
\label{group__Prefs}\index{Prefs@{Prefs}}


\subsection{Detailed Description}
\hypertarget{group__Prefs_elm-prefs-widget}{}\subsection{Prefs}\label{group__Prefs_elm-prefs-widget}
 
\begin{DoxyImage}
\includegraphics{img/widget/prefs/preview-00}
\caption{width=}
\end{DoxyImage}


 
\begin{DoxyImageNoCaption}
  \mbox{\includegraphics{prefs_inheritance_tree}}
\end{DoxyImageNoCaption}


Prefs is a special widget inside Elementary. It is mainly targeted to configuration dialogs. Its viewport is blank until you associate a definition file to it. That file (usually with {\bfseries }.epb extension), is a binary format (Eet) one, coming from a human-\/readable textual declaration. This textual form, an {\bfseries Elementary prefs collection} (usually with {\bfseries }.epc extension), is translated to the binary form by means of the {\bfseries prefs\+\_\+cc} compiler.

On it one declares U\+I elements to populate prefs widgets, which are contained in {\bfseries pages} (a prefs widget is always bound to one page). Those elements get properties like\+:
\begin{DoxyItemize}
\item default value,
\item maximum and minumum ranges,
\item acceptance and denial regular expressions, for strings,
\item visibility,
\item persistence,
\item editability, etc.
\end{DoxyItemize}

Once a prefs widget is created, after elm\+\_\+prefs\+\_\+file\+\_\+set() is issued on it, all of its U\+I elements will get default values, declared on that file. To fetch an user's own, personal set of those values, one gets to pair an {\bfseries \hyperlink{group__Elm__Prefs_elm-prefs-data}{Prefs Data}} handle to the prefs widget.

Personal, prefs data values with keys matching the ones present on the file passed on elm\+\_\+prefs\+\_\+file\+\_\+set() to will have their values applied to the respective U\+I elements of the widget.

When a prefs widget dies, the values of the elements declared on its {\bfseries }.epb file marked as permanent {\bfseries will be written back} to the user prefs data handle, if it is writable. One is also able to make this writing event to take place automatically after each U\+I element modification by using elm\+\_\+prefs\+\_\+autosave\+\_\+set().

This widget emits the following signals\+:
\begin{DoxyItemize}
\item {\ttfamily \char`\"{}page,saved\char`\"{}}\+: a given page has had its values saved back on user config file (event info is the page's name)
\item {\ttfamily \char`\"{}page,reset\char`\"{}}\+: a given page has had its values reset (event info is the page's name)
\item {\ttfamily \char`\"{}page,changed\char`\"{}}\+: a given page has been loaded {\bfseries with user ({\ttfamily }.cfg) values} (event info is the page's name)
\item {\ttfamily \char`\"{}page,loaded\char`\"{}}\+: a given page has been loaded {\bfseries with system ({\ttfamily }.epb) values} (event info is the page's name)
\item {\ttfamily \char`\"{}item,changed\char`\"{}}\+: a given page's item has changed (event info is the item's full hierarchical name, in the form {\ttfamily \char`\"{}page\+:subpage\+:subsubpage\+:item\char`\"{}})
\item {\ttfamily \char`\"{}action\char`\"{}}\+: an action item has been triggered (event info is the item's full hierarchical name, in the form {\ttfamily \char`\"{}page\+:subpage\+:subsubpage\+:item\char`\"{}})
\end{DoxyItemize}

\begin{DoxyItemize}
\item \hyperlink{epcref}{Elementary Prefs Data Collection Reference}\end{DoxyItemize}
The following are examples on how to use prefs\+: \begin{DoxyItemize}
\item \hyperlink{prefs_example_01}{Prefs Example 01} \item \hyperlink{prefs_example_02}{Prefs Example 02} \item \hyperlink{prefs_example_03}{Prefs Example 03} \end{DoxyItemize}
