In this chapter, the file format of the preferences.plist or, more general, the configuration files (see Section 4.3, “Working with Configurations”) is described which contain the application's configuration settings.
upCast may offer very specific configuration options in the future for which we will not provide a UI widget to not clutter the interface and confuse the average user. However, you may set that specific preference manually in the preferences file, which is XML based and must be valid according to the following DTD:
<ENTITY % plistObject "( date | dict | real | integer | string | true | false )" >
<ELEMENT plist %plistObject;>
<ATTLIST plist version CDATA "1.0" >
<-- Collections -->
<ELEMENT dict (key, %plistObject;)*>
<ELEMENT key (#PCDATA)>
<--- Primitive types -->
<ELEMENT string (#PCDATA)>
<ELEMENT date (#PCDATA)> <-- Contents should conform to a subset of ISO 8601 -->
<-- Numerical primitives -->
<ELEMENT true EMPTY> <-- Boolean constant true -->
<ELEMENT false EMPTY> <-- Boolean constant false -->
<ELEMENT real (#PCDATA)> <-- Contents should represent a floating point
number matching ("+" | "-")? d+ ("."d*)? ("E" ("+" | "-") d+)?
where d is a digit 0-9. -->
<ELEMENT integer (#PCDATA)> <-- Contents should represent a (possibly
signed) integer number in base 10 -->
Preference keys are hierarchically structured similar to the package names in the Java language, except that the internal hierarchy separator character is the SECTION SIGN '§'. This allows us to use URLs as key names, which may contain the dot character. The hierarchy separator character is only visible from within the application; on writing the preferences file, it is resolved into a hierarchy of key/dict element pairs.
An internal preference key/value pair (global§application§version, 4.0.1) will be resolved to
<key>global</key> <dict> <key>application</key> <dict> <key>version</key> <string>4.0.1</string> </dict> </dict>
This graphic shows the general structure of an upCast preferences.plist file:
When adding an export filter to the export filters list, it gets assigned a unique instance ID automatically created by upCast. This is necessary to be able to distinguish between several export filters of the same class. This instance ID is part of the preference name hierarchy, so that parameters for a specific filter instance are grouped in the preferences file. The converter preferences root holds the information on the active export filters using the converter§Dflt§outFilterClassX and converter§Dflt§outFilterInstIDX pairs of preferences, with X being the index (zero-based) of the filter in the export filters list.
To find the parameter set for the second export filter in the export filters list, first look for the value of the converter§Dflt§outFilterInstID1 preference key, which contains the respective filter's instance ID; say it is 5. Then, lookup the preferences root key for the filter implementation class given in converter§Dflt§outFilterClass1. Say, this is an instance of de.infinityloop.upcast.exportfilters.ExportFilter5, which is the XHTML 1.0 (strict) export filter. Its root key is the same as the selection constant as used in BCF or the upCast Conversion API, and in our example this is XHTML. So we look for all preference keys that start with XHTML§5§, which is the filter class selection constant with the instance ID added.
Filter preferences for custom filters have for their selection constant either the class name without the package part (i.e. ExportFilterX), or the string value of the getIdentificationName() method, if you chose to override it in your custom implementation.
Preference keys names are built using the algorithm described above. The names used as last component for import filter parameter keys and export filter parameter keys are the same as given in the respective filter description sections, so we will not repeat them here, but only describe global parameters.
- global
- TimedExecutionSwitch
A Boolean specifying the state of the Timed Execution function.
- converter
- UserInstanceID
A String specifying the instance ID the user set for the converter object. By default, upCast has only one instance of a converter object at any time, and it sets this value to Dflt.
- Dflt
This is the instance ID of the converter object. Since upCast by default only uses one converter object, this is normally fixed at Dflt.
- inFilterClass
The class for the current input filter in effect.
- instanceID
This is the saved current value of the instance ID generator, which creates sequential unique numbers during the usage of upCast every time a new filter instance is added to the list of export filters.
- inFilterInstID
The instance ID of the current import filter.
- imageDir
The folder where extracted images are saved to.
- inputFile
The path to the input file as specified in the respective UI text field.
- SwingPLAF
The class name of the Swing Pluggable Look And Feel class upCast should use for its UI.
- outputDir
The destination folder for conversion results.
- outFilterCount
The number of active export filters.
- outFilterClassX
The Java class for the output filter with index X, with X being a number in the range of [0,outFilterCount[ .
- outFilterInstIDX
The instance ID for the output filter with index X, with X being a number in the range of [0,outFilterCount[ .
- application
- name
The name of the application this preferences file belongs to.
- version
The version of the application this preferences file belongs to as an encoded decimal Integer.
- xml
- CatalogFile
Path to the XML Catalog to use. Can be set in the GUI using > ... (Choose XML Catalog file).