<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en">
	<id>https://wiki.dabo.leafe.com/index.php?action=history&amp;feed=atom&amp;title=PreferenceDialog</id>
	<title>PreferenceDialog - Revision history</title>
	<link rel="self" type="application/atom+xml" href="https://wiki.dabo.leafe.com/index.php?action=history&amp;feed=atom&amp;title=PreferenceDialog"/>
	<link rel="alternate" type="text/html" href="https://wiki.dabo.leafe.com/index.php?title=PreferenceDialog&amp;action=history"/>
	<updated>2026-11-21T13:30:42Z</updated>
	<subtitle>Revision history for this page on the wiki</subtitle>
	<generator>MediaWiki 1.39.12</generator>
	<entry>
		<id>https://wiki.dabo.leafe.com/index.php?title=PreferenceDialog&amp;diff=4164&amp;oldid=prev</id>
		<title>Ed: Created page with &quot;== Overview == The &#039;&#039;&#039;PreferenceDialog&#039;&#039;&#039; class is designed to make it easy for you to present users with options that they can configure. It ties in very nicely with the &lt;cod...&quot;</title>
		<link rel="alternate" type="text/html" href="https://wiki.dabo.leafe.com/index.php?title=PreferenceDialog&amp;diff=4164&amp;oldid=prev"/>
		<updated>2020-05-15T14:37:04Z</updated>

		<summary type="html">&lt;p&gt;Created page with &amp;quot;== Overview == The &amp;#039;&amp;#039;&amp;#039;PreferenceDialog&amp;#039;&amp;#039;&amp;#039; class is designed to make it easy for you to present users with options that they can configure. It ties in very nicely with the &amp;lt;cod...&amp;quot;&lt;/p&gt;
&lt;p&gt;&lt;b&gt;New page&lt;/b&gt;&lt;/p&gt;&lt;div&gt;== Overview ==&lt;br /&gt;
The &amp;#039;&amp;#039;&amp;#039;PreferenceDialog&amp;#039;&amp;#039;&amp;#039; class is designed to make it easy for you to present users with options that they can configure. It ties in very nicely with the &amp;lt;code&amp;gt;PreferenceManager&amp;lt;/code&amp;gt; class, so you can use a unified approach to managing user preferences and settings.&lt;br /&gt;
&lt;br /&gt;
The &amp;#039;&amp;#039;&amp;#039;PreferenceDialog&amp;#039;&amp;#039;&amp;#039; class is a dialog with one or more pages that contain controls that are used to adjust preferences and settings for your application. Typically, you group related settings onto their own page to make it easy for your users to find what they want to set.&lt;br /&gt;
&lt;br /&gt;
To do this, create pages using the &amp;lt;code&amp;gt;addCategory()&amp;lt;/code&amp;gt; method, and then populate those pages with controls that are bound to the preference settings you wish to manage. &amp;lt;code&amp;gt;addCategory()&amp;lt;/code&amp;gt; takes two parameters: the &amp;lt;code&amp;gt;caption&amp;lt;/code&amp;gt; (required), and the &amp;lt;code&amp;gt;position&amp;lt;/code&amp;gt; (optional; default is to append to the end).&lt;br /&gt;
&lt;br /&gt;
== Example ==&lt;br /&gt;
Here is a very simple example; we will discuss the code below:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;syntaxhighlight lang=&amp;quot;python&amp;quot;&amp;gt;&lt;br /&gt;
import wx&lt;br /&gt;
import dabo&lt;br /&gt;
dabo.ui.loadUI(&amp;quot;wx&amp;quot;)&lt;br /&gt;
from dabo.ui.dialogs.PreferenceDialog import PreferenceDialog&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
class CustomPrefDlg(PreferenceDialog):&lt;br /&gt;
  def addPages(self):&lt;br /&gt;
    # Set the preference keys that we will be using&lt;br /&gt;
    pm = self.PreferenceManager&lt;br /&gt;
    fontKey = pm.fonts&lt;br /&gt;
    checkChangesKey = pm.checkChanges&lt;br /&gt;
    self.preferenceKeys.append(fontKey)&lt;br /&gt;
    self.preferenceKeys.append(checkChangesKey)&lt;br /&gt;
    # Create one page for font prefs, another for updates&lt;br /&gt;
    fontPage = self.addCategory(&amp;quot;Fonts&amp;quot;)&lt;br /&gt;
    # Add controls to the font page.&lt;br /&gt;
    chk = dabo.ui.dCheckBox(fontPage, Caption=&amp;quot;Bold?&amp;quot;, &lt;br /&gt;
      DataSource=fontKey, DataField=&amp;quot;bold&amp;quot;)&lt;br /&gt;
    fontPage.Sizer.append(chk)&lt;br /&gt;
    # Add whatever other controls you need...&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
    # Add controls to the changes page.&lt;br /&gt;
    changesPage = self.addCategory(&amp;quot;Change Management&amp;quot;)&lt;br /&gt;
    chc = dabo.ui.dDropdownList(changesPage, Choices=[&amp;quot;Yes&amp;quot;, &amp;quot;No&amp;quot;, &amp;quot;Maybe&amp;quot;],&lt;br /&gt;
      DataSource=checkChangesKey, DataField=&amp;quot;checkForChanges&amp;quot;)&lt;br /&gt;
    changesPage.Sizer.append(chc)&lt;br /&gt;
    # Add whatever other controls you need...&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
class TestForm(dabo.ui.dForm):&lt;br /&gt;
  def afterInit(self):&lt;br /&gt;
    lbl = dabo.ui.dLabel(self, Caption=&amp;quot;Preference Manager Demo\n&amp;quot; +&lt;br /&gt;
      &amp;quot;Select &amp;#039;Preferences&amp;#039; from the menu.&amp;quot;, WordWrap=True)&lt;br /&gt;
    self.Sizer.append(lbl, halign=&amp;quot;center&amp;quot;)&lt;br /&gt;
&lt;br /&gt;
if __name__ == &amp;#039;__main__&amp;#039;:&lt;br /&gt;
  app = dabo.dApp(BasePrefKey = &amp;quot;demo.PrefDialog&amp;quot;)&lt;br /&gt;
  app.MainFormClass = TestForm&lt;br /&gt;
  app.PreferenceDialogClass = CustomPrefDlg&lt;br /&gt;
  app.start()&lt;br /&gt;
&amp;lt;/syntaxhighlight&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Defining the Custom Dialog class ==&lt;br /&gt;
The only method we typically have to override is the &amp;lt;code&amp;gt;addPages()&amp;lt;/code&amp;gt; method. As the name suggests, this is where we add the pages we need for our app&amp;#039;s settings. In this example, we only are using two: one for font settings, and one for tracking changes.&lt;br /&gt;
&lt;br /&gt;
== Preference Objects ==&lt;br /&gt;
This is also a good illustration of how to use the &amp;lt;code&amp;gt;PreferenceManager&amp;lt;/code&amp;gt; object. You simply define attributes of that object, and they are automagically added to it. In this example, we use &amp;lt;code&amp;gt;pm&amp;lt;/code&amp;gt; as the name of the app&amp;#039;s &amp;lt;code&amp;gt;PreferenceManager&amp;lt;/code&amp;gt; object, which has a path of &amp;lt;code&amp;gt;demo.PrefDialog&amp;lt;/code&amp;gt;, which is the app&amp;#039;s &amp;lt;code&amp;gt;BasePrefKey&amp;lt;/code&amp;gt;. We then create keys off of it named &amp;lt;code&amp;gt;fonts&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;checkChanges&amp;lt;/code&amp;gt; by simply referencing those keys as attributes of &amp;lt;code&amp;gt;pm&amp;lt;/code&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
One cool thing about preference objects is that they can either persist their value as soon as you set it, or they can cache those changes until you either call their &amp;lt;code&amp;gt;persist()&amp;lt;/code&amp;gt; method (to save) or their &amp;lt;code&amp;gt;cancel()&amp;lt;/code&amp;gt; method to discard the changes. This behavior is controlled by the &amp;lt;code&amp;gt;AutoPersist&amp;lt;/code&amp;gt; property of the preference object, but we don&amp;#039;t have to worry about dealing with that here. Simply add any preference keys whose values you want to manage to the &amp;lt;code&amp;gt;PreferenceDialog&amp;lt;/code&amp;gt;&amp;#039;s &amp;lt;code&amp;gt;preferenceKeys&amp;lt;/code&amp;gt; list, and their persistence settings will be handled for you. If the user cancels out of the dialog, none of the changes they made will be saved.&lt;br /&gt;
&lt;br /&gt;
== Adding the Pages ==&lt;br /&gt;
Now that we have the preference information set, we call the &amp;lt;code&amp;gt;addCategory()&amp;lt;/code&amp;gt; method to create the page for the font settings, passing in the caption &amp;#039;&amp;#039;&amp;#039;&amp;quot;Fonts&amp;quot;&amp;#039;&amp;#039;&amp;#039;. This method adds the page to the dialog&amp;#039;s paged control, and returns a reference to the newly-created page. We then use as the parent for the controls used for the font settings. To keep things simple, we have a single setting, called &amp;lt;code&amp;gt;bold&amp;lt;/code&amp;gt;. In a real app, you&amp;#039;d probably have default font faces, sizes, etc., but this will do for this demo. What&amp;#039;s critical to note are the [[DataSource]] and [[DataField]] properties: [[DataSource]] is set to the &amp;lt;code&amp;gt;fontKey&amp;lt;/code&amp;gt; object we defined, and [[DataField]] is set to &amp;lt;code&amp;gt;bold&amp;lt;/code&amp;gt;. This will automagically add the subkey of &amp;lt;code&amp;gt;bold&amp;lt;/code&amp;gt; to the &amp;lt;code&amp;gt;fontKey&amp;lt;/code&amp;gt; preference object (if it doesn&amp;#039;t already exist), making the full key path for this &amp;lt;code&amp;gt;demo.prefDialog.fonts.bold&amp;lt;/code&amp;gt;. Also, if there already is a setting saved for this key, it will be retrieved, and the control&amp;#039;s &amp;lt;code&amp;gt;Value&amp;lt;/code&amp;gt; will be set accordingly. We repeat this for the change management page, but this time we use a dropdown list to present the user with 3 options. This value will be saved to the preference database when the user clicks &amp;lt;code&amp;gt;OK&amp;lt;/code&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
== Defining the Form ==&lt;br /&gt;
The form really doesn&amp;#039;t do anything in this demo, so all we do is add a descriptive label.&lt;br /&gt;
&lt;br /&gt;
== Setting Up the Application ==&lt;br /&gt;
There are a few basic properties of the application object that we need to set:&lt;br /&gt;
&lt;br /&gt;
* &amp;#039;&amp;#039;&amp;#039;BasePrefKey:&amp;#039;&amp;#039;&amp;#039; This is the unique name under which your preferences are saved. For this demo I chose a subkey of prefDialog off of a main demo key.&lt;br /&gt;
* &amp;#039;&amp;#039;&amp;#039;MainFormClass:&amp;#039;&amp;#039;&amp;#039; the class used by the app for its startup form.&lt;br /&gt;
* &amp;#039;&amp;#039;&amp;#039;PreferenceDialogClass:&amp;#039;&amp;#039;&amp;#039; The class to display when the user selects the Preferences menu item. In this example, it is the CustomPrefDlg class we defined.&lt;/div&gt;</summary>
		<author><name>Ed</name></author>
	</entry>
</feed>