jApp
Class Application

java.lang.Object
  jApp.Application

public class Application
extends java.lang.Object

This class together with Document class implements the basic behaviour of a document based desktop application.

Author:

Kustaa Nyholm / SpareTimeLabs

Constructor Summary

protected

Application(java.lang.String[] args) Constructs the application object with a given title.

Method Summary

void	addItemsToRightClick(javax.swing.JPopupMenu popupMenu) Handles right clicks, the top of the chain of command for right clicks.
Variable	addVariable(java.lang.String name, Variable var) Adds an Appication Variable.
static void	centerWindow(java.awt.Window window) Centers a window on the screen so that it is horizontally in the center, vertically one third from the top.
protected void	checkDesktopIntegration() Checks and performs the desktop integration (file associations and icon installation) if this is the first launch of the application.
protected boolean	confirmIntegration() Shows the Desktop Integration confirmation dialog.
boolean	confirmReplaceFile(java.awt.Component component, java.io.File file) Short cut to confirmReplaceFile(Component, File, boolean).
int	confirmReplaceFile(java.awt.Component component, java.io.File file, boolean canCancel) Obtains confirmation from user for overwriting a file.
javax.swing.Action	createAboutMenuAction() Document calls this to create the 'About Appplication...' -action.
javax.swing.Action	createPreferencesMenuAction() Document calls this to create the 'Preferences...' -action.
java.awt.Point	ensureWindowOnScreen(java.awt.Point location) Ensures that a window is at least minimally on the screen so that the user can move it.
void	exitApplication() Tries to close all documents and exit the application with System.exit(0).
javax.swing.Action	getAboutMenuAction() Returns the 'About..." menu action that shows the 'About Application' dialog.
Document	getActiveDocument() Gets the active document.
java.awt.Frame	getActiveWindow() Gets the active window for use as parent frame for Application dialogs
java.lang.String	getApplicationConfigFileName() Gets the application config file name.
java.lang.String	getApplicationDirName() Gets the full path name for the application home directory.
java.lang.String	getApplicationFileNameBase() Gets the base file name for application files.
java.lang.String	getApplicationID() Gets the internal application for use as Windows Registry key etc.
java.util.ResourceBundle	getBundle() Gets the application resource bundle.
static java.lang.Object	getClipboard() Deprecated.
java.lang.String	getCopyright() Get the application copyright text from the application properties bundle.
java.lang.String	getDescription() Gets the application end user description.
java.lang.Iterable<Document>	getDocuments() Gets a an Iterable to iterate over all open documents
javax.swing.JFileChooser	getFileChooser() Gets a JFileChooser object.
java.io.File	getFileForReading(java.awt.Frame window, java.lang.String defaultname, java.lang.String desciption, java.lang.String[] extensions) Shows a file chooser dialog to let the user select, for reading from, an existing file with the given extension type and returns a File object to the selected file.
java.io.File	getFileForWriting(java.awt.Frame window, java.lang.String defaultname, java.lang.String extension) Shows a file chooser dialog to let the user select a file for writing to, new or existing,with the given extension type and returns a File object to the selected file.
FileTypeRegistry	getFileTypeRegistry() Gets the FileTypeRegistry for this this application.
java.lang.Iterable<FileType>	getFileTypes(Document handler) Gets an Iterable over the file FileTypes that the given Document can handle.
java.lang.String	getFullName() Gets the application end user full name.
static java.lang.String	getjAppVersion() Gets the jApp version string, which has the format major.minor.bugfix.development .
java.io.File	getLatesDirectory() Gets the latest directory user browsed with file chooser.
static java.io.FileInputStream	getlockedInputStream(java.io.File file) Tries to open a file as input stream in an exclusive but shared access mode.
static java.io.FileOutputStream	getLockedOutputStream(java.io.File file, boolean append) Tries to open a file as output stream in an exclusive access mode.
static int	getMenuShortcutKeyMask() A convenience method to get the menu short cut key mask, CTRL on windows, Comman/Apple on MacOS
protected javax.swing.Action	getNewAction() Gets the 'New...' document action that creates a new document of default type.
static javax.swing.KeyStroke	getNewShortcut() Gets the shortcut keystroke for the 'New...' action
static javax.swing.ImageIcon	getNullIcon() Gets a null icon to be used in menus when no icon is needed.
protected javax.swing.Action	getOpenAction() Gets the 'Open...' document that displays the file dialog and tries to open the selected document.
static javax.swing.KeyStroke	getOpenShortcut() Gets the shortcut keystroke for the 'Open...' action
javax.swing.Action	getPreferencesMenuAction() Returns the 'Preferences..." menu action that shows the 'Preferences' dialog.
java.lang.String	getResouceString(java.lang.String key, java.lang.String defaultValue) Gets a String resouce from the Application resource bundle.
java.lang.String	getShortName() Gets the application end user short name.
java.lang.String	getTemplateDirName() Gets the full path name of the directory for document templates.
java.lang.String	getVersion() Get the application version number from the application properties bundle.
protected void	initApplication() Initializes the application object.
protected void	initialized() Called when the application has been fully initialized.
protected void	initLinux() Does Linux specific initialisation.
protected void	initMacOS() Does MacOS specific initialisation.
protected void	initWindows() Does Microsoft Windows specific initialisation.
static boolean	inLinux() Returns true if running under Linux
static boolean	inMacOS() Returns true if running under MacOS
void	install(boolean install) Installs/uninstalls the application into/from the system.
void	installTemplate(java.lang.String name, java.io.InputStream src) Copies an input stream to the template directory under given file name.
protected void	installTemplates() Installs document templates.
static boolean	inWindows() Returns true if running under Windows
static boolean	isAqua() Returns true if running with Aqua Look and Feel under MacOS X.
static void	maximizeWindow(java.awt.Window window, java.awt.Insets insets) Maxizes a window on screen.
static javax.swing.JMenu	newMenu(java.lang.String title) This just a short cut for new JMenu(title).
static javax.swing.JMenuItem	newMenuItem(javax.swing.JMenu menu, java.lang.String title, javax.swing.Action action) Creates a JMenuItem with a given title for an action.
static javax.swing.JMenuItem	newMenuItem(javax.swing.JMenu menu, java.lang.String title, java.awt.event.ActionListener that) Creates a JMenuItem with the given title and 'null icon'.
protected void	openDocuments() Opens the documents passed to the application on the command line or an empty document of default type if no other documents are open at once the application is up and running.
Document	openNewDocument(java.lang.String type) Tries to create and open a new (empty) document of the given type.
Document	openOldDocument(java.lang.String file, boolean isTemplate) Given a filename tries to create and load an old (existing) document from that file.
static void	releaseInputStream(java.io.FileInputStream stream) Releases the lock and closes the stream.
static void	releaseOutputStream(java.io.FileOutputStream stream) Closes a stream and releases the lock.
void	reportException(java.lang.Exception e) Used to report an exception by showing an error message dialog and stack trace to the console.
void	run() Starts the Application createing and initializing everything as needed.
void	saveLatesDirectory(java.io.File dir) Saves the current browsing directory for the file chooser.
static void	setClipboard(java.lang.Object cbclipboard) Deprecated.
protected void	setLookAndFeel() Sets the look and feel for the Application.
int	showConfirmDialog(java.awt.Component component, java.lang.Object message, java.lang.String title, int type) Calls JOptionPane.showConfirmDialog(Component, Object, String, int).
void	showErrorMessage(java.lang.String message, java.lang.String title) Shortcut to showMessageDialog(Component, Object, String, int) with null parent component and message type set to JOptionPane.ERROR_MESSAGE.
void	showInfoMessage(java.lang.String message, java.lang.String title) Shortcut to showMessageDialog(Component, Object, String, int) with null parent component and message type set to JOptionPane.INFORMATION_MESSAGE.
void	showMessageDialog(java.awt.Component component, java.lang.Object message, java.lang.String title, int type) Calls JOptionPane.showMessageDialog(Component, Object, String, int).
void	showWarningMessage(java.lang.String message, java.lang.String title) Shortcut to showMessageDialog(Component, Object, String, int) with null parent component and message type set to JOptionPane.WARNING_MESSAGE.
Document	tryOpenNewDocument() Tries to open a new (empty) document of default type.
Document	tryOpenOldDocument() Tries to open an existing document by letting the user choose a file.
Document	tryOpenOldDocument(java.lang.String file, boolean isTemplate)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Application

protected Application(java.lang.String[] args)

Constructs the application object with a given title. The Application constructor attempts to load a resource bundle from

 ResourceBundle.getBundle(getClass().getCanonicalName());
 

For example if your main class is in package mypackage and your main class is called MyMainClass this will attempt to load the bundle from

file mypackage/MyMainClass.properties.

The Application attempts to read the following properties. These are not mandatory but should be set for any non trivial application. Especially application ID is important as it is used for example in registry entries in Windows. Some care should be exercised in order to come up with a unique name.

             jApp-copyright = a copyright text for the application, defaults to "Copyright (c) Undefined"
             jApp-version  = version number for the application, defaults to "Undefined"
             jApp-application-ID = a short indetifier to be used when an internal name is needed, defaults to "MyApp"
             jApp-applicagtion-description = an end user desription of the application, defaults to appliation ID
             jApp-application-short-name = short application name (max 16 chars), defaults to appliation ID
             jApp-application-full-name = full application name, defaults to appliation ID
             jApp-max-resent-files = number of recent files to remeber/store, defaults to 10
 

The following are optional, you can 'manually' register file types from with in your application code with calls to FileTypeRegistry.registerFileType(Class, String, String, String). The advatage of putting the following definition to the properties file is that the build process can access it. Note that for more than one file type the build scripts needs to be manually adjusted.

             jApp-application-doctypes =number of document types the application handles
 
             jApp-document-1-extension = file extension without the dot
             jApp-document-1-mimetype = the mime type for the document
             jApp-document-1-description = and end user description of the file/document type
             jApp-document-1-class = full class name for the document handler
 

Note that these are stored as properties to make it possible to utilize them in the build (Ant) process.

To use access them from the build file use 'loadproperties' Ant task as which includes only properties from lines that include the string 'jApp-'. This reduces the risk of name conflict between properties in the bundle and those in the build file.

                <loadproperties srcFile="./src/yourmainpackage/YourMainClass.properties">
                        <filterchain>
                                <linecontains>
                                        <contains value="jApp-" />
                                        </linecontains>
                                <filterchain>
                        </loadproperties>
 

Parameters:

args - You should pass the args argument from the Java main class main method to Application so that it gets access to command line parameters.

Method Detail

getMenuShortcutKeyMask

public static int getMenuShortcutKeyMask()

A convenience method to get the menu short cut key mask, CTRL on windows, Comman/Apple on MacOS

Returns:

the menu shortcut key mask

saveLatesDirectory

public void saveLatesDirectory(java.io.File dir)

Saves the current browsing directory for the file chooser.

Parameters:

dir - the direcotory to save

getLatesDirectory

public java.io.File getLatesDirectory()

Gets the latest directory user browsed with file chooser.

Returns:

the latest directory

getjAppVersion

public static java.lang.String getjAppVersion()

Gets the jApp version string, which has the format major.minor.bugfix.development . If the major and minor numbers of two different versions are the same then there is no new / changed functionality between those versions, in which case a non zero bugfix number indicates that this is a bug fix release, unless of course the development number is non-zero, in which case this a try-at-your-own-risk development version.

Returns:

the version string

getResouceString

public java.lang.String getResouceString(java.lang.String key,
                                         java.lang.String defaultValue)
                                  throws java.lang.IllegalArgumentException

Gets a String resouce from the Application resource bundle.

Parameters:

key - the resource key

defaultValue -

Returns:

the value for the from the resource bundle

Throws:

java.lang.IllegalArgumentException - if the resource cannot be found and defaultValue is null

See Also:

Application

getVersion

public java.lang.String getVersion()

Get the application version number from the application properties bundle. Application version number is the version number of the application not that of the jApp. The version number for your applicatio should be stored into a YourMainClass.properties resource bundle under key 'jApp-version'. The version number is stored in the properties file so that it is available to the build process (Ant based) and can be used in application packaging.

Returns:

the version string

See Also:

getBundle(), Application(String[])

getCopyright

public java.lang.String getCopyright()

Get the application copyright text from the application properties bundle. Application version number is the copyright text the application not that of the jApp. The version number for your applicatio should be stored into a YourMainClass.properties resource bundle under key 'jApp-copyright'. The version number is stored in the properties file so that it is available to the build process (Ant based) and can be used in application packaging.

Returns:

the copyright text string

See Also:

getVersion()

getBundle

public java.util.ResourceBundle getBundle()

Gets the application resource bundle.

Returns:

the application resource bundle

See Also:

Application

getActiveDocument

public Document getActiveDocument()

Gets the active document.

Returns:

the active document, can be null if there is none.

getFileChooser

public javax.swing.JFileChooser getFileChooser()

Gets a JFileChooser object. This returns always the same object, which is usually the prefered way of using a file chooser, because in this way the file chooser remembers the last used directory/folder. The file chooser is configured for selecting files (not directories) and to show all files. You can add your own filters, but these will be reset anytime this routine is called (again).

Returns:

the file chooser.

getClipboard

@Deprecated
public static java.lang.Object getClipboard()

Deprecated.

Gets the clipboard object. This is just an access function to a private essentially global variable that is used to hold the clipboard object. This is depracated, use Document.getClipboard() instead.

Returns:

the clup board object.

setClipboard

@Deprecated
public static void setClipboard(java.lang.Object cbclipboard)

Deprecated.

Sets the clipboard object. This is just a setter function to a private, essentially global variable, that is used to hold the clipboard object.

Parameters:

cbclipboard - the new cliboard object to set as the clicpboard

See Also:

Document.createClipboard()

exitApplication

public void exitApplication()

Tries to close all documents and exit the application with System.exit(0). May not exit if any of the windows refuses to close.

newMenuItem

public static javax.swing.JMenuItem newMenuItem(javax.swing.JMenu menu,
                                                java.lang.String title,
                                                java.awt.event.ActionListener that)

Creates a JMenuItem with the given title and 'null icon'. This is a static convenience function. The null icon is necessary for those menu items that do not have an icon otherwise many of the LAFs cannot properly align (left flush) the menu items on the menus.

If the menu parameter is not null adds the new menu item into that menu

Parameters:

menu - the menu to add the new item to

title - title of the menu item

that - an action listener

Returns:

the newly created menu item

newMenuItem

public static javax.swing.JMenuItem newMenuItem(javax.swing.JMenu menu,
                                                java.lang.String title,
                                                javax.swing.Action action)

Creates a JMenuItem with a given title for an action. If the action parameter is non null the action for the newly created menu item is set to action. Note that this may override/set the menu item title. This is a static convenience function.

Parameters:

menu -

title -

action -

Returns:

the newly created menu item

newMenu

public static javax.swing.JMenu newMenu(java.lang.String title)

This just a short cut for new JMenu(title).

Parameters:

title - the title for the menu.

Returns:

the new JMenu

openDocuments

protected void openDocuments()

Opens the documents passed to the application on the command line or an empty document of default type if no other documents are open at once the application is up and running. The empty document, if created, becomes the 'default document' which will be automatically closed,if not dirty, when and if we open some other document. This is necessery to ensure that at least one document is open at all times which is necessary to have a window for the application menu bar.

setLookAndFeel

protected void setLookAndFeel()

Sets the look and feel for the Application. Sets the LAF based on the Application variable "JAPP_PLATFORM_LAF". If the variable value is true the system (platform native) LAF is used, else the Java cross platform look and feel is used. Note that look and feel must be set early thats why Applications that want to set it need to do it in this method which gets called at initGUI. Can be overriden to implement different behaviour.

initMacOS

protected void initMacOS()

Does MacOS specific initialisation. Override if necessary but call super to get the standard behaviour.

initLinux

protected void initLinux()

Does Linux specific initialisation. Override if necessary but call super to get the standard behaviour.

initWindows

protected void initWindows()

Does Microsoft Windows specific initialisation. Override if necessary but call super to get the standard behaviour.

confirmIntegration

protected boolean confirmIntegration()

Shows the Desktop Integration confirmation dialog.

Returns:

true if the user confirms.

checkDesktopIntegration

protected void checkDesktopIntegration()

Checks and performs the desktop integration (file associations and icon installation) if this is the first launch of the application.

run

public void run()

Starts the Application createing and initializing everything as needed.

s Schedules the Application invokation, initilization and event processing to take place in the event dispatched thread.

initialized

protected void initialized()

Called when the application has been fully initialized.

getActiveWindow

public java.awt.Frame getActiveWindow()

Gets the active window for use as parent frame for Application dialogs

Returns:

either the topmost DocumentWindow or a hidden application window

ensureWindowOnScreen

public java.awt.Point ensureWindowOnScreen(java.awt.Point location)

Ensures that a window is at least minimally on the screen so that the user can move it. The location of the top left corner is passed as parameter

Parameters:

location - the windows location on screen

Returns:

the possible adjusted window location

Throws:

IllegalComponentStateException - if the window is not visible

centerWindow

public static void centerWindow(java.awt.Window window)

Centers a window on the screen so that it is horizontally in the center, vertically one third from the top. This is static utility function.

Parameters:

window - the window to center.

maximizeWindow

public static void maximizeWindow(java.awt.Window window,
                                  java.awt.Insets insets)

Maxizes a window on screen.

This is static utility function.

Maximes a window on screen leaving insets amount of space all aroung the window. If insets is null all screen space is utilized.

Parameters:

window - the window to maximize

insets - the insets use in maximizing

showMessageDialog

public void showMessageDialog(java.awt.Component component,
                              java.lang.Object message,
                              java.lang.String title,
                              int type)

Calls JOptionPane.showMessageDialog(Component, Object, String, int). This routine exists to be overridden in case some other widget toolkit than Swing is used. All methdo calls from within jApp framework that call JOptionPane.showMessageDialog(Component, Object, String, int) are routed through here.

Parameters:

component - the parent component for the swing method

message - the message string to the swing method

title - the title string to the swing method

type - the message type parameter to the swing method

See Also:

showConfirmDialog(Component, Object, String, int), JOptionPane

showConfirmDialog

public int showConfirmDialog(java.awt.Component component,
                             java.lang.Object message,
                             java.lang.String title,
                             int type)

Calls JOptionPane.showConfirmDialog(Component, Object, String, int). This routine exists to be overridden in case some other widget toolkit than Swing is used. All methdo calls from within jApp framework that call JOptionPane.showConfirmDialog(Component, Object, String, int) are routed through here.

Parameters:

component - the parent component for the swing method

message - the message string to the swing method

title - the title string to the swing method

type - the message type parameter to the swing method

See Also:

showMessageDialog(Component, Object, String, int), JOptionPane

showInfoMessage

public void showInfoMessage(java.lang.String message,
                            java.lang.String title)

Shortcut to showMessageDialog(Component, Object, String, int) with null parent component and message type set to JOptionPane.INFORMATION_MESSAGE.

Parameters:

message - the message to display to the user

title - the title for the dialog

showErrorMessage

public void showErrorMessage(java.lang.String message,
                             java.lang.String title)

Shortcut to showMessageDialog(Component, Object, String, int) with null parent component and message type set to JOptionPane.ERROR_MESSAGE.

Parameters:

message - the message to display to the user

title - the title for the dialog

showWarningMessage

public void showWarningMessage(java.lang.String message,
                               java.lang.String title)

Shortcut to showMessageDialog(Component, Object, String, int) with null parent component and message type set to JOptionPane.WARNING_MESSAGE.

Parameters:

message - the message to display to the user

title - the title for the dialog

reportException

public void reportException(java.lang.Exception e)

Used to report an exception by showing an error message dialog and stack trace to the console.

Parameters:

e - the Exception to report

openNewDocument

public Document openNewDocument(java.lang.String type)

Tries to create and open a new (empty) document of the given type. FileTypeRegistry is consulted to find out the class of the object that is used to handle the specified type of document. The handler must be a descandent of the class Document.

Parameters:

type - String designating the file type, e.g. ".txt" or ".doc"

See Also:

FileTypeRegistry

openOldDocument

public Document openOldDocument(java.lang.String file,
                                boolean isTemplate)
                         throws java.lang.Exception

Given a filename tries to create and load an old (existing) document from that file. FileTypeRegistry is consulted to find out the class of the object that is used to handle the specified type of document. The handler must be a descandent of the class Document.

Parameters:

file - a full path name for the document file

isTemplate - if true the Document is detached from the file and marked not dirty after reading in the contents of the document from the file

Throws:

java.lang.Exception

See Also:

FileTypeRegistry

tryOpenOldDocument

public Document tryOpenOldDocument(java.lang.String file,
                                   boolean isTemplate)

tryOpenNewDocument

public Document tryOpenNewDocument()

Tries to open a new (empty) document of default type.

tryOpenOldDocument

public Document tryOpenOldDocument()

Tries to open an existing document by letting the user choose a file.

getDocuments

public java.lang.Iterable<Document> getDocuments()

Gets a an Iterable to iterate over all open documents

Returns:

an Iterator to iterate over all open documents.

initApplication

protected void initApplication()

Initializes the application object. Override to do your initialisation that needs to be done befero the application variables are loaded and the GUI is constructed.

getFileForReading

public java.io.File getFileForReading(java.awt.Frame window,
                                      java.lang.String defaultname,
                                      java.lang.String desciption,
                                      java.lang.String[] extensions)

Shows a file chooser dialog to let the user select, for reading from, an existing file with the given extension type and returns a File object to the selected file.

Parameters:

window - the parent window for the file chooser dialog

defaultname - the default file name

desciption - a user description of the type of files such as 'Graphics Files'

extensions - the actual file extensions that are acceptable (including the 'dot', e.g. '.txt')

Returns:

the file object, null if user cancels, otherwise always refers to an existing file

confirmReplaceFile

public int confirmReplaceFile(java.awt.Component component,
                              java.io.File file,
                              boolean canCancel)

Obtains confirmation from user for overwriting a file. Shows via showConfirmDialog(Component, Object, String, int) a confirmation dialog to the user. The dialog is two way (yes/no) or three way (yes/no/cancel) depending on the parameter canCancel.

Parameters:

component - the parent component from which to obtain the Frame for the dialog. Can be null.

file - the file about to be overwritten

canCancel - true if the user is allowed to cancel

Returns:

one of JOptionPane.YES_OPTION/NO_OPTION/CANCEL_OPTION

confirmReplaceFile

public boolean confirmReplaceFile(java.awt.Component component,
                                  java.io.File file)

Short cut to confirmReplaceFile(Component, File, boolean). Call confirmReplaceFile(Component, File, boolean) with the last parameter set to false so that user neads to either confirm or deny, no cancel option is given.

Parameters:

component - the parent component from which to obtain the Frame for the dialog. Can be null.

file - the file about to be overwritten

Returns:

true if user confirms

getFileForWriting

public java.io.File getFileForWriting(java.awt.Frame window,
                                      java.lang.String defaultname,
                                      java.lang.String extension)

Shows a file chooser dialog to let the user select a file for writing to, new or existing,with the given extension type and returns a File object to the selected file. If the user selects an existing file, then a confirmation dialog is shown to confirm overwriting.

Parameters:

window - the parent window for the file chooser dialog

defaultname - the default file name

extension - the file extension (including the 'dot', e.g. '.txt')

Returns:

the file object, null if user cancels

getTemplateDirName

public java.lang.String getTemplateDirName()

Gets the full path name of the directory for document templates. The templates are stored in sub-directory of the application directory called templates.

Returns:

the full path for the template directory

See Also:

getApplicationDirName()

getApplicationDirName

public java.lang.String getApplicationDirName()

Gets the full path name for the application home directory. The application home directory is readable/writeable directory into which application can store configuration information, preferences, helper files etc.

Returns:

the full path for the application home directory.

getApplicationConfigFileName

public java.lang.String getApplicationConfigFileName()

Gets the application config file name.

Returns:

the full path name of the config file.

getApplicationFileNameBase

public java.lang.String getApplicationFileNameBase()

Gets the base file name for application files. This can be/is used with to form application specific file names by adding a suitable post fix/extension. The file name includes the path, which refers tot the Application directory.

Returns:

the base file name for application files, including full path.

See Also:

getApplicationDirName()

addVariable

public Variable addVariable(java.lang.String name,
                            Variable var)

Adds an Appication Variable. Application variables are loaded when the Application object has been initialized in initApplication and saved just before exiting the application. jApp client code can utilize Application Variables to store persistently whatever they need. The only requirement is that the value of the Variable needs to be serializable.

Internally jApp uses variables for example to store the 'recent files' list. The names of all variables used internally by jApp begin with "JAPP_" so it is best to avoid names like that in order to avoid name clashes.

Parameters:

name - for the varible

var - the variable object

Returns:

the parameter var

See Also:

Variable

installTemplate

public void installTemplate(java.lang.String name,
                            java.io.InputStream src)

Copies an input stream to the template directory under given file name.

Parameters:

name - the file name (without path) to copy the input stream to

src - the source input stream

installTemplates

protected void installTemplates()

Installs document templates. Override if your application wants to install document templates. This is called after the application has been initialized and persistent variables read in but before GUI has been initilized.

See Also:

installTemplate(String, InputStream)

inMacOS

public static boolean inMacOS()

Returns true if running under MacOS

inWindows

public static boolean inWindows()

Returns true if running under Windows

inLinux

public static boolean inLinux()

Returns true if running under Linux

isAqua

public static boolean isAqua()

Returns true if running with Aqua Look and Feel under MacOS X.

getNewShortcut

public static javax.swing.KeyStroke getNewShortcut()

Gets the shortcut keystroke for the 'New...' action

Returns:

the keystroke

getOpenShortcut

public static javax.swing.KeyStroke getOpenShortcut()

Gets the shortcut keystroke for the 'Open...' action

Returns:

the keystroke

getNewAction

protected javax.swing.Action getNewAction()

Gets the 'New...' document action that creates a new document of default type.

Returns:

the action

getOpenAction

protected javax.swing.Action getOpenAction()

Gets the 'Open...' document that displays the file dialog and tries to open the selected document.

Returns:

the action

getAboutMenuAction

public javax.swing.Action getAboutMenuAction()

Returns the 'About..." menu action that shows the 'About Application' dialog.

Returns:

the action that shows the dialog, can be null

getPreferencesMenuAction

public javax.swing.Action getPreferencesMenuAction()

Returns the 'Preferences..." menu action that shows the 'Preferences' dialog.

Returns:

the action that shows the dialog, can be null

createAboutMenuAction

public javax.swing.Action createAboutMenuAction()

Document calls this to create the 'About Appplication...' -action. Override to implement this functionality.

Returns:

the action to show the dialog, null by default

createPreferencesMenuAction

public javax.swing.Action createPreferencesMenuAction()

Document calls this to create the 'Preferences...' -action. Override to implement this functionality.

Returns:

the action to show the dialog, null by default

getApplicationID

public java.lang.String getApplicationID()

Gets the internal application for use as Windows Registry key etc. The contract is that the internal name is valid java identifier name, (even though it is just a String).

Returns:

the ID-string

getShortName

public java.lang.String getShortName()

Gets the application end user short name.

Returns:

the short name

See Also:

getFullName()

getFullName

public java.lang.String getFullName()

Gets the application end user full name. For example the full name is "Microsoft Excel" where as the short name is "Excel".

Returns:

the full name

See Also:

getShortName()

getDescription

public java.lang.String getDescription()

Gets the application end user description.

Returns:

the description string

getFileTypeRegistry

public FileTypeRegistry getFileTypeRegistry()

Gets the FileTypeRegistry for this this application.

Returns:

the registry

See Also:

FileTypeRegistry

getFileTypes

public java.lang.Iterable<FileType> getFileTypes(Document handler)

Gets an Iterable over the file FileTypes that the given Document can handle.

Parameters:

handler - the Document whose filetypes are requested

Returns:

the iterable over the file types for the given handler

install

public void install(boolean install)

Installs/uninstalls the application into/from the system.

s Installation means associating the application with its file types with the Desktop Manager. Does not nothing in Mac OS as file associations are handled automatically by properly packaging the application on that platform.

Parameters:

install - pass true for install false for un-install

getNullIcon

public static javax.swing.ImageIcon getNullIcon()

Gets a null icon to be used in menus when no icon is needed. In Mac OS Application very few applications seem to use icons in menus. When they do, the text is indented to make room for the icon. In Windows, the texts are aligned weather or not there is an icon. With current Swing Windows look & feel this does not happen automatically. Thus a null icon is needed to get more fidelity in Windows. Hence this routine.

Returns:

an empty icon or null;

getLockedOutputStream

public static java.io.FileOutputStream getLockedOutputStream(java.io.File file,
                                                             boolean append)
                                                      throws java.io.IOException

Tries to open a file as output stream in an exclusive access mode. Returns null if it is unable to obtain an exclusive lock on the file. Note that in Java the lock maybe only 'advisory' so this is not an absolute guarantee that the access is exclusive. Unlike direct call to FileChannel.tryLock(long, long, boolean) this method guards against access to the same file from the same process / thread.

Parameters:

file - the file to open in output mode

append - weather to open the in append mode or not

Returns:

the open FileOutputStream or null if the file was locked

Throws:

java.io.IOException - if the stream or lock open fails with exception

getlockedInputStream

public static java.io.FileInputStream getlockedInputStream(java.io.File file)
                                                    throws java.io.IOException

Tries to open a file as input stream in an exclusive but shared access mode. Returns null if it is unable to obtain an exclusive lock on the file. Note that in Java the lock maybe only 'advisory' so this is not an absolute guarantee that the access is exclusive. Unlike direct call to FileChannel.tryLock(long, long, boolean) this method guards against access to the same file from the same process / thread.

Parameters:

file - the file to open in input mode

Returns:

the open FileInputStream or null if the file was locked

Throws:

java.io.IOException - if the stream or lock open fails with exception

releaseInputStream

public static void releaseInputStream(java.io.FileInputStream stream)
                               throws java.io.IOException

Releases the lock and closes the stream.

Parameters:

stream - the locked stream to close and release

Throws:

java.io.IOException - if close operation failse

java.lang.IllegalArgumentException - the stream has not been previously locked with getlockedInputStream(File)

releaseOutputStream

public static void releaseOutputStream(java.io.FileOutputStream stream)
                                throws java.io.IOException

Closes a stream and releases the lock.

Parameters:

stream - the locked stream to close and release

Throws:

java.io.IOException - if close operation failse

java.lang.IllegalArgumentException - the stream has not been previously locked with getLockedOutputStream(File,boolean)

addItemsToRightClick

public void addItemsToRightClick(javax.swing.JPopupMenu popupMenu)

Handles right clicks, the top of the chain of command for right clicks.

Parameters:

popupMenu - the popup menu to fill in