PuffinApp

java.lang.Object
- net.talvi.puffinplot.PuffinApp

```
public class PuffinApp
extends java.lang.Object
```
Instantiating PuffinApp starts the PuffinPlot desktop application. It starts with no visible windows; a call to show() will open the main window. PuffinApp's main responsibility is connecting the GUI classes to the classes which handle the actual data. Most of the actions defined in PuffinActions act as thin wrappers around one or a few calls to PuffinApp. The most significant data classes used in PuffinApp are Suite, Site, and Sample.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`about()` Shows the application's ‘About’ dialog box, giving brief information about PuffinPlot.
`void`	`calculateGreatCirclesDirections()` For all selected sites, calculates the site mean direction by best-fit intersection of great circles fitted to that site's samples.
`void`	`calculateMultiSuiteMeans()` Calculate means across all currently loaded suites.
`void`	`clearAmsCalcs()` Clears the results of any AMS calculations for the current suite.
`void`	`clearPreferences()` Shows a confirmation dialog.
`void`	`clearSiteCalculations()` Clears any previously calculated Fisherian or great-circle site directions.
`void`	`closeCurrentSuite()` Closes the suite whose data is currently being displayed.
`void`	`copyStepSelection()` Copies the current pattern of selected treatment steps to a clipboard.
`static PuffinApp`	`create()` Create and return a new PuffinApp object.
`void`	`createNewSuite()` Creates a new, empty suite and adds it to the suite list.
`void`	`doAmsCalc(AmsCalculationType calcType, java.lang.String scriptName)` Performs statistical calculations on AMS data using a script from Lisa Tauxe's pmagpy software suite.
`void`	`doPcaOnSelection()` For all selected samples, determine a best-fit line to the selected treatment steps by principal component analysis.
`void`	`errorDialog(java.lang.String title, java.lang.String message)` Displays a dialog box reporting an error over this PuffinApp's main window.
`static void`	`errorDialog(java.lang.String title, java.lang.String message, java.awt.Component parent)` Displays a dialog box reporting an error.
`void`	`exportPdfFreehep(java.io.File pdfFile)` Writes a PDF file containing data plots with the current layout for all selected samples.
`void`	`exportPdfItext(java.io.File pdfFile)` Writes a PDF file containing data plots with the current layout for all selected samples.
`void`	`fitGreatCirclesToSelection()` For all selected samples, fit a great circle to the selected treatment steps.
`void`	`flipSelectedSamples(MeasurementAxis axis)` For all selected samples, rotates magnetization data 180° around the specified axis.
`PuffinActions`	`getActions()` Returns the actions associated with this PuffinApp.
`java.util.List<Sample>`	`getAllSamplesInSelectedSites()` Gets all the samples in all the sites having at least one selected sample.
`java.lang.String`	`getBuildProperty(java.lang.String key)` Reads values from the `build.properties` file.
`Correction`	`getCorrection()` Returns the correction currently being applied to the data displayed by this PuffinApp.
`java.awt.print.PageFormat`	`getCurrentPageFormat()` Returns the current page format.
`Sample`	`getCurrentSample()` Gets the currently displayed Sample
`Site`	`getCurrentSite()` Returns the site for which data is currently being displayed.
`Suite`	`getCurrentSuite()` Returns the currently displayed Suite.
`MainWindow`	`getMainWindow()` Returns this PuffinApp's main window
`PlotParams`	`getPlotParams()`
`PuffinPrefs`	`getPrefs()` Returns the preferences for this PuffinApp.
`RecentFileList`	`getRecentFiles()` Returns the list of recently used files.
`java.util.List<Sample>`	`getSelectedSamples()` Gets all the currently selected samples.
`java.util.List<Site>`	`getSelectedSites()` Gets all the sites containing any of the currently selected samples.
`SiteMeanWindow`	`getSiteEqAreaWindow()` Returns the great-circle statistics window.
`SuiteEqAreaWindow`	`getSuiteEqAreaWindow()` Returns the suite equal-area plot window.
`java.util.List<Suite>`	`getSuites()` Returns all the Suites currently open within this PuffinApp.
`TableWindow`	`getTableWindow()` Returns the data table window.
`Version`	`getVersion()` Returns the version of this PuffinPlot build.
`void`	`modifySelectedSamples(java.util.function.Consumer<Sample> function)` Applies the supplied function to each of the currently selected samples, then redoes any existing calculations for the selected samples and any sites that contain them.
`java.util.List<java.io.File>`	`openFileDialog(java.lang.String title)` Show an "open file" dialog.
`void`	`openFiles(java.util.List<java.io.File> files, boolean createNewSuite)` Reads data into the current suite, or a new suite, from the specified files.
`void`	`openWebPage(java.lang.String uriString)` Opens the specified URI in the default system browser.
`void`	`pasteStepSelection()` For each selected sample, selects the treatment steps corresponding to those last copied to the clipboard.
`void`	`quit()` Terminates this instance of PuffinApp immediately.
`void`	`recalculateSamplesAndSites(java.util.Collection<Sample> samples)` Redo existing sample and site calculations affected by specified samples.
`void`	`redoCalculationsForAllSuites()` Recalculates all sample and site calculations in all currently open suites.
`void`	`runJavascriptScript(java.lang.String scriptPath)` Runs a specified script written in JavaScript
`void`	`runPythonScriptInGui(java.lang.String scriptPath)` Runs a specified Python script, first downloading Jython if required.
`void`	`save()` Saves the current suite under its current filename.
`void`	`save(Suite suite)` Saves the specified suite under its current filename.
`void`	`setCorrection(Correction correction)` Sets the correction to apply to the displayed data.
`void`	`setCurrentSuite(int index)` Sets the currently displayed Suite.
`void`	`setRecentFiles(RecentFileList recentFiles)` Sets the list of recently used files (allowing it to be restored after restarting the application).
`void`	`show()` Shows the main window of this PuffinApp.
`void`	`showCalculateRpiDialog()` Calculates RPI using two loaded suites.
`void`	`showCreateBundleDialog()` Shows the dialog for creating and exporting a data and code bundle.
`void`	`showCustomFlagsWindow()` Shows the window for editing the titles of the custom flags.
`void`	`showCustomNotesWindow()` Shows the window for editing the titles of the custom notes.
`void`	`showDiscreteToContinuousDialog()` Shows the dialog for a discrete to continuous sample conversion.
`void`	`showImportAmsDialog()` Shows an ‘open files’ dialog box; if the user selects any files, AMS data will be imported from them.
`void`	`showImportPreferencesDialog()` Shows an ‘open file’ dialog box; if the user selects a file, the current preferences will be overwritten with preferences data from that file.
`void`	`showMacOpenFolderDialog()` Show the "Open folder" dialog on Mac OS X.
`void`	`showOpenFilesDialog(boolean createNewSuite)` Shows an ‘open files’ dialog box.
`void`	`showPageSetupDialog()` Opens the page setup dialog box.
`void`	`showPreferences()` Opens the preferences window.
`void`	`showPrintDialog(java.lang.String window)` Shows a print dialog.
`void`	`showRescaleMagSusDialog()` Scales all magnetic susceptibility values in the current suite by a user-specified factor.
`void`	`showRunJavascriptScriptDialog()` Opens a file selection dialog and runs the Javascript script (if any) which the user selects from that dialog.
`void`	`showRunPythonScriptDialog()` Opens a file selection dialog and runs the Python script (if any) which the user selects from that dialog.
`void`	`updateDisplay()` Updates the main window and table window to reflect any changes in the currently displayed data.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - create
```
public static PuffinApp create()
```
    Create and return a new PuffinApp object. The GUI elements are created, but not shown.
    
    Returns:
    
    a new PuffinApp object
  - show
```
public void show()
```
    Shows the main window of this PuffinApp. If the main window is already visible, this method has no effect.
  - getPlotParams
```
public PlotParams getPlotParams()
```
    Returns:
    
    the plot parameters controlled by the GUI of this PuffinApp instance
  - redoCalculationsForAllSuites
```
public void redoCalculationsForAllSuites()
```
    Recalculates all sample and site calculations in all currently open suites. Intended to be called when the correction (none/sample/formation) has changed.
  - getBuildProperty
```
public java.lang.String getBuildProperty(java.lang.String key)
```
    Reads values from the build.properties file. This is a properties file written into the PuffinPlot jar at build time, and currently contains the keys build.date and build.year.
    
    Parameters:
    
    key - the property key to read
    
    Returns:
    
    the value of the key
  - calculateGreatCirclesDirections
```
public void calculateGreatCirclesDirections()
```
    For all selected sites, calculates the site mean direction by best-fit intersection of great circles fitted to that site's samples.
  - recalculateSamplesAndSites
```
public void recalculateSamplesAndSites(java.util.Collection<Sample> samples)
```
    Redo existing sample and site calculations affected by specified samples.
    Any existing PCA calculations or great-circle fits will be done for the specified samples, and any existing great-circle or Fisherian calculations will be done for any site containing one of the specified samples. Site calculations will not be done for sites that don't have them already.
    This method does not update the display.
    
    Parameters:
    
    samples - samples which have changed
  - fitGreatCirclesToSelection
```
public void fitGreatCirclesToSelection()
```
    For all selected samples, fit a great circle to the selected treatment steps.
  - doPcaOnSelection
```
public void doPcaOnSelection()
```
    For all selected samples, determine a best-fit line to the selected treatment steps by principal component analysis.
    Any affected Fisherian site means or great-circle directions will be recalculated automatically. These directions will not be calculated for any sites that don't have them already.
  - getPrefs
```
public PuffinPrefs getPrefs()
```
    Returns the preferences for this PuffinApp.
    
    Returns:
    
    the preferences for this PuffinApp
  - getMainWindow
```
public MainWindow getMainWindow()
```
    Returns this PuffinApp's main window
    
    Returns:
    
    this PuffinApp's main window
  - getCorrection
```
public Correction getCorrection()
```
    Returns the correction currently being applied to the data displayed by this PuffinApp.
    
    Returns:
    
    the correction currently being applied to the displayed data
  - setCorrection
```
public final void setCorrection(Correction correction)
```
    Sets the correction to apply to the displayed data. This method is final because it is used in the constructor.
    
    Parameters:
    
    correction - the correction to apply to the displayed data
  - updateDisplay
```
public void updateDisplay()
```
    Updates the main window and table window to reflect any changes in the currently displayed data.
  - closeCurrentSuite
```
public void closeCurrentSuite()
```
    Closes the suite whose data is currently being displayed.
  - createNewSuite
```
public void createNewSuite()
```
    Creates a new, empty suite and adds it to the suite list. Mainly intended for use by scripts, so not currently accessible via the GUI.
  - openFiles
```
public void openFiles(java.util.List<java.io.File> files,
                      boolean createNewSuite)
```
    Reads data into the current suite, or a new suite, from the specified files.
    
    Parameters:
    
    files - the files from which to read data
    
    createNewSuite - whether to create a new suite; if this parameter is true or if there is no current suite, a new suite will be created for the data.
  - errorDialog
```
public static void errorDialog(java.lang.String title,
                               java.lang.String message,
                               java.awt.Component parent)
```
    Displays a dialog box reporting an error. The supplied message will be placed within an HTML <p> element to allow it to word-wrap.
    
    Parameters:
    
    title - the title for the dialog box
    
    message - the message to be displayed
    
    parent - the dialog will be displayed in this component's Frame
  - errorDialog
```
public void errorDialog(java.lang.String title,
                        java.lang.String message)
```
    Displays a dialog box reporting an error over this PuffinApp's main window. This is a convenience wrapper for the static errorDialog(java.lang.String, java.lang.String, java.awt.Component) method.
    
    Parameters:
    
    title - the title for the dialog box
    
    message - the message to be displayed
  - getSuites
```
public java.util.List<Suite> getSuites()
```
    Returns all the Suites currently open within this PuffinApp.
    
    Returns:
    
    all the currently open suites as an unmodifiable list
  - getCurrentSuite
```
public Suite getCurrentSuite()
```
    Returns the currently displayed Suite.
    
    Returns:
    
    the current Suite
  - setCurrentSuite
```
public void setCurrentSuite(int index)
```
    Sets the currently displayed Suite.
    
    Parameters:
    
    index - the index of the suite to be displayed within PuffinApp's list of suites
  - getCurrentSample
```
public Sample getCurrentSample()
```
    Gets the currently displayed Sample
    
    Returns:
    
    the current Sample, or null if there is no current sample.
  - getSelectedSamples
```
public java.util.List<Sample> getSelectedSamples()
```
    Gets all the currently selected samples. If there are no selected samples, an empty list will be returned.
    
    Returns:
    
    the currently selected samples
  - modifySelectedSamples
```
public void modifySelectedSamples(java.util.function.Consumer<Sample> function)
```
    Applies the supplied function to each of the currently selected samples, then redoes any existing calculations for the selected samples and any sites that contain them.
    
    Parameters:
    
    function - function to apply to the currently selected samples
  - getCurrentSite
```
public Site getCurrentSite()
```
    Returns the site for which data is currently being displayed.
    
    Returns:
    
    the current site, or null if there is no current site
  - getSelectedSites
```
public java.util.List<Site> getSelectedSites()
```
    Gets all the sites containing any of the currently selected samples.
    
    Returns:
    
    all the sites which contain any of the currently selected samples
  - getAllSamplesInSelectedSites
```
public java.util.List<Sample> getAllSamplesInSelectedSites()
```
    Gets all the samples in all the sites having at least one selected sample.
    
    Returns:
    
    all the samples contained in any site containing at least one selected sample
  - quit
```
public void quit()
```
    Terminates this instance of PuffinApp immediately.
  - about
```
public void about()
```
    Shows the application's ‘About’ dialog box, giving brief information about PuffinPlot.
  - showPreferences
```
public void showPreferences()
```
    Opens the preferences window.
  - showPageSetupDialog
```
public void showPageSetupDialog()
```
    Opens the page setup dialog box.
  - getCurrentPageFormat
```
public java.awt.print.PageFormat getCurrentPageFormat()
```
    Returns the current page format.
    
    Returns:
    
    the current page format
  - getTableWindow
```
public TableWindow getTableWindow()
```
    Returns the data table window.
    
    Returns:
    
    the data table window
  - getActions
```
public PuffinActions getActions()
```
    Returns the actions associated with this PuffinApp.
    
    Returns:
    
    the action associated with this PuffinApp
  - getSuiteEqAreaWindow
```
public SuiteEqAreaWindow getSuiteEqAreaWindow()
```
    Returns the suite equal-area plot window.
    
    Returns:
    
    the suite equal-area plot window
  - getSiteEqAreaWindow
```
public SiteMeanWindow getSiteEqAreaWindow()
```
    Returns the great-circle statistics window.
    
    Returns:
    
    the great-circle statistics window
  - getRecentFiles
```
public RecentFileList getRecentFiles()
```
    Returns the list of recently used files.
    
    Returns:
    
    the list of recently used files
  - setRecentFiles
```
public void setRecentFiles(RecentFileList recentFiles)
```
    Sets the list of recently used files (allowing it to be restored after restarting the application).
    
    Parameters:
    
    recentFiles - the list of recently used files
  - showCustomFlagsWindow
```
public void showCustomFlagsWindow()
```
    Shows the window for editing the titles of the custom flags.
  - showCustomNotesWindow
```
public void showCustomNotesWindow()
```
    Shows the window for editing the titles of the custom notes.
  - doAmsCalc
```
public void doAmsCalc(AmsCalculationType calcType,
                      java.lang.String scriptName)
```
    Performs statistical calculations on AMS data using a script from Lisa Tauxe's pmagpy software suite.
    
    Parameters:
    
    calcType - the type of calculation to perform
    
    scriptName - the external script which will perform the calculations
  - openFileDialog
```
public java.util.List<java.io.File> openFileDialog(java.lang.String title)
```
    Show an "open file" dialog.
    
    Parameters:
    
    title - title for the dialog
    
    Returns:
    
    a list of the files selected by the user; may be empty if no files were selected
  - showMacOpenFolderDialog
```
public void showMacOpenFolderDialog()
```
    Show the "Open folder" dialog on Mac OS X.
  - showOpenFilesDialog
```
public void showOpenFilesDialog(boolean createNewSuite)
```
    Shows an ‘open files’ dialog box.
    
    Parameters:
    
    createNewSuite - If true, or if there is no current suite, a new suite will be created for the data from the files; otherwise, the data will be added to the current suite.
  - showImportAmsDialog
```
public void showImportAmsDialog()
```
    Shows an ‘open files’ dialog box; if the user selects any files, AMS data will be imported from them. The files are expected to be in Agico ASC format, as produced by the SAFYR and SUSAR programs.
  - showImportPreferencesDialog
```
public void showImportPreferencesDialog()
```
    Shows an ‘open file’ dialog box; if the user selects a file, the current preferences will be overwritten with preferences data from that file. The file is expected to contain Java Preferences data in XML format.
  - clearPreferences
```
public void clearPreferences()
```
    Shows a confirmation dialog. If the user confirms, all user preferences data is deleted and preferences revert to default values.
  - copyStepSelection
```
public void copyStepSelection()
```
    Copies the current pattern of selected treatment steps to a clipboard.
    
    See Also:
    
    pasteStepSelection()
  - pasteStepSelection
```
public void pasteStepSelection()
```
    For each selected sample, selects the treatment steps corresponding to those last copied to the clipboard.
    
    See Also:
    
    copyStepSelection()
  - flipSelectedSamples
```
public void flipSelectedSamples(MeasurementAxis axis)
```
    For all selected samples, rotates magnetization data 180° around the specified axis. The intended use is to correct erroneous data caused by incorrect sample orientation during measurement.
    
    Parameters:
    
    axis - the axis around which to flip the selected samples
  - showRescaleMagSusDialog
```
public void showRescaleMagSusDialog()
```
    Scales all magnetic susceptibility values in the current suite by a user-specified factor.
  - clearSiteCalculations
```
public void clearSiteCalculations()
```
    Clears any previously calculated Fisherian or great-circle site directions.
  - clearAmsCalcs
```
public void clearAmsCalcs()
```
    Clears the results of any AMS calculations for the current suite.
  - exportPdfItext
```
public void exportPdfItext(java.io.File pdfFile)
                    throws java.io.FileNotFoundException,
                           com.itextpdf.text.DocumentException
```
    Writes a PDF file containing data plots with the current layout for all selected samples. One page is produced per selected sample.
    
    Parameters:
    
    pdfFile - the PDF file to which to write the plots
    
    Throws:
    
    com.itextpdf.text.DocumentException - if an error occurred while writing the PDF
    
    java.io.FileNotFoundException - if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason
  - exportPdfFreehep
```
public void exportPdfFreehep(java.io.File pdfFile)
                      throws java.io.IOException
```
    Writes a PDF file containing data plots with the current layout for all selected samples. One page is produced per selected sample.
    
    Parameters:
    
    pdfFile - the PDF file to which to write the plots
    
    Throws:
    
    java.io.IOException - if there was an error during file writing
  - calculateMultiSuiteMeans
```
public void calculateMultiSuiteMeans()
```
    Calculate means across all currently loaded suites.
  - runPythonScriptInGui
```
public void runPythonScriptInGui(java.lang.String scriptPath)
                          throws java.io.IOException,
                                 javax.script.ScriptException
```
    Runs a specified Python script, first downloading Jython if required. This method attempts to run a specified Python script. First it checks if the Jython jar is already cached locally in PuffinPlot's application data folder. If not, it prompts the user for confirmation and downloads and caches it from a hardcoded URL. If the download is successful, or if Jython is already available, the script will then be run, with the variable "puffin_app" set to this PuffinApp.
    
    Parameters:
    
    scriptPath - the path to the script
    
    Throws:
    
    java.io.IOException - if an IO error occurred while running the script
    
    javax.script.ScriptException - if a scripting error occurred
  - showRunPythonScriptDialog
```
public void showRunPythonScriptDialog()
```
    Opens a file selection dialog and runs the Python script (if any) which the user selects from that dialog.
  - runJavascriptScript
```
public void runJavascriptScript(java.lang.String scriptPath)
```
    Runs a specified script written in JavaScript
    
    Parameters:
    
    scriptPath - the path to the JavaScript script
  - showRunJavascriptScriptDialog
```
public void showRunJavascriptScriptDialog()
```
    Opens a file selection dialog and runs the Javascript script (if any) which the user selects from that dialog.
  - getVersion
```
public Version getVersion()
```
    Returns the version of this PuffinPlot build.
    
    Returns:
    
    the version of this PuffinPlot build
  - openWebPage
```
public void openWebPage(java.lang.String uriString)
```
    Opens the specified URI in the default system browser.
    
    Parameters:
    
    uriString - the URI to open
  - save
```
public void save()
```
    Saves the current suite under its current filename.
    If the suite has no current filename, one will be requested from the user using a standard file dialog.
  - showPrintDialog
```
public void showPrintDialog(java.lang.String window)
```
    Shows a print dialog.
    
    Parameters:
    
    window - An identifier specifying the window to print; valid values are MAIN, SITE, and SUITE.
  - save
```
public void save(Suite suite)
```
    Saves the specified suite under its current filename. If the suite has no current filename, one will be requested from the user using a standard file dialog.
    
    Parameters:
    
    suite - the suite to save
  - showCalculateRpiDialog
```
public void showCalculateRpiDialog()
```
    Calculates RPI using two loaded suites.
  - showDiscreteToContinuousDialog
```
public void showDiscreteToContinuousDialog()
```
    Shows the dialog for a discrete to continuous sample conversion.
  - showCreateBundleDialog
```
public void showCreateBundleDialog()
```
    Shows the dialog for creating and exporting a data and code bundle.

Class PuffinApp

Method Summary

Methods inherited from class java.lang.Object

Method Detail

create

show

getPlotParams

redoCalculationsForAllSuites

getBuildProperty

calculateGreatCirclesDirections

recalculateSamplesAndSites

fitGreatCirclesToSelection

doPcaOnSelection

getPrefs

getMainWindow

getCorrection

setCorrection

updateDisplay

closeCurrentSuite

createNewSuite

openFiles

errorDialog

errorDialog

getSuites

getCurrentSuite

setCurrentSuite

getCurrentSample

getSelectedSamples

modifySelectedSamples

getCurrentSite

getSelectedSites

getAllSamplesInSelectedSites

quit

about

showPreferences

showPageSetupDialog

getCurrentPageFormat

getTableWindow

getActions

getSuiteEqAreaWindow

getSiteEqAreaWindow

getRecentFiles

setRecentFiles

showCustomFlagsWindow

showCustomNotesWindow

doAmsCalc

openFileDialog

showMacOpenFolderDialog

showOpenFilesDialog

showImportAmsDialog

showImportPreferencesDialog

clearPreferences

copyStepSelection

pasteStepSelection

flipSelectedSamples

showRescaleMagSusDialog

clearSiteCalculations

clearAmsCalcs

exportPdfItext

exportPdfFreehep

calculateMultiSuiteMeans

runPythonScriptInGui

showRunPythonScriptDialog

runJavascriptScript

showRunJavascriptScriptDialog

getVersion

openWebPage

save

showPrintDialog

save

showCalculateRpiDialog

showDiscreteToContinuousDialog

showCreateBundleDialog