| package-info.java |
1 /* 2 * Distribution License: 3 * JSword is free software; you can redistribute it and/or modify it under 4 * the terms of the GNU Lesser General Public License, version 2.1 or later 5 * as published by the Free Software Foundation. This program is distributed 6 * in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even 7 * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 8 * See the GNU Lesser General Public License for more details. 9 * 10 * The License is available on the internet at: 11 * http://www.gnu.org/copyleft/lgpl.html 12 * or by writing to: 13 * Free Software Foundation, Inc. 14 * 59 Temple Place - Suite 330 15 * Boston, MA 02111-1307, USA 16 * 17 * © CrossWire Bible Society, 2007 - 2016 18 * 19 */ 20 /** 21 <p>Config allows an application to separate the responsibilities of setting 22 itself up, and providing a user interface from the real work that it needs 23 to do.</p> 24 25 <h2>Introduction</h2> 26 <p>Config is (mostly) all kept in a few packages in the util source tree. The 27 design aims for the following goals:</p> 28 <ul> 29 <li>Application Transparency - It should be possible to add a configuration 30 dialog to an application without adding hundreds of hooks either to your 31 application to read the current state, or to the configuration system to 32 work with the application. This is achieved via an xml config file and a 33 healthy dose of reflection.</li> 34 <li>View Independance - Currently there are a number of Swing front ends - 35 a Mozilla style config dialog with a tree, a more conventional tabbed dialog, 36 and a prototype wizard style interface. There has also been a servlet front-end 37 however the code to do this has suffered bit-rot, and should not be considered 38 useful. It does however prove the view independance concept.</li> 39 </ul> 40 41 <h3>How To Use Config</h3> 42 <p>There are a number of simple steps. First a config.xml file is needed to tell 43 the config system what to configure and how.</p> 44 45 <pre> 46 <config> 47 48 <span style="color: #336600"><!-- A configuration is a set of options ... --></span> 49 <span style="color: #336600"><!-- The key is a dot separated name - Imaging this in a Mozilla tree or some nested tabs. --></span> 50 <option key="Bibles.Sword.Base Directory" type="string"> 51 <span style="color: #336600"><!-- The type (above) along with the introspect line configures what JavaBean methods will be called --></span> 52 <introspect class="org.crosswire.jsword.book.sword.SwordBibleDriver" property="SwordDir"/> 53 <span style="color: #336600"><!-- The tool-tip (or similar) describing what is going on --></span> 54 <help>Where is the SWORD Project base directory.</help> 55 </option> 56 57 <span style="color: #336600"><!-- Another option, this time it is a boolean option which will show up as a tickbox --></span> 58 <option key="Bibles.Display.Persistent Naming" level="advanced" type="boolean"> 59 <introspect class="org.crosswire.jsword.passage.PassageUtil" property="PersistentNaming"/> 60 <help>True if the passage editor re-writes the references to conform to its notation.</help> 61 </option> 62 63 <span style="color: #336600"><!-- Another type again this one for the look and feel. --> 64 <!-- The reason for the helper class here is to alter windows that are not currently mapped --></span> 65 <option key="Looks.Look and Feel" type="class"> 66 <introspect class="org.crosswire.common.swing.LookAndFeelUtil" property="LookAndFeel"/> 67 <help>The look and feel of the application</help> 68 </option> 69 70 <span style="color: #336600"><!-- When we have have an Enum style config option ... --></span> 71 <option key="Bibles.Display.Book Case" level="advanced" type="int-options"> 72 <introspect class="org.crosswire.jsword.passage.Books" property="Case"/> 73 <help>What case should we use to display the references.</help> 74 <alternative number="0" name="lower"/> 75 <alternative number="1" name="Sentence"/> 76 <alternative number="2" name="UPPER"/> 77 <alternative number="3" name="mIXeD"/> 78 </option> 79 80 <span style="color: #336600"><!-- The options here are more complex and need to be provided as a string array by Java code (see below) --></span> 81 <option key="Bibles.Default" type="string-options"> 82 <introspect class="org.crosswire.jsword.book.Bibles" property="DefaultName"/> 83 <help>Which of the available Bibles is the default.</help> 84 <map name="biblenames"/> 85 </option> 86 87 <span style="color: #336600"><!-- This option is 'advanced' which means it is not visible to all users (see below) --></span> 88 <option key="Advanced.Source Path" level="advanced" type="path"> 89 <introspect class="org.crosswire.common.swing.DetailedExceptionPane" property="SourcePath"/> 90 <help>The directories to search for source code in when investigating an exception.</help> 91 </option> 92 93 <span style="color: #336600"><!-- When the choice is very custom you can always do your own implementation --> 94 <!-- This allows us to set users levels so not everyone gets asked hard questions --></span> 95 <option key="Advanced.User Level" type="custom" class="org.crosswire.common.util.UserLevel$UserLevelChoice"> 96 <help>How advanced is your knowledge of this program.</help> 97 </option> 98 99 <span style="color: #336600"><!-- There are other examples in config.xml --></span> 100 </config> 101 </pre> 102 103 <p>Then you need to add the Java code:</p> 104 <pre><span style="color: #336600"> 105 // To load the config.xml file: 106 </span>Config config = new Config("Tool Shed Options"); 107 Document xmlconfig = Project.resource().getDocument("config"); <span style="color: #336600">// Or whatever to get a JDOM Document</span> 108 config.add(xmlconfig); 109 110 <span style="color: #336600">// To load a saved config</span> 111 config.setProperties(Project.resource().getProperties("desktop")); <span style="color: #336600">// Or however you get a Properties</span> 112 config.localToApplication(true); 113 114 <span style="color: #336600">// And display it ...</span> 115 URL configurl = Project.resource().getPropertiesURL("desktop"); <span style="color: #336600">// URL of the Properties file to save to</span> 116 SwingConfig.showDialog(config, parentWind, configurl); 117 118 <span style="color: #336600">// The code above needed help in setting up a string choice. This is how ...</span> 119 ChoiceFactory.getDataMap().put("biblenames", Bibles.getBibleNames()); 120 </pre> 121 <p>There are more examples in <code>org.crosswire.bibledesktop.desktop.OptionsAction.</code></p> 122 123 */ 124 package org.crosswire.common.config; 125