Changed params to processPrefsTree 02 Jan 2002
-Original11 Dec 2001
- - -Steve Meredith
+
+
+
+
+
+
+
+ -Original
- - -Steve Meredith
Changed params to processPrefsTree
+02 Jan 2002
+ Original11 Dec 2001
+ Steve Meredith
+
+
+ Original
+ Steve Meredith
+
How to Add a PrefsTree Pref Editor Widget to a CCK Wizard Page
+Introduction
- -The Pref Editor is a widget for CCK/Factory, named PrefsTree in .ini -files. It is a tree control which displays prefs in a hierarchy and allows -a user to edit their values. It reads an XML file to determine the structure -of the tree control. The details of the XML file format can be found in the -document PrefsTreeFileFormat.htm - -. That document, together with this one, describe how to add a pref editor tree control to CCK. - + The Pref Editor is a widget for CCK/Factory, named PrefsTree in +.ini files. It is a tree control which displays prefs in a hierarchy and +allows a user to edit their values. It reads an XML file to determine the +structure of the tree control. The details of the XML file format can be +found in the document PrefsTreeFileFormat.htm. +That document, together with this one, describe how to add a pref editor +tree control to CCK.Example
- -The easiest way to understand how to add a PrefsTree pref edit widget is to look at an example.-
-
--
+ The easiest way to understand how to add a PrefsTree pref edit widget is +to look at an example.
+
+
+ +
+
The INI File
- -The .ini file used to insert this pref editor onto this widget page is as follows:-
-[Local Variables]
-Name=PrefsTree
-Title=Advanced Preferences
-Caption=1st level node
-Help=Online;%Root%Help\PrefsTree.html
-[Navigation Controls]
-onEnter=
-onNext=
-Help=
-[Image 4200]
-Type=Image
-Name=prefstree.bmp
-Value=
-Start_x=0
-Start_y=0
-Width=425
-Height=56
-[Widget 4201]
-Type=GlobalText
-Name=Text4201
-Value=Browse this tree to find other preferences that you want to customize. Double-click to edit.
-Start_x=0
-Start_y=32
-Width=400
-Height=30
-[Widget 4202]
-Type=PrefsTree
-Name=AdvancedPrefs
-Attrib=MetaPrefs.xml
-Value=
-Start_x=0
-Start_y=45
-Width=405
-Height=181
| Above is the section which defines the PrefsTree widget. The Name is important if you want to hook up the control to some buttons, as in our example. The Attrib
- specifies the name of the prefs XML file. This file belongs in the root
-with the .exe files. Once edited, a copy of the file gets saved in the working
-config directory. This is where install builder picks up its values. The
- Value is not used. |
-[Widget 4203]
-Type=Button
-Name=Button4203
-Value=Open
-Start_x=0
-Start_y=232
-Width=40
-Height=14
-onCommand=OpenPrefTreeItem(AdvancedPrefs)
| Above is the section defining the "Open" button. When pressed, it calls OpenPrefTreeItem()
- for the PrefsTree widget named in the parameter. If a pref is selected,
-a dialog is open which allows the user to edit that text. If a group is selected,
-then that group is expanded or collapsed, depending on its current state.
-You can also use the right-button menu to open a pref for editing. |
-[Widget 4204]
-Type=Button
-Name=Button4204
-Value=Find Pref
-Start_x=50
-Start_y=232
-Width=40
-Height=14
-onCommand=FindPrefTreeItem(AdvancedPrefs)
| Above is the section defining the "Find Pref" button. When pressed, it calls FindPrefTreeItem() for the PrefsTree widget named in the parameter. This function opens a find
-dialog which is used to find any text associated with a pref. It searches
-the pref name, its description, and its files for the text. You can also
-use the right-button menu to open the find dialog. |
-[Widget 4205]
-Type=Button
-Name=Button4205
-Value=Find Next
-Start_x=100
-Start_y=232
-Width=40
-Height=14
-onCommand=FindNextPrefTreeItem(AdvancedPrefs)
| Above is the section to define the "Find Next" button. When pressed, if calls FindNextPefTreeItem()
- for the PrefsTree widget named in the parameter. This function selects the
-next pref which matches the last text search. It opens a find dialog if "Find Pref" was never used. |
-[Widget 4206]
-Type=Button
-Name=Button4206
-Value=Add Pref
-Start_x=150
-Start_y=232
-Width=40
-Height=14
-onCommand=AddPrefTreeItem(AdvancedPrefs)+ The .ini file used to insert this pref editor onto this widget page is +as follows:
+
+ [Local Variables]
+ Name=PrefsTree
+ Title=Advanced Preferences
+ Caption=1st level node
+ Help=Online;%Root%Help\PrefsTree.html
-
-Above is the section to define the "Add Pref" button. It calls AddPrefTreeItem() for the PrefsTree widget named in the parameter. This function opens the add dialog which prompts the user for the name and description of the new pref. It then open the edit dialog which allows the user to set the value of the new pref.
+ onEnter=
+ onNext=
+ Help=
+
+ [Image 4200]
+ Type=Image
+ Name=prefstree.bmp
+ Value=
+ Start_x=0
+ Start_y=0
+ Width=425
+ Height=56
+
+ [Widget 4201]
+ Type=GlobalText
+ Name=Text4201
+ Value=Browse this tree to find other preferences that you want to customize.
+Double-click to edit.
+ Start_x=0
+ Start_y=32
+ Width=400
+ Height=30
+
+ [Widget 4202]
+ Type=PrefsTree
+ Name=AdvancedPrefs
+ Attrib=MetaPrefs.xml
+ Value=
+ Start_x=0
+ Start_y=45
+ Width=405
+ Height=181
+
+
+
+
+
+ Above is the section which defines the PrefsTree widget.
+The Name is important if you want to hook up the control to some
+buttons, as in our example. The Attrib specifies the name of the
+prefs XML file. This file belongs in the root with the .exe files. Once edited,
+a copy of the file gets saved in the working config directory. This is where
+install builder picks up its values. The Value is not used.
+
+
+
+
+ [Widget 4203]
+ Type=Button
+ Name=Button4203
+ Value=Open
+ Start_x=0
+ Start_y=232
+ Width=40
+ Height=14
+ onCommand=OpenPrefTreeItem(AdvancedPrefs)
+
+
+
+
+ Above is the section defining the
+"Open" button. When pressed, it calls OpenPrefTreeItem() for the
+PrefsTree widget named in the parameter. If a pref is selected, a dialog
+is open which allows the user to edit that text. If a group is selected, then
+that group is expanded or collapsed, depending on its current state. You
+can also use the right-button menu to open a pref for editing.
+
+
+
+
+
+ [Widget 4204]
+ Type=Button
+ Name=Button4204
+ Value=Find Pref
+ Start_x=50
+ Start_y=232
+ Width=40
+ Height=14
+ onCommand=FindPrefTreeItem(AdvancedPrefs)
+
+
+
+
+ Above is the section defining the
+"Find Pref" button. When pressed, it calls FindPrefTreeItem() for
+the PrefsTree widget named in the parameter. This function opens a find
+ dialog which is used to find any text associated with a pref.
+It searches the pref name, its description, and its files for the text. You
+can also use the right-button menu to open the find dialog.
+
+
+
+
+
+ [Widget 4205]
+ Type=Button
+ Name=Button4205
+ Value=Find Next
+ Start_x=100
+ Start_y=232
+ Width=40
+ Height=14
+ onCommand=FindNextPrefTreeItem(AdvancedPrefs)
+
+
+
+
+ Above is the section to define the
+"Find Next" button. When pressed, if calls FindNextPefTreeItem()
+ for the PrefsTree widget named in the parameter. This function selects the
+next pref which matches the last text search. It opens a find dialog
+if "Find Pref" was never used.
+
+
+
+
+
+ [Widget 4206]
+ Type=Button
+ Name=Button4206
+ Value=Add Pref
+ Start_x=150
+ Start_y=232
+ Width=40
+ Height=14
+ onCommand=AddPrefTreeItem(AdvancedPrefs)
+
+
+
+
+
+ Above is the section to define the
+"Add Pref" button. It calls AddPrefTreeItem() for the PrefsTree
+widget named in the parameter. This function opens the add dialog
+which prompts the user for the name and description of the new pref. It then
+open the edit dialog which allows the user to set the value of the
+new pref.
+
+
+
+
+
SCRIPT.IB
-
-A SCRIPT.IB entry must be made in order for Install Builder process the .XML file: processPrefsTree(PrefFile.xml,browser.xpi,bin/netscp6.cfg)
-. Spaces are not allowed between the parameters. The first parameter must
-be the name of the file as specified in the .ini file. The second param is
-the .xpi file that the preference file is in. The first paramater is the
-preferences file. If it ends with a .cfg, then it will be hashed.
-
-
\ No newline at end of file
+ A SCRIPT.IB entry must be made in order for Install Builder process the
+.XML file: processPrefsTree(PrefFile.xml,browser.xpi,bin/netscp6.cfg).
+Spaces are not allowed between the parameters. The first parameter must be
+the name of the file as specified in the .ini file. The second param is the
+.xpi file that the preference file is in. The first paramater is the preferences
+file. If it ends with a .cfg, then it will be hashed.
+
+
+
+
diff --git a/cck/docs/prefstree/PrefsTreeFileFormat.htm b/cck/docs/prefstree/PrefsTreeFileFormat.htm
index d49f09845524..d792dac6bb4e 100644
--- a/cck/docs/prefstree/PrefsTreeFileFormat.htm
+++ b/cck/docs/prefstree/PrefsTreeFileFormat.htm
@@ -1,424 +1,484 @@
-
-
-
+
+
+
Structure of the Pref Editor XML File for the PrefsTree Widget
-
-
-Removed MANAGE element. Added REMOTEADMIN
-element and default attribute 13 Feb 2002
-Mention the XSL stylesheet. 30 Jan 2002
- Added useradded attribute 28 Jan 2002
- Added the MANAGE element. 24 Jan 2002
- Removed elements INSTALLATIONFILE and PREFFILE. Changed
-processPrefsTree() number of params. 02 Jan
-2002
- Removed choose attribute. 13 Dec 2001
- Original version. 11 Dec 2001
- Steve Meredith
-
-
+
+
+Added tag METAPREFS. Added UTF-8 indicator to
+XML. 18 May 2002
+ Removed MANAGE element. Added REMOTEADMIN element and
+default attribute 13 Feb 2002
+ Mention the XSL stylesheet. 30 Jan 2002
+ Added useradded attribute 28 Jan 2002
+ Added the MANAGE element. 24 Jan 2002
+ Removed elements INSTALLATIONFILE and PREFFILE. Changed
+ processPrefsTree() number of params. 02 Jan
+ 2002
+ Removed choose attribute. 13 Dec 2001
+ Original version. 11 Dec 2001
+ Steve Meredith
+
+
Structure of the Pref Editor XML File for the PrefsTree Widget
-
+
Introduction
- The Pref Editor is a widget for CCK/Factory, named PrefsTree
- in .ini files. It is a tree control which displays prefs in a hierarchy
-and allows a user to edit their values. It reads an XML file to determine
-the structure of the tree control. This XML file includes information on
+ The Pref Editor is a widget for CCK/Factory, named PrefsTree
+ in .ini files. It is a tree control which displays prefs in a hierarchy
+ and allows a user to edit their values. It reads an XML file to determine
+ the structure of the tree control. This XML file includes information on
each pref, including its name, its default value, a description of it, etc.
It also includes structure for how these prefs are grouped in the tree control.
-The name of the XML file is specified in the .ini section for the PrefsTree
-Widget. The default file must be located in the same directory as the
-WIZARDMACHINE.EXE . When used, a copy of the file is saved in the working
-config directory. This copy contains the changes made by the CCK/Factory
+ The name of the XML file is specified in the .ini section for the PrefsTree
+ Widget. The default file must be located in the same directory as the
+ WIZARDMACHINE.EXE . When used, a copy of the file is saved in the working
+ config directory. This copy contains the changes made by the CCK/Factory
user, and is used by the install builder to write preferences in the install
image. A SCRIPT.IB entry must be made in order for it process the
-.XML file: processPrefsTree(,browser.xpi,bin/netscp6.cfg)
-. Note that spaces are not allowed between the parameters. For details on
-adding a PrefsTree control to wizard pages, see the document
-PrefsTree.htm
-
+.XML file: processPrefsTree(MetaPrefs.xml,browser.xpi,bin/netscp6.cfg)
+ . Note that spaces are not allowed between the parameters (CCK limitation).
+For details on adding a PrefsTree control to wizard pages, see the document PrefsTree.htm
+
Who This Document is For
- You will need to understand the structure of the XML file if you want to
-add or remove prefs to the Pref Editor or change how they are grouped.
-
+ You will need to understand the structure of the XML file if you want
+to add or remove prefs to the Pref Editor or change how they are grouped.
+
+
A Note on Prefs
- The XML described herein contains elements for prefs and elements to control
-how they are grouped in a UI. It was specifically designed for use in this
-Pref Editor tree control, but a complete representation of prefs in
-XML could be useful in other ways. But for this use, the only prefs which
-should be included in this file are prefs which can be set in advance and
-saved to a .cfg or .jsc file. Note that this excludes some prefs which might
-be found in a profile prefs.js , such as those prefs which define
-specific mail and news accounts, servers, and identities. These pref names
-are generated on the fly by the client. If this XML is to be expanded for
-use in other ways, for example as described in
-Bugzilla bug 17199 , new tags could be added to each pref to indicate
-whether or not it could be set in advance and stored in a .cfg file. The
-Pref Editor would have to be modified to respect this new information and
-only present the appropriate prefs for editting. Otherwise, any new elements
-and attributes are ignored as long as the basic structure of the file remains
-valid (<PREF>s are grouped within <PREFSGROUP>
-s) and the required attributes and subelements exist.
-
- The following prefs should not be placed into this XML file for use in
-the prefs editor because they are handled outside the prefs editor, and used
-to point to the file created by the install builder and prefs editor.
-
+ The XML described herein contains elements for prefs and elements to
+control how they are grouped in a UI. It was specifically designed for use
+in this Pref Editor tree control, but a complete representation of
+prefs in XML could be useful in other ways. But for this use, the only prefs
+which should be included in this file are prefs which can be set in advance
+and saved to a default .js, .cfg or remote .jsc file. Note that this excludes
+some prefs which might be found in a profile prefs.js , such as those
+prefs which define specific mail and news accounts, servers, and identities.
+These pref names are generated on the fly by the client. If this XML is to
+be expanded for use in other ways, for example as described in Bugzilla bug 17199
+, new tags could be added to each pref to indicate whether or not it could
+be set in advance and stored in a .cfg file. The Pref Editor would have to
+be modified to respect this new information and only present the appropriate
+prefs for editting. Otherwise, any new elements and attributes are ignored
+as long as the basic structure of the file remains valid (<PREF>s
+are grouped within <PREFSGROUP> s) and the required attributes
+and subelements exist.
+
+ The following prefs should not be placed into this XML file for use in
+ the prefs editor because they are handled outside the prefs editor, and
+used to point to the file created by the install builder and prefs editor.
+
- - autoadmin.global_config_url
- - autoadmin.failover_to_cached
- - autoadmin.offline_failover
- - autoadmin.refresh_interval
-
-
+ - autoadmin.global_config_url
+ - autoadmin.failover_to_cached
+ - autoadmin.offline_failover
+ - autoadmin.refresh_interval
+
+
-
+
Problem Prefs
-
+
- - browser.search.defaultengine: This is a string type, but
-it looks like it's a URL to a local file (engine://). I can't set this to
-a resonable default value as I don't know where Netscape is going to be installed.
-
- - browser.startup.homepage:
-Problem when used with lockPref().
- - network.cookie.p3plevel has an interaction with network.cookie.p3p
-. When you change network.cookie.p3p, network.cookie.p3plevel
- should get set to some value. This happens in the pref code in the browser.
-There is no way to do this with the Pref Editor right now--prefs are treated
-as individual entities. For now I have commented what is supposed to happen
-in the description text for these prefs. In the future, perhaps we could define
-such relationships in the XML.
-
+ - browser.search.defaultengine: This is a string type, but
+ it looks like it's a URL to a local file (engine://). I can't set this to
+ a resonable default value as I don't know where Netscape is going to be
+installed.
+ - browser.startup.homepage: Problem when used
+with lockPref().
+ - network.cookie.p3plevel has an interaction with network.cookie.p3p
+ . When you change network.cookie.p3p, network.cookie.p3plevel
+ should get set to some value. This happens in the pref code in the browser.
+ There is no way to do this with the Pref Editor right now--prefs are treated
+ as individual entities. For now I have commented what is supposed to happen
+ in the description text for these prefs. In the future, perhaps we could
+define such relationships in the XML.
+
-
+
Conventions
- For XML item tags, we use ALL CAPS. For attribute names, we use lower case.
-“true” and “false” are also written in lower case. Generally, for PREF items,
-the attributes are those things about the pref which are fixed, and use elements
-for thing the CCK/Factory app will change. The exception is for <CHOICES>
-, which are difficult to represent as attributes, so these are elements.
-
+ For XML item tags, we use ALL CAPS. For attribute names, we use lower
+case. “true” and “false” are also written in lower case. Generally, for PREF
+items, the attributes are those things about the pref which are fixed, and
+use elements for thing the CCK/Factory app will change. The exception is
+for <CHOICES> , which are difficult to represent as attributes,
+so these are elements.
+
General Structure of the XML File
-
+
XSL Stylesheet
- There may be a reference to an XSL stylesheet at the start of the XML file.
-For example, <?xml-stylesheet type="text/xsl" href="metaprefs.xsl"?>
- . This is not used by the Pref Editor. It is used when the XML file is
+ There may be a reference to an XSL stylesheet at the start of the XML
+file. For example, <?xml-stylesheet type="text/xsl" href="metaprefs.xsl"?>
+ . This is not used by the Pref Editor. It is used when the XML file is
loaded into a Gecko browser (or IE 6) to format the XML into an HTML table
that is easy to read. It is included so that the XML file may be self-documenting
-for internal use. The referenced XSL file must also exist in the same directory
-for the stylesheet to work.
-
+ for internal use. The referenced XSL file must also exist in the same directory
+ for the stylesheet to work.
+
Examples
-The easiest way to understand the format of the XML is to look at some short
-examples.
-
+ The easiest way to understand the format of the XML is to look at some
+short examples.
+
Example1
- The simplest file that may exist consists of one group containing one
-pref.
-
- <?xml version="1.0"?>
- <PREFSGROUP uiname="Netscape Preferences">
- <PREF uiname="Open Browser on Startup" prefname="general.startup.browser"
-type="bool" default="true" lockable="true" description="When the app starts,
-open a browser.">
- <VALUE>true</VALUE>
- <LOCKED>false</LOCKED>
- </PREF>
- </PREFSGROUP>
-
- The above file will result in a tree control with one parent, the group,
-and one child, the pref. See the example below.
-
- 
-
+ The simplest file that may exist consists of one group containing one
+ pref.
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <METAPREFS clientversion="7.01b" subversion="0">
+ <PREFSGROUP uiname="Netscape Preferences">
+ <PREF uiname="Open Browser on Startup" prefname="general.startup.browser"
+ type="bool" default="true" lockable="true" description="When the app starts,
+ open a browser.">
+ <VALUE>true</VALUE>
+ <LOCKED>false</LOCKED>
+ </PREF>
+ </PREFSGROUP>
+ <METAPREFS>
+
+ The above file will result in a tree control with one parent, the group,
+ and one child, the pref. See the example below.
+
+
+
Example 2
- The more complicated example below shows the top level group, with two
-sub groups, each with two preferences.
-
- <?xml version="1.0"?>
- <PREFSGROUP uiname="Netscape Preferences">
- <PREFSGROUP uiname="Group 1">
- <PREF uiname="Autoload What's Related" prefname="browser.related.autoload"
-type="int" default="0" lockable="true" description="A good description of
-this pref goes here.">
- <CHOICES>
- <CHOICE uiname="Always" value="0"/>
- <CHOICE uiname="After First
-Use" value="1"/>
- <CHOICE uiname="Never" value="2"/>
- </CHOICES>
- <VALUE>0</VALUE>
- <LOCKED>false</LOCKED>
- </PREF>
- <PREF uiname="Start Page" prefname="browser.startup.page"
-type="int" lockable="true" default="0" description="Display this page when
-Navigator starts up.">
- <CHOICES>
- <CHOICE uiname="Blank Page" value="0"/>
- <CHOICE uiname="Home Page" value="1"/>
- <CHOICE uiname="Last Page Visited" value="2"/>
- </CHOICES>
- <VALUE>0</VALUE>
- <LOCKED>false</LOCKED>
- </PREF>
- </PREFSGROUP>
- <PREFSGROUP uiname="Group 2">
- <PREF uiname="Bookmarks" prefname="browser.toolbars.showbutton.bookmarks"
-type="bool" default="true" lockable="true" description="Show Booksmarks button
+ The more complicated example below shows the top level group, with two
+ sub groups, each with two preferences.
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <METAPREFS clientversion="7.01b" subversion="0">
+ <PREFSGROUP uiname="Netscape Preferences">
+ <PREFSGROUP uiname="Group 1">
+ <PREF uiname="Autoload What's Related" prefname="browser.related.autoload"
+ type="int" default="0" lockable="true" description="A good description of
+ this pref goes here.">
+ <CHOICES>
+ <CHOICE uiname="Always" value="0"/>
+ <CHOICE uiname="After
+First Use" value="1"/>
+ <CHOICE uiname="Never"
+value="2"/>
+ </CHOICES>
+ <VALUE>0</VALUE>
+ <LOCKED>false</LOCKED>
+ </PREF>
+ <PREF uiname="Start Page" prefname="browser.startup.page"
+ type="int" lockable="true" default="0" description="Display this page when
+ Navigator starts up.">
+ <CHOICES>
+ <CHOICE uiname="Blank Page"
+value="0"/>
+ <CHOICE uiname="Home Page"
+value="1"/>
+ <CHOICE uiname="Last Page Visited"
+value="2"/>
+ </CHOICES>
+ <VALUE>0</VALUE>
+ <LOCKED>false</LOCKED>
+ </PREF>
+ </PREFSGROUP>
+ <PREFSGROUP uiname="Group 2">
+ <PREF uiname="Bookmarks" prefname="browser.toolbars.showbutton.bookmarks"
+ type="bool" default="true" lockable="true" description="Show Booksmarks button
on browser toolbar.">
- <VALUE>true</VALUE>
- <LOCKED>false</LOCKED>
- </PREF>
- <PREF uiname="Go" prefname="browser.toolbars.showbutton.go"
-type="bool" default="true" lockable="true" description="Show Go button on
-browser toolbar.">
- <VALUE>true</VALUE>
- <LOCKED>false</LOCKED>
- </PREF>
+ <VALUE>true</VALUE>
+ <LOCKED>false</LOCKED>
+ </PREF>
+ <PREF uiname="Go" prefname="browser.toolbars.showbutton.go"
+ type="bool" default="true" lockable="true" description="Show Go button on
+ browser toolbar.">
+ <VALUE>true</VALUE>
+ <LOCKED>false</LOCKED>
+ </PREF>
+ </PREFSGROUP>
</PREFSGROUP>
- </PREFSGROUP>
-
- The above example also demonstrates how to include multiple choice
-prefs. These make it easier for the CCK/Factory user to select pref values
-without understanding how they are implemented. This XML file results in
-the prefs tree structure in the example below.
-
-
-
-
+ <METAPREFS>
+
+ The above example also demonstrates how to include multiple choice
+ prefs. These make it easier for the CCK/Factory user to select pref values
+ without understanding how they are implemented. This XML file results in
+ the prefs tree structure in the example below.
+
+
+
+
Reference
- The structure of the file is important. Not much work as been put into handling
-malformed files. If the XML is invalid, you'll get an error that the file
-failed to load, an error type, and a line number. If you create valid XML,
-but don't follow the rules as defined here, the behaviour is undefined. It's
-probably easiest to start with an existing prefs XML file, then cut, paste,
-and edit the <PREF>s from there.
-
-<PREFSGROUP>
- Each <PREFSGROUP> element will make a new level of hierarchy
-in the tree control. A <PREFSGROUP> may contain <PREF>
-s or other <PREFSGROUP> or both, but must not be empty. The
-first element in the file must be a <PREFSGROUP>. These may
-be nested arbitrarily deep.
-
-
-
-
+ The structure of the file is important. Not much work as been put into
+handling malformed files. If the XML is invalid, you'll get an error that
+the file failed to load, an error type, and a line number. If you create valid
+XML, but don't follow the rules as defined here, the behaviour is undefined.
+It's probably easiest to start with an existing prefs XML file, then cut,
+paste, and edit the <PREF>s from there.
+
+<METAPREFS>
+ The entire prefs XML is surrounded by one of these tags. It contains a file
+version.
+
+
+
+
- Attribute
-
+ Attribute
+
Example
-
+
Description
+
+
+
+ clientversion
+
+ clientversion="7.01b"
+
+ This is the version of the client this file is for.
+It indicates which version of the browser client the file can be used customize.
- uiname
+ subversion
+ subversion="0"
- uiname="Netscape Preferences"
-
- This is the name of the group as it appears in the
-tree control. By convention, capitalize the words as if this were a title.
+ This is to keep track of minor revisions to the XML
+within the version.
-
+
+
+<PREFSGROUP>
+ Each <PREFSGROUP> element will make a new level of hierarchy
+ in the tree control. A <PREFSGROUP> may contain <PREF>
+ s or other <PREFSGROUP> or both, but must not be empty. The
+ first element in the file after the surrounding <METAPREFS>
+tag must be a <PREFSGROUP>. These may be nested arbitrarily
+deep.
+
+
+
+
+
+ Attribute
+
+ Example
+
+ Description
+
+
+
+ uiname
+
+ uiname="Netscape Preferences"
+
+ This is the name of the group as it appears in
+the tree control. By convention, capitalize the words as if this were a
+title.
+
+
+
+
+
+
<PREF>
- Each pref element will make a leaf node in the tree control--a pref which
-the user can edit.These elements must be contained in some <PREFSGROUP>
-.
-
-
-
-
-
- Attribute
-
- Example
-
- Description
-
-
-
- uiname
-
- uiname="Open Browser on Startup"
- This is the name of the pref as is appears in the
-tree control. It doesn't have to be the name of the pref--it should be something
-easy for the user to understand. By convention, capitalize the words as if
+ Each pref element will make a leaf node in the tree control--a pref which
+ the user can edit.These elements must be contained in some <PREFSGROUP>
+ .
+
+
+
+
+
+ Attribute
+
+ Example
+
+ Description
+
+
+
+ uiname
+
+ uiname="Open Browser on Startup"
+ This is the name of the pref as is appears in the
+ tree control. It doesn't have to be the name of the pref--it should be something
+ easy for the user to understand. By convention, capitalize the words as if
this were a title.
-
-
-
- prefname
-
- prefname="general.startup.browser"This is the real name of the pref as it is used by
-the Netscape client products.
-
-
-
- type
-
- type="bool"
- Must be one of int, bool
-, or string. This determines how the pref will be edited
+
+
+
+ prefname
+
+ prefname="general.startup.browser"This is the real name of the pref as it is used
+by the Netscape client products.
+
+
+
+ type
+
+ type="bool"
+ Must be one of int, bool
+ , or string. This determines how the pref will be edited
in the Pref Editor and how it is written to the prefs file in the install
image.
-
- bool Pref Editor user allowed to select “true” or
-“false” from a drop-down. No quotes are used when writing the pref in the
-pref file. For example, pref("general.startup.browser", true);
-
- int Pref Editor user allowed to enter integers.
-No quotes are used when writing the pref in the pref file. For example,
-pref("network.proxy.socks_version", 5);
-
- string Pref Editor user may enter whatever he
-likes. Quotes are used when writing the pref in the pref file. For example,
- pref("general.useragent.vendorComment", "AK-MyISP");
-
-
-
- lockable
-
- lockable="true"
- Determines whether or not the Pref Editor user can
-change the lock state the pref. This is included in case there are prefs
-which, for technical reasons, don't work when locked or locking them does
-not have the correct affect. If set to true, the Pref Editor should disable
-the "Lock this pref" checkbox.
-
-
-
- description
-
- description="When the application starts, open
-a browser window."
- This is some text which further describes the pref
-to the Pref Editor user. It appears when the user selected the pref for editing.
-Any text which helps the user under the pref should go here. There is space
+
+ bool Pref Editor user allowed to select “true” or
+ “false” from a drop-down. No quotes are used when writing the pref in the
+ pref file. For example, pref("general.startup.browser", true);
+
+ int Pref Editor user allowed to enter integers.
+ No quotes are used when writing the pref in the pref file. For example,
+ pref("network.proxy.socks_version", 5);
+
+ string Pref Editor user may enter whatever
+he likes. Quotes are used when writing the pref in the pref file. For example,
+ pref("general.useragent.vendorComment", "AK-MyISP");
+
+
+
+ lockable
+
+ lockable="true"
+ Determines whether or not the Pref Editor user
+can change the lock state the pref. This is included in case there are
+prefs which, for technical reasons, don't work when locked or locking them
+does not have the correct affect. If set to true, the Pref Editor should
+disable the "Lock this pref" checkbox.
+
+
+
+ description
+
+ description="When the application starts,
+open a browser window."
+ This is some text which further describes the pref
+ to the Pref Editor user. It appears when the user selected the pref for editing.
+ Any text which helps the user under the pref should go here. There is space
in the editor for maybe 125 characters or so. Of course, you can edit the
dialog resource to hold more if this becomes a limitation. Use proper sentences.
-
-
-
- useradded
-
- useradded="true"
-
- This pref is added and set to true by the Pref Editor
-for all new prefs added by the user via the UI. It is normally not present,
-and is assumed to be false if missing. User added prefs are deletable via
-the Pref Editor UI.
-
-
-
- default
-
- default="true"
-
- The Netscape default value for this pref. That is,
-the value that the pref will get in set to in the code or in some default
-.js file.
-
-
-
-
+
+
+
+ useradded
+
+ useradded="true"
+
+ This pref is added and set to true by the Pref
+Editor for all new prefs added by the user via the UI. It is normally not
+present, and is assumed to be false if missing. User added prefs are deletable
+via the Pref Editor UI.
+
+
+
+ default
+
+ default="true"
+
+ The Netscape default value for this pref. That is,
+ the value that the pref will get in set to in the code or in some default
+ .js file.
+
+
+
+
-
+
<CHOICES>
- This element can optionally appear in <PREF> element if
-the values are to be translated into easy to understand multiple choice options.
-It contains more than one <CHOICE> element. When the user
-edits one of these prefs, he gets a list box from which he can select from
-those choices described in the <CHOICE> elements which are
-contained in the <CHOICES> element. It will work for any type,
-but it is up to the person creating the XML to set the values in the
-value attribute to the correct type for the enclosing <PREF>
-. See Example 2, and <CHOICE>.
-
- The example below shows how a multiple choice pref will look like when
-the user selects it for editing.
-
- 
-
-
+ This element can optionally appear in <PREF> element if
+ the values are to be translated into easy to understand multiple choice
+options. It contains more than one <CHOICE> element. When
+the user edits one of these prefs, he gets a list box from which he can
+select from those choices described in the <CHOICE> elements
+which are contained in the <CHOICES> element. It will work
+for any type, but it is up to the person creating the XML to set the values
+in the value attribute to the correct type for the enclosing <PREF>
+ . See Example 2, and <CHOICE>.
+
+ The example below shows how a multiple choice pref will look like when
+ the user selects it for editing.
+
+
+
+
<CHOICE>
- This element appears in <CHOICES> elements to describe one
-item of a multiple choice. Each <CHOICE> element in a
+ This element appears in <CHOICES> elements to describe
+one item of a multiple choice. Each <CHOICE> element in a
<CHOICES> element for a <PREF> appears in a list
box when the user edits a pref of this type. When selected, the value of
the value attribute for the selected <CHOICE> is
saved as the pref's value. See Example 2, and <CHOICES>
-.
-
-
-
-
-
- Attribute
-
- Example
-
- Description
-
-
-
- uiname
-
- uiname="Blank Page"
- The text of this choice in the list box for this
-choice.
-
-
-
- value
-
- value="0"
- The value saved in the <VALUE> element
-for the <PREF> when the pref is edit and this choice is selected
-in the list box. The type of the value must be correct for the enclosing
+ .
+
+
+
+
+
+ Attribute
+
+ Example
+
+ Description
+
+
+
+ uiname
+
+ uiname="Blank Page"
+ The text of this choice in the list box for this
+ choice.
+
+
+
+ value
+
+ value="0"
+ The value saved in the <VALUE> element
+ for the <PREF> when the pref is edit and this choice is selected
+ in the list box. The type of the value must be correct for the enclosing
<PREF> element.
-
-
-
-
+
+
+
+
-
+
<VALUE>
- One and only one must appear in a <PREF> element. This is
-the value of the pref. No quotes, regardless of type. This gets modified
+ One and only one must appear in a <PREF> element. This
+is the value of the pref. No quotes, regardless of type. This gets modified
when the user edits the pref. Note that the modified file is saved to the
working config directory.
-
+
<LOCKED>
- One and only one must appear in a <PREF> element. This is
-true or false, depending on whether the pref is locked
+ One and only one must appear in a <PREF> element. This
+is true or false, depending on whether the pref is locked
or not. If locked, prefs are written as lockPref() instead of
pref(). See also <PREF lockable="true">.
-
+
<REMOTEADMIN>
- This pref is added by the pref editor, and is normally absent in a prefs
-XML file until it has been processed by the prefs editor. If the <REMOTEADMIN>
- tag is present, and its value is true, then this pref will be written to
-the autoconfig.jsc prefs file when the XML is processed by the install builder
-app.
-
+ This pref is added by the pref editor, and is normally absent in a prefs
+ XML file until it has been processed by the prefs editor. If the <REMOTEADMIN>
+ tag is present, and its value is true, then this pref will be written
+to the autoconfig.jsc prefs file when the XML is processed by the install
+builder app.
+
+
diff --git a/cck/driver/prefeditview.cpp b/cck/driver/prefeditview.cpp
index 37a6a5a137cc..cbbb1c9422dc 100644
--- a/cck/driver/prefeditview.cpp
+++ b/cck/driver/prefeditview.cpp
@@ -261,6 +261,25 @@ void CPrefEditView::startElement(const char *name, const char **atts)
m_pParsingPrefElement = new CPrefElement;
}
+ else if (stricmp(name, "METAPREFS") == 0)
+ {
+ ASSERT(atts[2]); // there must be a clientversion and subversion attribute
+
+ // Process the list of attribute/value pairs.
+ int i = 0;
+ while(atts[i])
+ {
+ const char* attrName = atts[i++];
+ const char* attrVal = atts[i++];
+
+ if (stricmp(attrName, "clientversion") == 0)
+ m_strXMLVersion = attrVal;
+ else if (stricmp(attrName, "subversion") == 0)
+ m_strXMLSubVersion = attrVal;
+ }
+
+ }
+
// Pass on all subelements to the pref element object to handle.
if (m_pParsingPrefElement)
m_pParsingPrefElement->startElement(name, atts);
@@ -554,10 +573,20 @@ BOOL CPrefEditView::DoSavePrefsTree(CString strFile)
return FALSE;
}
+ // start the outermost tag
+ CString strOuter;
+ strOuter.Format("\n\n", m_strXMLVersion, m_strXMLSubVersion);
+ fwrite(strOuter, strOuter.GetLength(), 1, fp);
+
+
CTreeCtrl &treeCtrl = GetTreeCtrl();
HTREEITEM hRoot = treeCtrl.GetRootItem();
WriteXMLItem(fp, 1, hRoot);
+ // close the outermost tag
+ strOuter = " ";
+ fwrite(strOuter, strOuter.GetLength(), 1, fp);
+
fclose(fp);
return TRUE;
}
diff --git a/cck/driver/prefeditview.h b/cck/driver/prefeditview.h
index 9fc47f04dac8..0275f78472ec 100644
--- a/cck/driver/prefeditview.h
+++ b/cck/driver/prefeditview.h
@@ -78,6 +78,8 @@ protected:
private:
CImageList m_imageList; // padlocks to show which prefs are locked
CString m_strXMLFile; // the XML file used to load the m_pPrefXMLTree, and hence the tree control
+ CString m_strXMLVersion; // the client version for the XML file
+ CString m_strXMLSubVersion; // minor version inside the XML file
// Stuff for Find and FindNext.
HTREEITEM m_hNextFind;