[jsword-devel] A Little Help

Joe Walker jsword-devel@crosswire.org
Wed, 16 Oct 2002 21:40:33 +0100


This is a multi-part message in MIME format.

------=_NextPart_000_001F_01C2755C.A7BC9430
Content-Type: text/plain;
	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable


Hi Keith,
Sorry about the HTML email. I've written some docs on config and added =
them as a JSP to the docs folder. This is a cut and paste job. If it =
doesn't work then please take a look in CVS, or in a few days we'll =
refresh the Crosswire website.
Joe.

The Config Sub-System
Introduction
Config is (mostly) all kept in a few packages in the util source tree. =
The design aims for the following goals:

  a.. Application Transparency - It should be possible to add a =
configuration dialog to an application without adding hundreds of hooks =
either to your application to read the current state, or to the =
configuration system to work with the application. This is achieved via =
an xml config file and a healthy dose of reflection.
  b.. View Independance - Currently there are a number of Swing front =
ends - a Mozilla style config dialog with a tree, a more conventional =
tabbed dialog, and a prototype wizard style interface. There has also =
been a servlet front-end however the code to do this has suffered =
bit-rot, and should not be considered useful. It does however prove the =
view independance concept.
How To Use Config
There are a number of simple steps. First a config.xml file is needed to =
tell the config system what to configure and how.

<config>

  <!-- A configuration is a set of options ... -->
  <!-- The key is a dot separated name - Imaging this in a Mozilla tree =
or some nested tabs. -->
  <option key=3D"Bibles.Sword.Base Directory" type=3D"string">
    <!-- The type (above) along with the introspect line configures what =
JavaBean methods will be called -->
    <introspect =
class=3D"org.crosswire.jsword.book.sword.SwordBibleDriver" =
property=3D"SwordDir"/>
    <!-- The tool-tip (or similar) describing what is going on -->
    <help>Where is the SWORD Project base directory.</help>
  </option>

  <!-- Another option, this time it is a boolean option which will show =
up as a tickbox -->
  <option key=3D"Bibles.Display.Persistent Naming" level=3D"advanced" =
type=3D"boolean">
    <introspect class=3D"org.crosswire.jsword.passage.PassageUtil" =
property=3D"PersistentNaming"/>
    <help>True if the passage editor re-writes the references to conform =
to its notation.</help>
  </option>

  <!-- Another type again this one for the look and feel. -->
  <!-- The reason for the helper class here is to alter windows that are =
not currently mapped -->
  <option key=3D"Looks.Look and Feel" type=3D"class">
    <introspect class=3D"org.crosswire.common.swing.LookAndFeelUtil" =
property=3D"LookAndFeel"/>
    <help>The look and feel of the application</help>
  </option>

  <!-- When we have have an Enum style config option ... -->
  <option key=3D"Bibles.Display.Book Case" level=3D"advanced" =
type=3D"int-options">
    <introspect class=3D"org.crosswire.jsword.passage.Books" =
property=3D"Case"/>
    <help>What case should we use to display the references.</help>
    <alternative number=3D"0" name=3D"lower"/>
    <alternative number=3D"1" name=3D"Sentance"/>
    <alternative number=3D"2" name=3D"UPPER"/>
    <alternative number=3D"3" name=3D"mIXeD"/>
  </option>

  <!-- The options here are more complex and need to be provided as a =
string array by Java code (see below) -->
  <option key=3D"Bibles.Default" type=3D"string-options">
    <introspect class=3D"org.crosswire.jsword.book.Bibles" =
property=3D"DefaultName"/>
    <help>Which of the available Bibles is the default.</help>
    <map name=3D"biblenames"/>
  </option>

  <!-- This option is 'advanced' which means it is not visible to all =
users (see below) -->
  <option key=3D"Advanced.Source Path" level=3D"advanced" type=3D"path">
    <introspect =
class=3D"org.crosswire.common.swing.DetailedExceptionPane" =
property=3D"SourcePath"/>
    <help>The directories to search for source code in when =
investigating an exception.</help>
  </option>

  <!-- When the choice is very custom you can always do your own =
implementation -->
  <!-- This allows us to set users levels so not everyone gets asked =
hard questions -->
  <option key=3D"Advanced.User Level" type=3D"custom" =
class=3D"org.crosswire.common.util.UserLevel$UserLevelChoice">
    <help>How advanced is your knowledge of this program.</help>
  </option>

  <!-- There are other examples in config.xml -->

</config>

Then you need to add the Java code:=20


// To load the config.xml file:
Config config =3D new Config("Tool Shed Options");
Document xmlconfig =3D Project.resource().getDocument("config"); // Or =
whatever to get a JDOM Document
config.add(xmlconfig);

// To load a saved config
config.setProperties(Project.resource().getProperties("desktop")); // Or =
however you get a Properties
config.localToApplication(true);

// And display it ...
URL configurl =3D Project.resource().getPropertiesURL("desktop"); // URL =
of the Properties file to save to
SwingConfig.showDialog(config, parentWind, configurl);

// The code above needed help in setting up a string choice. This is how =
...
ChoiceFactory.getDataMap().put("biblenames", Bibles.getBibleNames());
There are more examples in =
org.crosswire.jsword.view.swing.desktop.OptionsAction.


----- Original Message -----=20
From: "Keith Ralston" <ralstonk@attbi.com>
To: <jsword-devel@bibletechnologieswg.org>
Sent: Wednesday, October 16, 2002 3:19 AM
Subject: RE: [jsword-devel] A Little Help


> I have been trying to walk through this part of the code.  Do you have =
a
> sequence diagram of the portion  of the start up that identifies the =
drivers
> and loads them.  I have mapped most of it out, but am missing a few =
pieces.
> Specifically, I am missing where the available drivers are identified =
and
> their physical locations set.
>=20
> Thanks for the help.
>=20
> Keith
>=20
> > -----Original Message-----
> > From: owner-jsword-devel@crosswire.org
> > [mailto:owner-jsword-devel@crosswire.org]On Behalf Of Joe Walker
> > Sent: Friday, August 30, 2002 1:54 AM
> > To: jsword-devel@bibletechnologieswg.org
> > Subject: RE: [jsword-devel] A Little Help
> >
> >
> >
> > There a fair bit of code in org.crosswire.jsword.bible.sword
> > On my setup it finds and enumerates the Bibles OK, but doesn't =
correctly
> > render text. Fixing this for plain text sword modules should not be =
too
> > hard.
> >
> > iirc SwordBibleDriver is the code that does the Bible enumeration
> > (i.e. dig
> > around in the directory tree) and SwordBible is the code that (fails =
to)
> > deliver bible data to the GUI.
> >
> > Sorry I've been so quiet for the past week or so. I'm in the middle =
of
> > helping run a Bible week and trying to write an XML article for
> > JavaWorld. I
> > should be back soon.
> >
> > Joe.
> >
> > > -----Original Message-----
> > > From: owner-jsword-devel@crosswire.org
> > > [mailto:owner-jsword-devel@crosswire.org]On Behalf Of Keith =
Ralston
> > > Sent: 30 August 2002 04:26
> > > To: jsword-devel@bibletechnologieswg.org
> > > Subject: [jsword-devel] A Little Help
> > >
> > >
> > > Do we have any code that reads Sword modules?  I'm not really
> > > sure where to
> > > start on that.
> > >
> >
>=20
> _______________________________________________
> jsword-devel mailing list
> jsword-devel@crosswire.org
> http://www.crosswire.org/mailman/listinfo/jsword-devel
> 
------=_NextPart_000_001F_01C2755C.A7BC9430
Content-Type: text/html;
	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD>
<META http-equiv=3DContent-Type content=3D"text/html; =
charset=3Diso-8859-1">
<META content=3D"MSHTML 6.00.2800.1106" name=3DGENERATOR>
<STYLE></STYLE>
</HEAD>
<BODY>
<DIV><FONT face=3DVerdana color=3D#800000 size=3D2></FONT><%@ include =
file=3D"header.jsp" %></DIV>
<DIV><FONT face=3DVerdana color=3D#800000>Hi Keith,</FONT></DIV>
<DIV><FONT face=3DVerdana color=3D#800000>Sorry about the HTML email. =
I've written=20
some docs on config and added them as a JSP to the docs folder. This is =
a cut=20
and paste job. If it doesn't work then please take a look in CVS, or in =
a few=20
days we'll refresh the Crosswire website.</FONT></DIV>
<DIV><FONT face=3DVerdana color=3D#800000>Joe.</FONT></DIV>
<DIV><FONT face=3DVerdana color=3D#800000></FONT>&nbsp;</DIV>
<DIV>
<H1>The Config Sub-System</H1>
<H2>Introduction</H2>
<P>Config is (mostly) all kept in a few packages in the util source =
tree. The=20
design aims for the following goals:</P>
<UL>
  <LI>Application Transparency - It should be possible to add a =
configuration=20
  dialog to an application without adding hundreds of hooks either to =
your=20
  application to read the current state, or to the configuration system =
to work=20
  with the application. This is achieved via an xml config file and a =
healthy=20
  dose of reflection.</LI>
  <LI>View Independance - Currently there are a number of Swing front =
ends - a=20
  Mozilla style config dialog with a tree, a more conventional tabbed =
dialog,=20
  and a prototype wizard style interface. There has also been a servlet=20
  front-end however the code to do this has suffered bit-rot, and should =
not be=20
  considered useful. It does however prove the view independance=20
concept.</LI></UL>
<H3>How To Use Config</H3>
<P>There are a number of simple steps. First a config.xml file is needed =
to tell=20
the config system what to configure and how.</P><PRE>&lt;config&gt;

  <FONT color=3D#00cc00>&lt;!-- A configuration is a set of options ... =
--&gt;</FONT>
  <FONT color=3D#00cc00>&lt;!-- The key is a dot separated name - =
Imaging this in a Mozilla tree or some nested tabs. --&gt;</FONT>
  &lt;option key=3D"Bibles.Sword.Base Directory" type=3D"string"&gt;
    <FONT color=3D#00cc00>&lt;!-- The type (above) along with the =
introspect line configures what JavaBean methods will be called =
--&gt;</FONT>
    &lt;introspect =
class=3D"org.crosswire.jsword.book.sword.SwordBibleDriver" =
property=3D"SwordDir"/&gt;
    <FONT color=3D#00cc00>&lt;!-- The tool-tip (or similar) describing =
what is going on --&gt;</FONT>
    &lt;help&gt;Where is the SWORD Project base directory.&lt;/help&gt;
  &lt;/option&gt;

  <FONT color=3D#00cc00>&lt;!-- Another option, this time it is a =
boolean option which will show up as a tickbox --&gt;</FONT>
  &lt;option key=3D"Bibles.Display.Persistent Naming" level=3D"advanced" =
type=3D"boolean"&gt;
    &lt;introspect class=3D"org.crosswire.jsword.passage.PassageUtil" =
property=3D"PersistentNaming"/&gt;
    &lt;help&gt;True if the passage editor re-writes the references to =
conform to its notation.&lt;/help&gt;
  &lt;/option&gt;

  <FONT color=3D#00cc00>&lt;!-- Another type again this one for the look =
and feel. --&gt;
  &lt;!-- The reason for the helper class here is to alter windows that =
are not currently mapped --&gt;
</FONT>  &lt;option key=3D"Looks.Look and Feel" type=3D"class"&gt;
    &lt;introspect class=3D"org.crosswire.common.swing.LookAndFeelUtil" =
property=3D"LookAndFeel"/&gt;
    &lt;help&gt;The look and feel of the application&lt;/help&gt;
  &lt;/option&gt;

  <FONT color=3D#00cc00>&lt;!-- When we have have an Enum style config =
option ... --&gt;
</FONT>  &lt;option key=3D"Bibles.Display.Book Case" level=3D"advanced" =
type=3D"int-options"&gt;
    &lt;introspect class=3D"org.crosswire.jsword.passage.Books" =
property=3D"Case"/&gt;
    &lt;help&gt;What case should we use to display the =
references.&lt;/help&gt;
    &lt;alternative number=3D"0" name=3D"lower"/&gt;
    &lt;alternative number=3D"1" name=3D"Sentance"/&gt;
    &lt;alternative number=3D"2" name=3D"UPPER"/&gt;
    &lt;alternative number=3D"3" name=3D"mIXeD"/&gt;
  &lt;/option&gt;

  <FONT color=3D#00cc00>&lt;!-- The options here are more complex and =
need to be provided as a string array by Java code (see below) --&gt;
</FONT>  &lt;option key=3D"Bibles.Default" type=3D"string-options"&gt;
    &lt;introspect class=3D"org.crosswire.jsword.book.Bibles" =
property=3D"DefaultName"/&gt;
    &lt;help&gt;Which of the available Bibles is the =
default.&lt;/help&gt;
    &lt;map name=3D"biblenames"/&gt;
  &lt;/option&gt;

  <FONT color=3D#00cc00>&lt;!-- This option is 'advanced' which means it =
is not visible to all users (see below) --&gt;
</FONT>  &lt;option key=3D"Advanced.Source Path" level=3D"advanced" =
type=3D"path"&gt;
    &lt;introspect =
class=3D"org.crosswire.common.swing.DetailedExceptionPane" =
property=3D"SourcePath"/&gt;
    &lt;help&gt;The directories to search for source code in when =
investigating an exception.&lt;/help&gt;
  &lt;/option&gt;

  <FONT color=3D#00cc00>&lt;!-- When the choice is very custom you can =
always do your own implementation --&gt;
  &lt;!-- This allows us to set users levels so not everyone gets asked =
hard questions --&gt;
</FONT>  &lt;option key=3D"Advanced.User Level" type=3D"custom" =
class=3D"org.crosswire.common.util.UserLevel$UserLevelChoice"&gt;
    &lt;help&gt;How advanced is your knowledge of this =
program.&lt;/help&gt;
  &lt;/option&gt;

  <FONT color=3D#00cc00>&lt;!-- There are other examples in config.xml =
--&gt;
</FONT>
&lt;/config&gt;

</PRE>
<P>Then you need to add the Java code: <PRE><FONT color=3D#00cc00>
// To load the config.xml file:
</FONT>Config config =3D new Config("Tool Shed Options");
Document xmlconfig =3D Project.resource().getDocument("config"); <FONT =
color=3D#00cc00>// Or whatever to get a JDOM Document</FONT>
config.add(xmlconfig);

<FONT color=3D#00cc00>// To load a saved config</FONT>
config.setProperties(Project.resource().getProperties("desktop")); <FONT =
color=3D#00cc00>// Or however you get a Properties</FONT>
config.localToApplication(true);

<FONT color=3D#00cc00>// And display it ...</FONT>
URL configurl =3D Project.resource().getPropertiesURL("desktop"); <FONT =
color=3D#00cc00>// URL of the Properties file to save to</FONT>
SwingConfig.showDialog(config, parentWind, configurl);

<FONT color=3D#00cc00>// The code above needed help in setting up a =
string choice. This is how ...</FONT>
ChoiceFactory.getDataMap().put("biblenames", Bibles.getBibleNames());
</PRE>
<P>There are more examples in=20
<CODE>org.crosswire.jsword.view.swing.desktop.OptionsAction.</CODE></P><%=
@ include file=3D"footer.jsp" %></DIV>
<DIV><FONT face=3DVerdana color=3D#800000 size=3D2></FONT>&nbsp;</DIV>
<DIV><FONT face=3DVerdana color=3D#800000 size=3D2>----- Original =
Message -----=20
</FONT>
<DIV><FONT face=3DVerdana color=3D#800000 size=3D2>From: "Keith Ralston" =
&lt;</FONT><A=20
href=3D"mailto:ralstonk@attbi.com"><FONT face=3DVerdana color=3D#800000=20
size=3D2>ralstonk@attbi.com</FONT></A><FONT face=3DVerdana =
color=3D#800000=20
size=3D2>&gt;</FONT></DIV>
<DIV><FONT face=3DVerdana color=3D#800000 size=3D2>To: &lt;</FONT><A=20
href=3D"mailto:jsword-devel@bibletechnologieswg.org"><FONT =
face=3DVerdana=20
color=3D#800000 =
size=3D2>jsword-devel@bibletechnologieswg.org</FONT></A><FONT=20
face=3DVerdana color=3D#800000 size=3D2>&gt;</FONT></DIV>
<DIV><FONT face=3DVerdana color=3D#800000 size=3D2>Sent: Wednesday, =
October 16, 2002=20
3:19 AM</FONT></DIV>
<DIV><FONT face=3DVerdana color=3D#800000 size=3D2>Subject: RE: =
[jsword-devel] A=20
Little Help</FONT></DIV></DIV>
<DIV><FONT face=3DVerdana><BR><FONT color=3D#800000 =
size=3D2></FONT></FONT></DIV><FONT=20
face=3DVerdana color=3D#800000 size=3D2>&gt; I have been trying to walk =
through this=20
part of the code.&nbsp; Do you have a<BR>&gt; sequence diagram of the=20
portion&nbsp; of the start up that identifies the drivers<BR>&gt; and =
loads=20
them.&nbsp; I have mapped most of it out, but am missing a few =
pieces.<BR>&gt;=20
Specifically, I am missing where the available drivers are identified=20
and<BR>&gt; their physical locations set.<BR>&gt; <BR>&gt; Thanks for =
the=20
help.<BR>&gt; <BR>&gt; Keith<BR>&gt; <BR>&gt; &gt; -----Original=20
Message-----<BR>&gt; &gt; From: </FONT><A=20
href=3D"mailto:owner-jsword-devel@crosswire.org"><FONT face=3DVerdana =
color=3D#800000=20
size=3D2>owner-jsword-devel@crosswire.org</FONT></A><BR><FONT =
face=3DVerdana=20
color=3D#800000 size=3D2>&gt; &gt; =
[mailto:owner-jsword-devel@crosswire.org]On=20
Behalf Of Joe Walker<BR>&gt; &gt; Sent: Friday, August 30, 2002 1:54 =
AM<BR>&gt;=20
&gt; To: </FONT><A =
href=3D"mailto:jsword-devel@bibletechnologieswg.org"><FONT=20
face=3DVerdana color=3D#800000=20
size=3D2>jsword-devel@bibletechnologieswg.org</FONT></A><BR><FONT =
face=3DVerdana=20
color=3D#800000 size=3D2>&gt; &gt; Subject: RE: [jsword-devel] A Little =
Help<BR>&gt;=20
&gt;<BR>&gt; &gt;<BR>&gt; &gt;<BR>&gt; &gt; There a fair bit of code in=20
org.crosswire.jsword.bible.sword<BR>&gt; &gt; On my setup it finds and=20
enumerates the Bibles OK, but doesn't correctly<BR>&gt; &gt; render =
text. Fixing=20
this for plain text sword modules should not be too<BR>&gt; &gt; =
hard.<BR>&gt;=20
&gt;<BR>&gt; &gt; iirc SwordBibleDriver is the code that does the Bible=20
enumeration<BR>&gt; &gt; (i.e. dig<BR>&gt; &gt; around in the directory =
tree)=20
and SwordBible is the code that (fails to)<BR>&gt; &gt; deliver bible =
data to=20
the GUI.<BR>&gt; &gt;<BR>&gt; &gt; Sorry I've been so quiet for the past =
week or=20
so. I'm in the middle of<BR>&gt; &gt; helping run a Bible week and =
trying to=20
write an XML article for<BR>&gt; &gt; JavaWorld. I<BR>&gt; &gt; should =
be back=20
soon.<BR>&gt; &gt;<BR>&gt; &gt; Joe.<BR>&gt; &gt;<BR>&gt; &gt; &gt;=20
-----Original Message-----<BR>&gt; &gt; &gt; From: </FONT><A=20
href=3D"mailto:owner-jsword-devel@crosswire.org"><FONT face=3DVerdana =
color=3D#800000=20
size=3D2>owner-jsword-devel@crosswire.org</FONT></A><BR><FONT =
face=3DVerdana=20
color=3D#800000 size=3D2>&gt; &gt; &gt; =
[mailto:owner-jsword-devel@crosswire.org]On=20
Behalf Of Keith Ralston<BR>&gt; &gt; &gt; Sent: 30 August 2002 =
04:26<BR>&gt;=20
&gt; &gt; To: </FONT><A =
href=3D"mailto:jsword-devel@bibletechnologieswg.org"><FONT=20
face=3DVerdana color=3D#800000=20
size=3D2>jsword-devel@bibletechnologieswg.org</FONT></A><BR><FONT =
face=3DVerdana=20
color=3D#800000 size=3D2>&gt; &gt; &gt; Subject: [jsword-devel] A Little =

Help<BR>&gt; &gt; &gt;<BR>&gt; &gt; &gt;<BR>&gt; &gt; &gt; Do we have =
any code=20
that reads Sword modules?&nbsp; I'm not really<BR>&gt; &gt; &gt; sure =
where=20
to<BR>&gt; &gt; &gt; start on that.<BR>&gt; &gt; &gt;<BR>&gt; =
&gt;<BR>&gt;=20
<BR>&gt; _______________________________________________<BR>&gt; =
jsword-devel=20
mailing list<BR>&gt; </FONT><A =
href=3D"mailto:jsword-devel@crosswire.org"><FONT=20
face=3DVerdana color=3D#800000 =
size=3D2>jsword-devel@crosswire.org</FONT></A><BR><FONT=20
face=3DVerdana color=3D#800000 size=3D2>&gt; </FONT><A=20
href=3D"http://www.crosswire.org/mailman/listinfo/jsword-devel"><FONT =
face=3DVerdana=20
color=3D#800000=20
size=3D2>http://www.crosswire.org/mailman/listinfo/jsword-devel</FONT></A=
><BR><FONT=20
face=3DVerdana color=3D#800000 size=3D2>&gt; </FONT></BODY></HTML>

------=_NextPart_000_001F_01C2755C.A7BC9430--