Developer information
Fileformat
The fileformat might be the most important thing for other developers in CDox. The spec should be almost ready now for version 1. There is now also some plugin support in CDox, which partly corresponds to the fileformat. The information here refers to the CDox program since 1.0rc1.
A .cdx file is just a zip file containing other documents. The contents of the file are the following:
- The file documents.cdx. See below.
- The file coverPreview_image.png. This should be a small image snapshot of the cover(s).
- Data files. These files (currently only images) are referred from the documents.cdx.
The file documents.cdx
This is the central file of the fileformat. It's just a XML file following certain criteria described by the XML Schema that can be found right here. If you plan to support the fileformat, you should make sure that your generated documents.cdx files validate against this Schema. Even if you only want to read the files, you should take a look into it.
There are some more things apart from the pure Schema conformity that you
should know. The <text> tags have the attribute "text"
where the, yes, text is stored. But it's not plain text that is stored
there, but Base64 encoded text (otherwise it would be quite complicated to
store newlines, for example). Second, the values for colors are just RGB
integers. They can also be negative. The bits 24-31 are alpha, 16-23 are
red, 8-15 are green and 0-7 are blue. There are also some more tags that
should contain base64-encoded text (see the description section below).
Description elements
The description elements include some, well, descriptive information about the type of the CD. There exist currently three types of descriptions, although one can add more types by writing a plugin.
The AudioData type contains typical information about audio CDs, as well as the VideoData type contains typical information about video CDs. The GenericData type is a type that contains only a title and some strings. If you want to know more about them, look into the Schema or save a test.cdx, unzip it and look into the documents.cdx to get an example.
If you want to write a plugin and wonder how to store/read the descriptive
elements, here is how. There is a <description> tag in the
documents.cdx. This is the element which you get as DOM node when a document
is loaded or saved. You must make sure that there is an attribute
type on that element containing your plugin's class name
("AudioData"). Other than that, just make sure that you can read and write
your own format (ie, that you find your own information after that). See
below for more information about plugins.
Plugins
There are two types of plugins, the Data plugins and the DataSource ones. The Data plugins provide reading/writing and user editing of certain information. They implement the cdox.data.Data interface. For the user, they just provide a different Data type than the existing audio, video and generic types. The DataSource plugins provide a certain type of data by an automated process and implement the cdox.data.DataSource interface. An example is the FileSource class that is shipped with CDox.
There is not much to say about the plugins at all. Just implement the
interface and test it... The plugins should be placed in a directory called
plugins in the CDox directory. Under Linux, the
/usr/share/cdox/plugins directory is used as well as the ./plugins/
directory. You should not put your classes in a package at all, they work
out of the box if copied (as .class files) into these directories. For
examples, look into the source code (under plugins there can be found some
simple examples).
If you think you have written a useful plugin, just tell us. If we think it's good, we'll add it to the next version of CDox (if you agree). We're always happy to hear from CDox users!
Suggestions
For suggestions, just file a feature request/bug report at our sourceforge pages. Our long-term goal is to provide a good file format for anything that can (with good will) named "CD-Document", so feel free to participate in the process.
Please inform us also about incorrect information on this page (XML is quite interoperable, but humans sometimes are not due to mistakes they make).
Other useful stuff
We created several different utility classes during the creation of CDox. If you are interested in a XML-powered help browser, several easy-to-use image manipulation classes with GUI support or a configuration framework with automatic from-XML-to-Configuration-Dialogs then you should take a look into the sources/javadoc in the *util* packackes. As always, suggestions are welcome.