Jarnal - Startup

by David K. Levine

Startup

The command line format is java -jar jarnal.jar [options] [file_to_open].
Several command line options are supported

-t filename opens the file as a template so it will not be accidentally overwritten when saving
-b filename opens filename as a background file
-bb filename similar to -b except that if a file that begins with filename and ends with .jaj exists in the same directory, that file will be opened instead of opening filename as a background file.
-m filename opens filename as a metadata file; meta data files are described below
-n do not show the menu bar
-p restore window to previous position of file/template on the screen
-pnxm restore window to the absolute position nxm ignoring whatever the saved position might be
-l filename load filename as an "extra" file to be stored in the .jaj file (this option may be specified more than once)
-g use an external renderer such as ghostscript or xpdf to render pdf
-sg use a silent external renderer. Similar to -g except that if the renderer fails, instead of popping up a message and switching to the internal renderer, the internal render is used for the current page only without a message. Useful if you use ghostscript with documents that have bad pdf.
-mini supercedes all other command lines switches to open a mini-jarnal suitable for copying recognized text to the clipboard
-pen starts in pencentric mode
-s filename sets the name and directory the file will be saved in
-fs start up full-screen
-pdf filename converts the .jaj file into a pdf file called filename from the command line without opening the gui. You may use - for the filename in which case if the .jaj file is called fname.jaj the pdf file will be called fname.pdf. Note that the print options should already be set in the .jaj file. Note also that to run jarnal under linux you must have an xserver running. If you are running without one, install the dummy xserver Xvfb and use the command Xvfb :1 -screen 0 10x10x8 -pixdepths 1 &export DISPLAY=:1.0 ; java -Xmx192m -jar jarnal.jar -pdf - whatever.jaj making sure to kill Xvfb when you are done.
-connect hostname:port initiates a connection to the server operating on port at hostname

If filename begins with http:// the file will be downloaded from the url rather than loaded from the local filesystem.

MetadataFiles: A metadata file is a text file containing command line options plus other options. Here is a sample

[Globals]
jarnalFile=http://localhost/main/docs/newfiles/hi.jaj
templateFile=http://localhost/main/docs/newfiles/hi.jaj
netServer=http://localhost/workshops/testup.php3
netSaveName=myfile.jaj
backgroundFile=whatever
URLEncode=false
email=one@a.com, John <john@b.com>
[Net Options]
infile=$$jarnal

The format is the usual .ini file format. There are two sections in the metadata file [Globals] and [Net Options]. The [Net Options] section will be used as the default Network Save Options, to send information back to a server. The [Globals] section supports the following keys:

jarnalFile to open
templateFile to open
backgroundFile to open
email list of email addresses
loadFile an "extra" file to be saved in the .jaj zip; you may specify as many as you like
netServer to send network saves to
netSaveName sets the network save name
promptForNetSaveName whether if the network save name is not set and the user attempts to exit a prompt to set the network save name will be issued
URLEncode whether data going back to the server should be urlencoded - see below
showMenu set to false is the same as command line switch -n
setLocation set to true is the same as command line switch -p

The intended usage is that a web server can generate a metadata file on the fly instructing jarnal what file to download and open, and where the server is so that the file can be saved back to the server.

Applet Parameters: The applet uses parameters to set the metadata. The parameters pn where n is an integer, and the parameters are numbered sequentially starting with 0 become [Net Options]. For example the jarnal-demo.htm file uses the following (you can view the source by clicking on the files and viewing the code in your browser).

<applet code="jarnal/Jarnal" archive="jarnal.jar" width="20" height="20">
<param name=netServer value="http://www.dklevine.com/workshops/jarnal.php3">
<param name=p0 value="just=a test">
<param name=p1 value="infile=$$snapshot">
</applet>

This will cause the network save function to send a jpg snapshot under the name infile to the php script http://www.dklevine.com/workshops/jarnal.php3. Note that due to java security restrictions, this script will work only if loaded from www.dklevine.com.

All keys that can appear in metafiles can appear as applet parameters. In addition three additional keys are supported

metaFile load the specified metaFile
embed if set to true the applet will be embedded in the web page rather than appearing in a separate window
showGUI if set to true the entire GUI will be available, and the applet will behave the same way as the application. This must be used with caution. The applet can only interact with the server it was loaded to, and cannot access the local file system or clipboard. By default these options are disabled. However, if the applet is signed, it can be given access to the full resources available on the computer. The showGUI parameter is intended to be set only when the applet is signed.
loadFile should be specified as loadFilen where each file is assigned a different integer n

Priorities: When opened as an application, parameters can be read from several locations.

1. Either a template or a file can be opened, but not both, and no more than one of each should be specified. If both a template and a file to open are specified, whichever appears last on the command line is used; if a template was specified, the whichever file is used is treated as a template. If a metadatafile is used, the background, template and file replace those specified on the command line. The template in a metadatafile always has priority over opening a file. The first encountered file is used. Files specified in a metadata file have priority over files specified by applet parameters.

2. Only one background file should be specified as an option at loading; it is added to whatever backgrounds already exist in the file. The background in the file or template that is opened takes priority over that specified in the metadatafile or the command line. On the command line, the last encountered background file is used; in a metadata file the first encountered background file is used.

3. It is not regarded as an error to have duplicate network save parameters in different locations; since network save parameters are stored in the .jaj file, when a metadata file is loaded from the network, it will generally duplicate parameters stored in the loaded file. The parameters in the metadata file take precedence. applet parameters get second priority, and parameters in the file get least priority. Metadata variables ([Network Options]) are combined with those from the applet, and the two together replace any variables in the file.